Water supply/demand by basins in allocation (new node type LevelDemand)

[SouthEndMusic]

Fixes #564.

[SouthEndMusic]

To do:

• In stead of a single reference level, introduce a window;
• Split allocation.jl into allocation_init.jl and allocation_optim.jl;
• Potentially change the name of the new node type to something shorter;
• Add variables for flow into and out of the basins

$$ F_i^\text{basin in}, F_i^\text{basin out} \geq 0 \quad \forall i \in B_S $$

• Update flow conservation constraints with basin flows;
• Add capacity constraints on the basin flows, where the initial capacity is given by

$$ F_i^\text{basin out} \leq \max\left(0.0,\frac{u_i - V^\max}{\Delta t} + \phi_i(t)\right) \quad \forall i \in B_S $$

where $\Delta t$ is the allocation time step, $V^\max$ is the volume in the basin at its maximum level and $\phi_i$ is the sum of the vertical fluxes of the basin as introduced in the allocation documentation.

• At the priority of the AllocationTarget node, if there is a shortage situation, e.g. there is a positive demand

$$ d_i = \max\left(0.0, \frac{u_i - V^\min}{\Delta t} - \phi_i(t)\right), $$

add this as a term to the objective function comparing it to $F_i^\text{basin in}$.

• Fix existing tests;
• Is it useful to define F_basin_in and F_basin_out for basins that have no min/max level? In that case the functions get_basin_inflow and get_basin_outflow are redundant.
• Add new tests;
• Update usage documentation;
• Update theory documentation.

As a side note, I am not completely happy with the conversion from volumes to flows by dividing by $\Delta t$ here. What this choice means is that the optimization assumes that all supply/demand of a basin is resolved in the time until the next allocation timepoint. What I don't like about this is that the behavior of this is strongly dependent on the choice of allocation time interval.

[gijsber]

Hi @SouthEndMusic, just a small check. When using the vertical fluxes from the simulation, I assume you take the average or accumulation and not the instantaneous values

[SouthEndMusic]

@gijsber, good point, I currently take instantaneous values. I am somewhat aware of efforts to obtain integrated values (also requested for coupling: #1084). As far as I am aware the ball for this one is in @visr's court.

[SouthEndMusic]

To do for adding flows into basins to the objective function:

• Define absolute value variables for the flows into the basins
• Define constraints on these variables so that they act as the absolute value of the right expression
• Finish add_basin_term! by passing the proper constraints to add_objective_term!
• Properly call add_basin_term! add the end of set_objective_priority!

[SouthEndMusic]

I added some tests with this model:

The idea is that basin 2 starts with its level below the minimum level, and so user 3 will only abstract after the basin has been filled. This does work:

There are 5 stages:

1. Before the first allocation solve, the user abstracts fully (identical to when allocation is not used);
2. Between the first allocation solve and when the basin reaches its maximum level, the user does not abstract;
3. After the basin has reached its maximum level, the user abstracts fully again;
4. At some point precipitation stops, but the user can still abstract because the basin has a surplus, leading to a net decrease in basin storage;
5. The user abstracts what the flow boundary provides, the basin storage remains constant. Not exactly sure why that happens.

[visr]

Left some comments, but looks good overall. I can rename to TargetLevel in a separate PR.