From 49149307c51ee7b8e0ea08f30873e55679b5a063 Mon Sep 17 00:00:00 2001 From: Bart de Koning Date: Fri, 10 Nov 2023 17:10:32 +0100 Subject: [PATCH 1/3] diagram draft --- docs/core/allocation.qmd | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/core/allocation.qmd b/docs/core/allocation.qmd index 35f09279a..0a2ed05fc 100644 --- a/docs/core/allocation.qmd +++ b/docs/core/allocation.qmd @@ -6,6 +6,34 @@ Allocation is the process of assigning an allocated abstraction flow rate to use The allocation problem is solved per subnetwork of the Ribasim model, from which a new graph is created called the allocation graph. The allocation graph is used to formulate an optimization problem with the [JuMP](https://jump.dev/JuMP.jl/stable/) package, which is solved using the [HiGHS solver](https://highs.dev/). For more information see also the example of solving the maximum flow problem with `JuMP.jl` [here](https://jump.dev/JuMP.jl/stable/tutorials/linear/network_flows/#The-max-flow-problem). +```{mermaid} +sequenceDiagram + participant Sim as Process: Ribasim simulation + participant Param as Data: Parameters + participant State as Data: State + participant Optim as process: Allocation optimization + loop Simulation timestep, several times + State-->>Sim: Input + Param-->>Sim: Input + Sim-->>Param: Parameter updates by control + activate Sim + Sim->>Sim: Compute flows over edges per node type + Sim-->>Param: Set flows + Sim->>Sim: Time integration step + Sim-->>State: Update state + deactivate Sim + end + loop Allocation optimization, per allocation network + Param-->>Optim: Input + activate Optim + State-->>Optim: Input + Optim->>Optim: Optimize basin allocations if below target level + Optim->>Optim: Optimize user allocation, per priority + Optim-->>Param: Set allocated flow rates + deactivate Optim + end +``` + # The allocation problem The following data of the parameters and state of a Ribasim model are relevant for the allocation problem. From 457750a5b83a9a62902f7a5edd41535552aec9fd Mon Sep 17 00:00:00 2001 From: Bart de Koning Date: Mon, 13 Nov 2023 12:01:56 +0100 Subject: [PATCH 2/3] Move and update diagram --- docs/core/allocation.qmd | 28 ---------------------------- docs/core/index.qmd | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 28 deletions(-) diff --git a/docs/core/allocation.qmd b/docs/core/allocation.qmd index 0a2ed05fc..35f09279a 100644 --- a/docs/core/allocation.qmd +++ b/docs/core/allocation.qmd @@ -6,34 +6,6 @@ Allocation is the process of assigning an allocated abstraction flow rate to use The allocation problem is solved per subnetwork of the Ribasim model, from which a new graph is created called the allocation graph. The allocation graph is used to formulate an optimization problem with the [JuMP](https://jump.dev/JuMP.jl/stable/) package, which is solved using the [HiGHS solver](https://highs.dev/). For more information see also the example of solving the maximum flow problem with `JuMP.jl` [here](https://jump.dev/JuMP.jl/stable/tutorials/linear/network_flows/#The-max-flow-problem). -```{mermaid} -sequenceDiagram - participant Sim as Process: Ribasim simulation - participant Param as Data: Parameters - participant State as Data: State - participant Optim as process: Allocation optimization - loop Simulation timestep, several times - State-->>Sim: Input - Param-->>Sim: Input - Sim-->>Param: Parameter updates by control - activate Sim - Sim->>Sim: Compute flows over edges per node type - Sim-->>Param: Set flows - Sim->>Sim: Time integration step - Sim-->>State: Update state - deactivate Sim - end - loop Allocation optimization, per allocation network - Param-->>Optim: Input - activate Optim - State-->>Optim: Input - Optim->>Optim: Optimize basin allocations if below target level - Optim->>Optim: Optimize user allocation, per priority - Optim-->>Param: Set allocated flow rates - deactivate Optim - end -``` - # The allocation problem The following data of the parameters and state of a Ribasim model are relevant for the allocation problem. diff --git a/docs/core/index.qmd b/docs/core/index.qmd index daeb53b2b..ab2638d3f 100644 --- a/docs/core/index.qmd +++ b/docs/core/index.qmd @@ -16,3 +16,37 @@ can be found in the [Ribasim repository](https://github.com/Deltares/Ribasim) un %%| file: ../assets/c4_component_ribasim.mmd %%| fig-cap: "Component overview of Ribasim" ``` + +# The simulation loop + +`Ribasim.jl` in the above figure can be divided into 3 parts: + +- Model initialization +- Running the simulation loop +- Writing the output files + +The figure below gives a more detailed description of the simulation loop in the form of a [sequence diagram](https://en.wikipedia.org/wiki/Sequence_diagram). + +```{mermaid} +sequenceDiagram + participant Sim as Process: Ribasim simulation + participant Param as Data: Parameters + participant State as Data: State + participant Optim as Process: Allocation optimization + loop Simulation loop (OrdinaryDiffEq.jl) + opt if allocation timestep has passed:
Allocation optimization, per allocation network (JuMP.jl, HiGHS) + Param-->>Optim: Input + State-->>Optim: Input + Optim->>Optim: Optimize Basin allocations if below target level + Optim->>Optim: Optimize User allocation, per priority + Optim-->>Param: Set allocated flow rates + end + State-->>Sim: Input + Param-->>Sim: Input + Sim-->>Param: Parameter updates by control + Sim->>Sim: Compute flows over edges per node type + Sim-->>Param: Set flows + Sim->>Sim: Time integration step + Sim-->>State: Update state + end +``` From dc3559ed2589e9773a8345fb2dcc5dc8e71e1239 Mon Sep 17 00:00:00 2001 From: Bart de Koning Date: Tue, 14 Nov 2023 11:20:26 +0100 Subject: [PATCH 3/3] Update diagram and its description --- docs/core/index.qmd | 63 +++++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/docs/core/index.qmd b/docs/core/index.qmd index ab2638d3f..167feb357 100644 --- a/docs/core/index.qmd +++ b/docs/core/index.qmd @@ -25,28 +25,59 @@ can be found in the [Ribasim repository](https://github.com/Deltares/Ribasim) un - Running the simulation loop - Writing the output files -The figure below gives a more detailed description of the simulation loop in the form of a [sequence diagram](https://en.wikipedia.org/wiki/Sequence_diagram). +The figure below gives a more detailed description of the simulation loop in the form of a [sequence diagram](https://en.wikipedia.org/wiki/Sequence_diagram). From top to bottom, it contains the following blocks: + +- Allocation optimization; activated when the allocation timestep has been passed; +- Control actions; activated when some discrete control callback is triggered; +- Water balance; computing the flows over flow edges happens each timestep; +- Time integration step; Done by the selected integrator from `OrdinaryDiffEq.jl`. ```{mermaid} sequenceDiagram - participant Sim as Process: Ribasim simulation + autonumber + participant Int as Process: Integrator + participant Optim as Process: Allocation optimization participant Param as Data: Parameters participant State as Data: State - participant Optim as Process: Allocation optimization + participant Sim as Process: Water balance loop Simulation loop (OrdinaryDiffEq.jl) - opt if allocation timestep has passed:
Allocation optimization, per allocation network (JuMP.jl, HiGHS) - Param-->>Optim: Input - State-->>Optim: Input - Optim->>Optim: Optimize Basin allocations if below target level - Optim->>Optim: Optimize User allocation, per priority - Optim-->>Param: Set allocated flow rates + activate Int + %% Allocation + rect rgb(200, 200, 200) + opt Allocation optimization, per allocation network (JuMP.jl, HiGHS) + activate Optim + Int->>Optim: Callback: allocation timestep has passed + Param-->>Optim: Input + State-->>Optim: Input + Optim->>Optim: Optimize Basin allocations if below target level + Optim->>Optim: Optimize User allocation, per priority + Optim-->>Param: Set allocated flow rates + deactivate Optim + end + end + %% Control + rect rgb(200, 200, 200) + opt Control actions + Int->>Int: DiscreteControl callback + Int-->>Param: Parameter updates by control + end + end + %% water_balance! + rect rgb(200, 200, 200) + activate Sim + State-->>Sim: Input + Param-->>Sim: Input + Sim->>Sim: Compute flows over edges per node type + Sim-->>Param: Set flows + deactivate Sim + end + %% Time integration + rect rgb(200, 200, 200) + State-->>Int: Input + Param-->>Int: Input + Int->>Int: Time integration step + Int-->>State: Update state end - State-->>Sim: Input - Param-->>Sim: Input - Sim-->>Param: Parameter updates by control - Sim->>Sim: Compute flows over edges per node type - Sim-->>Param: Set flows - Sim->>Sim: Time integration step - Sim-->>State: Update state + deactivate Int end ```