Node keys
Scripts, edit files and feedback forms refer to nodes by their key, not by their node ID. A key follows from the source data, so it stays the same when the node IDs change: with another library version, or when a node is added or removed elsewhere in the model. A node ID is the next free number, and nothing may depend on its value.
The key of a node
The key is in the node column meta_key, and is unique in the model of a water authority. In the coupled model a node is identified by its authority, meta_waterbeheerder, and its key. A key is set when the node is created, and does not change after that, also when the type or the name of the node changes, or another Basin is merged into it.
The models that are built from source data set the keys of their nodes.
| Node | Key | Example |
|---|---|---|
Gravity controlled, ribasim_nl.keys.lumped_keys |
||
| Connector node on a structure | the code of the structure | GA1-st9 |
| Connector node on open water | ow: and the code of its hydroobject |
ow:KD25.1_0 |
| Boundary | bnd: and its ID in the boundaries layer |
bnd:28 |
| Basin | up: and the key of the connector node it drains through, the smallest if it has several. Without one, down: and the connector node that feeds it |
up:GA1-st9 |
Level controlled, ribasim_nl.crossings.model.crossing_keys |
||
| Connector node on a structure | the code of its gemaal, or else of its stuw, the smallest if it has several | KST-1375 |
| Connector node on open water | ow: and the code of its hydroobject, the smallest if it has several |
ow:KDU15754 |
| Several connector nodes with the same code | also the codes of the areas they connect, <code>|<from>><to> |
KGM-108|GPG-1011_36>GPG-1012_56 |
| Basin | the code of its aggregation area or peilgebied | P-D21.006 |
| Boundary | bnd: and the key of the connector node it lies beside |
bnd:KGM-72 |
Rijkswaterstaat, ribasim_nl.keys.named_keys |
||
| Connector node on a structure | the code of the structure, or else its name | 39B-002-02 |
| Basin | the name of its water | Markermeer |
| Boundary | bnd: and the code of its measuring location, or else its name |
bnd:LOBH |
| Other connector node | the keys of the Basins it connects, <from>><to> |
Waal@3>Waal@2 |
Every other node gets a key when the model is written, or when a key is looked up that no node has yet, with ribasim_nl.keys.fill_keys:
| Node | Key | Example |
|---|---|---|
Connector node with a meta_code_waterbeheerder |
that code | KST1 |
| RWZI | rwzi: and its code |
rwzi:30021 |
| Observation, UserDemand | the node type and its name | observation:NL27_KD_3 |
| Storing (bergend) Basin, and the node that connects it | bergend: and bergend_link: with the key of the Basin it stores for |
bergend:up:GA1-st9 |
| Control or demand node | the node type and the key of the node it controls, the smallest if it controls several | discrete_control:GA1-st9 |
Part of a Basin that is split from a file, SplitBasins |
the key of the Basin and the ID of the part in the file | PBH0248142/1 |
| Junction | junction:<from>><to>#<n>x<m>: the smallest key of the n nodes that flow into it, and of the m nodes it flows to |
|
| Any other node | its location in whole metres | loc:152150,365169 |
Equal keys get a number, @1, @2, in an order that follows from the data: along the hydroobject, or by location. The keys of the Junctions are set again every time, since their trees are rebuilt along the way. Model.write checks that every node has a key and that no two nodes of a water authority have the same one.
Refer to a node
In a script, right after the model is read:
model = Model.read(ribasim_toml)
# nodes and links are referred to by their key, see docs/dev/node-keys.qmd
n = model.node_id
lk = model.link_id
model.merge_basins(node_id=n("up:ow:SG1_0"), to_node_id=n("up:DO1-st3"))
model.reverse_link(link_id=lk("up:KS52-st2", "KS52-st2"))n returns the ID of the one node with a key, and raises a KeyError if there is none or more than one. A link has no key: lk returns the ID of the link between two nodes.
- Model edits. A layer of
model_edits.gpkgrefers to a node in a column<name>_key, whichModel.apply_editspasses to the argument<name>_idof the edit method:node_key,to_basin_key. It refers to a link in the columnslink_from_keyandlink_to_key. The layeradd_basingives the new Basin a key in its columnkey; a node ID in the layer is not used. static_data.xlsx. The sheetsPump,OutletandBasinrefer to a node in their columnkey.- Feedback forms. The sheet
Feedback_Formulierrefers to nodes in itsNode keycolumns. A row that adds a node gives the key of the new node, by which later rows and scripts refer to it. The sheets with target levels, pump functions and supply areas refer to nodes in aBasin key,Pump keyorOutlet keycolumn. - The coupled model. The tables of
pipeline/09_koppelen_modellen.pyand of the package refer to a node by its water authority and key,NodeKey("Noorderzijlvest", "KGM056").ribasim_nl.keys.resolve_keysreplaces them by the node IDs of the model that is coupled. In a script,model.node_id("KGM056", authority="Noorderzijlvest")does the same for one node.
Add a node
A node that a script adds gets the next free node ID, and a key by the rules above. Do not give it a node ID, and give it a key yourself where it is referred to later, so that the reference reads well:
model.outlet.add(Node(geometry=Point(152150, 365169), meta_key="inlaat-keersop"), tables=[...])A node that replaces another one, such as a FlowBoundary that becomes a LevelBoundary, gets the key of the node it replaces.
Find a node by an old node ID
Issues, pull requests and feedback of water authorities name nodes by the node ID of the model of that moment. To find such a node in the latest model, give its ID with the date on which it was right, or with the commit of a link to the model viewer:
pixi run node-key 1100540 1100695 --date 2026-11-19
pixi run node-key 203892 --commit 21ce19f26c
pixi run node-key --link 1100306 --date 2026-11-19It prints a Markdown table with the key of each node, its node ID now, and a link to it in the model viewer:
| node ID | type | name | key | node ID now | matched by |
|---|---|---|---|---|---|
| 1100540 | Pump | Poldergemaal Dooijersluis | AmstelGooienVecht:KGM00534 | 1100540 | name |
| 1100695 | Outlet | AmstelGooienVecht:KST00098 | 1100695 | node ID, 125 m away |
Leave the issue as it was written, and add the table as a comment.
--datetakes the model ofmainat the end of that day. Without a date or commit, the IDs are those of the latest model.- A link has no key, so
--linkfinds it by its nodes. - The nodes are read from the model of the commit in the model viewer. That needs no credentials, but the model must still be published there.
- Models from before November 2026 have no keys. Their nodes are matched with the first model with keys: by location, else by name, else by node ID. The table says which. Check a node that is matched by its ID and moved far. A Junction is only matched by its location, since the Junction trees are rebuilt in every run.
Not a node ID
Not every integer in a script is a node ID. Row numbers of source layers (fid_as_index=True), codes of areas, capacities and levels stay as they are. Refer to a row of a source layer by its code where it has one.