Reservoir API

Methods of the ReservoirModel are listed below. Schemes can be applied by overwriting the ReservoirModel.apply_schemes() method.

Available schemes include:

ReservoirModel.apply_spillway()
ReservoirModel.apply_passflow()
ReservoirModel.apply_poolq()
ReservoirModel.apply_rulecurve()
ReservoirModel.apply_adjust()
ReservoirModel.include_rain()
ReservoirModel.include_evaporation()
ReservoirModel.include_rainevap()

An overview of all schemes is given below.

rtctools_simulation.reservoir.model.VARIABLES = ['Area', 'H', 'H_crest', 'Q_evap', 'Q_in', 'Q_out', 'Q_rain', 'Q_spill', 'Q_turbine', 'Q_sluice', 'V']: Reservoir model variables.

class rtctools_simulation.reservoir.model.ReservoirModel(config: ModelConfig, use_default_model=True, **kwargs)[source]

Class for a reservoir model.

apply_adjust()[source]

Scheme to adjust simulated volume to observed volume.

This scheme can be applied inside ReservoirModel.apply_schemes(). When applying this scheme, V is set to V_observed provided by the input file and a corrected version of the outflow, Q_out_corrected, is calculated in order to preserve the mass balance.

apply_passflow()[source]

Scheme to let the outflow be the same as the inflow.

This scheme can be applied inside ReservoirModel.apply_schemes().

Note

This scheme cannot be used in combination with ReservoirModel.apply_poolq(), or ReservoirModel.set_q() when the target variable is Q_out.

apply_poolq()[source]

Scheme to let the outflow be determined by a lookup table with name “qout_from_v”.

This scheme can be applied inside ReservoirModel.apply_schemes().

Note

This scheme cannot be used in combination with ReservoirModel.apply_passflow(), or ReservoirModel.set_q() when the target variable is Q_out.

apply_rulecurve(outflow: str = 'Q_turbine')[source]

Scheme to set the outflow of the reservoir in order to reach a rulecurve.

This scheme can be applied inside ReservoirModel.apply_schemes(). This scheme uses the lookup table v_from_h and requires the following parameters from the rtcParameterConfig.xml file.

rule_curve_q_max: Upper limiting discharge while blending pool elevation (m^3/timestep)

rule_curve_blend: Number of timesteps over which to bring the pool back to the scheduled elevation.

The user must also provide a timeseries with the name rule_curve. This contains the water level target for each timestep.

Parameters:: outflow – outflow variable that is modified to reach the rulecurve.

Note

This scheme does not correct for the inflows to the reservoir. As a result, the resulting height may differ from the rule curve target.

apply_schemes()[source]

Apply schemes.

This method is called at each timestep and should be implemented by the user. This method should contain the logic for which scheme is applied under which conditions.

apply_spillway()[source]

Scheme to enable water to spill from the reservoir.

This scheme can be applied inside ReservoirModel.apply_schemes(). This scheme ensures that the spill “Q_spill” is computed from the elevation “H” using a lookuptable “qspill_from_h”.

calculate_output_variables()[source]

Calculate output variables.

This method is called after the simulation has finished. The user can implement this method to calculate additional output variables.

calculate_rule_curve_deviation(periods: int, inflows: ndarray | None = None, q_max: float = inf, maximum_difference: float = inf)[source]

Calculate the moving average between the rule curve and the simulated elevations.

This method calculates the moving average between the rule curve and the simulated elevations over a specified number of periods. It takes the following parameters:

Parameters:

periods – The number of periods over which to calculate the moving average.
inflows – Optional. The inflows to the reservoir. If provided, the moving average will be calculated only for the periods with non-zero inflows.
q_max – Optional. The maximum discharge allowed while calculating the moving average. Default is infinity, required if q_max is set.
maximum_difference – Optional. The maximum allowable difference between the rule curve and the simulated elevations.

Note

The rule curve timeseries must be present in the timeseries import. The results

are stored in the timeseries “rule_curve_deviation”.

get_current_datetime() → datetime[source]

Get the current datetime.

Returns:: the current time in datetime format.

get_current_time() → int[source]

Get the current time (in seconds).

Returns:: the current time (in seconds).

get_output_variables()[source]

Method to get, and extend output variables

This method gets all output variables of the reservoir model, and extends the output to also include input variables like “Q_in” and “Q_turbine” such that they appear in the timeseries_export.xml.

