Skip to main content

Reproducing models

Until November 2026, scripts referred to the nodes and links of a model by their ID: the 01_fix_model.py scripts and model_edits.gpkg files of the gravity controlled models, and the feedback forms of the level controlled models. A model that was rebuilt from its source data therefore had to get the same IDs, or all these references would break. They now refer to nodes by their key, which follows from the source data, and nothing gives a node a fixed ID anymore: a node gets the next free ID, and the tools that compare models and runs match nodes by key. This page describes how the input models of the gravity controlled (#903) and level controlled models were reproduced, and the differences between library versions that were found on the way.

The input models of the gravity controlled models

In July 2024, Sweco made the input models <authority>_2024_6_3 of the 11 gravity controlled water authorities with ribasim_lumping, at commit 65c7ef53 of #118, in four notebooks: apply manual changes to the HyDAMO data, lump the network into basins, and convert the result into a Ribasim model. This code is ported to ribasim_nl.lumping, and the DVC pipeline runs it:

  • pipeline/00a_process_hydamo.py applies the manual changes to the HyDAMO data of 7 water authorities. For Aa en Maas, De Dommel and Vallei en Veluwe, the processed HyDAMO data is source data.
  • pipeline/00b_lump_model.py lumps the HyDAMO network of 10 water authorities into their input model.
  • pipeline/noorderzijlvest/00_lump_model.py lumps the D-HYDRO model of Noorderzijlvest.

All node IDs and link IDs of the 11 input models are reproduced, but for 21 basins that the lumping of 2024 left out, see Moving fixes into the lumping: 2 in De Dommel, 4 in Limburg and 15 in Vechtstromen. They get the IDs after those of the other nodes, and no longer the IDs that the fix scripts gave them. In Limburg, whose input data differs from the data of the run in 2024, 4 nodes get another name. The basin areas are no longer reproduced, since the lumping now gives every area to a basin, see Moving fixes into the lumping.

The input models of the level controlled models

HKV made the input models <authority>_boezemmodel_<version> of the 10 level controlled water authorities with peilbeheerst_model, in three steps: parse_crossings found the crossings of the hydro-objects with the boundaries of the peilgebieden in spring 2024, notebooks found the shortest paths through the boezems, and crossings_to_ribasim made the models on 4 December 2024, at commit 91b23140 of #244. Wetterskip Fryslân followed on 19 and 20 May 2025, at commit 50638080 of #331. This code is ported to ribasim_nl.crossings, together with the scripts that turned the data the water authorities delivered into the postprocessed data, see Level controlled.

All tables of the 10 input models are reproduced from the deliveries, but for one pump of Wetterskip Fryslân, and the node IDs of 7 of them, see below. Some links to and from the boezems get another geometry, since they follow shortest paths, of which a few now take another route of the same length or have their vertices in another order, and some nodes and areas differ by less than a centimetre, see GEOS.

The postprocessed data

pipeline/<authority>/00_postprocess.py ports the preprocessing and postprocessing scripts of peilbeheerst_model, which are removed; see them at commit 1115d284. These scripts were not the version that made the data of 2024, which HKV ran locally: some no longer ran, others read other deliveries, or kept other rows. The ports reconstruct that version from the data of 2024, the deliveries on the cloud storage, and the notebooks of HKV in the git history, and reproduce the postprocessed data of 2024 exactly, but for:

  • the columns meta_name and meta_capaciteit, which nothing uses;
  • coordinates that differ by less than 1e-6 m, from reprojections with another PROJ and unions with another GEOS;
  • 4 peilgebieden of Hollands Noorderkwartier, which HKV clipped by water board boundaries that are not on the cloud storage, and which differ by 1 to 4 m².

HKV corrected some of the delivered data by hand, such as gaps between the peilgebieden of Zuiderzeeland, and the KRW water bodies that became peilgebieden in Hollandse Delta. verwerkt/corrections.gpkg holds these corrections as edits of the delivered layers, which ribasim_nl.crossings.postprocess.derive_edits derived from the data of 2024, and which apply_edits applies in place, keeping the order of the rows. For Rijnland, it also holds the results of 2024 where GEOS 3.14 differs, see GEOS. The aggregation areas follow from the deliveries: copies of the peilgebieden, or polders, supply areas or drainage units that the peilgebieden are joined with. Only the 12 parts into which HKV split the boezem of Delfland are source data, verwerkt/aggregation_area.gpkg.

Other findings:

  • The delivered levels of Amstel, Gooi en Vecht and Rivierenland are float32 values such as -2.0999999 in the files themselves; HKV rounded them to centimetres, and so do the ports.
  • GDAL 3.13 splits a self-touching ring of a shapefile into an outer ring and a hole. Hollands Noorderkwartier reads its peilgebieden as stored, as GDAL 3.10 did.
  • ruff’s fix of 2024 changed comparisons of columns such as df.col == False into df.col is False, which is always false; the ports compare as before.

The node IDs

The input models keep the IDs that ribasim_nl.crossings.model gives their nodes and links, in the order of the crossings. Until the feedback forms, the feedback scripts and the coupling referred to nodes by their key, the nodes and links were numbered after those of the input models of 2024. The feedback step numbers the links anew, in their order, so a link that is added or removed before it shifts the IDs of the links after it; the scripts that follow refer to links by their nodes.

With exactly the same postprocessed data, 7 input models have the IDs of 2024. The coordinate noise above swaps a few nodes at the same place: 9 nodes of Amstel, Gooi en Vecht and 8 of Zuiderzeeland have another ID. The crossings of Wetterskip Fryslân of May 2025 cannot be reproduced: the same code on the same data finds some stacked crossings in another order, with numpy 2.2 and GEOS 3.13, with or without AVX2 and AVX-512, and so does the port. Of its 3852 nodes, 3033 have another ID than in 2025; 9 of them, crossings that moved along the boundary of their peilgebied, are 4 to 134 m from where they were, and one pump that the feedback form does not use is gone.

In Hollandse Delta, a hydro-object crosses the boundary between peilgebieden 94 and 95 almost in parallel, so the direction of the crossing depends on rounding: GEOS 3.12 found it from 95 to 94, GEOS 3.14 also from 94 to 95. pipeline/00c_parse_crossings.py excludes the second, and checks that it is found.

Process

  1. Find the code and the data as they were. The git history has the code, and the cloud storage has the data with its modification dates. Compare the dates of the inputs with those of the outputs: an input that changed after the run cannot reproduce it.
  2. Recreate the environment of the time, with the library versions of then, and run the original code on the current data. That gives the reference: differences between the reference and the original outputs come from the data, differences between the reference and the port come from the code.
  3. Port the code, and compare its intermediate results with those of the original code, table by table and including the order of the rows, not only the final model. The order of rows is often the order of the IDs.
  4. Where the order differs, emulate the old behaviour where the IDs follow from it, rather than sorting afterwards.
  5. Run the downstream scripts on the original and on the reproduced model, and compare their results.

For the input models, the reference environment was a separate Pixi project with Python 3.12, pandas 2.1.4, numpy 1.26.4, geopandas 0.14.4, shapely 2.0.4 with GEOS 3.12.2, fiona 1.9.6, pyogrio 0.7 and networkx 3.3. The environment Sweco used is not known, but this one reproduces its IDs.

For the level controlled input models, three reference environments followed the lock files of then. The crossings: Python 3.12.2, numpy 1.26.4, pandas 2.2.1, geopandas 0.14.3, shapely 2.0.3 with GEOS 3.12.1, fiona 1.9.6, pyogrio 0.7.2 and networkx 3.3, without AVX-512, which NPY_DISABLE_CPU_FEATURES turns off. The input models of December 2024: Python 3.12.7, numpy 2.0.2, pandas 2.2.3, geopandas 1.0.1, shapely 2.0.6 with GEOS 3.13.0, ribasim 2024.11.0, pandera 0.20.4 and pydantic 2.9.2. That of May 2025: Python 3.13.3, numpy 2.2.5, pandas 2.2.3, shapely 2.1.0 with GEOS 3.13.1, networkx 3.4.2 and ribasim 2025.3.0.

Library differences

Library Old behaviour Effect Emulated in ribasim_nl
pandas < 2.2 An inner merge groups the rows by key, in order of first appearance in the left table. Since pandas 2.2 it keeps the order of the left table. The order of the nodes and links, and so their IDs lumping.utils.merge_grouped
numpy < 2 argsort(kind="quicksort"), also used by sort_values and sort_index, is an unstable introsort, which decides the order of equal values. With AVX-512, numpy 1.26 used another algorithm, and numpy 2 uses yet others, which depend on the CPU as well. The 2024 models were made without AVX-512. The link IDs of the boundaries, the order of the basin areas, and the order of the crossings lumping.utils.quicksort_order, the introsort of numpy 1.26 in Python, and with it crossings.parse.sort_index_2024 and sort_values_2024
Ribasim 2024.9 Wrote the tables sorted by node ID with that unstable sort The row numbers of the basin areas No longer emulated
Ribasim 2024.11 Kept the index of a table assigned to a model, on which some joins of crossings_to_ribasim aligned the rows The metadata of the level controlled input models crossings.model keeps the tables as then until the model is written
Ribasim 2025.3 Changed the geometries of the basin areas when assigned, so their names were not set No names for the basins of Wetterskip Fryslân crossings.model.Options.add_names names the pumps only
geopandas < 1 overlay fixes invalid polygons with buffer(0), keeps the polygonal parts of collections, and with pandas < 2.2 groups the intersections by the polygon of the second table Which basin gets an unassigned area No longer emulated
pandas < 3 Formats a missing string in an f-string as None The IDs of edges that are split In lumping.utils.split_edges_by_dx
pandas < 3 Strings are objects with None for missing values, which are equal. In pandas 3 they are NaN, which are not. Extra crossings between two missing peilgebieden crossings.parse.pandas2_strings and crossings.model.to_object
Python The order of a set of strings differs per process The order of the IDs in the columns stuw and gemaal of the crossings, but not the model They are sorted
GEOS See below The geometry of the basin areas, and of links along shortest paths, and one crossing Not emulated

GEOS

The results of geometric operations such as union, intersection, buffer(0) and make_valid differ between versions and builds of GEOS. Coordinates differ by about 1e-9 m, the results get other slivers and tiny holes, and adjacent parts of a union may or may not be merged. That cannot be emulated: GEOS 3.12.2 reproduces 858 of the 859 basin areas of De Dommel topologically, but only 190 of the 543 of Stichtse Rijnlanden.

The IDs of the level controlled models depend on it in one place: a crossing in Hollandse Delta that GEOS 3.14 finds in both directions, see above. Their shortest paths through the boezems depend on it as well: a few take another route of the same length, or merge their lines with the vertices in another order, which gives their links another geometry. And in Rijnland, 56 peilgebieden without crossings get another aggregation area in the column agg_area of the peilgebieden of the crossings, since GEOS 3.14 computes other overlaps with the aggregation areas; nothing uses it. Its postprocessing takes the praktijk peilgebieden off the vigerend ones, which leaves mostly slivers along their boundaries, and adds a margin of 1 m to the parts of its boezem. GEOS 3.14 makes other slivers and margins than GEOS 3.12 did, so verwerkt/corrections.gpkg holds those of 2024 where they differ, in the layers remnants and boezem.

The IDs of the gravity controlled models do not depend on it, but scripts that select geometries do. They now allow for these differences:

  • Model.select_basin_area, used by remove_basin_area and update_basin_area, takes geometries as equal if their boundaries are on average at most 1 mm apart. Without a basin area that equals a polygon, it selects the basin areas that together make it up, or else splits the polygon from the basin areas that cover it. So it works whether adjacent parts are merged or not. It skips slivers.
  • ribasim_nl.geometry.connected_parts splits a (Multi)Polygon in the parts connected to the part with a given point, and the other parts, instead of taking the parts by position.

A union with slivers can also go wrong, in GEOS 3.12 as well as 3.14: it can lose or add whole parts. In Hunze en Aas, a union of 25 pieces of a basin area lost 2.1 km², and the union of a basin area of 61 vertices with a sliver of 1e-9 m² gained 0.066 km². ribasim_nl.geometry.union_polygons checks that a union is not larger than the polygons together, and contains a point inside each polygon. If not, it takes the union again with a fixed precision of 1 mm, or without the slivers. The lumping and Model.dissolve_basin_area use it. That check does not catch a part lost within a large polygon, though. Overlays with a fixed precision (grid_size), on geometries made valid at that precision with shapely.set_precision, are robust. ribasim_nl.berging.supply_area_basin_ids overlays basin areas with supply areas that way, since a floating point overlay found no overlap for 3 basins of Drents Overijsselse Delta that lie entirely in a supply area.

Writing reproducible code

  • Sort with kind="stable", and with keys that decide the order of all rows that matter. The order of equal values in an unstable sort depends on the library version and the CPU.
  • Do not rely on the order of rows after a merge, a groupby or a spatial join; sort explicitly where the order sets IDs.
  • Refer to objects by a stable key, such as their code, rather than by row number. gpd.read_file(..., fid_as_index=True) makes a script depend on the order of the rows in the file, so keep that order when such a file is rewritten.
  • Select geometries with a tolerance, and do not rely on the order or number of the parts of geometries from geometric operations.
  • Do not let a result depend on whether geometries touch. Whether the end of a line on a boundary reaches into a polygon by 1e-9 m depends on coordinate noise. The profiles counted a hydro-object with its whole length in every basin it intersected, so noise of at most 1e-8 m changed 185 of the 215 Basin profiles of Zuiderzeeland, with bottoms up to 4.85 m apart, while its network hardly changed. ribasim_nl.profiles.path_finder.overlaps requires an overlap of 1 mm. Rounding the coordinates also removes the noise, but lines then still count in polygons they only touch, decided by the rounding.
  • Of the shortest paths of equal length, networkx takes the one it reaches first, which depends on the order in which the graph was built. Build graphs from geometries in an order that follows from them, as ribasim_nl.profiles.path_finder.canonical does.
  • Where the result of an overlay decides something, overlay with a fixed precision, on geometries made valid at that precision.
  • The DVC pipeline records the code, data and environment of every output, in git, dvc.lock and pixi.lock, so an output can always be reproduced.

Moving fixes into the lumping

The 01_fix_model.py scripts correct the input models afterwards. Now that the pipeline makes the input models, most of these fixes can move into the lumping or its inputs, or the lumping algorithm can change, so that the input models are right from the start. These have moved:

  • Lost basins. The lumping of 2024 left out the basins whose ID was taken by a split node, and those at a LevelBoundary without split node, while links still referred to them. The fix scripts added them again, and removed the duplicate links. ribasim_nl.lumping.model.number_lost_basins now does that.
  • Basin areas. Every area of verwerkt/3_input/areas.gpkg goes to a basin, see ribasim_nl.lumping.network.assign_areas: the basin it drains to, or else the basin with whose areas it shares the longest border, preferably in its drainage area. Each basin gets one MultiPolygon, and gaps between them up to 5000 m² are filled. The fix scripts no longer fill holes from verwerkt/4_ribasim/areas.gpkg, which differed from it for 3 authorities. As their last step, they fill the holes that their own edits leave with Model.fill_basin_area_holes, by the same rules, which also checks that every Basin has a basin area. A Basin that a fix script adds gets its areas by their code, since the area that its node lies in can be far too small. Parts outside the model are excluded there, such as the Twentekanaal of the Rijkswaterstaat model in Vechtstromen.
  • Node IDs. They follow from the order of the boundaries, split nodes and basins, so a new split node renumbers all basins after it. The fix scripts, model_edits.gpkg and pipeline/09_koppelen_modellen.py refer to nodes by their key, so that no longer breaks them. Nothing gives a node a fixed ID anymore: the lost basins, and the nodes that the fix scripts and model edits add, get the next free ID.

These remain:

  • Edits of the lumping inputs. Splitting basin areas with lines, or removing and renaming them with model_edits.gpkg, can become edits of the split nodes, boundaries and areas that the lumping reads, which have stable codes. The tolerant Model.select_basin_area only bridges until then. The area split lines of Stichtse Rijnlanden, for instance, were drawn on the basin areas of 2024. Splitting areas.gpkg along them before the lumping gives 20 of the 28 basins that need them an area by drainage.