# UserDemand

A UserDemand takes water from the Basin that supplies it.

When allocation is not used, a `UserDemand`

node attempts to extract the full demand from the connected Basin. When allocation is used, the amount a `UserDemand`

node is allowed to abstract is determined by the allocation algorithm. This algorithm first tries to allocate from the directly connected basin, and then from other sources whose flow can reach the `UserDemand`

node. Note that `priority`

is used to determine the order in which the UserDemands are allocated water. This parameter is only used when allocation is active and is optional when allocation is not active.

When the connected Basin is almost empty or reaches the minimum level at which the UserDemand can extract water (`min_level`

), it will stop extraction.

UserDemands need an outgoing flow edge along which they can send their return flow, this can also be to the same Basin from which it extracts water. The amount of return flow is always a fraction of the inflow into the UserDemand. The difference is consumed by the UserDemand.

# 1 Tables

## 1.1 Static

This table contains the static form of the `UserDemand`

node.

column | type | unit | restriction |
---|---|---|---|

node_id | Int32 | - | sorted |

active | Bool | - | (optional, default true) |

demand | Float64 | \(\text{m}^3/\text{s}\) | non-negative |

return_factor | Float64 | - | between [0 - 1] |

min_level | Float64 | \(\text{m}\) | - |

priority | Int32 | - | positive, sorted per node id |

## 1.2 Time

This table is the transient form of the `UserDemand`

table. The only difference is that a time column is added and activity is assumed to be true. The table must by sorted by time, and per time it must be sorted by `node_id`

. With this the demand can be updated over time. In between the given times the demand is interpolated linearly, and outside the demand is constant given by the nearest time value. The `priority`

is not allowed to change over time. Note that a `node_id`

can be either in this table or in the static one, but not both.

column | type | unit | restriction |
---|---|---|---|

node_id | Int32 | - | sorted |

priority | Int32 | - | positive, sorted per node id |

time | DateTime | - | sorted per priority per node id |

demand | Float64 | \(\text{m}^3/\text{s}\) | non-negative |

return_factor | Float64 | - | between [0 - 1] |

min_level | Float64 | \(\text{m}\) | - |

## 1.3 Concentration

This table defines the concentration of substances for the flow from the UserDemand.

column | type | unit | restriction |
---|---|---|---|

node_id | Int32 | - | sorted |

time | DateTime | - | sorted per node_id |

substance | String | - | can correspond to known Delwaq substances |

concentration | Float64 | \(\text{g}/\text{m}^3\) |

# 2 Equations

UserDemand receive an allocated flow rate \(F^p\) per priority \(p=1,2,\ldots, p_{\max}\), which is either determined by allocation optimization or simply equal to the demand at time \(t\); \(F^p = d^p(t)\). The realized abstraction rate of a UserDemand is given by \[ Q_\text{in} = \phi(u, 10.0)\phi(h-l_{\min}, 0.1)\sum_{p=1}^{p_{\max}} \min\left(F^p, d^p(t)\right). \]

From left to right:

- The first reduction factor lets the UserDemand abstraction go smoothly to \(0\) as the source Basin dries out;
- The second reduction factor lets the UserDemand abstraction go smoothly to \(0\) as the source Basin level approaches the minimum source Basin level (from above);
- The last term is the sum of the allocations over the priorities. If the current demand happens to be lower than the allocation at some priority, the demand is taken instead.

UserDemands also have a return factor \(0 \le r \le 1\), which determines the return flow (outflow) of the UserDemand:

\[ Q_\text{out} = r \cdot Q_\text{in}. \]

Note that this means that the UserDemand has a consumption rate of \((1-r)Q_\text{in}\).