seasonal_levels

seasonal_levels

Summer and winter target levels (zomer- en winterpeil) in a model with one target level per Basin.

The models are built with one target level per Basin, meta_streefpeil in the Basin / area table, from which the levels of their control are derived: the thresholds of the DiscreteControl conditions on its level, and the min_upstream_level and max_downstream_level of the Outlets and Pumps around it. apply_seasonal_levels varies these over the year with the level management of the peilgebieden of ribasim_nl.peilbeheer, see https://github.com/Deltares/Ribasim-NL/issues/893:

assign_peilbeheer gives a Basin the level management of the peilgebied that covers most of its area, or of the weir near it with the closest target level. Its target level stays the same in the season of which the target level of the peilgebied is closest to it, since the target levels of the models are checked with the water boards. The peilgebied gives the difference with the other season, and the bounds of the target level. A peilgebied of which both target levels are far from that of the Basin does not describe its water, and is not assigned. join_peilbeheer gives the Basins that are joined by resistance nodes, and so are one water in the model, the level management of the largest area of them, also none.
The thresholds of the DiscreteControl conditions on the level of a Basin follow its target level. Thresholds with the default band of DEFAULT_LEVEL_THRESHOLD_RANGE around a level get the bounds of the target level instead.
The Outlets and Pumps controlled by a DiscreteControl node get a winter and a summer variant of each control state, with the levels of that season. A condition on the season switches between them.
The initial level of a Basin follows its target level at the start of the model.

The levels change at once, at the begin of the transitions between summer and winter. A gradual transition needs Ribasim to support parameters of control states that change over time. The DiscreteControl nodes that change over the year get cyclic timeseries, over the year of the start of the model.

The regional models get the seasons in ribasim_nl.regional_model.finish_regional_model. koppelen removes them with remove_seasonal_levels, since the coupling works with the fixed levels, and applies them again to the coupled model. The fixed levels and thresholds are kept in the meta_fixed_ columns for this.

Functions

Name	Description
apply_seasonal_levels	Vary the target levels of the Basins and their control between summer and winter, see the module docstring.
assign_peilbeheer	Assign the level management of the peilgebieden to the Basins with a target level.
join_peilbeheer	Give the Basins that are joined by resistance nodes the same level management.
joined_basins	Group the Basins that are joined by ManningResistance or LinearResistance nodes, also through Junctions.
node_authority	The authority of nodes of the coupled model, from their node ID, see `ribasim_nl.aquo`.
remove_seasonal_levels	Restore the fixed levels and thresholds of the control, the inverse of `apply_seasonal_levels`.
season_levels	The `min_upstream_level` and `max_downstream_level` of static rows in each season.
season_switch	The season over a year, indexed by the time from which it applies.
seasonal_differences	The difference of the target level with `meta_streefpeil`, and of the bounds with the target level, per season.
seasonal_thresholds	The thresholds over the year of conditions on the level of one Basin each, with the same transitions.

apply_seasonal_levels

seasonal_levels.apply_seasonal_levels(
    model,
    peilgebieden,
    *,
    authority=None,
    shift_state=True,
    min_overlap=MIN_OVERLAP,
    max_offset=MAX_OFFSET,
)

Vary the target levels of the Basins and their control between summer and winter, see the module docstring.

The seasons that the model already has are removed first, with remove_seasonal_levels.

Parameters

Name	Type	Description	Default
model	Model	model	required
peilgebieden	gpd.GeoDataFrame	the level management of the peilgebieden, see `ribasim_nl.peilbeheer.read_peilbeheer`	required
authority	str \| None	the authority of all Basins of a regional model, see `assign_peilbeheer`	`None`
shift_state	bool	let the initial levels follow the target levels, not when they already do, as the final state of a model with the seasons	`True`
min_overlap	float	see `assign_peilbeheer`	`MIN_OVERLAP`
max_offset	float	see `assign_peilbeheer`	`MAX_OFFSET`

Returns

Name	Type	Description
	pd.DataFrame	the level management of the Basins, see `assign_peilbeheer`

assign_peilbeheer

seasonal_levels.assign_peilbeheer(
    model,
    peilgebieden,
    authority=None,
    min_overlap=MIN_OVERLAP,
    max_offset=MAX_OFFSET,
)

Assign the level management of the peilgebieden to the Basins with a target level.

A Basin gets the peilgebied of its authority that covers most of its area, if that is at least min_overlap of it. A Basin without such a peilgebied gets the peilgebied that is a point within POINT_DISTANCE of it with the closest target level, such as the weir that it drains over. The levels of the peilgebied are shifted such that its target level in the season of which it is closest to the target level of the Basin, is that target level. A peilgebied of which both target levels are further than max_offset from that of the Basin does not describe its water, and is not assigned.

