apply_spillway Scheme Example

This example shows how to use the ReservoirModel.apply_spillway() scheme when modelling a single reservoir model.

Note

For details about the full model file structure please see Basic Single Reservoir.

We consider a reservoir with a single inflow, Q_in, and an outflow Q_out. Q_out is comprised of two components, a spillway, Q_spill, and a turbine Q_turbine. The reservoir outflow is determined based upon the reservoir elevation, H, at each timestep.

\[ \begin{align}\begin{aligned}\begin{split}Q_{out} = Q_{turbine}+Q_{spill}\\\end{split}\\\begin{split}Q_{spill} = \begin{cases} Q_{spill}(H) & \text{if $H > H_{crest}$}\\ 0 & \text{otherwise}\\ \end{cases}\\\end{split}\\\begin{split}Q_{turbine} = \begin{cases} 0.6 & \text{if $H > H_{crest}$}\\ 0.4 & \text{otherwise}\\ \end{cases}\end{split}\end{aligned}\end{align} \]

The ReservoirModel.apply_spillway() and ReservoirModel.set_q() schemes can be applied to model these operations.

Main Model (python) File

An example of the main model file spillway_example.py is given below.

"""Example that illustrates how to use spillway scheme."""

from pathlib import Path

from rtctools.util import run_simulation_problem

from rtctools_simulation.reservoir.model import InputVar, ModelConfig, ReservoirModel

CONFIG = ModelConfig(base_dir=Path(__file__).parent)


class SingleReservoir(ReservoirModel):
    """Example single reservoir model."""

    def apply_schemes(self):
        """Apply schemes for controlling the reservoir."""

        # Apply schemes.
        h = self.get_var("H")
        h_crest = self.get_var("H_crest")
        if h > h_crest:
            self.apply_spillway()
            self.set_q(
                target_variable=InputVar.Q_TURBINE,
                input_type="parameter",
                input_data=0.6,
            )
        else:
            self.set_q(
                target_variable=InputVar.Q_TURBINE,
                input_type="parameter",
                input_data=0.4,
            )


# Create and run the model.
if __name__ == "__main__":
    run_simulation_problem(SingleReservoir, config=CONFIG)

The template file mentioned in the Basic Single Reservoir will look very similar to this file, except that the apply_schemes() method still needs to be filled out.

The line

CONFIG = ModelConfig(base_dir=Path(__file__).parent)

sets the model configuration. This model configuration is defined by the base directory base_dir. In most cases, the base directory is Path(__file__).parent, which is the directory of the current file.

The line

class SingleReservoir(ReservoirModel):

defines a class SingleReservoir that inherits all properties and functionalities of the predefined class ReservoirModel. An overview of this class can be found in Reservoir API and details of the underlying model it uses can be found in Single Reservoir Model.

The method ReservoirModel.apply_schemes() is called every timestep and contains the logic for which schemes are applied. The first argument self is the SingleReservoir object itself. Since SingleReservoir inherits from ReservoirModel, self can call any of the ReservoirModel methods, such as ReservoirModel.get_var(), ReservoirModel.set_q(), and ReservoirModel.apply_spillway(), An overview of all available ReservoirModel methods can be found in Reservoir API.

In this example, the ReservoirModel.apply_schemes() method starts by collecting the current reservoir elevation as this is used to determine operations. The method then checks if the elevation, H, is higher than the crest level. The crest level is supplied to the model via the rtcParameterConfig.xml input file. The set_q or apply_spillway scheme is then applied to set the reservoir outflow through the spillway or turbine.

Lookup tables

This model uses the standard lookup tables h_from_v.

The ReservoirModel.apply_spillway() scheme ensures that the spill, Q_spill, is computed from the elevation, H, using a lookuptable qspill_from_h.

This file, h_qspill.csv looks as follows,

<base_dir>/lookup_tables/h_qspill.csv

height_m	qspill_m3_per_s
0	0
1598.543038	0
1598.69544	1.245941268
1599.000244	10.76040186
1599.305048	24.35248842
1599.609851	41.62576509
1599.914655	62.01389493
1600.219459	85.51687794
1600.524262	111.8515457
1600.829066	140.7347296
1601.13387	171.8832613
1601.438673	205.0139723
1601.743477	240.1268626
1602.048281	276.3724267
1602.353085	314.3170017
1602.657888	354.243756
1602.962692	396.435858
1603.267496	441.1764763
1603.572299	487.8992738
1603.877103	536.6042507
1604.181907	587.0082383
1604.486711	639.1112368
1604.791514	692.6300776
1605.096318	747.2815923
1605.401122	803.3489494
1605.705925	859.9826434
1606.010729	917.4658428
1606.315533	975.7985476

This file is mapped to the internal qspill_from_h table via the lookup_tables.csv file

<base_dir>/lookup_tables/lookup_tables.csv

name	data	var_in	var_out
h_from_v	v_h.csv	volume_m3	height_m
v_from_h	v_h.csv	height_m	volume_m3
area_from_v	v_area.csv	volume_m3	area_m2
qout_from_v	qout_v.csv	day volume_m3	qout_m3_per_s
qspill_from_h	h_qspill.csv	height_m	qspill_m3_per_s

For other lookup tables, defaults from the generated template files can be used.

Note

For further details about the lookup tables please see Basic Single Reservoir.

Input Data Files

The crest level is supplied to the model via the rtcParameterConfig.xml input file.

        <parameter id="H_crest">
        	<dblValue>1598.543038</dblValue>
        </parameter>

Note

For further details about input file structure please see Basic Single Reservoir.

Output Data

The results of the simulation will appear in the output folder in a file called timeseries_export.xml. The data is linked to model variables via the rtcDataConfig.xml in the same way as with timeseries_import.xml.

Automatic Plotting

You can optionally include a plot_table.csv in the input folder. This is used by the rtc-tools-interfaces module (automatically installed with this package) to plot the model output. For more details on how to use this file and visualize results, see RTC-Tools-Interface.

The results of the simulation run can be seen in the plot below.