Improve docs home page

docs/_quarto.yml

@@ -9,8 +9,6 @@ website:
   navbar:
     logo: https://user-images.githubusercontent.com/4471859/224825908-bee7e044-bc6b-4561-8b08-5d330cce3ed5.png
     left:
-      - text: "Model concept"
-        file: modelconcept/index.qmd
       - text: "Julia core"
         file: core/index.qmd
       - text: "Python tooling"
@@ -25,14 +23,10 @@ website:
         aria-label: GitHub
 
   sidebar:
-    - title: "Model concept"
-      contents:
-        - modelconcept/index.qmd
-        - core/equations.qmd
-        - core/allocation.qmd
     - title: "Julia core"
       contents:
         - core/index.qmd
+        - core/modelconcept.qmd
         - core/usage.qmd
         - core/validation.qmd
         - core/equations.qmd

docs/contribute/core.qmd

@@ -4,70 +4,15 @@ title: "Julia core development"
 
 # Julia core overview
 
-This section is about the Julia core in `Ribasim.jl`. See the component overview [here](index.qmd) for the context of this computational core.
+The computational core is one of the components of Ribasim as illustrated in the [component overview](index.qmd##sec-components).
 
-`Ribasim.jl` can be divided into 3 parts:
+The computational process can be divided in three phases:
 
 - 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). 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 integrator from `OrdinaryDiffEq.jl`.
