Docs update

docs/core/allocation.qmd

@@ -40,7 +40,7 @@ The allocation problem is solved per subnetwork, which is given by a subset $S \
 
 Sources are indicated by a set of edges in the subnetwork
 $$
-E_S^\text{source} \subset \left(S \times S\right) \cap E.
+E_S^\text{source} \subset E.
 $$
 That is, if $(i,j) \in E_S^\text{source}$, then $Q_{ij}$ (see the [formal model description](equations.qmd#formal-model-description)) is treated as a source flow in the allocation problem. These edges are either coming from a boundary/source node (e.g. a level or flow boundary) or connect the main network to a subnetwork.
 
@@ -49,15 +49,15 @@ That is, if $(i,j) \in E_S^\text{source}$, then $Q_{ij}$ (see the [formal model
 The subnetwork contains a subset of UserDemand nodes $U_S \subset S$, who all have static or time varying demands over various priorities $p$:
 $$
     d^p_i(t), \quad i \in U_S, p = 1,2,\ldots, p_{\max}.
-$$ However, in
+$$
 
 :::{.callout-note}
-On this page we assume that the priorities are given by all integers from $1$ to some $p_{\max} \in \mathbb{N}$.the Ribasim input this is not a requirement; some of these in between priority values can be missing, only the ordering of the given priorities is taken into account.
+On this page we assume that the priorities are given by all integers from $1$ to some $p_{\max} \in \mathbb{N}$. For the Ribasim input this is not a requirement; some of these in between priority values can be missing, only the ordering of the given priorities is taken into account.
 :::
 
 ### Flow demands
 
-The subnetwork contains a subset of nodes $FD_S \in S$ which have a demand of a single priority $p_{\text{fd}}$. With this we define
+The subnetwork contains a subset of nodes $FD_S \subset S$ which have a demand of a single priority $p_{\text{fd}}$. With this we define
 $$
     d^p_i(t) =
     \begin{cases}
@@ -93,35 +93,24 @@ for all $i \in B_S$. Here $\Delta t_{\text{alloc}}$ is the simulated time betwee
 ### Constraining factors
 
 #### Flow magnitude and direction constraints
-Nodes in the Ribasim model that have a `max_flow_rate`, i.e. pumps and outlets, put a constraint on the flow through that node. Some nodes only allow flow in one direction, like pumps, outlets and tabulated rating curves.
+Nodes in the Ribasim model that have a `max_flow_rate`, i.e. pumps, outlets and linear resistances, put a constraint on the flow through that node. Some nodes only allow flow in one direction, like pumps, outlets and tabulated rating curves.
 
 #### FractionalFlow and UserDemand return flows
-Both FractionalFlow and UserDemand nodes dictate proportional relationships between flows over edges in the subnetwork. UserDemands have a return factor $0 \le r_i \le 1, i \in U_S$.
-
-## The allocation network
-
-A new graph is created from the subnetwork, which we call an allocation network. The allocation network is almost a subgraph of the main (flow) model, apart from the fact that an allocation network can contain edges which are a combination of multiple edges in the main model.
-
-### Nodes and edges
-
-The allocation network consists of:
+Both FractionalFlow and UserDemand nodes dictate proportional relationships between flows over edges in the subnetwork. UserDemands have a return factor $0 \le r_i \le 1, i \in U_S$. and Fractional Flow nodes have an associated fraction $f_j$ which can be updated by DiscreteControl.
 
-- Nodes $V'_S \subset V_S$. Nodes that are represented in the allocation network are:
-nodes of type `Basin`, `UserDemand` and `Terminal`, nodes that have `FractionalFlow` downstream neighbors, nodes that have a flow demand and nodes that are connected to a source edge.
-- Edges $E_S$, which are either edges that also appear between nodes in the subnetwork or represent a sequence of those, creating a shortcut.
+## The subnetwork
+The subnetwork consists of a set of nodes $S \subset V$ and edges
 
-For notational convenience, we use the notation
-
-\begin{align}
-    V^{\text{out}}_S(i) = \left\{j \in V'_S : (i,j) \in E_S\right\} \\
-    V^{\text{in}}_S(j) = \left\{i \in V'_S : (i,j) \in E_S\right\}
-\end{align}
+$$
+    E_S = (S \times S) \cup E_S^\text{source},
+$$
 
-for the set of in-neighbors and out-neighbors of a node in the allocation network respectively.
+i.e. the edges that lie within the subnetwork together with the source edges (which can be partially outside the subnetwork).
+The nodes in $S$ together with the connected nodes outside the subnetwork are called the extended subnetwork.
 
 ### Capacities
 
-Each edge in the allocation network has an associated capacity. These capacities are collected in the sparse capacity matrix $C_S \in \overline{\mathbb{R}}_{\ge 0}^{n'\times n'}$ where $n' = \#V'_S$ is the number of nodes in the allocation network. The capacities can be infinite, if there is nothing in the model constraining the capacity of the edge.
+Each edge in the subnetwork has an associated capacity. These capacities are collected in the sparse capacity matrix $C_S \in \overline{\mathbb{R}}_{\ge 0}^{n\times n}$ where $n$ is the number of nodes in the extended subnetwork. The capacities can be infinite, if there is nothing in the model constraining the capacity of the edge.
 
 The capacities are determined in different ways:
 
@@ -144,7 +133,7 @@ The optimization problem for a subnetwork is a linear optimization problem consi
 
 There are several types of variable whose value has to be determined to solve the allocation problem:
 
-- The flows $F \in \mathbb{R}_{\ge 0}^{n'\times n'}$ over the edges in the allocation network;
+- The flows $F \in \mathbb{R}_{\ge 0}^{n\times n}$ over the edges in the allocation network;
 - The flows $F^\text{basin out}_{i}, F^\text{basin in}_{i} \geq 0$ for all $i \in B_S$ supplied and consumed by the basins respectively;
 - The flows $F^\text{buffer out}_{i}, F^\text{buffer in}_{i} \ge 0$ for all $i \in FD_S$ supplied and consumed by the flow buffers of nodes with a flow demand respectively.
 
@@ -162,7 +151,7 @@ $$
 $$
 
 :::{.callout-note}
-When performing main network allocation, the connections to subnetworks are also interpreted as UserDemand with demands determined by subnetwork demand collection.
+When performing main network allocation, the connections to subnetworks are also interpreted as UserDemand nodes with demands determined by subnetwork demand collection.
 :::
 
 This type of objective cares about the absolute amount of water allocated to a demand. It treats all deviations equally which means it doesn't give larger punishment per flow unit if deviations increase.
@@ -180,6 +169,16 @@ $$
 $$
 
 ## The optimization constraints
+
+For convenience, we use the notation
+
+\begin{align}
+    V^{\text{out}}_S(i) = \left\{j \in V : (i,j) \in E_S\right\} \\
+    V^{\text{in}}_S(j) = \left\{i \in V : (i,j) \in E_S\right\}
+\end{align}
+
+for the set of in-neighbors and out-neighbors of a node in the allocation network respectively.
+
 - Flow conservation: For the basins in the allocation network we have that
 $$
     F^\text{basin in}_k + \sum_{j \in V^{\text{out}}_S(k)} F_{kj} = F^\text{basin out}_k + \sum_{i \in V^{\text{in}}_S(k)} F_{ik}, \quad \forall k \in B_S .

docs/core/usage.qmd

@@ -624,8 +624,6 @@ node_id               | Int32   | -            | sorted
 
 # DisceteControl {#sec-discrete-control}
 
-DiscreteControl is implemented based on [VectorContinuousCallback](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#VectorContinuousCallback).
-
 ## DiscreteControl / variable
 
 The compound variable schema defines linear combinations of variables which can be used in conditions. This means that