diff --git a/changelog.html b/changelog.html index 9d73cdf2a..a505b51d3 100644 --- a/changelog.html +++ b/changelog.html @@ -98,7 +98,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/concept/allocation.html b/concept/allocation.html index a27743b09..67e36e48f 100644 --- a/concept/allocation.html +++ b/concept/allocation.html @@ -160,7 +160,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • @@ -574,7 +578,7 @@

    4.4 Example

    The following is an example of an optimization problem for the example shown here:

    -
    +
    Code 
    using Ribasim
@@ -598,25 +602,25 @@ 
    
 
    Min F[(Basin #2, UserDemand #3)]² + F[(Basin #5, UserDemand #6)]²
 Subject to
- flow_conservation[TabulatedRatingCurve #7] : -F[(TabulatedRatingCurve #7, Terminal #8)] + F[(Basin #5, TabulatedRatingCurve #7)] = 0
- flow_conservation[Basin #2] : F[(UserDemand #3, Basin #2)] - F[(Basin #2, UserDemand #3)] - F[(Basin #2, LinearResistance #4)] + F[(LinearResistance #4, Basin #2)] + F[(FlowBoundary #1, Basin #2)] = 0
- flow_conservation[Basin #5] : F[(UserDemand #6, Basin #5)] + F[(LinearResistance #4, Basin #5)] - F[(Basin #5, LinearResistance #4)] - F[(Basin #5, UserDemand #6)] - F[(Basin #5, TabulatedRatingCurve #7)] = 0
- flow_conservation[LinearResistance #4] : F[(Basin #2, LinearResistance #4)] - F[(LinearResistance #4, Basin #2)] - F[(LinearResistance #4, Basin #5)] + F[(Basin #5, LinearResistance #4)] = 0
+ flow_conservation[Basin #5] : -F[(Basin #5, TabulatedRatingCurve #7)] + F[(LinearResistance #4, Basin #5)] - F[(Basin #5, LinearResistance #4)] + F[(UserDemand #6, Basin #5)] - F[(Basin #5, UserDemand #6)] = 0
  flow_conservation[Terminal #8] : F[(TabulatedRatingCurve #7, Terminal #8)] = 0
+ flow_conservation[LinearResistance #4] : -F[(LinearResistance #4, Basin #5)] + F[(Basin #5, LinearResistance #4)] + F[(Basin #2, LinearResistance #4)] - F[(LinearResistance #4, Basin #2)] = 0
+ flow_conservation[Basin #2] : F[(FlowBoundary #1, Basin #2)] - F[(Basin #2, UserDemand #3)] + F[(UserDemand #3, Basin #2)] - F[(Basin #2, LinearResistance #4)] + F[(LinearResistance #4, Basin #2)] = 0
+ flow_conservation[TabulatedRatingCurve #7] : F[(Basin #5, TabulatedRatingCurve #7)] - F[(TabulatedRatingCurve #7, Terminal #8)] = 0
  source[(FlowBoundary #1, Basin #2)] : F[(FlowBoundary #1, Basin #2)] ≤ 172800
  source_user[UserDemand #6] : F[(UserDemand #6, Basin #5)] ≤ 0
  source_user[UserDemand #3] : F[(UserDemand #3, Basin #2)] ≤ 0
+ F[(FlowBoundary #1, Basin #2)] ≥ 0
+ F[(Basin #5, TabulatedRatingCurve #7)] ≥ 0
+ F[(LinearResistance #4, Basin #5)] ≥ 0
+ F[(Basin #5, LinearResistance #4)] ≥ 0
  F[(UserDemand #6, Basin #5)] ≥ 0
+ F[(Basin #2, UserDemand #3)] ≥ 0
  F[(TabulatedRatingCurve #7, Terminal #8)] ≥ 0
+ F[(Basin #5, UserDemand #6)] ≥ 0
  F[(UserDemand #3, Basin #2)] ≥ 0
- F[(Basin #2, UserDemand #3)] ≥ 0
  F[(Basin #2, LinearResistance #4)] ≥ 0
  F[(LinearResistance #4, Basin #2)] ≥ 0
- F[(FlowBoundary #1, Basin #2)] ≥ 0
- F[(LinearResistance #4, Basin #5)] ≥ 0
- F[(Basin #5, LinearResistance #4)] ≥ 0
- F[(Basin #5, UserDemand #6)] ≥ 0
- F[(Basin #5, TabulatedRatingCurve #7)] ≥ 0
    diff --git a/concept/concept.html b/concept/concept.html index c6920a494..837b1f299 100644 --- a/concept/concept.html +++ b/concept/concept.html @@ -120,7 +120,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/concept/core.html b/concept/core.html index e538e7f24..fe0c014ca 100644 --- a/concept/core.html +++ b/concept/core.html @@ -101,7 +101,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/concept/equations.html b/concept/equations.html index d514fe12c..d74aa2163 100644 --- a/concept/equations.html +++ b/concept/equations.html @@ -147,7 +147,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/concept/modelconcept.html b/concept/modelconcept.html index 7f6c70b43..40b5e1ab6 100644 --- a/concept/modelconcept.html +++ b/concept/modelconcept.html @@ -150,7 +150,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/concept/numerics.html b/concept/numerics.html index 4b280ffa5..3ba6b8de4 100644 --- a/concept/numerics.html +++ b/concept/numerics.html @@ -127,7 +127,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/addnode.html b/dev/addnode.html index a6d802609..fd4ddbe47 100644 --- a/dev/addnode.html +++ b/dev/addnode.html @@ -161,7 +161,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/allocation.html b/dev/allocation.html index 53cdb7755..154973a29 100644 --- a/dev/allocation.html +++ b/dev/allocation.html @@ -135,7 +135,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/benchmark.html b/dev/benchmark.html index 9c4534bc9..bb61ce684 100644 --- a/dev/benchmark.html +++ b/dev/benchmark.html @@ -98,7 +98,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/bmi.html b/dev/bmi.html index 0178b343a..17372636d 100644 --- a/dev/bmi.html +++ b/dev/bmi.html @@ -127,7 +127,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/ci.html b/dev/ci.html index 8d0f45a96..6a9fed6a2 100644 --- a/dev/ci.html +++ b/dev/ci.html @@ -101,7 +101,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/core.html b/dev/core.html index c34a286b7..c5b61bd24 100644 --- a/dev/core.html +++ b/dev/core.html @@ -132,7 +132,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/index.html b/dev/index.html index 3f324b7fb..d309c6e2a 100644 --- a/dev/index.html +++ b/dev/index.html @@ -131,7 +131,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/python.html b/dev/python.html index 0f912ba20..2ebfa9366 100644 --- a/dev/python.html +++ b/dev/python.html @@ -132,7 +132,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/qgis.html b/dev/qgis.html index d20fb7d09..97817ccad 100644 --- a/dev/qgis.html +++ b/dev/qgis.html @@ -98,7 +98,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/qgis_test_plan.html b/dev/qgis_test_plan.html index 7fa996c54..cbcfbb817 100644 --- a/dev/qgis_test_plan.html +++ b/dev/qgis_test_plan.html @@ -97,7 +97,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/dev/release.html b/dev/release.html index d5c1a6b6f..ea068a3c7 100644 --- a/dev/release.html +++ b/dev/release.html @@ -132,7 +132,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • diff --git a/guide/coupling.html b/guide/coupling.html index 552ff0216..9989d6153 100644 --- a/guide/coupling.html +++ b/guide/coupling.html @@ -101,7 +101,11 @@ Overview
  • - + +Tutorials +
    • +
  • + How-to guides
  • @@ -148,12 +152,6 @@
    -
    model.edge.add(model.level_boundary[1], model.linear_resistance[2])
-model.edge.add(model.linear_resistance[2], model.basin[3])
-model.edge.add(model.basin[3], model.outlet[4])
-model.edge.add(model.basin[3], model.outlet[5])
-model.edge.add(model.outlet[4], model.terminal[6])
-model.edge.add(model.outlet[5], model.terminal[7])
-
-# Define which node is controlled by each continuous control node
-model.edge.add(model.continuous_control[8], model.outlet[4])
-model.edge.add(model.continuous_control[9], model.outlet[5])
    +
    model.edge.add(model.level_boundary[1], model.linear_resistance[2])
+model.edge.add(model.linear_resistance[2], model.basin[3])
+model.edge.add(model.basin[3], model.outlet[4])
+model.edge.add(model.basin[3], model.outlet[5])
+model.edge.add(model.outlet[4], model.terminal[6])
+model.edge.add(model.outlet[5], model.terminal[7])
+
+# Define which node is controlled by each continuous control node
+model.edge.add(model.continuous_control[8], model.outlet[4])
+model.edge.add(model.continuous_control[9], model.outlet[5])

    Let’s take a look at the model:

    -
    model.plot()
    +
    model.plot()
    /home/runner/work/Ribasim/Ribasim/python/ribasim/ribasim/model.py:484: FutureWarning:
 
@@ -1593,35 +1583,35 @@ 
    7 Model with cont
 
    With this setup we want to split the flow coming into the basin into a 60% - 40% ratio.
    
 
    Write the model to a TOML and GeoPackage:
    
 
    
-
    toml_path = datadir / "outlet_continuous_control/ribasim.toml"
-model.write(toml_path)
    
+
    toml_path = datadir / "outlet_continuous_control/ribasim.toml"
+model.write(toml_path)
    
 
    
 
    PosixPath('data/outlet_continuous_control/ribasim.toml')
    
 
    
 
    
 
    Now run the model (for running instructions see here). After running the model, read back the results:
    
 
    
-
    df_flow = pd.read_feather(datadir / "outlet_continuous_control/results/flow.arrow")
-fig, ax = plt.subplots()
-
-
-def plot_edge_flow(from_node_type, from_node_id, to_node_type, to_node_id):
-    df_flow_filtered = df_flow[
-        (df_flow["from_node_id"] == from_node_id)
-        & (df_flow["to_node_id"] == to_node_id)
-    ]
-    df_flow_filtered.plot(
-        x="time",
-        y="flow_rate",
-        ax=ax,
-        label=f"{from_node_type} #{from_node_id} → {to_node_type} #{to_node_id}",
-    )
-
-
-plot_edge_flow("LinearResistance", 1, "Basin", 1)
-plot_edge_flow("Basin", 1, "Outlet", 1)
-plot_edge_flow("Basin", 1, "Outlet", 2)
-ax.set_ylabel("flow [m³s⁻¹]");
    
+
    df_flow = pd.read_feather(datadir / "outlet_continuous_control/results/flow.arrow")
+fig, ax = plt.subplots()
+
+
+def plot_edge_flow(from_node_type, from_node_id, to_node_type, to_node_id):
+    df_flow_filtered = df_flow[
+        (df_flow["from_node_id"] == from_node_id)
+        & (df_flow["to_node_id"] == to_node_id)
+    ]
+    df_flow_filtered.plot(
+        x="time",
+        y="flow_rate",
+        ax=ax,
+        label=f"{from_node_type} #{from_node_id} → {to_node_type} #{to_node_id}",
+    )
+
+
+plot_edge_flow("LinearResistance", 1, "Basin", 1)
+plot_edge_flow("Basin", 1, "Outlet", 1)
+plot_edge_flow("Basin", 1, "Outlet", 2)
+ax.set_ylabel("flow [m³s⁻¹]");
    
 
    
 
    
 
    
@@ -2057,9 +2047,6 @@ 
    7 Model with cont
  • - + +Tutorials +
    • +
  • + How-to guides
  • @@ -145,12 +149,6 @@
    • - - Quick start guide -
      -
      • -
    • -
      Examples
      diff --git a/guide/quickstart.html b/guide/quickstart.html deleted file mode 100644 index 574cc2ef1..000000000 --- a/guide/quickstart.html +++ /dev/null @@ -1,1594 +0,0 @@ - - - - - - - - - -Quick start guide – Ribasim - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      -
      - - -
      - -
      - - -
      - - - -
      - -
      -
      -

      Quick start guide

      -
      - - - -
      - - - - -
      - - - -
      - - -
      -
      -

      -
      -
      -
      -

      1 Introduction

      -

      Welcome to Ribasim! This guide will help you get started with the basics of installing and using Ribasim for river basin simulation. In this guide, the schematization of models will be implemented in Python using the Ribasim Python package. The Ribasim package (named ribasim) simplifies the process of building, updating, and analyzing Ribasim model programmatically. It also allows for the creation of entire models from base data, ensuring that your model setup is fully reproducible. This package is available on PyPI.

      -
      -

      1.1 Learning objectives

      -

      In this guide, we will focus on a fictional river basin called Crystal, which will serve as our case study. The guide is divided into different modules, each covering various scenarios. These include simulating natural flow, implementing reservoirs, and observing the impact of other structures. While not all node types and possibilities will be demonstrated, the focus will be on the most commonly used and significant situations. By the end of the guide, users will be able to:

      -
        -
      • Set Up a Basic Ribasim Model: Understand how to create a new model for a river basin using the Ribasim Python package.
        • -
      • Evaluate the Impact of Demands: Introduce water demand (such as irrigation) and assess their effects on the river basin.
        • -
      • Modify and Update Models: Learn how to update existing models with new data and changes.
        • -
      • Analyze Simulation Results: Use built-in tools to analyze and interpret the results of your simulations.
        • -
      -
      -
      -
      -

      2 Starting RIBASIM

      -
      -

      2.1 System requirements

      -

      Before installing Ribasim, ensure your system meets the following requirements:

      -
        -
      • Operating System: Windows 10 or later, or Linux (latest distributions)
        • -
      • Processor: x86-64 (64-bit)
        • -
      • RAM: 4 GB minimum, 8 GB recommended
        • -
      • Hard Drive: 1GB of free space
        • -
      -
      -
      -

      2.2 Installation

      -
        -
      1. Download Ribasim: Obtain the Ribasim 9 installation package from the official website: Ribasim - Installation under chapter ‘2 Download’:
        2. -
      -
        -
      • For Windows download: ribasim_windows.zip
        • -
      • For Linux: ribasim_linux.zip
        • -
      -
        -
      1. Unpack the .zip archive: It is important to keep the contents of the zip file organized within a single directory. The Ribasim executable can be found in the directory;
        2. -
      2. Check installation: To check whether the installation was performed successfully, in cmd go to the executable path and type ribasim with no arguments in the command line. This will give the following message:
        3. -
      -
      error: the following required arguments were not provided:
- <TOML_PATH>
-Usage: ribasim <TOML_PATH>
-For more information, try '--help'.
      -
        -
      1. We use a command line interface (CLI) to install our Ribasim packages. To install Ribasim open PowerShell or Windows command prompt and write:
        2. -
      -
      conda install ribasim
      -

      or

      -
      mamba install ribasim
      -
      -
      -

      2.3 Data preparation

      -

      Download the Crystal_Basin.zip file from the website. Extract Crystal_Basin.zip and place it in the same directory as your Ribasim installation. This folder includes:

      -
        -
      • QuickStartGuide.pdf
        • -
      • data: Contains data inputs such as time series needed for running the case. Additionally, your Python model (.py) and eventually the output files will also be saved in this folder.
        • -
      -
      -
      -
      -

      3 Modual 1 - Crystal River Basin

      -

      We will examine a straightforward example of the Crystal River Basin, which includes a main river and a single tributary flowing into the sea (see Figure 1). An average discharge of \(44.45 \text{ m}^3/\text{s}\) is measured at the confluence. In this module, the basin is free of any activities, allowing the model to simulate the natural flow. The next step is to include a demand (irrigation) that taps from a canal out of the main river.

      -
      -
      -
      - -
      -
      -Figure 1: Crystal Basin based on natural flow -
      -
      -
      -

      After this module the user will be able to:

      -
        -
      • Build a river basin model from scratch
        • -
      • Understand the functionality of the ‘demand’ and ‘basin’ nodes
        • -
      • Generate overview of results
        • -
      • Evaluate the simulation results
        • -
      -
      -

      3.1 Modual 1.1 - Natural Flow

      -
      -

      3.1.1 Step 1: Import packages

      -

      Before building the model we need to import some modules. Open your python platform (Spyder, VS code etc.), created a new file and name it Crystal_1.1 and save it into your model folder Crystal_Basin. Import the following modules in python:

      -
      import shutil
-from pathlib import Path
-import pathlib
-import matplotlib.pyplot as plt
-import numpy as np
-import pandas as pd
-from ribasim import Allocation, Model, Node # The main library used for river basin modeling.
-from ribasim.nodes import (
-    flow_boundary,
-    basin,
-    tabulated_rating_curve,
-    terminal
-)
-from shapely.geometry import Point
-import subprocess  # For running the model
      -
      -
      -

      3.1.2 Step 2: Setup paths and model configuration

      -

      Reference the paths of the Ribasim installation and model directory and define the time period (2022-01-01 until 2023-01-01) for the model simulation:

      -
      base_dir = Path("c:/Ribasim")
-model_dir = base_dir / "Crystal_Basin"
-data_path = model_dir / "data/input/ACTINFLW.csv"
-
-starttime = "2022-01-01"
-endtime = "2023-01-01"
-model = Model(
-    starttime=starttime,
-    endtime=endtime,
-    crs="EPSG:4326",
-)
      -
      -
      -

      3.1.3 Step 3: Flow boundary nodes

      -

      Crystal Basin consists of two inflow points, the tributary and the main Crystal river, we will call them Minor and Main respectively. In order to define the time series flow rate (\(\text{m}^3/\text{s}\)) we read the discharge data from ACTINFLW.csv. This inflow data goes monthly from 2014 to 2023. However, for this exercise actual runtime is already defined in step 2.

      -
      data = pd.read_csv(data_path, sep=";")
-data['sum']= data['minor']+data['main']
-#Average inflow and max. of the whole summed inflow data timeseries
-#From 2014 - 2023
-print('Average inflowQ m3/s:',data['sum'].mean())
-print('Average inflowQ m3/s:',data['sum'].max)
-
-model.flow_boundary.add(
-    Node(1, Point(0.0, 0.0), name='Main'),
-    [flow_boundary.Time(time=data.time, flow_rate=data.main,
-    )]
-)
-
-model.flow_boundary.add(
-    Node(2, Point(-3.0, 0.0), name='Minor'),
-    [flow_boundary.Time(time=data.time, flow_rate=data.minor,
-    )]
-)
      -
      -
      -

      3.1.4 Step 4: Basin node (confluence)

      -

      To schematize the confluence from the tributary we will use the Basin node. The node by itself portrays as a bucket with a certain volume of water and can be used for different purposes, such as a reservoir, a lake or in this case a confluence. Figure 2 visualizes a cross section of the confluence point in our model.

      -
      -
      -
      - -
      -
      -Figure 2: Basin node concept for the confluence -
      -
      -
      -

      Table 1 shows the input data for the basin node profile.

      -
      -
      -
      -Table 1: Profile data for the basin node -
      -
      - - - - - - - - - - - - - - - - - -
      Area [\(\text{m}^2\)]Level [\(\text{m}\)]
      \(672000.0\)\(0.0\)
      \(5600000.0\)\(6.0\)
      -
      -
      -
      -

      To specify the basin profile, the following code is used:

      -
      model.basin.add(
-    Node(3, Point(-1.5, -1), name='Conf'),
-    [basin.Profile(area=[672000, 5600000], level=[0, 6]),
-     basin.State(level=[4]),
-     basin.Time(time=[starttime, endtime]),
-    ],
-)
      -
      -
      -

      3.1.5 Step 5: Tabulated rating curve

      -

      In the previous step we implemented a Basin node that functions as a confluence. Conceptually, the basin acts like a bucket of water, accumulating inflows and then releasing them. However, the model does not run if the basin is directly connected to the terminal node. This is because, for the model to function properly, we need to define a relation between the water level (\(h\)) in the basin and the outflow (\(Q\)) from the basin. This relation is defined by the Tabulated Rating Curve and thus serves as a critical component. This setup mimics the behavior of a gate or spillway, allowing us to model how varying water levels influence flow rates at the confluence.

      -

      As the two inflows come together at the confluence, we expect, as mentioned and coded before, a discharge average of \(44.45 \text{ m}^3/\text{s}\). It is therefore expected that the confluence basin reaches a level where the outflow is equal to the inflow via the rating curve. Only then is the confluence basin in equilibrium. To ensure that inflow equals outflow (IN=OUT) and keeping in mind the maximum depth of the river is \(6 \text{ m}\), the \(Q(h)\) relationship in Table 2 will be used as input.

      -
      -
      -
      -Table 2: Input data for the Tabulated Rating Curve -
      -
      - ---- - - - - - - - - - - - - - - - - - - - - -
      Water Level (\(h\)) [\(\text{m}\)]Outflow (\(Q\)) [\(\text{m}^3/\text{s}\)]
      \(0.0\)\(0.0\)
      \(2.0\)\(50.0\)
      \(5.0\)\(200.0\)
      -
      -
      -
      -

      In Ribasim, the \(Q(h)\) relation is a linear function, so the points in between will be linearly interpolated. Figure 3 illustrates the visual process and shows a progressive increase in discharge with rising water levels. In this case this means:

      -
        -
      • At level \(0.0\): No discharge occurs. This represents a condition where the water level is too low for any flow to be discharged.
        • -
      • At level \(2.0\): Discharge is max. \(50.0 \text{ m}^3/\text{s}\). This is a bit above the average discharge rate, corresponding to the water level where normal flow conditions are established.
        • -
      • At level \(5.0\): Discharge rate reaches \(200.0 \text{ m}^3/\text{s}\). This discharge rate occurs at the water level during wet periods, indicating higher flow capacity.
        • -
      -
      -
      -
      - -
      -
      -Figure 3: Discharge at corresponding water levels -
      -
      -
      -

      Taking this into account, add the Tabulated Rating Curve as follows:

      -
      model.tabulated_rating_curve.add(
-    Node(4, Point(-1.5, -1.5), name='MainConf'),
-    [tabulated_rating_curve.Static(
-        level=[0.0, 2, 5],
-        flow_rate=[0.0, 50, 200],
-        )
-    ]
-)
      -
      -
      -

      3.1.6 Step 6: Terminal node

      -

      Finally all the water will discharge into the ocean. Schematize this with the terminal node as it portrays the end point of the model. Besides the node number/name and location, no further input is needed.

      -
      model.terminal.add(Node(5, Point(-1.5, -3.0), name="Terminal"))
      -
      -
      -

      3.1.7 Step 7: Defining edges

      -

      Implement the connections (edges) between the nodes, in the following order:

      -
        -
      1. Flow boundaries to the basin;
        2. -
      2. Basin to the rating curve;
        3. -
      3. Tabulated rating curve to the terminal.
        4. -
      -
      model.edge.add(model.flow_boundary[1], model.basin[3])
-model.edge.add(model.flow_boundary[2], model.basin[3])
-model.edge.add(model.basin[3], model.tabulated_rating_curve[4])
-model.edge.add(model.tabulated_rating_curve[4], model.terminal[5])
      -
      -
      -

      3.1.8 Step 8: Visualization and model execution

      -

      Plot the schematization, write the model configuration to the TOML file. Name the output file Crystal_1.1/ribasim.toml:

      -
      model.plot()
-
-toml_path = model_dir/ "Crystal_1.1/ribasim.toml"
-model.write(toml_path)
-rib_path = base_dir / "ribasim_windows/ribasim.exe"
      -

      The schematization should look like Figure 4.

      -
      -
      -
      - -
      -
      -Figure 4: Schematization of the Crystal basin 1.1 -
      -
      -
      -

      After writing model.write a subfolder Crystal_1.1 is created, which contains the model input data and configuration:

      -
        -
      • ribasim.toml: The model configuration
        • -
      • database.gpkg: A geopackage containing the shapes of your schematization and the input data of the nodes used.
        • -
      -

      Now run the model:

      -
      subprocess.run([rib_path, toml_path], check=True)
      -
      -
      -

      3.1.9 Step 9: Post-processing results

      -

      Read the arrow files and plot the simulated flows from different edges and the levels and storages at our confluence point:

      -
      df_basin = pd.read_feather(model_dir / "Crystal_1.1/results/basin.arrow")
-
-# Create pivot tables and plot for basin data
-df_basin_wide = df_basin.pivot_table(
-index="time", columns="node_id", values=["storage", "level"]
-)
-
-# Skip the first timestep as it’s the initialization step
-df_basin_wide = df_basin_wide.iloc[1:]
-
-# Plot level and storage on the same graph with dual y-axes
-fig, ax1 = plt.subplots(figsize=(12, 6))
-
-# Plot level on the primary y-axis
-color = 'b'
-ax1.set_xlabel('Time')
-ax1.set_ylabel('Level [m]', color=color)
-ax1.plot(df_basin_wide.index, df_basin_wide["level"], color=color)
-ax1.tick_params(axis='y', labelcolor=color)
-
-# Create a secondary y-axis for storage
-ax2 = ax1.twinx()
-color = 'r'
-ax2.set_ylabel('Storage [m³]', color='r')
-ax2.plot(df_basin_wide.index, df_basin_wide["storage"],linestyle='--', color=color)
-ax2.tick_params(axis='y', labelcolor=color)
-
-fig.tight_layout()  # Adjust layout to fit labels
-plt.title('Basin Level and Storage Over Time')
-plt.show()
-
-
-# Plot flow data
-# Read the data from feather format
-df_flow = pd.read_feather(model_dir / "Crystal_1.1/results/flow.arrow")
-# Create 'edge' and 'flow_m3d' columns
-df_flow["edge"] = list(zip(df_flow.from_node_id, df_flow.to_node_id))
-
-# Create a pivot table
-pivot_flow = df_flow.pivot_table(index="time", columns="edge", values="flow_rate")
-
-# Skip the first timestep
-pivot_flow = pivot_flow.iloc[1:]
-
-line_styles = ['-', '--', '-', '-.']
-num_styles = len(line_styles)
-
-fig, ax = plt.subplots(figsize=(12, 6))
-for i, column in enumerate(pivot_flow.columns):
-    pivot_flow[column].plot(ax=ax, linestyle=line_styles[i % num_styles],linewidth=1.5, alpha=0.8)
-
-# Set labels and title
-ax.set_xlabel('Time')
-ax.set_ylabel('Flow [m³/s]')
-ax.legend(bbox_to_anchor=(1.15, 1), title="Edge")
-plt.title('Flow Over Time')
-plt.grid(True)
-plt.show()
      -

      Figure 5 shows the storage and levels in the basin node.

      -

      In this configuration the basin node is designed to ensure that inflow equals outflow, effectively simulating a controlled junction where water flow is managed rather than stored. To accurately represent the relationship between water levels and discharge rates at this confluence, a rating curve node is implemented. This setup mimics the behavior of a gate or spillway, allowing us to model how varying water levels influence flow rates at the confluence. Since the basin node is functioning as a confluence rather than a storage reservoir, the simulated water levels and storage trends will closely follow the inflow patterns. This is because there is no net change in storage; all incoming water is balanced by outgoing flow.

      -
      -
      -
      - -
      -
      -Figure 5: Simulated basin level and storage -
      -
      -
      -

      Figure 6 shows the discharges in \(\text{m}^3/\text{s}\) on each edge. Edge (3,4) represents the flow from the confluence to the tabulated rating curve and edge (4,5) represents the flow from the tabulated rating curve to the terminal. Both show the same discharge over time. Which is expected in a natural flow environment, as what is coming into the confluence must come out.

      -
      -
      -
      - -
      -
      -Figure 6: Simulated flows on each edge -
      -
      -
      -
      -
      -
      -

      3.2 Modual 1.2 - Irrigation demand

      -

      Let us modify the environment to include agricultural activities within the basin, which necessitate irrigation. In a conventional irrigation setup, some water is diverted from the Main River through a canal, with a portion of it eventually returning to the main river (see Figure 7).

      -
      -
      -
      - -
      -
      -Figure 7: Crystal basin with irrigation -
      -
      -
      -

      For this update schematization, we need to incorporate three additional nodes:

      -
        -
      • Basin: Represents a cross-sectional point where water is diverted.
        • -
      • User Demand: Represents the irrigation demand.
        • -
      • Tabulates Rating Curve: Defines the remaining water flow from the main river at the diversion point.
        • -
      -
      -

      3.2.1 Step 1: Setup the model & adjust Import Packages

      -

      Copy and paste the python script Crystal_1.1 and rename it Crystal_1.2. De import modules remain the same, except a demand needs to be added and if you want to have a more interactive plot then importing plotly can be useful.

      -
      import shutilfrom
-import pathlib
-import matplotlib.pyplot as plt
-import numpy as np
-import pandas as pd
-from ribasim import Allocation, Model, Node # The main library used for river basin modeling.
-from ribasim.nodes import (
-    flow_boundary,
-    basin,
-    tabulated_rating_curve,
-    user_demand,
-    terminal
-)
-from shapely.geometry import Point
-import subprocess  # For running the model
-import plotly.express as px
      -
      -
      -

      3.2.2 Step 2: Add a second Basin node

      -

      Schematically we are dealing with two basins. To keep the order of flow from upstream to downstream it is recommended to adjust the node_id numbers accordingly. In this case node_id = 3 will be node_id = 4. Basin 3 will portray as the point in the river where the diversion takes place, getting the name Div. Its profile area at this intersection is slightly smaller than at the confluence.

      -
      model.basin.add(
-    Node(3, Point(-0.75, -0.5), name='Div'),
-    [basin.Profile(area=[500000, 5000000], level=[0, 6]),
-     basin.State(level=[3]),
-     basin.Time(time=[starttime, endtime]),
-    ],
-)
-
-model.basin.add(
-    Node(4, Point(-1.5, -1), name='Conf'),
-    [basin.Profile(area=[672000, 5600000], level=[0, 6]),
-     basin.State(level=[4]),
-     basin.Time(time=[starttime, endtime]),
-    ],
-)
      -
      -
      -

      3.2.3 Step 3: Add the irrigation demand

      -

      A big farm company needs to apply irrigation to its field starting from April to September. The irrigated field is \(> 17000 \text{ ha}\) and requires around \(5 \text{ mm/day}\). In this case the farm company diverts from the main river an average flow rate of \(10 \text{ m}^3/\text{s}\) and \(12 \text{ m}^3/\text{s}\) during spring and summer, respectively. Start of irrigation takes place on the 1st of April until the end of August. The farmer taps water through a canal (demand).

      -

      For now, let’s assume the return flow remains \(0.0\) (return_factor). Meaning all the supplied water to fulfill the demand is consumed and does not return back to the river. The user demand node interpolates the demand values. Thus the following code needs to be implemented:

      -
      model.user_demand.add(
-    Node(6, Point(-1.5, 1.0), name='IrrA'),
-    [user_demand.Time(
-        demand=[0.0, 0.0, 10, 12, 12, 0.0],
-        return_factor=0,
-        min_level=0,
-        priority=1,
-        time=[starttime, "2022-03-31", "2022-04-01", "2022-07-01", "2022-09-30", "2022-10-01"]
-        )
-    ]
-)
      -
      -
      -

      3.2.4 Step 4: Add a tabulated rating curve

      -

      The second Tabulated Rating Curve node will simulate the rest of the water that is left after diverting a part from the main river to the farm field. The rest of the water will flow naturally towards the confluence:

      -
      model.tabulated_rating_curve.add(
-    Node(7, Point(-1.125, -0.75), name='MainDiv'),
-    [tabulated_rating_curve.Static(
-        level=[0.0, 1.5, 5],
-        flow_rate=[0.0, 45, 200],
-        )
-    ]
-)
      -

      It is up to the user to renumber the ID’s of the nodes. Applying the ID number based on the order of the nodes from up- to downstream keeps it more organized, but not necessary.

      -
      -
      -

      3.2.5 Step 5: Adjust the terminal node id and edges

      -

      Adjust the terminal node id. Since we added more nodes we have more edges. Add and adjust the edges:

      -
      model.terminal.add(Node(8, Point(-1.5, -3.0), name="Terminal"))
-
-model.edge.add(model.flow_boundary[1], model.basin[3])
-model.edge.add(model.flow_boundary[2], model.basin[4])
-model.edge.add(model.basin[3], model.user_demand[6])
-model.edge.add(model.user_demand[6], model.basin[4])
-model.edge.add(model.basin[3], model.tabulated_rating_curve[7])
-model.edge.add(model.tabulated_rating_curve[7], model.basin[4])
-model.edge.add(model.basin[4], model.tabulated_rating_curve[5])
-model.edge.add(model.tabulated_rating_curve[5], model.terminal[8])
      -
      -
      -

      3.2.6 Step 6: Plot model and run

      -

      Plot the schematization and run the model. This time the new outputs should be written in a new folder called Crystal_1.2:

      -
      model.plot()
-
-toml_path = model_dir/ "Crystal_1.2/ribasim.toml"
-model.write(toml_path)
-rib_path = base_dir / "ribasim_windows/ribasim.exe"
-
-subprocess.run([rib_path, toml_path], check=True)
      -

      The schematization should look like Figure 8.

      -
      -
      -
      - -
      -
      -Figure 8: Schematization of the Crystal basin with irrigation -
      -
      -
      -
      -
      -

      3.2.7 Step 7: Name the edges and basins

      -

      The names of each nodes are defined and saved in the geopackage. However, in the dataframe this needs to be added by creating a dictionary and map it within the dataframe.

      -
      # Dictionary mapping node_ids to names
-edge_names = {
-    (1,3): 'Main',
-    (2,4): 'Minor',
-    (3,6): 'IrrA Demand',
-    (6,4): 'IrrA Drain',
-    (3,7): 'Div2Main',
-    (7,4): 'Main2Conf',
-    (4,5): 'Conf2TRC',
-    (5,8): 'TRC2Term',
-}
-
-# Dictionary mapping basins (node_ids) to names
-node_names = {
-    3: 'Div',
-    4: 'Conf',
-}
      -
      -
      -

      3.2.8 Step 8: Plot and compare the basin results

      -

      Plot the simulated levels and storages at the diverted section (basin 3) and at the confluence (basin 4).

      -
      
-df_basin_div = df_basin_wide.xs('Div', axis=1, level=1, drop_level=False)
-df_basin_conf = df_basin_wide.xs('Conf', axis=1, level=1, drop_level=False)
-
-def plot_basin_data(ax, ax_twin, df_basin, level_color='b', storage_color='r', title='Basin'):
-    # Plot level data
-    for idx, column in enumerate(df_basin["level"].columns):
-        ax.plot(df_basin.index, df_basin["level"][column],
-                linestyle='-', color=level_color,
-                label=f'Level - {column}')
-
-    # Plot storage data
-    for idx, column in enumerate(df_basin["storage"].columns):
-        ax_twin.plot(df_basin.index, df_basin["storage"][column],
-                     linestyle='--', color=storage_color,
-                     label=f'Storage - {column}')
-
-    ax.set_ylabel('Level [m]', color=level_color)
-    ax_twin.set_ylabel('Storage [m³]', color=storage_color)
-
-    ax.tick_params(axis='y', labelcolor=level_color)
-    ax_twin.tick_params(axis='y', labelcolor=storage_color)
-
-    ax.set_title(title)
-
-    # Combine legends from both axes
-    lines, labels = ax.get_legend_handles_labels()
-    lines_twin, labels_twin = ax_twin.get_legend_handles_labels()
-    ax.legend(lines + lines_twin, labels + labels_twin, loc='upper left')
-
-# Create subplots
-fig, (ax1, ax3) = plt.subplots(2, 1, figsize=(12, 12), sharex=True)
-
-# Plot Div basin data
-ax2 = ax1.twinx()  # Secondary y-axis for storage
-plot_basin_data(ax1, ax2, df_basin_div, title='Div Basin Level and Storage over Time')
-
-# Plot Conf basin data
-ax4 = ax3.twinx()  # Secondary y-axis for storage
-plot_basin_data(ax3, ax4, df_basin_conf, title='Conf Basin Level and Storage over Time')
-
-# Common X label
-ax3.set_xlabel('Time')
-
-fig.tight_layout()  # Adjust layout to fit labels
-plt.show()
      -

      Figure 9 illustrates the water levels and storage capacities for each basin. At the diverted section, where the profile is narrower than at the confluence, we anticipate lower storage and water levels compared to the confluence section.

      -

      When compared to the natural flow conditions, where no water is abstracted for irrigation (See Crystal 1.1), there is a noticeable decrease in both storage and water levels at the confluence downstream. This reduction is attributed to the irrigation demand upstream with no return flow, which decreases the amount of available water in the main river, resulting in lower water levels at the confluence.

      -
      -
      -
      - -
      -
      -Figure 9: Simulated basin levels and storages -
      -
      -
      -
      -
      -

      3.2.9 Step 9: Plot and compare the flow results

      -

      Plot the flow results in an interactive plotting tool.

      -
      df_flow = pd.read_feather(model_dir / "Crystal_1.2/results/flow.arrow")
-df_flow["edge"] = list(zip(df_flow.from_node_id, df_flow.to_node_id))
-df_flow["name"] = df_flow["edge"].map(edge_names)
-
-# Plot the flow data, interactive plot with Plotly
-pivot_flow = df_flow.pivot_table(index="time", columns="name", values="flow_rate").reset_index()
-fig = px.line(pivot_flow, x="time", y=pivot_flow.columns[1:], title="Flow Over Time [m3/s]")
-
-fig.update_layout(legend_title_text='Edge')
-fig.write_html(model_dir/ "Crystal_1.2/plot_edges.html")
-fig.show()
      -

      The plot will be saved as an HTML file, which can be viewed by dragging the file into an internet browser (Figure 10).

      -
      -
      -
      - -
      -
      -Figure 10: Simulated flows of each edge -
      -
      -
      -

      When selecting only the flow demanded by the User Demand node, or in other words the supply for irrigation increases at times when it is required (Figure 11) and the return flow remains zero, as the assumption defined before was that there is no drain.

      -
      -
      -
      - -
      -
      -Figure 11: Supplied irrigation and return flow -
      -
      -
      -

      Figure 12 shows the flow to the ocean (Terminal). Compared to Crystal 1.1 the flow has decreased during the irrigated period. Indicating the impact of irrigation without any drain.

      -
      -
      -
      - -
      -
      -Figure 12: Simulated flow to Terminal -
      -
      -
      -
      -
      -
      -
      -

      4 Modual 2 – Reservoirs and Public Water Supply

      -

      Due to the increase of population and climate change Crystal city has implemented a reservoir upstream to store water for domestic use (See Figure 13). The reservoir is to help ensure a reliable supply during dry periods. In this module, the user will update the model to incorporate the reservoir’s impact on the whole Crystal Basin.

      -
      -
      -
      - -
      -
      -Figure 13: Crystal basin with demands and a reservoir -
      -
      -
      -
      -

      4.1 Modual 2.1 – Reservoir

      -
      -

      4.1.1 Step 1: Add a basin

      -

      This time the basin 3 will function as a reservoir instead of a diversion, meaning it’s storage and levels will play an important role for the users (the city and the farmer). The reservoir has a max. area of \(32.3 \text{ km}^2\) and a max. depth of \(7 \text{ m}\). The profile of basin 3 should change to:

      -
      model.basin.add(
-    Node(3, Point(-0.75, -0.5), name='Rsv'),
-    [basin.Profile(area=[20000000, 32300000], level=[0, 7]),
-     basin.State(level=[3.5]),
-     basin.Time(time=[starttime, endtime]),
-    ],
-)
      -
      -
      -

      4.1.2 Step 2: Adjust the code

      -

      Adjust the naming of the basin in the dictionary mapping and the saving file should be Crystal_2.1 instead of *_1.2.

      -
      toml_path = model_dir/ "Crystal_2.1/ribasim.toml"
-model.write(toml_path)
-rib_path = base_dir / "ribasim_windows/ribasim.exe"
      -
      # Dictionary mapping node_ids to names
-edge_names = {
-    (1,3): 'Main',
-    (2,4): 'Minor',
-    (3,6): 'IrrA Demand',
-    (6,4): 'IrrA Drain',
-    (3,7): 'Rsv2Main',
-    (7,4): 'Main2Conf',
-    (4,5): 'Conf2TRC',
-    (5,8): 'TRC2Term',
-}
-
-# Dictionary mapping basins (node_ids) to names
-node_names = {
-    3: 'Rsv',
-    4: 'Conf',
-}
-
-df_basin = pd.read_feather(model_dir / "Crystal_2.1/results/basin.arrow")
      -
      # Create pivot tables and plot for basin data
-df_basin_rsv = df_basin_wide.xs('Rsv', axis=1, level=1, drop_level=False)
-df_basin_conf = df_basin_wide.xs('Conf', axis=1, level=1, drop_level=False)
      -
      # Plot Rsv basin data
-ax2 = ax1.twinx()  # Secondary y-axis for storage
-plot_basin_data(ax1, ax2, df_basin_rsv, title='Reservoir Level and Storage Over Time')
      -
      # Sample data loading and preparation
-df_flow = pd.read_feather(model_dir / "Crystal_2.1/results/flow.arrow")
-df_flow["edge"] = list(zip(df_flow.from_node_id, df_flow.to_node_id))
-df_flow["name"] = df_flow["edge"].map(edge_names)
-
-# Plot the flow data, interactive plot with Plotly
-pivot_flow = df_flow.pivot_table(index="time", columns="name", values="flow_rate").reset_index()
-fig = px.line(pivot_flow, x="time", y=pivot_flow.columns[1:], title="Flow Over Time [m3/s]")
-
-fig.update_layout(legend_title_text='Edge')
-fig.write_html(model_dir/ "Crystal_2.1/plot_edges.html")
-fig.show()
      -
      -
      -

      4.1.3 Step 3: Plotting results

      -

      Figure 14 illustrates the new storage and water level at the reservoir. As expected, after increasing the profile of basin 3 to mimic the reservoir, its storage capacity increased as well.

      -
      -
      -
      - -
      -
      -Figure 14: Simulated basin storages and levels -
      -
      -
      -
      -
      -
      -

      4.2 Module 2.2 – Public Water Supply

      -
      -

      4.2.1 Step 1: Rename the saving files

      -

      Rename the files to Crystal_2.2

      -
      -
      -

      4.2.2 Step 2: Add a demand node

      -

      \(50.000\) people live in Crystal City. To represents the total flow rate or abstraction rate required to meet the water demand of \(50,000\) people, another demand node needs to be added assuming a return flow of \(60%\).

      -
      model.user_demand.add(
-    Node(9, Point(0.0, -0.25), name='PWS'),
-    [user_demand.Time(
-        demand=[0.07, 0.08, 0.09, 0.10, 0.12, 0.14, 0.15, 0.14, 0.12, 0.10, 0.09, 0.08],  # Total demand in m³/s
-        return_factor=0.6,
-        min_level=0,
-        priority=1,
-        time=[
-            starttime,
-            "2022-02-01",
-            "2022-03-01",
-            "2022-04-01",
-            "2022-05-01",
-            "2022-06-01",
-            "2022-07-01",
-            "2022-08-01",
-            "2022-09-01",
-            "2022-10-01",
-            "2022-11-01",
-            "2022-12-01"
-        ]
-    )]
-)
      -
      -
      -

      4.2.3 Step 3: Add the edges

      -

      The connection between the reservoir and the demand node needs to be defined:

      -
      model.edge.add(model.flow_boundary[1], model.basin[3])
-model.edge.add(model.flow_boundary[2], model.basin[4])
-model.edge.add(model.basin[3], model.user_demand[6])
-model.edge.add(model.basin[3], model.user_demand[9])
-model.edge.add(model.user_demand[6], model.basin[4])
-model.edge.add(model.user_demand[9], model.basin[4])
-model.edge.add(model.basin[3], model.tabulated_rating_curve[7])
-model.edge.add(model.tabulated_rating_curve[7], model.basin[4])
-model.edge.add(model.basin[4], model.tabulated_rating_curve[5])
-model.edge.add(model.tabulated_rating_curve[5], model.terminal[8])
      -
      -
      -

      4.2.4 Step 4: Adjust the name dictionaries

      -
      # Dictionary mapping node_ids to names
-edge_names = {
-    (1,3): 'Main',
-    (2,4): 'Minor',
-    (3,6): 'IrrA Demand',
-    (6,4): 'IrrA Drain',
-    (3,9): 'PWS Demand',
-    (9,4): 'PWS Return',
-    (3,7): 'Rsv2Main',
-    (7,4): 'Main2Conf',
-    (4,5): 'Conf2TRC',
-    (5,8): 'TRC2Term',
-}
      -
      -
      -

      4.2.5 Step 5: Check the simulated demands

      -

      Figure 15 shows the flow to (PWS Demand) and out (PWS Return) of the PWS node. Figure 16 shows the downstream flow to the ocean. The impact is clear. Due to the demands upstream (irrigation and public water supply) an expected decrease of discharge is shown downstream.

      -
      -
      -
      - -
      -
      -Figure 15: Simulated flows to and from the city -
      -
      -
      -
      -
      -
      - -
      -
      -Figure 16: Simulated basin storages and levels -
      -
      -
      - - -
      -
      -
      - -
      - - -
      - - - - - \ No newline at end of file diff --git a/index.html b/index.html index f10d242fb..6f26ff428 100644 --- a/index.html +++ b/index.html @@ -97,7 +97,11 @@ Overview
    • - + +Tutorials +
      • +
    • + How-to guides
    • diff --git a/install.html b/install.html index 4bcf935c5..0401b3139 100644 --- a/install.html +++ b/install.html @@ -20,6 +20,40 @@ margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */ vertical-align: middle; } +/* CSS for syntax highlighting */ +pre > code.sourceCode { white-space: pre; position: relative; } +pre > code.sourceCode > span { line-height: 1.25; } +pre > code.sourceCode > span:empty { height: 1.2em; } +.sourceCode { overflow: visible; } +code.sourceCode > span { color: inherit; text-decoration: inherit; } +div.sourceCode { margin: 1em 0; } +pre.sourceCode { margin: 0; } +@media screen { +div.sourceCode { overflow: auto; } +} +@media print { +pre > code.sourceCode { white-space: pre-wrap; } +pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; } +} +pre.numberSource code + { counter-reset: source-line 0; } +pre.numberSource code > span + { position: relative; left: -4em; counter-increment: source-line; } +pre.numberSource code > span > a:first-child::before + { content: counter(source-line); + position: relative; left: -1em; text-align: right; vertical-align: baseline; + border: none; display: inline-block; + -webkit-touch-callout: none; -webkit-user-select: none; + -khtml-user-select: none; -moz-user-select: none; + -ms-user-select: none; user-select: none; + padding: 0 4px; width: 4em; + } +pre.numberSource { margin-left: 3em; padding-left: 4px; } +div.sourceCode + { } +@media screen { +pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } +} @@ -101,7 +135,11 @@ Overview
    • - + +Tutorials +
      • +
    • + How-to guides
    • @@ -288,7 +326,7 @@

      3 Install Ribasim

      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.

      The Ribasim Python package is registered in PyPI and conda-forge and can therefore be installed with pip, conda or pixi:

      -
      pip install ribasim
      +
      pip install ribasim

      For documentation please see the examples and API reference.

      diff --git a/known_issues.html b/known_issues.html index 43bacd887..a18012c7e 100644 --- a/known_issues.html +++ b/known_issues.html @@ -97,7 +97,11 @@ Overview

    • - + +Tutorials +
      • +
    • + How-to guides
    • diff --git a/reference/index.html b/reference/index.html index b9f17b0e6..fb44caedf 100644 --- a/reference/index.html +++ b/reference/index.html @@ -97,7 +97,11 @@ Overview
    • - + +Tutorials +
      • +
    • + How-to guides
    • diff --git a/reference/node/basin.html b/reference/node/basin.html index 38da2f344..9363979c0 100644 --- a/reference/node/basin.html +++ b/reference/node/basin.html @@ -180,7 +180,11 @@ Overview
    • - + +Tutorials +
      • +
    • + How-to guides
    • @@ -472,7 +476,7 @@

      1.2.1 Interpolation

      At the given timestamps the values are set in the simulation, such that the timeseries can be seen as forward filled.

      -
      +
      Code 
      import numpy as np
@@ -671,7 +675,7 @@ 
      
 
      1.4.1.1 Level to area
      
 
      The level to area relationship is defined with the Basin / profile data using linear interpolation. An example of such a relationship is shown below.
      
-
      
+
      
 
      
 Code
 
      fig, ax = plt.subplots()
@@ -754,7 +758,7 @@ 
      \[
     S(h) = \int_{h_0}^h A(h')\text{d}h'.
 \]
      
-
      
+
      
 
      
 Code
 
      storage = np.diff(level) * area[:-1] + 0.5 * np.diff(area) * np.diff(level)
@@ -799,7 +803,7 @@ 
      
 
      1.4.1.3 Interactive basin example
      
 
      The profile data is not detailed enough to create a full 3D picture of the basin. However, if we assume the profile data is for a stretch of canal of given length, the following plot shows a cross section of the basin.
      
-
      
+
      
 
      
 Code
 
      import plotly.graph_objects as go
@@ -914,9 +918,9 @@ 
      fig.show()
      
 
      
 
      
-
                                  
                  
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+
+
+
+
+
+
+
+
+
      
+  
      
+    
+  
+
      
+
+
      
+
+  
+
      
+
+    
+
+
      
+
+
      
+
      
+
      Irrigation demand
      
+
      
+
+
+
+
      
+
+    
+  
+    
+  
      
+  
+
+
+
      
+
+
+
      
+
      from pathlib import Path
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import plotly.express as px
+from ribasim import Model, Node
+from ribasim.nodes import (
+    basin,
+    flow_boundary,
+    tabulated_rating_curve,
+    user_demand,
+)
+from shapely.geometry import Point
      
+
      
+
      
+
      base_dir = Path("crystal-basin")
+
+starttime = "2022-01-01"
+endtime = "2023-01-01"
+model = Model(
+    starttime=starttime,
+    endtime=endtime,
+    crs="EPSG:4326",
+)
      
+
      
+
      These nodes are identical to the previous tutorial:
      
+
      
+
      # FlowBoundary
+data = pd.DataFrame({
+    "time": pd.date_range(start="2022-01-01", end="2023-01-01", freq="MS"),
+    "main": [74.7, 57.9, 63.2, 183.9, 91.8, 47.5, 32.6, 27.6, 26.5, 25.1, 39.3, 37.8, 57.9],
+    "minor": [16.3, 3.8, 3.0, 37.6, 18.2, 11.1, 12.9, 12.2, 11.2, 10.8, 15.1, 14.3, 11.8]
+})  # fmt: skip
+data["total"] = data["minor"] + data["main"]
+main = model.flow_boundary.add(
+    Node(1, Point(0.0, 0.0), name="main"),
+    [
+        flow_boundary.Time(
+            time=data.time,
+            flow_rate=data.main,
+        )
+    ],
+)
+minor = model.flow_boundary.add(
+    Node(2, Point(-3.0, 0.0), name="minor"),
+    [
+        flow_boundary.Time(
+            time=data.time,
+            flow_rate=data.minor,
+        )
+    ],
+)
+
+# Basin
+confluence = model.basin.add(
+    Node(3, Point(-1.5, -1), name="confluence"),
+    [
+        basin.Profile(area=[672000, 5600000], level=[0, 6]),
+        basin.State(level=[4]),
+        basin.Time(time=[starttime, endtime]),
+    ],
+)
+
+# TabulatedRatingCurve
+weir = model.tabulated_rating_curve.add(
+    Node(4, Point(-1.5, -1.5), name="weir"),
+    [
+        tabulated_rating_curve.Static(
+            level=[0.0, 2, 5],
+            flow_rate=[0.0, 50, 200],
+        )
+    ],
+)
+
+# Terminal
+sea = model.terminal.add(Node(5, Point(-1.5, -3.0), name="sea"))
      
+
      
+
      
+
      1 Irrigation demand
      
+
      Let us modify the environment to include agricultural activities within the basin, which necessitate irrigation. Water is diverted from the main river through an irrigation canal, with a portion of it eventually returning to the main river (see Figure 1).
      
+
      
+
      
+
      
+
+
      
+
      
+Figure 1: Crystal basin with irrigation
+
      
+
      
+
      
+
      For this schematization update, we need to incorporate three additional nodes:
      
+
        
+
      • Basin: Represents a cross-sectional point where water is diverted.
        • 
+
      • UserDemand: Represents the irrigation demand.
        • 
+
      • TabulatedRatingCurve: Defines the remaining water flow from the main river at the diversion point.
        • 
+
      
+
      
+
      1.1 Add a second Basin node
      
+
      This Basin will portray as the point in the river where the diversion takes place, getting the name diversion. Its profile area at this intersection is slightly smaller than at the confluence.
      
+
      
+
      diversion_basin = model.basin.add(
+    Node(6, Point(-0.75, -0.5), name="diversion_basin"),
+    [
+        basin.Profile(area=[500000, 5000000], level=[0, 6]),
+        basin.State(level=[3]),
+        basin.Time(time=[starttime, endtime]),
+    ],
+)
      
+
      
+
      
+
      
+
      1.2 Add the irrigation demand
      
+
      An irrigation district needs to apply irrigation to its field starting from April to September. The irrigated area is \(> 17000 \text{ ha}\) and requires around \(5 \text{ mm/day}\). In this case the irrigation district diverts from the main river an average flow rate of \(10 \text{ m}^3/\text{s}\) and \(12 \text{ m}^3/\text{s}\) during spring and summer, respectively. Start of irrigation takes place on the 1st of April until the end of August. The water intake is through a canal (demand).
      
+
      For now, let’s assume the return flow remains \(0.0\) (return_factor). Meaning all the supplied water to fulfill the demand is consumed and does not return back to the river. The user demand node interpolates the demand values. Thus the following code needs to be implemented:
      
+
      
+
      irrigation = model.user_demand.add(
+    Node(7, Point(-1.5, 0.5), name="irrigation"),
+    [
+        user_demand.Time(
+            demand=[0.0, 0.0, 10, 12, 12, 0.0],
+            return_factor=0,
+            min_level=0,
+            priority=1,
+            time=[
+                starttime,
+                "2022-03-31",
+                "2022-04-01",
+                "2022-07-01",
+                "2022-09-30",
+                "2022-10-01",
+            ],
+        )
+    ],
+)
      
+
      
+
      
+
      
+
      1.3 Add a TabulatedRatingCurve
      
+
      The second TabulatedRatingCurve node will simulate the rest of the water that is left after diverting a part from the main river to the irrigation disctrict. The rest of the water will flow naturally towards the confluence:
      
+
      
+
      diversion_weir = model.tabulated_rating_curve.add(
+    Node(8, Point(-1.125, -0.75), name="diversion_weir"),
+    [
+        tabulated_rating_curve.Static(
+            level=[0.0, 1.5, 5],
+            flow_rate=[0.0, 45, 200],
+        )
+    ],
+)
      
+
      
+
      
+
      
+
      1.4 Add edges
      
+
      
+
      model.edge.add(main, diversion_basin, name="main")
+model.edge.add(minor, confluence, name="minor")
+model.edge.add(diversion_basin, irrigation, name="irrigation")
+model.edge.add(irrigation, confluence)
+model.edge.add(diversion_basin, diversion_weir, name="not diverted")
+model.edge.add(diversion_weir, confluence)
+model.edge.add(confluence, weir)
+model.edge.add(weir, sea, name="sea")
      
+
      
+
      
+
      toml_path = base_dir / "Crystal-2/ribasim.toml"
+model.write(toml_path)
+cli_path = "ribasim"
      
+
      
+
      
+
      
+
      1.5 Plot model and run
      
+
      Plot the schematization and run the model. This time the new outputs should be written in a new folder called Crystal-2:
      
+
      
+
      model.plot();
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      1.6 Plot and compare the Basin results
      
+
      Plot the simulated levels and storages at the diverted section and at the confluence.
      
+
      
+
      df_basin = pd.read_feather(base_dir / "Crystal-2/results/basin.arrow")
+
+# Create pivot tables and plot for basin data
+df_basin_wide = df_basin.pivot_table(
+    index="time", columns="node_id", values=["storage", "level"]
+)
+
+df_basin_div = df_basin_wide.loc[:, pd.IndexSlice[:, diversion_basin.node_id]]
+df_basin_conf = df_basin_wide.loc[:, pd.IndexSlice[:, confluence.node_id]]
+
+
+def plot_basin_data(
+    ax, ax_twin, df_basin, level_color="b", storage_color="r", title="Basin"
+):
+    # Plot level data
+    for column in df_basin["level"].columns:
+        ax.plot(
+            df_basin.index,
+            df_basin["level"][column],
+            linestyle="-",
+            color=level_color,
+            label=f"Level - {column}",
+        )
+
+    # Plot storage data
+    for column in df_basin["storage"].columns:
+        ax_twin.plot(
+            df_basin.index,
+            df_basin["storage"][column],
+            linestyle="--",
+            color=storage_color,
+            label=f"Storage - {column}",
+        )
+
+    ax.set_ylabel("Level [m]", color=level_color)
+    ax_twin.set_ylabel("Storage [m³]", color=storage_color)
+
+    ax.tick_params(axis="y", labelcolor=level_color)
+    ax_twin.tick_params(axis="y", labelcolor=storage_color)
+
+    ax.set_title(title)
+
+    # Combine legends from both axes
+    lines, labels = ax.get_legend_handles_labels()
+    lines_twin, labels_twin = ax_twin.get_legend_handles_labels()
+    ax.legend(lines + lines_twin, labels + labels_twin, loc="upper left")
+
+
+# Create subplots
+fig, (ax1, ax3) = plt.subplots(2, 1, figsize=(12, 12), sharex=True)
+
+# Plot Div basin data
+ax2 = ax1.twinx()  # Secondary y-axis for storage
+plot_basin_data(ax1, ax2, df_basin_div, title="Diversion Basin level and storage")
+
+# Plot Conf basin data
+ax4 = ax3.twinx()  # Secondary y-axis for storage
+plot_basin_data(ax3, ax4, df_basin_conf, title="Confluence Basin level and storage")
+
+# Common X label
+ax3.set_xlabel("Time")
+fig.tight_layout()  # Adjust layout to fit labels
+plt.show()
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      The figure above illustrates the water levels and storage capacities for each Basin.
      
+
      When compared to the natural flow conditions, where no water is abstracted for irrigation (See Crystal 1), there is a noticeable decrease in both storage and water levels at the confluence downstream. This reduction is attributed to the irrigation demand upstream with no return flow, which decreases the amount of available water in the main river, resulting in lower water levels at the confluence.
      
+
      
+
      
+
      1.7 Plot and compare the flow results
      
+
      Plot the flow results in an interactive plotting tool.
      
+
      
+
      df_flow = pd.read_feather(base_dir / "Crystal-2/results/flow.arrow")
+# Add the edge names and then remove unnamed edges
+df_flow["name"] = model.edge.df["name"].loc[df_flow["edge_id"]].to_numpy()
+df_flow = df_flow[df_flow["name"].astype(bool)]
+
+# Plot the flow data, interactive plot with Plotly
+pivot_flow = df_flow.pivot_table(
+    index="time", columns="name", values="flow_rate"
+).reset_index()
+fig = px.line(pivot_flow, x="time", y=pivot_flow.columns[1:], title="Flow [m3/s]")
+
+fig.update_layout(legend_title_text="Edge")
+fig.show()
      
+
      
+
                                  
                          
      
+
      
+
      
+
      Try toggling the edges on and off by clicking on them in the edges.
      
+
+
+
      
+
      
+
+
       
+
+
+
       
+
+
+
+
+
\ No newline at end of file
diff --git a/tutorial/irrigation-demand_files/figure-html/cell-10-output-1.png b/tutorial/irrigation-demand_files/figure-html/cell-10-output-1.png
new file mode 100644
index 000000000..2c990095c
Binary files /dev/null and b/tutorial/irrigation-demand_files/figure-html/cell-10-output-1.png differ
diff --git a/tutorial/irrigation-demand_files/figure-html/cell-12-output-1.png b/tutorial/irrigation-demand_files/figure-html/cell-12-output-1.png
new file mode 100644
index 000000000..6edf20da6
Binary files /dev/null and b/tutorial/irrigation-demand_files/figure-html/cell-12-output-1.png differ
diff --git a/tutorial/natural-flow.html b/tutorial/natural-flow.html
new file mode 100644
index 000000000..1bffd9713
--- /dev/null
+++ b/tutorial/natural-flow.html
@@ -0,0 +1,1206 @@
+
+
+
+
+
+
+
+
+
+Getting started – Ribasim
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+
+
+
+
+
+
+
+
+
      
+  
      
+    
+  
+
      
+
+
      
+
+  
+
      
+
+    
+
+
      
+
+
      
+
      
+
      Getting started
      
+
      
+
+
+
+
      
+
+    
+  
+    
+  
      
+  
+
+
+
      
+
+
+
      
+
      1 Introduction
      
+
      Welcome to Ribasim! This tutorial will help you get started with the basics of using Ribasim for river basin simulation. In this tutorial, the schematization of models is done in Python using the Ribasim Python package. The Ribasim Python package (named ribasim) simplifies the process of building, updating, and analyzing Ribasim model programmatically. It also allows for the creation of entire models from base data, ensuring that your model setup is fully reproducible.
      
+
      
+
      1.1 Learning objectives
      
+
      In this tutorial, we will focus on a fictional river basin called Crystal, which will serve as our case study. The guide is divided into different modules, each covering various scenarios. These include simulating natural flow, implementing reservoirs, and observing the impact of other structures. While not all node types and possibilities will be demonstrated, the focus will be on the most commonly used and significant situations. By the end of the tutorial, users will be able to:
      
+
        
+
      • Set up a basic Ribasim model: Understand how to create a new model for a river basin using the Ribasim Python package.
        • 
+
      • Evaluate the impact of demands: Introduce water demand (such as irrigation) and assess their effects on the river basin.
        • 
+
      • Modify and update models: Learn how to update existing models with new data and changes.
        • 
+
      • Analyze simulation results: Use built-in tools to analyze and interpret the results of your simulations.
        • 
+
      
+
      
+
      
+
      1.2 Prerequisites
      
+
      First install the latest release of Ribasim as documented in the installation guide.
      
+
      Download the Crystal_Basin.zip file from the website. Extract Crystal_Basin.zip and place it in the same directory as your Ribasim installation. This folder includes:
      
+
        
+
      • QuickStartGuide.pdf
        • 
+
      • data: Contains data inputs such as time series needed for running the case. Additionally, your Python model (.py) and the results will also be saved in this folder.
        • 
+
      
+
      
+
      
+
      
+
      2 Crystal River Basin
      
+
      We will examine a straightforward example of the Crystal river basin, which includes a main river and a single tributary flowing into the sea (see Figure 1). An average discharge of \(44.45 \text{ m}^3/\text{s}\) is measured at the confluence. In this module, the basin is free of any activities, allowing the model to simulate the natural flow. The next step is to include a demand (irrigation) that taps from a canal out of the main river.
      
+
      
+
      
+
      
+
+
      
+
      
+Figure 1: Crystal Basin based on natural flow
+
      
+
      
+
      
+
      After this module the user will be able to:
      
+
        
+
      • Build a river basin model from scratch
        • 
+
      • Understand the functionality of the Demand and Basin nodes
        • 
+
      • Generate overview of results
        • 
+
      • Evaluate the simulation results
        • 
+
      
+
      
+
      2.1 Natural flow
      
+
      
+
      2.1.1 Import packages
      
+
      Before building the model we need to import some modules. Open your favorite Python editor (Visual Studio Code, Jupyter, …) and create a new script or notebook and name it Crystal_1.1 and save it into your model folder Crystal_Basin. Import the following modules in Python:
      
+
      
+
      from pathlib import Path
+
+import matplotlib.pyplot as plt
+import pandas as pd
+from ribasim import Model, Node
+from ribasim.nodes import basin, flow_boundary, tabulated_rating_curve
+from shapely.geometry import Point
      
+
      
+
      
+
      
+
      2.1.2 Setup paths and model configuration
      
+
      Reference the paths of the Ribasim installation and model directory and define the time period (2022-01-01 until 2023-01-01) for the model simulation. The coordinate reference system (CRS) is also required, and set to EPSG:4326, which means all coordinates are interpreted as latitude and longitude values. The CRS is important for correctly placing Ribasim models on the map, but since this is a fictional model, it is not important.
      
+
      
+
      base_dir = Path("crystal-basin")
+
+starttime = "2022-01-01"
+endtime = "2023-01-01"
+model = Model(
+    starttime=starttime,
+    endtime=endtime,
+    crs="EPSG:4326",
+)
      
+
      
+
      
+
      
+
      2.1.3 FlowBoundary nodes
      
+
      The Crystal basin consists of two inflow points, the tributary and the main Crystal river, we will call them Minor and Main respectively. This is a monthly inflow timeseries from 2014 to 2023. The used simulation period is defined by the starttime and endtime of the model, not by the input timeseries.
      
+
      
+
      data = pd.DataFrame({
+    "time": pd.date_range(start="2022-01-01", end="2023-01-01", freq="MS"),
+    "main": [74.7, 57.9, 63.2, 183.9, 91.8, 47.5, 32.6, 27.6, 26.5, 25.1, 39.3, 37.8, 57.9],
+    "minor": [16.3, 3.8, 3.0, 37.6, 18.2, 11.1, 12.9, 12.2, 11.2, 10.8, 15.1, 14.3, 11.8]
+})  # fmt: skip
+data["total"] = data["minor"] + data["main"]
+display(data)
+
+# Average and max inflow of the total inflow data timeseries
+# From 2014 - 2023
+print("Average inflow [m3/s]:", data["total"].mean())
+print("Maximum inflow [m3/s]:", data["total"].max())
+
+main = model.flow_boundary.add(
+    Node(1, Point(0.0, 0.0), name="main"),
+    [
+        flow_boundary.Time(
+            time=data.time,
+            flow_rate=data.main,
+        )
+    ],
+)
+
+minor = model.flow_boundary.add(
+    Node(2, Point(-3.0, 0.0), name="minor"),
+    [
+        flow_boundary.Time(
+            time=data.time,
+            flow_rate=data.minor,
+        )
+    ],
+)
      
+
      
+
      
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      timemainminortotal
      02022-01-0174.716.391.0
      12022-02-0157.93.861.7
      22022-03-0163.23.066.2
      32022-04-01183.937.6221.5
      42022-05-0191.818.2110.0
      52022-06-0147.511.158.6
      62022-07-0132.612.945.5
      72022-08-0127.612.239.8
      82022-09-0126.511.237.7
      92022-10-0125.110.835.9
      102022-11-0139.315.154.4
      112022-12-0137.814.352.1
      122023-01-0157.911.869.7
      
+
+
      
+
      
+
      
+
      Average inflow [m3/s]: 72.62307692307692
+Maximum inflow [m3/s]: 221.5
      
+
      
+
      
+
      
+
      
+
      2.1.4 Basin node (confluence)
      
+
      To schematize the confluence from the tributary we will use the Basin node. The node by itself portrays as water storage with a certain volume of water and can be used for different purposes, such as a reservoir, river reach, lake or in this case a confluence. Figure 2 visualizes a cross section of the confluence point in our model.
      
+
      
+
      
+
      
+
+
      
+
      
+Figure 2: Basin node concept for the confluence
+
      
+
      
+
      
+
      Table 1 shows the input data for the Basin node profile.
      
+
      
+
      
+
      
+Table 1: Profile data for the basin node
+
      
+
      
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      Area [\(\text{m}^2\)]Level [\(\text{m}\)]
      \(672000.0\)\(0.0\)
      \(5600000.0\)\(6.0\)
      
+
      
+
      
+
      
+
      Whilst in this case the level starts at \(0.0\) and therefore happens to be the same as the depth, it should never be interpreted as a depth. All water levels in Ribasim are assumed to be with respect to a shared reference datum, like mean sea level (MSL). The first water level in the profile is the height of the Basin bottom above this reference datum.
      
+
      To specify the Basin profile, the following code is used:
      
+
      
+
      confluence = model.basin.add(
+    Node(3, Point(-1.5, -1), name="confluence"),
+    [
+        basin.Profile(area=[672000, 5600000], level=[0, 6]),
+        basin.State(level=[4]),
+        basin.Time(time=[starttime, endtime]),
+    ],
+)
      
+
      
+
      
+
      
+
      2.1.5 TabulatedRatingCurve
      
+
      In the previous step we implemented a Basin node that functions as a confluence. Conceptually, the Basin acts as a store of water, accumulating inflows and then releasing them. A Basin cannot directly connect to another Basin, because the rules for water exchange between them need to be defined. Connector nodes take care of this. The first such node we introduce is the TabulatedRatingCurve. It defines a relation between the water level (\(h\)) in the Basin and the outflow (\(Q\)) from the Basin. This setup mimics the behavior of a gate or spillway, allowing us to model how varying water levels influence flow rates at the confluence.
      
+
      As the two inflows come together at the confluence, we expect, as mentioned above, a discharge average of \(44.45 \text{ m}^3/\text{s}\). It is therefore expected that the confluence Basin goes towards a level where the outflow is equal to the inflow via the rating curve. Only then is the confluence Basin in equilibrium. The maximum depth of the river is \(6 \text{ m}\), and the maximum inflow is \(221.5 \text{ m}^3/\text{s}\) The \(Q(h)\) relationship in Table 2 allows such inflows with reasonable water levels.
      
+
      
+
      
+
      
+Table 2: Input data for the Tabulated Rating Curve
+
      
+
      
+
++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      



      Water Level (\(h\)) [\(\text{m}\)]Outflow (\(Q\)) [\(\text{m}^3/\text{s}\)]
      \(0.0\)\(0.0\)
      \(2.0\)\(50.0\)
      \(5.0\)\(200.0\)
      
+
      
+
      
+
      
+
      In Ribasim, the \(Q(h)\) relation is a piecewise linear function, so the points in between will be linearly interpolated. Figure 3 illustrates the visual process and shows a progressive increase in discharge with rising water levels. In this case this means:
      
+
        
+
      • At level \(0.0\): No discharge occurs. This represents a condition where the water level is too low for any flow to be discharged.
        • 
+
      • At level \(2.0\): Discharge is \(50.0 \text{ m}^3/\text{s}\). This is a bit above the average discharge rate, corresponding to the water level where normal flow conditions are established.
        • 
+
      • At level \(5.0\): Discharge rate reaches \(200.0 \text{ m}^3/\text{s}\). This discharge rate occurs at the water level during wet periods, indicating higher flow capacity.
        • 
+
      
+
      
+
      
+
      
+
+
      
+
      
+Figure 3: Discharge at corresponding water levels
+
      
+
      
+
      
+
      Taking this into account, add the TabulatedRatingCurve as follows:
      
+
      
+
      weir = model.tabulated_rating_curve.add(
+    Node(4, Point(-1.5, -1.5), name="weir"),
+    [
+        tabulated_rating_curve.Static(
+            level=[0.0, 2, 5],
+            flow_rate=[0.0, 50, 200],
+        )
+    ],
+)
      
+
      
+
      
+
      
+
      2.1.6 Terminal node
      
+
      Finally all the water will discharge into the sea. We schematize this with the Terminal node, as it portrays the end point of the model, that can receive but not give water. Besides the node number/name and location, no further input is needed.
      
+
      
+
      sea = model.terminal.add(Node(5, Point(-1.5, -3.0), name="sea"))
      
+
      
+
      
+
      
+
      2.1.7 Defining edges
      
+
      Implement the connections (edges) between the nodes.
      
+
      
+
      model.edge.add(main, confluence, name="main")
+model.edge.add(minor, confluence, name="minor")
+model.edge.add(confluence, weir)
+model.edge.add(weir, sea, name="sea")
      
+
      
+
      
+
      
+
      2.1.8 Visualization and model execution
      
+
      Plot the schematization.
      
+
      
+
      model.plot();
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      Write the model configuration to the TOML file. Name the output file Crystal-1/ribasim.toml:
      
+
      
+
      toml_path = base_dir / "Crystal-1/ribasim.toml"
+model.write(toml_path)
+cli_path = "ribasim"
      
+
      
+
      After running model.write a subfolder Crystal-1 is created, which contains the model input data and configuration:
      
+
        
+
      • ribasim.toml: The model configuration
        • 
+
      • database.gpkg: A GeoPackage containing the network geometry and input data of the nodes used.
        • 
+
      
+
      Now run the model. You can open a terminal and run it from there. For example:
      
+
      ribasim Crystal-1/ribasim.toml
      
+
      From Python you can run it with:
      
+
      import subprocess
+result = subprocess.run([cli_path, toml_path], capture_output=True, encoding="utf-8")
+print(result.stderr)
+result.check_returncode()
      
+
      Where cli_path is a string with either the full path to the Ribasim executable, like r"c:\bin\ribasim\ribasim", or just "ribasim" in case you added the ribasim folder to your PATH.
      
+
      The print(result.stderr) ensures you see the same logging and error messages that you would see in the terminal. And result.check_returncode() will throw an error when the simulation was not successful.
      
+
      
+
      
+
      2.1.9 Post-processing results
      
+
      Read the Arrow files and plot the simulated flows from different edges and the levels and storages at our confluence point:
      
+
      
+
      df_basin = pd.read_feather(base_dir / "Crystal-1/results/basin.arrow")
+
+# Create pivot tables and plot for Basin data
+df_basin_wide = df_basin.pivot_table(
+    index="time", columns="node_id", values=["storage", "level"]
+)
+
+# Plot level and storage on the same graph with dual y-axes
+fig, ax1 = plt.subplots(figsize=(12, 6))
+
+# Plot level on the primary y-axis
+color = "b"
+ax1.set_xlabel("Time")
+ax1.set_ylabel("Level [m]", color=color)
+ax1.plot(df_basin_wide.index, df_basin_wide["level"], color=color)
+ax1.tick_params(axis="y", labelcolor=color)
+
+# Create a secondary y-axis for storage
+ax2 = ax1.twinx()
+color = "r"
+ax2.set_ylabel("Storage [m³]", color="r")
+ax2.plot(df_basin_wide.index, df_basin_wide["storage"], linestyle="--", color=color)
+ax2.tick_params(axis="y", labelcolor=color)
+
+fig.tight_layout()  # Adjust layout to fit labels
+plt.title("Basin level and storage")
+plt.show()
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      The figure above shows the storage and levels in the Basin node.
      
+
      To accurately represent the relationship between water levels and discharge rates at this confluence, a TabulatedRatingCurve is used. This setup mimics the behavior of a gate or spillway, allowing us to model how varying water levels influence flow rates at the confluence. Since the basin node is functioning as a confluence rather than a storage reservoir, the simulated water levels and storage trends will closely follow the inflow patterns. This is because there is no net change in storage; all incoming water is balanced by outgoing flow.
      
+
      
+
      # Plot flow data
+# Read the flow results
+df_flow = pd.read_feather(base_dir / "Crystal-1/results/flow.arrow")
+# Add the edge names and then remove unnamed edges
+df_flow["name"] = model.edge.df["name"].loc[df_flow["edge_id"]].to_numpy()
+df_flow = df_flow[df_flow["name"].astype(bool)]
+
+# Create a pivot table
+pivot_flow = df_flow.pivot_table(index="time", columns="name", values="flow_rate")
+
+line_styles = ["-", "--", "-", "-."]
+num_styles = len(line_styles)
+
+fig, ax = plt.subplots(figsize=(12, 6))
+for i, column in enumerate(pivot_flow.columns):
+    pivot_flow[column].plot(
+        ax=ax, linestyle=line_styles[i % num_styles], linewidth=1.5, alpha=0.8
+    )
+
+# Set labels and title
+ax.set_xlabel("Time")
+ax.set_ylabel("Flow [m³/s]")
+ax.legend(bbox_to_anchor=(1.15, 1), title="Edge")
+plt.title("Flow")
+plt.grid(True)
+plt.show()
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      The figure above shows the discharges in \(\text{m}^3/\text{s}\) on each edge.
      
+
      Edge (3,4) represents the flow from the confluence to the TabulatedRatingCurve and edge (4,5) represents the flow from the TabulatedRatingCurve to the Terminal. Both show the same discharge over time. Which is expected in a natural flow environment, as what is coming into the confluence must come out.
      
+
+
+
      
+
      
+
      
+
+
       
+
+
+
       
+
+
+
+
+
\ No newline at end of file
diff --git a/tutorial/natural-flow_files/figure-html/cell-12-output-1.png b/tutorial/natural-flow_files/figure-html/cell-12-output-1.png
new file mode 100644
index 000000000..4cd6d1fec
Binary files /dev/null and b/tutorial/natural-flow_files/figure-html/cell-12-output-1.png differ
diff --git a/tutorial/natural-flow_files/figure-html/cell-13-output-1.png b/tutorial/natural-flow_files/figure-html/cell-13-output-1.png
new file mode 100644
index 000000000..229292b47
Binary files /dev/null and b/tutorial/natural-flow_files/figure-html/cell-13-output-1.png differ
diff --git a/tutorial/natural-flow_files/figure-html/cell-9-output-1.png b/tutorial/natural-flow_files/figure-html/cell-9-output-1.png
new file mode 100644
index 000000000..abaa43480
Binary files /dev/null and b/tutorial/natural-flow_files/figure-html/cell-9-output-1.png differ
diff --git a/tutorial/reservoir.html b/tutorial/reservoir.html
new file mode 100644
index 000000000..9f6ff45c9
--- /dev/null
+++ b/tutorial/reservoir.html
@@ -0,0 +1,1002 @@
+
+
+
+
+
+
+
+
+
+Reservoir – Ribasim
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+
+
+
+
+
+
+
+
+
      
+  
      
+    
+  
+
      
+
+
      
+
+  
+
      
+
+    
+
+
      
+
+
      
+
      
+
      Reservoir
      
+
      
+
+
+
+
      
+
+    
+  
+    
+  
      
+  
+
+
+
      
+
+
+
      
+
      from pathlib import Path
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import plotly.express as px
+from ribasim import Model, Node
+from ribasim.nodes import (
+    basin,
+    flow_boundary,
+    tabulated_rating_curve,
+    user_demand,
+)
+from shapely.geometry import Point
      
+
      
+
      
+
      base_dir = Path("crystal-basin")
+
+starttime = "2022-01-01"
+endtime = "2023-01-01"
+model = Model(
+    starttime=starttime,
+    endtime=endtime,
+    crs="EPSG:4326",
+)
      
+
      
+
      These nodes are identical to the previous tutorial:
      
+
      
+
      # FlowBoundary
+data = pd.DataFrame({
+    "time": pd.date_range(start="2022-01-01", end="2023-01-01", freq="MS"),
+    "main": [74.7, 57.9, 63.2, 183.9, 91.8, 47.5, 32.6, 27.6, 26.5, 25.1, 39.3, 37.8, 57.9],
+    "minor": [16.3, 3.8, 3.0, 37.6, 18.2, 11.1, 12.9, 12.2, 11.2, 10.8, 15.1, 14.3, 11.8]
+})  # fmt: skip
+data["total"] = data["minor"] + data["main"]
+main = model.flow_boundary.add(
+    Node(1, Point(0.0, 0.0), name="main"),
+    [
+        flow_boundary.Time(
+            time=data.time,
+            flow_rate=data.main,
+        )
+    ],
+)
+minor = model.flow_boundary.add(
+    Node(2, Point(-3.0, 0.0), name="minor"),
+    [
+        flow_boundary.Time(
+            time=data.time,
+            flow_rate=data.minor,
+        )
+    ],
+)
+
+# Basin
+confluence = model.basin.add(
+    Node(3, Point(-1.5, -1), name="confluence"),
+    [
+        basin.Profile(area=[672000, 5600000], level=[0, 6]),
+        basin.State(level=[4]),
+        basin.Time(time=[starttime, endtime]),
+    ],
+)
+
+# TabulatedRatingCurve
+weir = model.tabulated_rating_curve.add(
+    Node(4, Point(-1.5, -1.5), name="weir"),
+    [
+        tabulated_rating_curve.Static(
+            level=[0.0, 2, 5],
+            flow_rate=[0.0, 50, 200],
+        )
+    ],
+)
+diversion_weir = model.tabulated_rating_curve.add(
+    Node(8, Point(-1.125, -0.75), name="diversion_weir"),
+    [
+        tabulated_rating_curve.Static(
+            level=[0.0, 1.5, 5],
+            flow_rate=[0.0, 45, 200],
+        )
+    ],
+)
+
+# UserDemand
+irrigation = model.user_demand.add(
+    Node(7, Point(-1.5, 0.5), name="irrigation"),
+    [
+        user_demand.Time(
+            demand=[0.0, 0.0, 10, 12, 12, 0.0],
+            return_factor=0,
+            min_level=0,
+            priority=1,
+            time=[
+                starttime,
+                "2022-03-31",
+                "2022-04-01",
+                "2022-07-01",
+                "2022-09-30",
+                "2022-10-01",
+            ],
+        )
+    ],
+)
+
+# Terminal
+sea = model.terminal.add(Node(5, Point(-1.5, -3.0), name="sea"))
      
+
      
+
      Due to the increase of population and climate change Crystal city has implemented a reservoir upstream to store water for domestic use (See Figure 1). The reservoir is to help ensure a reliable supply during dry periods. In this module, the user will update the model to incorporate the reservoir’s impact on the whole Crystal basin.
      
+
      
+
      
+
      
+
+
      
+
      
+Figure 1: Crystal basin with demands and a reservoir
+
      
+
      
+
      
+
      
+
      1 Reservoir
      
+
      
+
      1.1 Add a Basin
      
+
      The diversion_basin from the previous tutorial is not used, but replaced by a larger reservoir Basin. Its water will play an important role for the users (the city and the irrigation district). The reservoir has a maximum area of \(32.3 \text{ km}^2\) and a maximum depth of \(7 \text{ m}\).
      
+
      
+
      reservoir = model.basin.add(
+    Node(6, Point(-0.75, -0.5), name="reservoir"),
+    [
+        basin.Profile(area=[20000000, 32300000], level=[0, 7]),
+        basin.State(level=[3.5]),
+        basin.Time(time=[starttime, endtime]),
+    ],
+)
      
+
      
+
      
+
      
+
      1.2 Add a demand node
      
+
      \(50.000\) people live in Crystal City. To represents the total flow rate or abstraction rate required to meet the water demand of \(50.000\) people, another demand node needs to be added assuming a return flow of \(60%\).
      
+
      
+
      city = model.user_demand.add(
+    Node(9, Point(0, -1), name="city"),
+    [
+        user_demand.Time(
+            # Total demand in m³/s
+            demand=[0.07, 0.08, 0.09, 0.10, 0.12, 0.14, 0.15, 0.14, 0.12, 0.10, 0.09, 0.08],
+            return_factor=0.6,
+            min_level=0,
+            priority=1,
+            time=pd.date_range(start="2022-01-01", periods=12, freq="MS"),
+        )
+    ],
+)  # fmt: skip
      
+
      
+
      
+
      model.edge.add(main, reservoir, name="main")
+model.edge.add(minor, confluence, name="minor")
+model.edge.add(reservoir, irrigation, name="irrigation")
+model.edge.add(irrigation, confluence)
+model.edge.add(reservoir, city, name="city")
+model.edge.add(city, confluence, name="city returnflow")
+model.edge.add(reservoir, diversion_weir, name="not diverted")
+model.edge.add(diversion_weir, confluence)
+model.edge.add(confluence, weir)
+model.edge.add(weir, sea, name="sea")
      
+
      
+
      
+
      model.plot();
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      toml_path = base_dir / "Crystal-3/ribasim.toml"
+model.write(toml_path)
+cli_path = "ribasim"
      
+
      
+
      
+
      
+
      1.3 Adjust the code
      
+
      Adjust the naming of the Basin in the dictionary mapping and the saving file should be Crystal-3.
      
+
      
+
      
+
      
+
      2 Plot reservoir storage and level
      
+
      
+
      df_basin = pd.read_feather(base_dir / "Crystal-3/results/basin.arrow")
+
+# Create pivot tables and plot for Basin data
+df_basin_wide = df_basin.pivot_table(
+    index="time", columns="node_id", values=["storage", "level"]
+)
+df_basin_wide = df_basin_wide.loc[:, pd.IndexSlice[:, reservoir.node_id]]
+
+# Plot level and storage on the same graph with dual y-axes
+fig, ax1 = plt.subplots(figsize=(12, 6))
+
+# Plot level on the primary y-axis
+color = "b"
+ax1.set_xlabel("Time")
+ax1.set_ylabel("Level [m]", color=color)
+ax1.plot(df_basin_wide.index, df_basin_wide["level"], color=color)
+ax1.tick_params(axis="y", labelcolor=color)
+
+# Create a secondary y-axis for storage
+ax2 = ax1.twinx()
+color = "r"
+ax2.set_ylabel("Storage [m³]", color="r")
+ax2.plot(df_basin_wide.index, df_basin_wide["storage"], linestyle="--", color=color)
+ax2.tick_params(axis="y", labelcolor=color)
+
+fig.tight_layout()  # Adjust layout to fit labels
+plt.title("Basin level and storage")
+plt.show()
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      
+
      The figure above illustrates the storage and water level at the reservoir. As expected, after increasing the profile of the Basin, its storage capacity increased as well.
      
+
      
+
      
+
      3 Plot flows
      
+
      
+
      df_flow = pd.read_feather(base_dir / "Crystal-3/results/flow.arrow")
+# Add the edge names and then remove unnamed edges
+df_flow["name"] = model.edge.df["name"].loc[df_flow["edge_id"]].to_numpy()
+df_flow = df_flow[df_flow["name"].astype(bool)]
+
+# Plot the flow data, interactive plot with Plotly
+pivot_flow = df_flow.pivot_table(
+    index="time", columns="name", values="flow_rate"
+).reset_index()
+fig = px.line(pivot_flow, x="time", y=pivot_flow.columns[1:], title="Flow [m3/s]")
+
+fig.update_layout(legend_title_text="Edge")
+fig.show()
      
+
      
+
                                  
                          
      
+
      
+
      
+
+
+
      
+
+
       
+
+
+
       
+
+
+
+
+
\ No newline at end of file
diff --git a/tutorial/reservoir_files/figure-html/cell-11-output-1.png b/tutorial/reservoir_files/figure-html/cell-11-output-1.png
new file mode 100644
index 000000000..676c05817
Binary files /dev/null and b/tutorial/reservoir_files/figure-html/cell-11-output-1.png differ
diff --git a/tutorial/reservoir_files/figure-html/cell-8-output-1.png b/tutorial/reservoir_files/figure-html/cell-8-output-1.png
new file mode 100644
index 000000000..15c6e93f9
Binary files /dev/null and b/tutorial/reservoir_files/figure-html/cell-8-output-1.png differ