flowchart LR hws["hws_transient"] --> merge gravity["11 <authority>_dynamic_model"] --> merge level["10 <authority>_forcing"] --> merge merge(["samenvoegen<br>08_samenvoegen_modellen.py"]) --> parts["lhm_parts"] parts --> couple(["koppelen<br>09_koppelen_modellen.py"]) netwerk["netwerk.gpkg, Top10NL, OSM fairways"] --> couple peilbeheer["peilbeheer.gpkg"] --> couple couple --> coupled["lhm_coupled"] classDef step fill:#dfedef,stroke:#0c6a77 class merge,couple step
Coupling
The nationwide model is made in two stages. samenvoegen merges the 22 models into one model file in which they are still separate, lhm_parts. koppelen connects them where they meet, into lhm_coupled.
Merging
pipeline/08_samenvoegen_modellen.py reads each model, makes its IDs unique with prefix_index, see Node IDs, and appends all its tables with concat. The original IDs stay available in meta_node_id_waterbeheerder and meta_link_id_waterbeheerder, and meta_waterbeheerder holds the authority. The merged model starts with the settings of the model of the main water system, and the solver settings are set here.
Connecting the models
In each regional model, a LevelBoundary stands for the water on the other side of its border. AssignAuthorities records whose water that is in the column meta_couple_authority of the node table, with Noordzee or Buitenland where it leaves the model. The boundaries of the main water system have Noordzee or Buitenland as well, so they stay boundaries.
process_boundary_nodes then goes through the boundaries of the regional models:
flowchart TD
start["LevelBoundary"] --> own{"Couples to its own authority,<br>Noordzee or Buitenland?"}
own -->|yes| stays["Stays a boundary"]
own -->|no| forced{"In forced_coupling?"}
forced -->|yes| target["Connect to the given<br>Basin or Junction"]
forced -->|no| near{"Boundaries of the other authority<br>within 20 m?"}
near -->|"more than one"| stays
near -->|one| pair{"Two Outlets in opposite directions,<br>both with or both without control?"}
pair -->|yes| merged["Merge into one Outlet"]
pair -->|no| basin
near -->|none| basin["Connect to the nearest Basin / area<br>of the other authority"]
meta_couple_authority.Connecting to the nearest Basin is the easiest and most common case. It relinks the connector nodes of the boundary, for instance an Outlet, so an inflow into the boundary becomes an outlet into the Basin, and an outflow becomes an inlet from it. If a path in the opposite direction already exists, that path and the connector are removed instead, to avoid a cycle. replace_listen_node_id points control nodes that listened to the boundary to the node that replaces it. For the Basins of Rijkswaterstaat, the new link follows the topology of Rijkswaterstaat/verwerkt/netwerk.gpkg, instead of a direct line. No new control nodes are added.
Two LevelBoundaries close to one another, especially between two water boards, are treated as duplicates, and merged if they meet the conditions above.
Where two Pumps, or an Outlet and a Pump, meet at a border, or Outlets do not meet these conditions, they are handled as a connector to a Basin. That leaves duplicate connector nodes in place, and might duplicate a flow. Still to do are couplings for Pump | LevelBoundary . LevelBoundary | Pump and Pump | LevelBoundary . LevelBoundary | Outlet, and investigating whether other connections happen.
forced_coupling lists the exceptions, usually with an issue that explains them. For instance, LevelBoundary 1500551 of Delfland couples to Basin 4000298, the Brielse Meer, rather than to the nearest Basin in the Hartelkanaal.
The other steps of koppelen
couple_model in pipeline/09_koppelen_modellen.py runs these steps in order:
- Remove the summer and winter levels, since the coupling and its level check work with fixed levels, and the nodes listed in
remove_nodes, mostly structures that belong to the neighbouring model and boundaries without a link. - Replace the boundaries, as above.
- Set names and levels of the nodes where a boundary was a placeholder.
- Convert open connections:
convert_outlets_to_manning_resistanceturns Outlets on open water, such as 1100600 Angstel-ARK (#820), into ManningResistances. - Fix profiles: where an Outlet has a
min_upstream_levelbelow the bottom of the Basin upstream of it, the bottom of the Basin moves down. - Remove invalid nodes, with a warning:
remove_invalid_topology_nodesremoves nodes that the coupling left without a valid topology. - Route the links between models over Top10NL, with
netwerk.gpkgas the main route. A link stays straight if it is listed instraight_rws_links, such as those of the Zeesluis Muiden (#916). - Add user demands that cross models, such as the Evides drinking water of the Maasvlakte (#857).
- Attach RWZIs to the routes of Basins that only exist after coupling. For instance, RWZI Stein discharges to the Julianakanaal instead of a Basin of Limburg.
- Link observations that measure on links between models, which need the coupled network, see
ribasim_nl.observations. - Tidy the layout, see Layout, and link the observations that need the merged Junction trees.
- Write the model, validate it with
validate_ribasim_nl, and write the links that were added tolink.gpkg. - Correct the coupling levels, see below.
- Apply the summer and winter levels again, without changing the initial state, since the final state of the regional models already follows the seasons.
Coupling levels
The connectors at a border must respect the target level of the Basin on the other side, which the regional model did not know. run_configured_coupling_level_check corrects min_upstream_level and max_downstream_level of the Outlets and Pumps on links between authorities, and the thresholds of their DiscreteControl nodes. The function of a connector follows from its capacity per control state.
| Limit | Applies to | Set to |
|---|---|---|
min_upstream_level |
outlet, or drain state of an inlet or flow control node | target level upstream |
min_upstream_level |
supply state of an inlet or flow control node | target level upstream − 0.04 m |
min_upstream_level |
inlet from Rijkswaterstaat | lowest level of the profile of the Basin + 0.1 m |
max_downstream_level |
supply state with capacity | target level downstream |
This is done for connectors of the 11 gravity controlled authorities (COUPLING_LEVEL_APPLY_AUTHORITIES), not for those of the level controlled authorities or Rijkswaterstaat, and rows with meta_level_update_protected or meta_threshold_update_protected opt out. FlowDemand-controlled inlets stay untouched, with exceptions in Aa en Maas, De Dommel and Limburg. See ribasim_nl.coupling_levels.
After coupling
koppelen does not run the model. run_lhm_coupled copies the model to runs/lhm_coupled and runs the first 2 of its 3 years, and validate_lhm_coupled checks the results. The model viewer shows them, with the fit to the measurements.

