Update documentation

docs/core/allocation.qmd

@@ -56,11 +56,17 @@ $$
 
 We consider fluxes into the basin to be positive and out of the basin to be negative.
 
-Secondly, there is the available water in each basin above the minimum level $l_{\min,i}$ corresponding to a minimum storage $s_{\min,i}$:
+Secondly, there is either a supply or demand from the storage in the basin. Given a minimum elevel $\ell_{\min, i}$ and a maximum level $\ell_{\max, i}$ which correspond to a minimum storage $s_{\min, i}$ and maximum storage $s_{\max, i}$ respectively, we get a flow supply of
 $$
-    u_i(t)-s_{\min,i}, \quad \forall i \in B_S.
+    F^{\text{basin out}}_{\max, i} = \max\left(0.0, \frac{u_i(t)-s_{\max,i}}{\Delta t_{\text{alloc}}} + \phi_i(t)\right)
 $$
-Note that this value can be negative, which we interpret as a demand from the basin.
+
+and a demand of
+$$
+    d^p_i = \max\left(0.0, \frac{s_{\min,i} - u_i(t)}{\Delta t_{\text{alloc}}} - \phi_i(t)\right),
+$$
+
+for all $i \in B_S$. Here $\Delta t_{\text{alloc}}$ is the simulated time between two consecutive allocation solves. Note that the basin demand has only a single priority, so for other priorities this demand is $0$.
 
 ### Constraining factors
 
@@ -94,47 +100,50 @@ for the set of in-neighbors and out-neighbors of a node in the allocation graph
 
 Each edge in the allocation graph 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 graph. The capacities can be infinite, if there is nothing in the model constraining the capacity of the edge.
 
-The capacities are determined in 4 different ways:
+The capacities are determined in different ways:
 
 - If an edge does not exist in the allocation graph, i.e. $(i,j) \notin E_S$ for certain $1 \le i,j\le n'$, then $(C_S)_{i,j} = 0$;
 - The capacity of the edge $e \in E_S$ is given by the smallest `max_flow_rate` of the nodes along the equivalent edges in the subnetwork. If there are no nodes with a `max_flow_rate`, the edge capacity is infinite;
 - If the edge is a source, the capacity of the edge is given by the flow rate of that source.
 
+There are also capacities $C^B_S \in \mathbb{R}^b$ where $b = \# B_S$ is the number of basins, for the flow supplied by basins.
+
 # The optimization problem
 
 The optimization problem for a subnetwork is a linear optimization problem consisting of an objective function with associated constraints on a set of variables, all of which are introduced below.
 
 ## The optimization variables
 
-There are 2 types of variable whose value has to be determined to solve the allocation problem:
+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 graph;
-- The flows $F^\text{basin}_{i}$ for all $i \in B_S$ supplied (positive) or consumed (negative) by the basins.
+- 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 optimization objective
 
-:::{.callout-note}
-Currently the basin allocations are not taken into account in the implementation.
-:::
+The goal of allocation is to get the flow to nodes with demands as close as possible to these demands. To achieve this, a sum error of terms is minimized. The form of these error terms is determined by the choice of one of the supported objective function types, which are discussed further below.
 
-## The optimization objective
+$$
+    \min E_{\text{user}} + E_{\text{basin}}
+$$
 
-The goal of allocation is to get the flow to the users as close as possible to their demand. To achieve this, the following objectives are supported:
+### User demands
 
 - `quadratic_absolute`:
 $$
-    \min \sum_{(i,j)\in E_S\;:\; i\in U_S} \left( F_{ij} - d_j^p(t)\right)^2
+    E_{\text{user}} = \sum_{(i,j)\in E_S\;:\; i\in U_S} \left( F_{ij} - d_j^p(t)\right)^2
 $$
 - `quadratic_relative`:
 $$
-    \min \sum_{(i,j)\in E_S\;:\; i\in U_S} \left( 1 - \frac{F_{ij}}{d_j^p(t)}\right)^2
+    E_{\text{user}} = \sum_{(i,j)\in E_S\;:\; i\in U_S} \left( 1 - \frac{F_{ij}}{d_j^p(t)}\right)^2
 $$
 - `linear_absolute` (default):
 $$
-    \min \sum_{(i,j)\in E_S\;:\; i\in U_S} \left| F_{ij} - d_j^p(t)\right| + c \sum_{e \in E_S} F_e
+    E_{\text{user}} = \sum_{(i,j)\in E_S\;:\; i\in U_S} \left| F_{ij} - d_j^p(t)\right| + c \sum_{e \in E_S} F_e
 $$
 - `linear_relative`:
 $$
-    \min \sum_{(i,j)\in E_S\;:\; i\in U_S} \left|1 - \frac{F_{ij}}{d_j^p(t)}\right| + c \sum_{e \in E_S} F_e
+    E_{\text{user}} = \sum_{(i,j)\in E_S\;:\; i\in U_S} \left|1 - \frac{F_{ij}}{d_j^p(t)}\right| + c \sum_{e \in E_S} F_e
 $$
 
 :::{.callout-note}
@@ -158,17 +167,45 @@ The absolute value applied here is not supported in a linear programming context
 In the future new optimization objectives will be introduced, for demands of basins and priorities over sources. These will be used in combination with the above, in the form of goal programming.
 :::
 
+### Basin demands
+
+- `quadratic_absolute`:
+$$
+    E_{\text{basin}} = \sum_{i \in B_S} \left( F_i^\text{basin in} - d_i^p(t)\right)^2
+$$
+- `quadratic_relative`:
+$$
+    E_{\text{basin}} = \sum_{i \in B_S} \left( 1 - \frac{F_i^\text{basin in}}{d_i^p(t)}\right)^2
+$$
+- `linear_absolute` (default):
+$$
+    E_{\text{basin}} = \sum_{i \in B_S} \left| F_i^\text{basin in} - d_i^p(t)\right|
+$$
+- `linear_relative`:
+$$
+    E_{\text{basin}} = \sum_{i \in B_S} \left|1 - \frac{F_i^\text{basin in}}{d_i^p(t)}\right|
+$$
+
 ## The optimization constraints
 - Flow conservation: For the basins in the allocation graph we have that
 $$
-    \sum_{j=1}^{n'} F_{kj} \le F^\text{basin}_k + \sum_{i=1}^{n'} F_{ik}, \quad \forall k \in B_S .
+    F^\text{basin in}_k + \sum_{j=1}^{n'} F_{kj} \le F^\text{basin out}_k + \sum_{i=1}^{n'} F_{ik}, \quad \forall k \in B_S .
 $$  {#eq-flowconservationconstraint}
 Note that we do not require equality here; in the allocation we do not mind that excess flow is 'forgotten' if it cannot contribute to the allocation to the users.
+
+:::{.callout-note}
+In @eq-flowconservationconstraint, the placement of the basin flows might seem counter-intuitive. Think of the basin storage as a separate node connected to the basin node.
+:::
+
 - Capacity: the flows over the edges are positive and bounded by the edge capacity:
 $$
     F_{ij} \le \left(C_S\right)_{ij}, \quad \forall(i,j) \in E_S.
 $$ {#eq-capacityconstraint}
-By the definition of $C_S$ this also includes the source flows.
+By the definition of $C_S$ this also includes the source flows. The same holds for the basin outflows:
+
+$$
+    F^{\text{basin out}}_{i} \le F^{\text{basin out}}_{\max, i}, \quad \forall i \in B_S.
+$$
 
 :::{.callout-note}
 When performing subnetwork demand collection, these capacities are set to $\infty$ for edges which connect the main network to a subnetwork.