Closed gijsber closed 6 months ago
This is my suggestion for the update of the Home page (https://deltares.github.io/Ribasim/)
Decision makers need to balance the supply and demand of water in complex situations at the river basin scale and under increasing pressure from climate change. RIBASIM provides a free software tool to visualize, evaluate and prioritize water allocation strategies based on their impact. This provides insights to decision makers, enabling them to build consensus amongst water users and make smart decisions about how to manage water resources optimally considering uncertainties now and in the future. RIBASIM 9 is a water balance simulator composed of 3 conceptual layers: a physical layer representing water bodies and associated infrastructure, a rule-based control layer to manage the infrastructure, and a priority-based allocation layer to take centralized decisions on user abstractions. Typically hydrological processes on land will be represented by other models which can be coupled (online) to Ribasim 9. Currently, an online coupling with Modflow 6 (groundwater) and with Metaswap+Modflow 6 (unsaturated zone + groundwater) is available. Ribasim 9 is the follow up of Ribasim 7 (applied world wide), and SIMRES (applied in the Netherlands), and the surface water models Distribution Model and Mozart of the Dutch National Hydrologhical Instrument.
Ribasim is conceptually organized in three layers:
To represent the physical characteristics of the water system in an area, Ribasim allows you to divide the area into a network of connected representative elementary watersheds (Reggiani, Sivapalan, and Majid Hassanizadeh 1998). Within Ribasim, these elements are called basins, which are essentially buckets or reservoirs holding an aggregated volume of water bodies in an area. Basins are chained in a graph with connector nodes determining the exchange of water between the basins. These connector nodes can represent open water connections (e.g. bifurcations or resistance in a free flowing open water channel) or infrastructure elements such as pumps, gates or weirs.
Infrastructure elements are often controlled by humans to implement a certain water management strategy. Ribasim allows the configuratrion of conditional rules to influence the exchange of water between basins, either by controlling the inflow or outflow, or by controlling a water level . Control rules evaluate one or multiple conditions to change a parameter setting of an infrastructure element when the conditional criteria are met. Conditions can be either calculated values within the network as well as boundary conditions or (todo) external observations, i.e. observation values external to the model.
Ribasim allows water users (water demands) to abstract water from the basins (i.e. from the physical layer) unless the water level drops below a minimum level. Under dry conditions, water managers may want to prioritize some abstractions over other abstractions. The Ribasim allocation layer can take care of this prioritization by reducing the abstraction rates of lower-priority demands to ensure that sufficient water remains available in the system for the higher-priority demands.
The layers and the main components and dataflows between the layers are shown in the next figure:
---
title: Conceptual model
---
flowchart RL
subgraph physical[physical layer]
user-->|abstraction|basin
basin<-->|flow|connector[basin connector]
end
subgraph rbc[rule based control layer]
control[control rules]:::system
end
subgraph allocation[allocation layer]
alloc[global allocation]:::system
end
user-->|request demand|alloc
alloc-->|assign allocation|user
basin-->|volume|alloc
basin-->|volume or level|control
alloc-->|update setpoint|control
control-->|action|connector
Nested allocation Since water systems may be extensive, like in the Netherlands, Ribasim models may become massive networks with multiple 10,000’s of nodes. To keep a proper functioning allocation concept under these circumstances, the modeller can decompose the network domain into a main network and multiple sub-networks. The allocation will then be conducted in three steps:
The users then know what they can extract from the water system in the upcoming period and the rule-based simulation will determine the actual abstraction.
The following sequence diagram illustrates this calculation process.
---
title: Calculation process with nested allocation
---
sequenceDiagram
participant boundary
participant basin
participant user
participant allocation_subNetwork
participant allocation_mainNetwork
user->>allocation_subNetwork: demand
par
allocation_subNetwork-->>allocation_mainNetwork: demand inventory at inlets
end
boundary->>allocation_mainNetwork: source availablility
basin->>allocation_mainNetwork: source availablility
allocation_mainNetwork-->>allocation_mainNetwork: allocate to inlets
allocation_mainNetwork->>allocation_subNetwork: allocated
par
allocation_subNetwork-->>allocation_subNetwork: allocate to users
end
allocation_subNetwork->>user: allocated
user->>basin: abstracted
Remember: reality may deviate from this planning
The kernel of Ribasim is written in the Julia programming language and is built on top of the SciML: Open Source Software for Scientific Machine Learning libraries, notably DifferentialEquations.jl. Ribasim has two API’s, both written in the Python programming language. The Ribasim python package (https://deltares.github.io/Ribasim/python/) offers an API to build, update and analyze Ribasim models programmatically. For runtime data exchange and coupling with other models, ribasim_api is utilized which implements the Basic Modelling Interface BMI (https://bmi-spec.readthedocs.io/en/latest/).
The Ribasim QGIS plugin allows users to construct a model from scratch without programming. For specific tasks, like adding observed rainfall timeseries, it can be faster to use Python instead.
One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible.
See Usage for more information.
%%| file: assets/c4_system.mmd
%%| fig-cap: "System overview of Ribasim"
The nightly builds contain the latest developments and can be found below. It is important to either use the release or nightly for all components.
The Ribasim python package is registered in PyPI and can therefore be installed with pip:
pip install ribasim
For wheel (.whl
) downloads, including nightly builds, see the download section.
After downloading wheels can be installed by referring to the correct path:
pip install path/to/ribasim-*.whl
Parking lot for the sequence diagram explaining the nested allocation and interaction with the main loop
sequenceDiagram
participant boundary
participant basin
participant user
participant allocation_subNetwork
participant allocation_mainNetwork
user->>allocation_subNetwork: demand
par
allocation_subNetwork-->>allocation_mainNetwork: demand inventory at inlets
end
boundary->>allocation_mainNetwork: source availablility
basin->>allocation_mainNetwork: source availablility
allocation_mainNetwork-->>allocation_mainNetwork: allocate to inlets
allocation_mainNetwork->>allocation_subNetwork: allocated
par
allocation_subNetwork-->>allocation_subNetwork: allocate to users
end
allocation_subNetwork->>user: allocated
user->>basin: abstracted
Parking lot
Just to be clear, make sure you keep the mermaid syntax. In Quarto we use this rather than a PNG render, see https://github.com/Deltares/Ribasim/blob/605e5b9b20eea77cd29ab3f39f06f7bfe6933571/docs/core/index.qmd#L15-L39.
No worries, if you go to edit mode in the comment you get the mermaid syntax for both figures. Github does the rendering to a picture
Ribasim 9 versus Ribasim 7 Ribasim 7 is a heuristic water allocation model where prioritized water demands are met from preferential sources such as inflows or surface water reservoirs (i.e. dams). Nodes in the network typically do not have a storage component (except for reservoir nodes or natural lakes). typical timesteps therefore are 10-day, by-monthly or monthly as this allows a drop of water to reach the end of the network within the timestep. Ribasim 7 allows flow direction in one-way only (ie downstream), while demands can be propagated upstream to reservoirs or diversions. Ribasim 7 allows various formulations to compute water demand for agriculture or plublic water supply, while it also offers a reservoir node with hydropower oriented operations. The water distribution is primarily derived by matching source availability with demands given reservoir rules (flood control-target and firm levels) and hedging rules) local flow-based control options for diversions and bifurcations. Ribasim 9 deviates from this paradigm as its water balance is not driven by a demand-allocation matching algorith. Instead it is driven by a numerical scheme that solves the water balance equation for a chain of basins (buckets) with storages which are connected by elements that determine the flow exchange between the basins based on Qh-relations, resistance (i.e. a head difference) or control rules. This numerical scheme chooses its internal timestepping. Compared to Ribasim 7, Ribasim 9 allows much more flexibility to define control rules. Ribasim 9 also deviates on the allocation paradigm as its allocation algorithm primarily is focussed on deciding where water abstractions need to be reduced - in the rule-based simulation - to keep sufficient water in the system for high-prioirity users. Also in terms of water demand, Ribasim 9 deviates from Ribasim 7, as the kernel is given a user/abstraction demand, either via a preprocessed timeseries, or via an online coupling with other models (e.g. unsaturated zone or groundwater models). Ribasim 9 versus D-Hydro
This is my suggestion for the update of the Home page (https://deltares.github.io/Ribasim/)
I like it, I do have some comments:
Notes:
What:
Why the current documentation has a strong developer and technical reference orientation (=good), but lacks a conceptual introduction.
How
[ ] reorganize home page https://deltares.github.io/Ribasim/ into table of contents:
introduction
Conceptualization (physical-control-allocation layer)
Development planning
About the code
Downloads
[ ] add https://deltares.github.io/Ribasim/concepts page. Table of contents:
Water balance in time & space
Control concepts
Equations
Allocation
Respective related tasks: