suminf and floodflag Utilities Example

This example shows how to use the ReservoirModel.calculate_cumulative_inflows() and ReservoirModel.get_flood_flag() Utilities 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.

Main Model (python) File

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

"""Example that illustrates use of the suminf and floodflag utilities."""

from pathlib import Path

import numpy as np
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 pre(self, *args, **kwargs):
        super().pre(*args, **kwargs)
        # Find the cumulative inflows. This scheme will also set the "cumulative_inflow" timeseries
        self.calculate_cumulative_inflows()

        # Get the flood flag for this model run
        # Note: these parameters could also be provided via the rtcDataConfig.xml
        self.flood_elevation = 1598.7
        self.q_out_daily_average = 1.0
        flood_flag = self.get_flood_flag(
            q_out_daily_average=self.q_out_daily_average,
            flood_elevation=self.flood_elevation,
        )

        # Set the flood flag and flood elevation as timeseries such that they can be plotted.
        # Note: these timeseries are not used in the simulation, but only for plotting.
        flood_flag_ts = np.full_like(self.times(), flood_flag)
        self.set_timeseries("flood_flag", flood_flag_ts)
        flood_elevation_ts = np.full_like(self.times(), self.flood_elevation)
        self.set_timeseries("flood_elevation", flood_elevation_ts)

    def apply_schemes(self):
        """Apply the schemes."""
        # Set the outflow to the q_out_daily_average value.
        self.set_q(
            target_variable=InputVar.Q_OUT,
            input_type="parameter",
            input_data=self.q_out_daily_average,
        )


# 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 ReservoirModel.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.apply_adjust(). An overview of all available ReservoirModel methods can be found in Reservoir API.

The ReservoirModel.set_q() scheme is applied to set reservoir outflow to 1.0 m3/s (the q_out_daily_average).

Lookup tables

This model uses only the standard lookup table h_from_v, for other lookup tables, defaults from the generated template files can be used. Lookup table h_from_v is also used to convert the observed/initial elevations (H_observed) into observed/initial volumes.

Note

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

Input Data Files

No special input is required when using these utilities.

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. The plot containts the cumulative inflow in a separate plot. The plot also shows the flood flag. This is set to one as, given the q_out_daily_average, within the pre-porcessing it is expected that the elevation H will exceed the flood level flood_elevation at some point during the simulatiom.

Within ReservoirModel.apply_schemes(), ReservoirModel.set_q() is used to set the outflow equal to q_out_daily_average. Hence the plots also show the elevation, H rising above flood_elevation.