Add FlowDemand node type

[SouthEndMusic]

Fixes #78.

[SouthEndMusic]

I've updated addnode.qmd as I went trough it, I'm not sure everything is now accurate. The description at the bottom of what happens when running pixi run codegen is probably outdated now, but that should be updated by someone else. More generally, would it be a good idea to have a (developer) docs page about all available pixi commands?

[SouthEndMusic]

Could there be conflicting/changing code formatting? Since my latest commit contains formatting changes to lines of code I didn't touch.

[SouthEndMusic]

Concept of flow demand within an optimization problem

1. Flow conservation constraint of a node with a flow demand at priority other than the flow demand priority ($p \ne p_\text{fd}$):

$$ F_\text{flow out} = F_\text{flow in} + F_\text{buffer out} $$

where the value of $F_\text{buffer out}$ is bounded from above by the capacity of the buffer, which is set to $0.0$ before the optimization for the first priority.

2. Flow conservation constraint of a node with a flow demand at the flow demand priority ($p = p_\text{fd}$):

$$ F_\text{buffer in} = F_\text{flow in} $$

where $F_\text{buffer in}$ is set as the capacity of the buffer (which is bounded from above by the flow demand) after optimization for this priority. $|F_\text{buffer in} - d|$ is added as a term to the objective function. Here $d = 0$ when $p \ne p_\text{fd}$ and when $p=p_\text{fd}$ then $d$ is what is left of the flow demand after subtracting the flows trough the node with demands at $p < p_\text{fd}$.

3. The above can be combined into:

$$ F_\text{flow out} + F_\text{buffer in} = F_\text{flow in} + F_\text{buffer out} $$

This constraint can exist unmodified as a combination of 1. and 2. because:

• For $p \ne p_\text{fd}$ we have that $F_\text{buffer in} = 0$ because $d = 0$ in the objective function;
• For $p = p_\text{fd}$ we have that $F_\text{buffer out} = 0$ because the buffer capacity at that point is still $0.0$ and $F_\text{flow out} = 0$ because we can constrain it that way.

It must be noted that the choice to do it in this way makes it potentially hard in the future to allow flow demands for multiple priorities for the same node.

Concept of the user demand within an optimization problem

This is slightly different from the flow demand, because the user does not act as a 'conductor' of flow in the absence of demand. Therefore we can just add a buffer capacity constraint on the user outflow edge variable and add to this buffer the return fraction of the abstraction of the user.

Note that with this concept we are not all the way there when it comes to avoiding circular flows:

• We do prevent that the optimizer makes up flow out of nothing by letting a user use its own return flow from the same priority, so the water balance aspect of the problem is solved;
• We do not prevent that a user uses its own return flow at all, since the same user can still use the return flow from one priority as abstraction in a later priority.

To do

• Initialize the described variables (also the ones needed for absolute values)
• Update the flow conservation equation to the one above
• Add the term to the objective function (preferably after merging of Deleted relevant code of alternative object functions in Ribasim python and core #1199)
• Set the demand for the flow demand as described above
• Add the capacity to the outflow that is $\infty$ for $p \ne p_{\text{fd}}$ and $0.0$ otherwise
• Make new issue for update of user behavior: UserDemand outflow source #1212
• Add tests of optimization behavior
• Add docstrings to complex functions
• Update allocation documentation

[Huite]

Just drive-by review: would be good to break these into shorter functions.