Parameters

Name	Type	Description	Default
model	Model	model	required
peilgebieden	gpd.GeoDataFrame	the level management of the peilgebieden, see `ribasim_nl.peilbeheer.read_peilbeheer`	required
authority	str \| None	the authority of all Basins of a regional model, or else their authority follows from their node ID, as in the coupled model	`None`
min_overlap	float	the minimum fraction of the area of a Basin that its peilgebied covers	`MIN_OVERLAP`
max_offset	float	the maximum difference between the target levels of the Basin and its peilgebied [m]	`MAX_OFFSET`

Returns

Name	Type	Description
	pd.DataFrame	the level management per Basin node_id, with the target level `meta_streefpeil` of the Basin, the code of its peilgebied as `peilgebied`, the fraction of the Basin that it covers as `overlap`, and the shift of the levels of the peilgebied as `offset`

join_peilbeheer

seasonal_levels.join_peilbeheer(model, regimes)

Give the Basins that are joined by resistance nodes the same level management.

The flow between these Basins follows their difference in level, so they are one water in the model, of which the seasons should not change the levels relative to each other. Of their level management, also none, the one of the largest area applies to all of them, relative to their own target level.

Parameters

Name	Type	Description	Default
model	Model	model	required
regimes	pd.DataFrame	the level management of the Basins, see `assign_peilbeheer`	required

Returns

Name	Type	Description
	pd.DataFrame	the level management of the Basins, see `assign_peilbeheer`, with `overlap` and `offset` NaN for the Basins that get it from the Basins they are joined to

joined_basins

seasonal_levels.joined_basins(model)

Group the Basins that are joined by ManningResistance or LinearResistance nodes, also through Junctions.

Returns

Name	Type	Description
	pd.Series	the number of the group per Basin node_id

node_authority

seasonal_levels.node_authority(node_ids)

The authority of nodes of the coupled model, from their node ID, see ribasim_nl.aquo.

remove_seasonal_levels

seasonal_levels.remove_seasonal_levels(model)

Restore the fixed levels and thresholds of the control, the inverse of apply_seasonal_levels.

The initial levels of the Basins stay as they are.

season_levels

seasonal_levels.season_levels(static, neighbors, differences, bottoms)

The min_upstream_level and max_downstream_level of static rows in each season.

The finite levels move with the target level of the Basin upstream and downstream of their node respectively. Ribasim requires a min_upstream_level above the bottom of the Basin upstream, so it stays above it.

Parameters

Name	Type	Description	Default
static	pd.DataFrame	static rows of Outlets or Pumps	required
neighbors	pd.DataFrame	the `upstream` and `downstream` node per node_id	required
differences	pd.DataFrame	see `seasonal_differences`	required
bottoms	pd.Series	the lowest level of the profile per Basin	required

Returns

Name	Type	Description
	pd.DataFrame	the levels with the suffix `_zomer` and `_winter`, with the index of `static`

season_switch

seasonal_levels.season_switch(transitions, year)

The season over a year, indexed by the time from which it applies.

It is 1 in summer, from the begin of the transition to summer until the begin of the transition to winter, and 0 in winter.

Parameters

Name	Type	Description	Default
transitions	Sequence[str]	the begin and end of the transition to summer, and of the transition to winter, as “dd-mm”	required
year	int	the year	required

seasonal_differences

seasonal_levels.seasonal_differences(regimes)

The difference of the target level with meta_streefpeil, and of the bounds with the target level, per season.

Parameters

Name	Type	Description	Default
regimes	pd.DataFrame	the level management of the Basins, see `assign_peilbeheer`	required

Returns

Name	Type	Description
	pd.DataFrame	per Basin node_id, `delta`, `below` and `above`, each with the suffix `_zomer` and `_winter`

seasonal_thresholds

seasonal_levels.seasonal_thresholds(conditions, differences, season)

The thresholds over the year of conditions on the level of one Basin each, with the same transitions.

The thresholds move with the target level of their Basin. Thresholds with the default band around a level get the bounds of the target level around that level instead.

Parameters

Name	Type	Description	Default
conditions	pd.DataFrame	the conditions, with the `basin` and the `weight` of their variable, which is 1 or -1	required
differences	pd.DataFrame	see `seasonal_differences`	required
season	pd.Series	the `season_switch` of the Basins	required

Returns

Name	Type	Description
	tuple[np.ndarray, np.ndarray]	`threshold_low` and `threshold_high`, with a row per condition and a column per time of `season`