Skip to content

Commit

Permalink
Quick start (#1787)
Browse files Browse the repository at this point in the history 
Fixes #1158 

The quick start guide is now also in our documentation.

When I was working on this, I thought about what is the best way to make
sure the offline and online one are synchronized, so that when we modify
the old module or add new module to the docx, it can be updated in the
documentation.

I tried conversion between docx and qmd and it doesn't work very well. 

For now I suggest we should keep to modifying the qmd instead of
modifying the docx.

---------

Co-authored-by: Bart de Koning <[email protected]>
  • Loading branch information
@Jingru923 @SouthEndMusic
Jingru923 and SouthEndMusic authored Sep 3, 2024
1 parent 95a5ed1 commit 1943a19
Show file tree
Hide file tree
Showing 18 changed files with 948 additions and 185 deletions.
3 changes: 2 additions & 1 deletion docs/_quarto.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ website:
- text: "Overview"
file: index.qmd
- text: "How-to guides"
file: guide/examples.ipynb
file: guide/quickstart.qmd
- text: "Concepts"
file: concept/concept.qmd
- text: "Reference"
Expand All @@ -33,6 +33,7 @@ website:

- title: "How-to guides"
contents:
- guide/quickstart.qmd
- guide/examples.ipynb
- guide/qgis.qmd
- guide/coupling.qmd
Expand Down
1 change: 1 addition & 0 deletions docs/concept/concept.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Besides a model simulation core, Ribasim also includes tooling to assist in buil
The model and its results provides insights to decision makers, enabling them to build consensus amongst water users and make informed decisions about how to manage water resources optimally.

The model concept of Ribasim is composed of multiple layers:

- a physical layer representing water bodies and associated infrastructure as well as abstractions,
- a rule-based control layer to manage the infrastructure, and
- (optionally) a priority-based allocation layer to take centralized decisions on user abstractions.
Expand Down
761 changes: 761 additions & 0 deletions docs/guide/quickstart.qmd
View file

Large diffs are not rendered by default.

72 changes: 36 additions & 36 deletions docs/reference/node/basin.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ similar schema, with the time column added. A static value for a variable is onl
there is no dynamic forcing data for that variable. Specifically, if there is either no
time table, it is empty, or all timestamps of that variable are missing.

column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
precipitation | Float64 | $m s^{-1}$ | non-negative
potential_evaporation | Float64 | $m s^{-1}$ | non-negative
drainage | Float64 | $m^3 s^{-1}$ | non-negative
infiltration | Float64 | $m^3 s^{-1}$ | non-negative
column | type | unit | restriction
--------- | ------- | --------------------- | -----------
node_id | Int32 | - | sorted
precipitation | Float64 | $\text{m}/\text{s}$ | non-negative
potential_evaporation | Float64 | $\text{m}/\text{s}$ | non-negative
drainage | Float64 | $\text{m}^3/\text{s}$ | non-negative
infiltration | Float64 | $\text{m}^3/\text{s}$ | non-negative

Note that if variables are not set in the static table, default values are used when
possible. These are generally zero, e.g. no precipitation, no inflow. If it is not possible
Expand Down Expand Up @@ -93,7 +93,7 @@ The state table gives the initial water levels of all Basins.
column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
level | Float64 | $m$ | $\ge$ basin bottom
level | Float64 | $\text{m}$ | $\ge$ basin bottom

Each Basin ID needs to be in the table.
To use the final state of an earlier simulation as an initial condition, copy [`results/basin_state.arrow`](/reference/usage.qmd#sec-state) over to the `input_dir`, and point the TOML to it:
Expand All @@ -114,8 +114,8 @@ The profile table defines the physical dimensions of the storage reservoir of ea
column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
area | Float64 | $m^2$ | non-negative, per node_id: start positive and not decreasing
level | Float64 | $m$ | per node_id: increasing
area | Float64 | $\text{m}^2$ | non-negative, per node_id: start positive and not decreasing
level | Float64 | $\text{m}$ | per node_id: increasing

The level is the level at the basin outlet. All levels are defined in meters above a datum
that is the same for the entire model. An example of the first 4 rows of such a table is
Expand Down Expand Up @@ -365,12 +365,12 @@ The subgrid table defines a piecewise linear interpolation from a basin water le
Many subgrid elements may be associated with a single basin, each with distinct interpolation functions.
This functionality can be used to translate a single lumped basin level to a more spatially detailed representation (e.g comparable to the output of a hydrodynamic simulation).

column | type | unit | restriction
------------- | ------- | ----- | ------------------------
subgrid_id | Int32 | - | sorted
node_id | Int32 | - | constant per subgrid_id
basin_level | Float64 | $m$ | sorted per subgrid_id
subgrid_level | Float64 | $m$ | sorted per subgrid_id
column | type | unit | restriction
------------- | ------- | ------------ | ------------------------
subgrid_id | Int32 | - | sorted
node_id | Int32 | - | constant per subgrid_id
basin_level | Float64 | $\text{m}$ | sorted per subgrid_id
subgrid_level | Float64 | $\text{m}$ | sorted per subgrid_id

The table below shows example input for two subgrid elements:

Expand All @@ -394,33 +394,33 @@ Generally, to create physically meaningful subgrid water levels, the subgrid tab
## Concentration {#sec-basin-conc}
This table defines the concentration(s) of (a) substance(s) for the inflow boundaries of a Basin node.

column | type | unit | restriction
------------- | -------- | --------------- | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | | can correspond to known Delwaq substances
drainage | Float64 | $g m^{-3}$ | (optional)
precipitation | Float64 | $g m^{-3}$ | (optional)
column | type | unit | restriction
------------- | -------- | ------------------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | | can correspond to known Delwaq substances
drainage | Float64 | $\text{g}/\text{m}^3$ | (optional)
precipitation | Float64 | $\text{g}/\text{m}^3$ | (optional)

## ConcentrationState {#sec-basin-conc-state}
This table defines the concentration(s) of (a) substance(s) in the basin at the start of the simulation.

column | type | unit | restriction
-------------- | -------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $g m^{-3}$ |
column | type | unit | restriction
-------------- | -------- | ------------------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $\text{g}/\text{m}^3$ |

## ConcentrationExternal
This table is used for (external) concentrations, that can be used for Control lookups.

column | type | unit | restriction
-------------- | -------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $g m^{-3}$ |
column | type | unit | restriction
-------------- | -------- | ------------------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $\text{g}/\text{m}^3$ |

# Equations

Expand Down Expand Up @@ -520,7 +520,7 @@ $$
Q_\text{inf} = \sum_{i=1}^{n} \sum_{j=1}^{m} \max(Q_{\mathrm{mf6}_{i,j}}, 0.0)
$$ {#eq-inf}
Where $i$ is the index of the boundary condition, $j$ the MODFLOW 6 cell index, $n$ the number of boundary conditions, and $m$ the number of MODFLOW 6 cells in the Basin.
Where $i$ is the index of the boundary condition, $j$ the MODFLOW 6 cell index, $n$ the number of boundary conditions, and $\text{m}$ the number of MODFLOW 6 cells in the Basin.
$Q_{\mathrm{mf6}_{i,j}}$ is the flow computed by MODFLOW 6 for cell $j$ for boundary condition $i$.
Drainage is a lump sum for the Basin, and consists of the sum of the absolute value of all **negative** flows of the MODFLOW 6 boundary conditions in the Basin.
Expand Down
16 changes: 8 additions & 8 deletions docs/reference/node/continuous-control.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,14 @@ $$

which can be for instance an average or a difference of variables. If a variable comes from a timeseries, a look ahead $\Delta t$ can be supplied. There is only one compound variable per `ContinuousControl` node.

column | type | unit | restriction
-------------------- | -------- | ------- | -----------
node_id | Int32 | - | sorted
listen_node_type | String | - | known node type
listen_node_id | Int32 | - | sorted per node_id
variable | String | - | must be "level" or "flow_rate", sorted per listen_node_id
weight | Float64 | - | (optional, default 1.0)
look_ahead | Float64 | $s$ | Only on transient boundary conditions, non-negative (optional, default 0.0).
column | type | unit | restriction
-------------------- | -------- | ---------- | -----------
node_id | Int32 | - | sorted
listen_node_type | String | - | known node type
listen_node_id | Int32 | - | sorted per node_id
variable | String | - | must be "level" or "flow_rate", sorted per listen_node_id
weight | Float64 | - | (optional, default 1.0)
look_ahead | Float64 | $\text{s}$ | Only on transient boundary conditions, non-negative (optional, default 0.0).

## Function

Expand Down
18 changes: 9 additions & 9 deletions docs/reference/node/discrete-control.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,15 +46,15 @@ $$

which can be for instance an average or a difference of variables. If a variable comes from a time-series, a look ahead $\Delta t$ can be supplied.

column | type | unit | restriction
-------------------- | -------- | ------- | -----------
node_id | Int32 | - | sorted
compound_variable_id | Int32 | - | sorted per node_id
listen_node_type | String | - | known node type
listen_node_id | Int32 | - | sorted per node_id
variable | String | - | must be "level" or "flow_rate", sorted per listen_node_id
weight | Float64 | - | (optional, default 1.0)
look_ahead | Float64 | $s$ | Only on transient boundary conditions, non-negative (optional, default 0.0).
column | type | unit | restriction
-------------------- | -------- | -----------| -----------
node_id | Int32 | - | sorted
compound_variable_id | Int32 | - | sorted per node_id
listen_node_type | String | - | known node type
listen_node_id | Int32 | - | sorted per node_id
variable | String | - | must be "level" or "flow_rate", sorted per listen_node_id
weight | Float64 | - | (optional, default 1.0)
look_ahead | Float64 | $\text{s}$ | Only on transient boundary conditions, non-negative (optional, default 0.0).

These variables can be listened to:
- The level of a Basin
Expand Down
36 changes: 18 additions & 18 deletions docs/reference/node/flow-boundary.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ It can be used as a boundary condition like a measured upstream flow rate, or la

We require that the edge connecting the FlowBoundary to the Basin should point towards the Basin,
so that positive flow corresponds to water being added to the model.
The set flow rate will be pumped unless the intake storage (for a negative flow rate) is less than $10~m^3$,
in which case the flow rate will be linearly reduced to $0~m^3/s$.
The set flow rate will be pumped unless the intake storage (for a negative flow rate) is less than $10~\text{ m}^3$,
in which case the flow rate will be linearly reduced to $0~\text{ m}^3/s$.
Note that the connected node must always be a Basin.

column | type | unit | restriction
------------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
active | Bool | - | (optional, default true)
flow_rate | Float64 | $m^3 s^{-1}$ | non-negative
column | type | unit | restriction
------------- | ------- | --------------------- | -----------
node_id | Int32 | - | sorted
active | Bool | - | (optional, default true)
flow_rate | Float64 | $\text{m}^3/\text{s}$ | non-negative

## Time

Expand All @@ -31,21 +31,21 @@ flow rate is interpolated linearly, and outside the flow rate is constant given
nearest time value.
Note that a `node_id` can be either in this table or in the static one, but not both.

column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
flow_rate | Float64 | $m^3 s^{-1}$ | non-negative
column | type | unit | restriction
--------- | ------- | --------------------- | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
flow_rate | Float64 | $\text{m}^3/\text{s}$ | non-negative

## Concentration {#sec-flow-boundary-conc}
This table defines the concentration(s) of (a) substance(s) for the flow from the FlowBoundary.

column | type | unit | restriction
-------------- | -------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $g m^{-3}$ |
column | type | unit | restriction
-------------- | -------- | --------------------- | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $\text{g}/\text{m}^3$ |

# Equations

Expand Down
22 changes: 11 additions & 11 deletions docs/reference/node/flow-demand.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,20 @@ FlowDemand nodes can set a flow demand only for a single connector node.

## Static

column | type | unit | restriction
------------- | -------- | ------------ | -----------
node_id | Int32 | - | sorted
priority | Int32 | - | positive
demand | Float64 | $m^3 s^{-1}$ | non-negative
column | type | unit | restriction
------------- | -------- | --------------------- | -----------
node_id | Int32 | - | sorted
priority | Int32 | - | positive
demand | Float64 | $\text{m}^3/\text{s}$ | non-negative

## Time

This table is the transient form of the `FlowDemand` table, in which a time-dependent demand can be supplied.
Similar to the static version, only a single priority per `FlowDemand` node can be provided.

column | type | unit | restriction
------------- | -------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
priority | Int32 | - | positive
demand | Float64 | $m^3 s^{-1}$ | non-negative
column | type | unit | restriction
------------- | -------- | --------------------- | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
priority | Int32 | - | positive
demand | Float64 | $\text{m}^3/\text{s}$ | non-negative
16 changes: 8 additions & 8 deletions docs/reference/node/level-boundary.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ column | type | unit | restriction
------------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
active | Bool | - | (optional, default true)
level | Float64 | $m$ | -
level | Float64 | $\text{m}$ | -

## Time

Expand All @@ -31,17 +31,17 @@ column | type | unit | restriction
--------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
level | Float64 | $m$ | -
level | Float64 | $\text{m}$ | -

## Concentration {#sec-level-boundary-conc}
This table defines the concentration(s) of (a) substance(s) for the flow from the LevelBoundary.

column | type | unit | restriction
-------------- | -------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $g m^{-3}$ |
column | type | unit | restriction
-------------- | -------- | --------------------- | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node_id
substance | String | - | can correspond to known Delwaq substances
concentration | Float64 | $\text{g}/\text{m}^3$ |

# Equations

Expand Down
8 changes: 4 additions & 4 deletions docs/reference/node/level-demand.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ If both are missing, `LevelDemand` won't have any effects on allocation.
column | type | unit | restriction
------------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
min_level | Float64 | $m$ | (optional, default -Inf)
max_level | Float64 | $m$ | (optional, default Inf)
min_level | Float64 | $\text{m}$ | (optional, default -Inf)
max_level | Float64 | $\text{m}$ | (optional, default Inf)
priority | Int32 | - | positive

## Time
Expand All @@ -33,6 +33,6 @@ column | type | unit | restriction
------------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
time | DateTime | - | sorted per node id
min_level | Float64 | $m$ | -
max_level | Float64 | $m$ | -
min_level | Float64 | $\text{m}$ | -
max_level | Float64 | $\text{m}$ | -
priority | Int32 | - | positive
14 changes: 7 additions & 7 deletions docs/reference/node/linear-resistance.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ Bidirectional flow proportional to the level difference between the connected ba

## Static

column | type | unit | restriction
------------- | ------- | ------------ | -----------
node_id | Int32 | - | sorted
control_state | String | - | (optional) sorted per node_id
active | Bool | - | (optional, default true)
resistance | Float64 | $sm^{-2}$ | -
max_flow_rate | Float64 | $m^3 s^{-1}$ | non-negative
column | type | unit | restriction
------------- | ------- | --------------------- | -----------
node_id | Int32 | - | sorted
control_state | String | - | (optional) sorted per node_id
active | Bool | - | (optional, default true)
resistance | Float64 | $\text{s}/\text{m}^2$ | -
max_flow_rate | Float64 | $\text{m}^3/s$ | non-negative

# Equations

Expand Down
Loading

0 comments on commit 1943a19

Please sign in to comment.