TabulatedRatingCurve

A TabulatedRatingCurve determines outflow from a Basin by looking up the flow rate that corresponds to the current upstream level from a rating curve. The TabulatedRatingCurve takes a rating curve as input. Use it for instance to model flow over a weir.

1 Tables

1.1 Static

column	type	unit	restriction
node_id	Int32	-
control_state	String	-	(optional)
active	Bool	-	(optional, default true)
max_downstream_level	Float64	\(\text{m}\)	(optional)
level	Float64	\(\text{m}\)	unique
flow_rate	Float64	\(\text{m}^3/\text{s}\)	start at 0, increasing

1.1.1 Interpolation

The \(Q(h)\) relationship of a tabulated rating curve is defined as a linear interpolation.

Code

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from IPython.display import display, Markdown

fontsize = 15

level = [12.0, 12.2, 12.5, 13.0]
flow = [0.0, 0.5, 2.5, 8.0]
fig, ax = plt.subplots()
ax.set_xticks([])
ax.set_yticks([0])
ax.scatter(level, flow, label = "data")
ax.plot(level, flow, label = "interpolation", color = "C0")
ax.plot([level[0] - 0.2, level[0]], [0, 0], label = "extrapolation", linestyle = "dashed")
ax.legend()
ax.set_xlabel("level", fontsize = fontsize)
ax.set_ylabel("flow", fontsize = fontsize)

level_extrap = 2 * level[-1] - level[-2]
flow_extrap = 2 * flow[-1] - flow[-2]
ax.plot([level[-1], level_extrap], [flow[-1], flow_extrap], color = "C0", linestyle = "dashed")
ax.set_xlim(level[0] - 0.2, (level[-1] + level_extrap)/2)

markdown_table = pd.DataFrame(
        data = {
            "level" : level,
            "flow" : flow
        }
    ).to_markdown(index = False)

display(Markdown(markdown_table))

level	flow
12	0
12.2	0.5
12.5	2.5
13	8

Below the lowest given level of 12.0, the flow rate is kept at 0. Between given levels the flow rate is interpolated linearly. Above the maximum given level of 13.0, the flow rate keeps increases linearly according to the slope of the last segment.

For tabulated rating curves with a fixed maximum value (e.g. max capacity of a weir), enter a new row and re-enter the maximum flow_rate at a higher level:

node_id	level	flow_rate
2	12.0	0.0
2	12.2	0.5
2	12.5	2.5
2	13.0	8.0
2	13.1	8.0

Now this tabulated rating curve node has a flow rate of 8.0 \(\text{m}^3/\text{s}\) for for all levels 13.0 or higher.

The flow rate is not allowed to decrease with higher levels. If you wish to e.g. simulate the (partial) closing of a weir when the water level exceeds a certain threshold, you can use and Outlet with a control node to set flow rates.

1.2 Time

This table is the transient form of the TabulatedRatingCurve table. The only difference is that a time column is added. With this the rating curves can be updated over time. The max_downstream_level currently cannot be updated 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	-
time	DateTime	-
level	Float64	\(\text{m}\)
flow_rate	Float64	\(\text{m}^3/\text{s}\)	non-negative
max_downstream_level	Float64	\(\text{m}\)	(optional)

2 Equations

The TabulatedRatingCurve is a tabulation of a Basin’s discharge behavior. It describes a piecewise linear relationship between the Basin’s level and its discharge. It can be understood as an empirical description of a Basin’s properties. This can include a weir, but also the lumped hydraulic behavior of the upstream channels.

\[ Q = \phi f(h) \]

Where:

\(h\) is the upstream water level
\(f\) is a piecewise linear function describing the given rating curve \(Q(h)\)
\(\phi\) is the reduction factor, which smoothly reduces flow based on all of these criteria:
- The upstream volume is below the equivalent of a water depth of \(10 \;\text{cm}\).
- The upstream level is less than \(0.02 \;\text{m}\) above the downstream level.
- The downstream level is above max_downstream_level - \(0.02 \;\text{m}\)