get_var(var: str) → float[source]

Get the value of a given variable at the current time.

Parameters:: var – name of the variable. Should be one of VARIABLES.
Returns:: value of the given variable.

include_evaporation()[source]

Scheme to include the effect of evaporation on the reservoir volume.

This scheme can be applied inside ReservoirModel.apply_schemes(). This scheme computes

Q_evap = Area * mm_evaporation_per_hour / 3600 / 1000 * include_evaporation.

This is then treated in the mass balance of the reservoir

der(V) = Q_in - Q_out + Q_rain - Q_evap.

include_rain()[source]

Scheme to include the effect of rainfall on the reservoir volume.

This scheme can be applied inside ReservoirModel.apply_schemes(). This scheme computes

Q_rain = max_reservoir_area * mm_rain_per_hour / 3600 / 1000 * include_rain.

This is then treated in the mass balance of the reservoir

der(V) = Q_in - Q_out + Q_rain - Q_evap.

Note

To include rainfall, make sure to set the max_reservoir_area parameter.

include_rainevap()[source]

Scheme to include the effect of both rainfall and evaporation on the reservoir volume.

This scheme can be applied inside ReservoirModel.apply_schemes(). This scheme implements both ReservoirModel.include_rain() and ReservoirModel.include_evaporation().

initialize_input_variables()[source]

Initialize input variables.

This method calls ReservoirModel.set_default_input(). This method can be overwritten to initialise input variables. It is only called at the start of the simulation.

Note

Be careful if you choose to overwrite this method as default values have been carefully chosen to select the correct default schemes.

pre(*args, **kwargs)[source]: This method can be overwritten to perform any pre-processing before the simulation begins.

Note

Be careful if you choose to overwrite this method as default values have been carefully chosen to select the correct default schemes.

set_default_input()[source]

Set default input values.

This method sets default values for internal variables at each timestep. This is important to ensure that the schemes behave as expected.

set_input_variables()[source]

Set input variables.

This method calls ReservoirModel.set_default_input() and ReservoirModel.apply_schemes(). This method can be overwritten to set input at each timestep.

Note

Be careful if you choose to overwrite this method as default values have been carefully chosen to select the correct default schemes.

set_q(target_variable: str = 'Q_turbine', input_type: str = 'timeseries', input_data: str | float | list[float] = None, apply_func: str = 'MEAN', timestep: int = None, nan_option: str = None)[source]

Scheme to set one of the input or output discharges to a given value, or a value determined from an input list.

This scheme can be applied inside ReservoirModel.apply_schemes().

Note

This scheme cannot be used in combination with ReservoirModel.apply_poolq(), or ReservoirModel.apply_passflow() if the target variable is Q_out.

Parameters:

target_variable – str (default: ‘Q_turbine’) The variable that is to be set. Needs to be an internal variable, limited to discharges.
input_type – str (default: ‘timeseries’) The type of target data. Either ‘timeseries’ or ‘parameter’. If it is a timeseries, the timeseries is assumed to have a regular time interval.
input_data – str | float | list[float] (default: None) Single value or a list of values for each time step to set the target. It can also be a name of a parameter or input variable.
apply_func –
str (default: ‘MEAN’) Function that is used to find the fixed_value if input_type = ‘timeseries’.
- ’MEAN’ (default): Finds the average value, excluding nan-values.
- ’MIN’: Finds the minimum value, excluding nan-values.
- ’MAX’: Finds the maximum value, excluding nan-values.
- ’INST’: Finds the value marked by the corresponding timestep ‘t’. If the selected value is NaN, nan_option determines the procedure to find a valid value.
timestep – int (default: None) The timestep at which the input data should be read at if input_type = ‘timeseries’, the default is the current timestep of the simulation run.
nan_option –
str (default: None) the user can indicate the action to be take if missing values are found. Usable in combination with input_type = ‘timeseries’ and apply_func = ‘INST’.
- ’MEAN’: It will take the mean of the timeseries excluding nans.
- ’PREV’: It attempts to find the closest previous valid data point.
- ’NEXT’: It attempts to find the closest next valid data point.
- ’CLOSEST’: It attempts to find the closest valid data point, either backwards or forward. If same distance, take average.
- ’INTERP’: Interpolates linearly between the closest forward and backward data points.