Improve bc file formatting

[veenstrajelmer]

Is your feature request related to a problem? Please describe.
example code:

from pathlib import Path

from hydrolib.core.io.bc.models import (
    ForcingModel,
    QuantityUnitPair,
    TimeInterpolation,
    TimeSeries,
)

# Chosen approach: separate .bc file for each boundary (east and south)
bc_east = ForcingModel()

# Each .bc file can contain 1 or more timeseries, one for each support point:
steric = TimeSeries(
    name="east2_0001",
    quantityunitpair=[QuantityUnitPair(quantity="time", unit="seconds since 2022-01-01 00:00:00 +00:00"), #TODO: should fail if only one QUP is supplied, but does not: https://github.com/Deltares/HYDROLIB-core/issues/305
                      QuantityUnitPair(quantity="waterlevel", unit="m")],
    timeinterpolation=TimeInterpolation.linear,
    datablock=[[0, 1.1], [3600, 2.3], [7200, 3.5], [10800, 2.4], [86400, -0.123]],
)
bc_east.forcing.append(steric)

bc_east.save(filepath=Path("steric_east2.bc"))

Results in this file:

[Forcing]
name              = east2_0001
function          = timeseries
timeInterpolation = linear
offset            = 0.0
factor            = 1.0
quantity          = time
unit              = seconds since 2022-01-01 00:00:00 +00:00
quantity          = waterlevel
unit              = m
0.0        1.1
3600.0     2.3
7200.0     3.5
10800.0    2.4
86400.0    -0.123 

Describe the solution you'd like
The time and data values are not neatly aligned. This can easily be solved. User provides a formatting string for time and data columns, or done semi-automatically. Some thinking is still required, since different data types require different precision.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered (if applicable).

Additional context
This is important with large t3D bc files, because of readability, but also disk space. The latter is significantly reduced when reducing precision and that is relevant since even then the bc files are >1GB. It could also be that formatting with limited significance improves writing speed.

[tim-vd-aardweg]

Discussed the issue with @veenstrajelmer. The data blocks in the .bc file were not as bad as he remembered. We did discuss that we will do the following:

• Reduce the default number of spaces between columns on 2 (instead of 4).
• The user should be able to specify the number of decimals they want written for the non-time columns.
• We will not change the way the numbers are currently aligned.

[tim-vd-aardweg]

Initially, I had a working implementation by adding a new optional property (that defaults to none) to the DataBlockINIBasedModel called something like number_of_decimals_to_write.

In the _to_section() function of that same class (where the data is implicitly converted from floats to strings) we can then do something like:

def _to_section(self) -> Section:
        section = super()._to_section()
        if not self.number_of_decimals_to_write:
            section.datablock = self.datablock
        else:
            section.datablock = []
            for row in self.datablock:
                formatted_row = [
                    f"%.{self.number_of_decimals_to_write}f" % i for i in row
                ]

            section.datablock.append(formatted_row)

        return section

This correctly formats the datablocks in the .bc file and can be used as follows:

for model in forcingmodel.forcing:
     model.number_of_decimals_to_write = 12

or by specifiying the number_of_decimals_to_write when creating for example a T3D block.

However, after discussing it with Jelmer, we came to the conclusion that this is not very intuitive for the user. The user may think that the precision of the actual data (so the floats) are set, but that's not the case. We also came to the conclusion that it would be more intuitive to somehow add it to the save method. For example:
forcingModel.save(filepath, number_of_decimals_to_write=12)

[tim-vd-aardweg]

So I discussed these requirements with Prisca and she thought it would be best to make something like a SaveConfig class that would not only hold the number_of_decimals_to_write, but could also be used for, for example, whether or not to recursively save models.

Also, after talking to Jelmer once more, he also mentioned that he would like to be able to specifiy the precision for, for example, the poly file. So the issue is in fact bigger than only the datablock in the .bc file and therefore requires a solution at a higher level. We should create a better design than the very limited option I initially wrote.

[priscavdsluis]

PR #407 has been created to reduce the datablock spacing from 4 to 2.

[veenstrajelmer]

Just tested the performance with the code in #313. These are the results:

1000 rows with hydrolib (unformatted):     0.27 sec
1000 rows with hydrolib (formatted single): 0.26 sec
1000 rows with savetxt (unformatted):       0.08 sec
1000 rows with savetxt (formatted single):  0.03 sec
1000 rows with savetxt (formatted percol):  0.03 sec

10000 rows with hydrolib (unformatted):     2.79 sec
10000 rows with hydrolib (formatted single): 4.40 sec
10000 rows with savetxt (unformatted):       0.66 sec
10000 rows with savetxt (formatted single):  0.22 sec
10000 rows with savetxt (formatted percol):  0.21 sec

100000 rows with hydrolib (unformatted):     31.48 sec
100000 rows with hydrolib (formatted single): 29.18 sec
100000 rows with savetxt (unformatted):       6.57 sec
100000 rows with savetxt (formatted single):  2.30 sec
100000 rows with savetxt (formatted percol):  3.63 sec

In the original issue, the performance of hydrolib and savetxt was equal in unformatted mode, while it is a factor 5 different now. The limited performance of hydrolib seems to mainly come from the formatting, the writing of the file seems quite fast. numpy.savetxt() seems to format per line instead of per item (if I interpret it correctly): https://github.com/numpy/numpy/blob/v1.23.0/numpy/lib/npyio.py#L1553
However, that would interfere with the hydrolib column aligner I think, which is a useful feature.