Skip to main content

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.

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

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"]

What happens to a LevelBoundary with a 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.

Two authorities with several pairs of triangles along their border, each with links on one side.

Before coupling, in lhm_parts. Rijnland (green) and Amstel, Gooi en Vecht (blue) both end in LevelBoundaries (triangles) along their border.

The same area with squares on the border where the triangles were, and links that cross the border.

After coupling, in lhm_coupled. Each pair of LevelBoundaries with the Outlets next to it is now one Outlet (square) with links to both sides.

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:

  1. 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.
  2. Replace the boundaries, as above.
  3. Set names and levels of the nodes where a boundary was a placeholder.
  4. Convert open connections: convert_outlets_to_manning_resistance turns Outlets on open water, such as 1100600 Angstel-ARK (#820), into ManningResistances.
  5. Fix profiles: where an Outlet has a min_upstream_level below the bottom of the Basin upstream of it, the bottom of the Basin moves down.
  6. Remove invalid nodes, with a warning: remove_invalid_topology_nodes removes nodes that the coupling left without a valid topology.
  7. Route the links between models over Top10NL, with netwerk.gpkg as the main route. A link stays straight if it is listed in straight_rws_links, such as those of the Zeesluis Muiden (#916).
  8. Add user demands that cross models, such as the Evides drinking water of the Maasvlakte (#857).
  9. 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.
  10. Link observations that measure on links between models, which need the coupled network, see ribasim_nl.observations.
  11. Tidy the layout, see Layout, and link the observations that need the merged Junction trees.
  12. Write the model, validate it with validate_ribasim_nl, and write the links that were added to link.gpkg.
  13. Correct the coupling levels, see below.
  14. 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.