Skip to content

Commit

Permalink
restructure headings of usage page
Browse files Browse the repository at this point in the history 
So the tables are subheadings of the node types.
  • Loading branch information
@visr
visr committed Sep 14, 2023
1 parent cc44c49 commit 03d2eb7
Showing 1 changed file with 69 additions and 93 deletions.
162 changes: 69 additions & 93 deletions docs/core/usage.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,15 @@ This will give the following message:
Usage: ribasim 'path/to/config.toml'
```


## Input and output files

### Configuration file
# Configuration file

Ribasim has a single configuration file, which is written in the [TOML](https://toml.io/)
format. It contains settings, as well as paths to other input and output files.

```{.toml include="../../core/test/docs.toml"}
```

#### Solver settings
## Solver settings

The solver section in the configuration file is entirely optional, since we aim to use defaults that will generally work well.
Common reasons to modify the solver settings are to adjust the calculation or output stepsizes: `adaptive`, `dt`, and `saveat`.
Expand Down Expand Up @@ -66,7 +63,7 @@ The total maximum number of iterations `maxiters = 1e9`, can normally stay as-is

The absolute and relative tolerance for adaptive timestepping can be set with `abstol` and `reltol`. For more information on these and other solver options, see the [DifferentialEquations.jl docs](https://docs.sciml.ai/DiffEqDocs/latest/basics/common_solver_opts/#solver_options).

### GeoPackage and Arrow tables
# GeoPackage and Arrow tables

The input and output tables described below all share that they are tabular files. The Node
and Edge tables always have to be in the [GeoPackage](https://www.geopackage.org/) file, and
Expand Down Expand Up @@ -108,7 +105,7 @@ Tables are also allowed to have rows for timestamps that are not part of the sim
these will be ignored. That makes it easy to prepare data for a larger period, and test
models on a shorted period.

### Node
# Node

Node is a table that specifies the ID and type of each node of a model. The ID must be
unique among all nodes, and the type must be one of the available node types listed below.
Expand Down Expand Up @@ -166,7 +163,7 @@ Adding a geometry to the node table can be helpful to examine models in
[QGIS](https://qgis.org/en/site/), as it will show the location of the nodes on the map. The
geometry is not used by Ribasim.

### Edge
# Edge

Edges define connections between nodes. The only thing that defines an edge is the nodes it connects, and in what direction.
There are currently 2 possible edge types:
Expand Down Expand Up @@ -194,20 +191,7 @@ geom | geometry | (optional)
Similarly to the node table, you can use a geometry to visualize the connections between the
nodes in QGIS. For instance, you can draw a line connecting the two node coordinates.

### Basin / state

The state table aims to capture the full state of the Basin, such that it can be used as an
initial condition, potentially the outcome of an earlier simulation. Currently only the
Basin node types have state.

column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int | - | sorted
level | Float64 | $m$ | $\ge$ basin bottom

Each Basin ID needs to be in the table.

### Basin
# Basin

The Basin table can be used to set the static value of variables. The forcing table has a
similar schema, with the time column added. A static value for a variable is only used if
Expand All @@ -227,15 +211,28 @@ Note that if variables are not set in the static table, default values are used
possible. These are generally zero, e.g. no precipitation, no inflow. If it is not possible
to have a reasonable and safe default, a value must be provided in the static table.

### Basin / forcing
## Basin / forcing

This table is the transient form of the `Basin` table.
The only difference is that a time column is added.
The table must by sorted by time, and per time it must be sorted by `node_id`.
A linear interpolation between the given timesteps is currently done if the
solver takes timesteps between the given data points. More options will be available later.

### Basin / profile
## Basin / state

The state table aims to capture the full state of the Basin, such that it can be used as an
initial condition, potentially the outcome of an earlier simulation. Currently only the
Basin node types have state.

column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int | - | sorted
level | Float64 | $m$ | $\ge$ basin bottom

Each Basin ID needs to be in the table.

## Basin / profile

The profile table defines the physical dimensions of the storage reservoir of each basin.

Expand Down Expand Up @@ -263,7 +260,36 @@ Internally this get converted to two functions, $A(S)$ and $h(S)$, by integratin
The minimum area cannot be zero to avoid numerical issues.
The maximum area is used to convert the precipitation flux into an inflow.

### FractionalFlow
## Basin output

The basin table contains outputs of the storage and level of each basin at every solver
timestep. The initial condition is also written to the file.

column | type | unit
-------- | -------- | ----
time | DateTime | -
node_id | Int | -
storage | Float64 | $m^3$
level | Float64 | $m$

The table is sorted by time, and per time it is sorted by `node_id`.

## Flow output

The flow table contains outputs of the flow on every edge in the model, for each solver
timestep.

column | type | unit
------------- | -------- | ----
time | DateTime | -
edge_id | Int | -
from_node_id | Int | -
to_node_id | Int | -
flow | Float64 | $m^3 s^{-1}$

The table is sorted by time, and per time the same edge_id order is used, though not sorted.

# FractionalFlow

Lets a fraction (in [0,1]) of the incoming flow trough.

Expand All @@ -273,8 +299,7 @@ node_id | Int | - | sorted
fraction | Float64 | - | in the interval [0,1]
control_state | String | - | (optional)


### TabulatedRatingCurve
# TabulatedRatingCurve

This table is similar in structure to the Basin profile. The TabulatedRatingCurve gives a
relation between the storage of a connected Basin (via the outlet level) and its outflow.
Expand All @@ -295,7 +320,7 @@ node_id | discharge | level
2 | 0.942702 | 20.095
3 | 0.0 | 2.129

### TabulatedRatingCurve / time
## TabulatedRatingCurve / time

This table is the transient form of the `TabulatedRatingCurve` table.
The only difference is that a time column is added.
Expand All @@ -310,8 +335,7 @@ node_id | Int | - | sorted per time
level | Float64 | $m$ | -
discharge | Float64 | $m^3 s^{-1}$ | non-negative


### Pump
# Pump

Pump water from a source node to a destination node.
The set flow rate will be pumped unless the intake storage is less than $10~m^3$,
Expand All @@ -328,7 +352,7 @@ min_flow_rate | Float64 | $m^3 s^{-1}$ | (optional, default 0.0)
max_flow_rate | Float64 | $m^3 s^{-1}$ | (optional)
control_state | String | - | (optional)

### Outlet
# Outlet

The outlet is very similar to the pump. The outlet has two additional physical constraints: water only flows trough the outlet when the head difference is positive (i.e. water flows down by gravity), and the upstream level must be above the minimum crest level if the upstream level is defined.
When PID controlled, the outlet must point towards the controlled basin in terms of edges.
Expand All @@ -343,7 +367,7 @@ max_flow_rate | Float64 | $m^3 s^{-1}$ | (optional)
min_crest_level | Float64 | $m$ | (optional)
control_state | String | - | (optional)

### LevelBoundary
# LevelBoundary

Acts like an infinitely large basin where the level does not change by flow.
This can be connected to a basin via a `LinearResistance`.
Expand All @@ -356,8 +380,7 @@ node_id | Int | - | sorted
active | Bool | - | (optional, default true)
level | Float64 | $m^3$ | -


### LevelBoundary / time
## LevelBoundary / time

This table is the transient form of the `LevelBoundary` table.
The only difference is that a time column is added and activity is assumed to be true.
Expand All @@ -373,9 +396,7 @@ time | DateTime | - | sorted
node_id | Int | - | sorted per time
level | Float64 | $m^3 s^{-1}$ | -



### FlowBoundary
# FlowBoundary

Pump water to a destination node.
We require that the edge connecting the flow boundary to the Basin should point towards the basin,
Expand All @@ -390,7 +411,7 @@ node_id | Int | - | sorted
active | Bool | - | (optional, default true)
flow_rate | Float64 | $m^3 s^{-1}$ | non-negative

### FlowBoundary / time
## FlowBoundary / time

This table is the transient form of the `FlowBoundary` table.
The only differences are that a time column is added and the nodes are assumed to be active so this column is removed.
Expand All @@ -406,7 +427,7 @@ time | DateTime | - | sorted
node_id | Int | - | sorted per time
flow_rate | Float64 | $m^3 s^{-1}$ | non-negative

### LinearResistance
# LinearResistance

Flow proportional to the level difference between the connected basins.

Expand All @@ -417,8 +438,7 @@ active | Bool | - | (optional, default true)
resistance | Float64 | $sm^{-2}$ | -
control_state | String | - | (optional)


### ManningResistance
# ManningResistance

Flow through this connection is estimated by conservation of energy and the Manning-Gauckler formula to estimate friction losses.

Expand All @@ -432,7 +452,7 @@ profile_with | Float64 | $m$ | positive
profile_slope | Float64 | - | -
control_state | String | - | (optional)

### Terminal
# Terminal

A terminal is a water sink without state or properties.
Any water that flows into a terminal node is removed from the model.
Expand All @@ -443,40 +463,11 @@ column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int | - | sorted

### Basin output

The basin table contains outputs of the storage and level of each basin at every solver
timestep. The initial condition is also written to the file.

column | type | unit
-------- | -------- | ----
time | DateTime | -
node_id | Int | -
storage | Float64 | $m^3$
level | Float64 | $m$

The table is sorted by time, and per time it is sorted by `node_id`.

### Flow output

The flow table contains outputs of the flow on every edge in the model, for each solver
timestep.

column | type | unit
------------- | -------- | ----
time | DateTime | -
edge_id | Int | -
from_node_id | Int | -
to_node_id | Int | -
flow | Float64 | $m^3 s^{-1}$

The table is sorted by time, and per time the same edge_id order is used, though not sorted.

### DisceteControl
# DisceteControl

DiscreteControl is implemented based on [VectorContinuousCallback](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#VectorContinuousCallback).

#### DiscreteControl / condition {#sec-condition}
## DiscreteControl / condition {#sec-condition}

The condition schema defines conditions of the form 'the discrete_control node with this node id listens to whether the given variable of the node with the given listen feature id is grater than the given value'. If the condition variable comes from a time-series, a look ahead $\Delta t$ can be supplied.

Expand All @@ -488,7 +479,7 @@ variable | String | - | must be "level" or "flow_rate"
greater_than | Float64 | various | -
look_ahead | Float64 | $s$ | Only on transient boundary conditions, non-negative (optional, default 0)

#### DiscreteControl / logic
## DiscreteControl / logic

The logic schema defines which control states are triggered based on the truth of the conditions a discrete_control node listens to.
DiscreteControl is applied in the Julia core as follows:
Expand All @@ -507,8 +498,7 @@ node_id | Int | - | sorted
truth_state | String | - | Consists of the characters "T" (true), "F" (false), "U" (upcrossing), "D" (downcrossing) and "*" (any)
control_state | String | - |


#### DiscreteControl output
## DiscreteControl output

The control table contains a record of each change of control state: when it happened, which control node was involved, to which control state it changed and based on which truth state.

Expand All @@ -519,9 +509,7 @@ control_node_id | Int
truth_state | String
control_state | String



### PidControl
# PidControl

The PidControl node controls the level in a basin by continuously controlling the flow rate of a connected pump or outlet. See also [PID controller](https://en.wikipedia.org/wiki/PID_controller). When A PidControl node is made inactive, the node under its control retains the last flow rate value, and the error integral is reset to 0.

Expand All @@ -540,8 +528,7 @@ integral | Float64 | $s^{-2}$ | -
derivative | Float64 | - | -
control_state | String | - | -


### PidControl / time
## PidControl / time

This table is the transient form of the `PidControl` table.
The differences are that a time column is added and the nodes are assumed to be active so this column is removed.
Expand All @@ -553,21 +540,10 @@ Note that a `node_id` can be either in this table or in the static one, but not

column | type | unit | restriction
-------------- | -------- | -------- | -----------
node_id | Int | - | sorted
node_id | Int | - | sorted per time
time | DateTime | - | sorted
listen_node_id | Int | - | -
target | Float64 | $m$ | -
proportional | Float64 | $s^{-1}$ | -
integral | Float64 | $s^{-2}$ | -
derivative | Float64 | - | -


## Example input files

From [this link](https://github.com/visr/ribasim-artifacts/releases) you can download an
existing schematization for the Netherlands that was used for testing purposes during
development. It is provided here as an example to help people get started. Based on the
description of the input files above, you can also generate your own schematization using
your tools of choice. For Python users
[ribasim-python](https://github.com/Deltares/ribasim-python) was created to make it easy to
do pre- and postprocessing.

0 comments on commit 03d2eb7

Please sign in to comment.