Adapt 2d boundary

[xldeltares]

Kind of request

Changing existing functionality

Enhancement Description

In order to be consistent with 2D/3D requirements and in line with the effort in moving reading/writing into hydrolib-core Deltares/HYDROLIB-core#553, The use of 2d boundary needs to be adapted.

This involves mainly the writing of 2D boundary. For now in hydromt-delft3dfm, during setup, we set a hydromt forcing object (xarray.DataArray) with all data fields required by the hydrolin-core.ForcingModel as attributes. We need an extra step to convert that into a new xarray.DataArray with attributes that conforms the dflowfm convention. Then one could easily write the 2D boundary into .nc instead of .bc.

What needs to be adapted?

• use xarray.DataArray: we already do that but the format is different (refer to the next point)
• conform to 'Delft3D FM' netcdf convention (https://content.oss.deltares.nl/delft3d/D-Flow_FM_User_Manual_1D2D.pdf E.2.4)

What followups needed?

• Make a separate function that writes 2D boundaries as a netcdf files. hydromt_delft3dfm.utils._write_ncdicts
• Test if model runs with the netcdf file, confirm on the fileformat.
• Harmonize fileformat with 2D3D. Rename hydrolib converted dataset varname/dims/vars dfm_tools#527
• Implement 'hydrolib-core' conversion function so that .bc <-> .netcdf: Improve conversions between hydrolib and xarray dataset dfm_tools#590

How does the hydromt forcing object for 2D boundary looks like?

data
A 3D array holding the values of the DataArray. It is created from the 2D da data ("index", "time"), but expanded to a 3D shape to store support points on lines "numcoordinates". 

dims:
These are the names of the three dimensions:
index: Refers to the individual linestring geometry.
time: Represents the time steps from the original da DataArray.
numcoordinates: Refers to the individual coordinates within each linestring.

coords:
These are the actual coordinates that label the data along each dimension.
index: The original index from the GeoDataFrame.
time: The standardized time steps processed by _standardize_forcing_timeindexes.
numcoordinates: Represents the position of each coordinate within a linestring.
x: The x-coordinates of each linestring, structured to match the index and numcoordinates dimensions.
y: Similarly, the y-coordinates of each linestring.

attrs:
This dictionary holds metadata or attributes that provide additional context to the DataArray.
function: Indicates the data represents a time series.
timeInterpolation: Specifies the interpolation method used with the time data.
quantity: Represents the type of forcing, either 'dischargebnd' or 'waterlevelbnd'.
units: Specifies the unit for the forcing data, either 'm3/s' or 'm'.
time_unit: A string denoting the time unit, structured to indicate a starting point (like "hours since YYYY-MM-DD HH:MM:SS").

How does the 'Delft3D FM' netcdf convention looks like?

netcdf timeseries {
dimensions:
        strlen = 7 ;
        node = 3 ;
        time = UNLIMITED ; // (18 currently)
variables:
        double time(time) ;
                time:units = "hours since 2000-01-01 00:00:00" ;
        char location(node, strlen) ;
                location:cf_role = "timeseries_id" ;
        double x(node) ;
                x:axis = "x" ;
                x:units = "km" ;
                x:long_name = "x coordinate of projection" ;
                x:standard_name = "projection_x_coordinate" ;
        double y(node) ;
                y:axis = "y" ;
                y:units = "km" ;
                y:long_name = "y coordinate of projection" ;
                y:standard_name = "projection_y_coordinate" ;
        double rainfall(time, node) ;
                rainfall:long_name = "Rainfall" ;
                rainfall:standard_name = "precipitation" ;
                rainfall:units = "mm" ;
                  rainfall:_FillValue = "-999.9f" ;

Steps for hydromt_delft3dfm.utils._write_ncdicts

• make sure a bndid is used for .pli, .nc and .ext.
• For each bndid, write all support points into {bndid}.pli file.
• For each bndid, write one timeseries for the first support point into {bndid}.nc file.
• Use a xarray.Dataset internally for {bndid}.nc
• Use quantity (e.g. "waterlevelbnd") in the xarray.Dataset as data variable to store the timeseries.
• Use location (e.g. "polylin_0001") in the xarray.Dataset as data variable; because location label and quantity name uniquely identify the timeseries.
• Use "strlen", "node" and "time" as dimensions, e.g. location(node, strlen); waterlevelbnd(time, node)

Additional Context

Use line geometry in geodataset is done in this issue below:
(#6)
Discussion of whether 2D boundary in 1D2D and 2D3D shares enough similarities yields the renaming of setup_2dboundary to setup_2dboundary_from_lines. So that it is clearer to the user that they are applying 2D boundary as lines, and each line accepts one timeseries - more common for 1D2D models.

Question

The fileformat required by 1D2D seems different from 2D3D as reported in Deltares/dfm_tools#527.

[xldeltares]

Linked to issue: Deltares/dfm_tools#527
There is an example of the netcdf to conform to.

[xldeltares]

Something to discuss: for 1D2D urban type of models, it is rarely seen that the 2D boundary is as complex as 2D3D coastal models. If we enforce the 2D3D model, that might leads to large model files.

Why for 1D2D the 2D boundary is less complex? that is because in 1D2D urban applications, the 2D is mainly used for model overland flow. The water on the surface either come from overflow of underground sewer network, or overtopping from the river. for the former, we do not need to use 2D boundary while for the latter, often 1D2D links are used to simulate that. Besides that, one scenario is that we use 2D boundary to simulate the water flowing out of the domain instead of being bounded in the 2D mesh. Therefore, the initial condition and the boundary is often dry, or far less complex.