-
-```{mermaid, style="margin-top: 0"}
-sequenceDiagram
-    autonumber
-    participant Int as Process: Integrator
-    participant Optim as Process: Allocation optimization
-    participant Param as Data: Parameters
-    participant State as Data: State
-    participant Sim as Process: Water balance
-    loop Simulation loop (OrdinaryDiffEq.jl)
-        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
-        deactivate Int
-  end
-```
+A more detailed sequence diagram of the simulation loop is available at the [Core](./index.qmd#sec-simulationloop) home page.
 
 # Set up the developer environment
 

docs/core/index.qmd

@@ -5,37 +5,119 @@ title: "Julia core"
 With the term "core", we mean the computational engine of Ribasim. As detailed in the
 [usage](usage.qmd) documentation, it is generally used as a command line tool.
 
+A quick overview of the model concept is available at the [Home](../index.qmd#sec-conceptualization) page, while a more indepth discussion is available on the [model concept](modelconcept.qmd) page.
 The theory is described on the [equations](equations.qmd) page, and more in-depth numerical considerations are described on the [numerical considerations](numerics.qmd) page. As allocation is a large and self-contained part of the Ribasim core, it is described on the separate [allocation](allocation.qmd) page. Input validation is described on the [validation](validation.qmd) page.
 
 The core is implemented in the [Julia programming language](https://julialang.org/), and
 can be found in the [Ribasim repository](https://github.com/Deltares/Ribasim) under the
 `core/` folder. For developers we also advise to read the
 [developer documentation](../contribute/core.qmd).
 
+An overview of all components is given on the [Home page](../index.qmd#sec-components)
+
+# The simulation loop {#sec-simulationloop}
+
+The computational process can be divided in three phases:
+
+- 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). 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 integrator from `OrdinaryDiffEq.jl`.
+
 ```{mermaid}
-%%| file: ../assets/c4_component_ribasim.mmd
-%%| fig-cap: "Component overview of Ribasim"
+sequenceDiagram
+    autonumber
+    participant Int as Process: Integrator
+    participant Optim as Process: Allocation optimization
+    participant Param as Data: Parameters
+    participant State as Data: State
+    participant Sim as Process: Water balance
+    loop Simulation loop (OrdinaryDiffEq.jl)
+        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
+        deactivate Int
+  end
 ```
 
-# The simulation loop
+**Nested allocation** {#sec-nestedallocation}
+
+Since water systems may be extensive, like in the Netherlands, Ribasim models may become massive networks with multiple 10,000’s of nodes.
+To keep a proper functioning allocation concept under these circumstances, the modeller can decompose the network domain into a main network and multiple sub-networks.
+The allocation will then be conducted in three steps:
+
+1. conduct an inventory of demands from the sub-networks to inlets from the main network,
+2. allocate the available water in the main network to the subnetworks inlets,
+3. allocate the assigned water within each subnetwork to the individual water users.
 
-The figure below shows a simple flowchart of the simulation in `Ribasim.jl`.
+The users then will request this updated demand from the rule-based simulation.
+Whether this updated demand is indeed abstracted depends on all dry-fall control mechanism implemented in the rule-based simulation.
+
+The following sequence diagram illustrates this calculation process within then allocation phase.
 
 ```{mermaid}
-flowchart LR
-Start((Start))
-Init[Initialize model]
-Con[Conditional: allocation, control]
-Sim[Simulate flows over timestep]
-Finished{End of simulation period?}
-Done((Done))
-
-Start --> Init
-Init --> Con
-Con --> Sim
-Sim --> Finished
-Finished -->|no| Con
-Finished -->|yes| Done
+sequenceDiagram
+participant boundary
+participant basin
+participant user
+participant allocation_subNetwork
+participant allocation_mainNetwork
+
+user->>allocation_subNetwork: demand
+loop
+   allocation_subNetwork-->>allocation_mainNetwork: demand inventory at inlets
+end
+user->>allocation_mainNetwork: demand
+boundary->>allocation_mainNetwork: source availability
+basin->>allocation_mainNetwork: source availability
+allocation_mainNetwork-->>allocation_mainNetwork: allocate to inlets (and users)
+allocation_mainNetwork->>user: allocated
+allocation_mainNetwork->>allocation_subNetwork: allocated
+loop
+   allocation_subNetwork-->>allocation_subNetwork: allocate to users
+end
+allocation_subNetwork->>user: allocated
+user->>basin: abstracted
 ```
 
 

docs/modelconcept/index.qmd → docs/core/modelconcept.qmd

@@ -1,11 +1,12 @@
 ---
-title: Ribasim model concept
+title: Model concept
 ---
 A brief summary of the conceptualization is given on the documentation [home page](../index.qmd#sec-conceptualization)
 As indicated, the model concept is organized in three layers:
-    a physical layer representing water bodies and associated infrastructure,
-    a rule-based control layer to manage the infrastructure, and
-    a priority-based allocation layer to take centralized decisions on user abstractions.
+
+- a physical layer representing water bodies and associated infrastructure,
+- a rule-based control layer to manage the infrastructure, and
+- a priority-based allocation layer to take centralized decisions on user abstractions.
 
 # The physical layer
 ## Water balance equations
@@ -100,8 +101,36 @@ graph LR;
     P --> B["basin B"];
 ```
 
-As each (sub)basin has its own volume, low throughput (high volume, low discharge, long residence time) and high throughput (low volume, high discharge, short residence time) systems can be represented in a lumped manner; of course, more detail requires more parameters.
+As each (sub)basin has its own volume, low throughput (high volume, low discharge, long residence time) and high throughput (low volume, high discharge, short residence time) systems
+can be represented in a lumped manner; of course, more detail requires more parameters.
+
+## Structures in a water system
+In addition to free flowing waterbodies, a watersystem typically has structures to control the flow of water. Ribasim uses connector nodes which simplify the hydraulic behaviour for the
+free flowing conditions or structures.
+The following type of connector nodes are available for this purpose:
+
+- [TabulatedRatingCurve](.\usage.qmd#sec-tabulatedratingcurve): one-directional flow based on upstream head. Node type typically used for gravity flow conditions either free flowing open water channels
+or over a fixed structure.
+- [LinearResistance](.\usage.qmd#sec-linearresistance): bi-directional flow based on head difference and linear resistance. Node type typically used for bi-directional flow
+situations or situations where head difference over a structure determines its actual flow capacity.
+- [ManningResistance](.\usage.qmd#sec-manningresistance): bi-directional flow based on head difference and resistance using Manning-Gauckler formula. Same usage as LinearResistance,
+providing a better hydrological meaning to the resistance parameterization.
+- [Pump](.\usage.qmd#sec-pump): one-directional structure with a set flow rate. Node type typically used in combination with control to force water over the edge.
+- [Outlet](.\usage.qmd#sec-outlet): one-directional gravity structure with a set flow rate. Node type typically used in combination with control to force water over the edge, even if
+their is a mismatch in actual hydraulic capacity. The node type has an automated mechanism to stop the flow when the head difference is zero.
+- [FractionalFlow](.\usage.qmd#sec-fractionalflow): to split an outflow over multiple edges based on a flow fraction. Node type is typically used for diversions or bifurcations with a known and fixed ratio.
+
+The control layer can activate or deactivate nodes, set flow rates for the Pump and Outlet, or choose different parameterizations for TabulatedRatingCurve, LinearResistance, ManningResistance or FractionalFlow.
+
+Connector nodes are required within a Ribasim network to determine the flow exchange between basins.
 
 # The control layer
+## Discrete Control
+To do:
 
+## Pid Control
 To do.
+
+
+# Example situations
+To do: take example situations from the real world  and explain how they can be modelled, if possible with pro's and cons.