maxq utility Example

This example shows how to use the ReservoirModel.maxq() utility 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 both spillway and turbine discharges. The reservoir outflow is determined based upon the reservoir elevation, H, at each timestep. The utility aims to compute the maximum possible release based on the current reservoir elevation. It can consider 3 different options, a fixed maximum discharge (‘Fixed’), a fixed maximum discharge plus Q/H spillway relation (‘Spillway’) and a option where the downstream tailwater discharge relation is taken into account (‘Tailwater’).

Main Model (python) File

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

"""Example that illustrates use of the maxq utility."""
from pathlib import Path

import numpy as np
from rtctools.util import run_simulation_problem

from rtctools_simulation.reservoir.model import ModelConfig, ReservoirModel

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


class MaxQModel(ReservoirModel):
    """Class for simulating a model with an adjust scheme."""

    def pre(self, **kwargs):
        super().pre()
        self.maxq = np.zeros(shape=(3, 3))

    def apply_schemes(self):
        if self.get_current_time() > 0:
            maxq1 = self.find_maxq("Spillway")
            maxq2 = self.find_maxq("Fixed")
            maxq3 = self.find_maxq("Tailwater")
            timestep_int = int(self.get_current_time() / self.get_time_step())
            # Save the calculated maximum discharges to set as timeseries in postprocessing.
            self.maxq[timestep_int, 0] = maxq1
            self.maxq[timestep_int, 1] = maxq2
            self.maxq[timestep_int, 2] = maxq3

    def calculate_output_variables(self):
        # Set the calculated maximum discharges as timeseries such that they can be plotted.
        self.set_timeseries("Qmax_spillway", self.maxq[:, 0])
        self.set_timeseries("Qmax_fixed", self.maxq[:, 1])
        self.set_timeseries("Qmax_tailwater", self.maxq[:, 2])


# Create and run the model.
if __name__ == "__main__":
    run_simulation_problem(MaxQModel, 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 MaxQModel(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() and ReservoirModel.maxq(). 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 model timestep, since the utility only works for timesteps after the first. The maxq() utility is then applied to compute the hypothetical maximum release using the 3 different cases.

Lookup tables

This model uses a variety of lookup tables, which are all defined in the file ‘’lookup_tables.csv’’

name,data,var_in,var_out
h_from_v,data.csv,v,h
v_from_h,data.csv,h,v
area_from_v,data.csv,v,area
qout_from_v,qout_from_v.csv,day v,qout
qspill_from_h,data.csv,h,qspill
qnotspill_from_dh,qnotspill_from_dh.csv,dh,qturbine
qtw_from_tw,qtw_from_tw.csv,tw,qtailwater

The required lookup_tables depend on the option that is chosen. For ‘Fixed’, none are required. For option ‘Spillway’, the Q/H relationship of the spillway is required to be passed in a lookup_table named ‘qspill_from_h’. If the option ‘Tailwater’ is chosen, we also need the Q/H relationship downstream, as well as the Q/dh relationship of the turbine. The configurator needs to provide those through lookup_tables ‘qtw_from_tw’ and ‘qnotspill_from_dh’ respectively. Lastly, for “Tailwater” a optional variable ‘solve_guess’ can be provided to guide the equilibrium solver in finding the final value. If nothing is passed, it defaults to the current reservoir elevation as an initial guess.

Note

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

Input Data Files

Note

For 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

There is 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, including the theoretical maximum discharges for each method. 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.