Filling a Reservoir¶
The purpose of this example is to understand the technical setup of an RTC-Tools model, how to run the model, and how to interpret the results.
The scenario is the following: A reservoir operator is trying to fill a reservoir. They are given a six-day forecast of inflows given in 12-hour increments. The operator wants to save as much of the inflows as possible, but does not want to end up with too much water at the end of the six days. They have chosen to use RTC-Tools to calculate how much water to release and when to release it.
If you installed using source, the library and examples directory are available in the git repositories. If you installed using pip directly, you first need to download/copy the examples and libraries to a convenient location. See Downloading and running examples and Copying Modelica libraries for detailed instructions.
<examples directory>\basic contains a complete RTC-Tools
optimization problem. An RTC-Tools directory has the following structure:
input: This folder contains the model input data. These are several files in comma separated value format,
model: This folder contains the Modelica model. The Modelica model contains the physics of the RTC-Tools model.
output: The folder where the output is saved in the file
src: This folder contains a Python file. This file contains the configuration of the model and is used to run the model .
The first step is to develop a physical model of the system. The model can be viewed and edited using the OpenModelica Connection Editor (OMEdit) program. For how to download and start up OMEdit, see Getting OMEdit.
- Load the Deltares library into OMEdit
- Using the menu bar: File -> Open Model/Library File(s)
- Load the example model into OMEdit
- Using the menu bar: File -> Open Model/Library File(s)
Once loaded, we have an OpenModelica Connection Editor window that looks like this:
Example.mo represents a simple system with the following
- a reservoir, modeled as storage element
- an inflow boundary condition
- an outfall boundary condition
- connectors (black lines) connecting the elements.
You can use the mouse-over feature help to identify the predefined models from the Deltares library. You can also drag the elements around- the connectors will move with the elements. Adding new elements is easy- just drag them in from the Deltares Library on the sidebar. Connecting the elements is just as easy- click and drag between the ports on the elements.
In text mode, the Modelica model looks as follows (with annotation statements removed):
1 2 3 4 5 6 7 8 9 10 11 12 13 14
model Example Deltares.ChannelFlow.SimpleRouting.BoundaryConditions.Inflow inflow; Deltares.ChannelFlow.SimpleRouting.Storage.Storage storage(V(nominal=4e5, min=2e5, max=6e5)); Deltares.ChannelFlow.SimpleRouting.BoundaryConditions.Terminal outfall; input Modelica.SIunits.VolumeFlowRate Q_in(fixed = true); input Modelica.SIunits.VolumeFlowRate Q_release(fixed = false, min = 0.0, max = 6.5); output Modelica.SIunits.Volume V_storage; equation connect(inflow.QOut, storage.QIn); connect(storage.QOut, outfall.QIn); storage.Q_release = Q_release; inflow.Q = Q_in; V_storage = storage.V; end Example;
The three water system elements (storage, inflow, and outfall) appear under
model Example statement. The
equation part connects these three
elements with the help of connections. Note that
storage extends the partial
QSISO which contains the connectors
storage can be connected on two sides. The
element also has a variable
Q_release, which is the decision variable the
OpenModelica Connection Editor will automatically generate the element and
connector entries in the text text file. Defining inputs and outputs requires
editing the text file directly. Relationships between the inputs and outputs and
the library elements must also be defined in the
In addition to elements, the input variables
Q_release are also
Q_in is determined by the forecast and the operator cannot control
it, so we set
Q_in(fixed = true). The actual values of
Q_in are stored
timeseries_import.csv. In the
equation section, equations are defined
to relate the inputs to the appropriate water system elements.
Because we want to view the water volume in the storage element in the output
file, we also define an output variable
There is a subtle difference between these quantities:
V_storage at time t holds
the volume of water in storage at that specific point in time. On the other hand,
Q_release are aggregated measures: at time, t, their value
represents the total flow between time t-1 and t.
The Optimization Problem¶
The python script is created and edited in a text editor. In general, the python script consists of the following blocks:
- Import of packages
- Definition of the optimization problem class
- Objective function
- Definition of constraints
- Any additional configuration
- A run statement
Packages are imported using
from ... import ... at the top of the file. In
our script, we import the classes we want the class to inherit, the
run_optimization_problem form the
rtctools.util package, and
any extra packages we want to use. For this example, the import block looks
1 2 3 4 5
from rtctools.optimization.collocated_integrated_optimization_problem \ import CollocatedIntegratedOptimizationProblem from rtctools.optimization.csv_mixin import CSVMixin from rtctools.optimization.modelica_mixin import ModelicaMixin from rtctools.util import run_optimization_problem
The next step is to define the optimization problem class. We construct the class by declaring the class and inheriting the desired parent classes. The parent classes each perform different tasks related to importing and exporting data and solving the optimization problem. Each imported class makes a set of methods available to the our optimization class.
class Example(CSVMixin, ModelicaMixin, CollocatedIntegratedOptimizationProblem):
Next, we define an objective function. This is a class method that returns the value that needs to be minimized.
13 14 15 16 17
def objective(self, ensemble_member): # Minimize water pumped. The total water pumped is the integral of the # water pumped from the starting time until the stoping time. In # practice, self.integral() is a summation of all the discrete states. return self.integral('Q_release', ensemble_member=ensemble_member)
Constraints can be declared by declaring the
path_constraints() method. Path
constraints are constraints that are applied every timestep. To set a constraint
at an individual timestep, we could define it inside the
Other parent classes also declare this method, so we call the
so that we don’t overwrite their behaviour.
19 20 21 22 23 24
def path_constraints(self, ensemble_member): # Call super() class to not overwrite default behaviour constraints = super().path_constraints(ensemble_member) # Constrain the volume of storage between 380000 and 420000 m^3 constraints.append((self.state('storage.V'), 380000, 420000)) return constraints
Run the Optimization Problem¶
To make our script run, at the bottom of our file we just have to call
run_optimization_problem() method we imported on the optimization
problem class we just created.
The Whole Script¶
All together, the whole example script is as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
from rtctools.optimization.collocated_integrated_optimization_problem \ import CollocatedIntegratedOptimizationProblem from rtctools.optimization.csv_mixin import CSVMixin from rtctools.optimization.modelica_mixin import ModelicaMixin from rtctools.util import run_optimization_problem class Example(CSVMixin, ModelicaMixin, CollocatedIntegratedOptimizationProblem): """ A basic example for introducing users to RTC-Tools 2 """ def objective(self, ensemble_member): # Minimize water pumped. The total water pumped is the integral of the # water pumped from the starting time until the stoping time. In # practice, self.integral() is a summation of all the discrete states. return self.integral('Q_release', ensemble_member=ensemble_member) def path_constraints(self, ensemble_member): # Call super() class to not overwrite default behaviour constraints = super().path_constraints(ensemble_member) # Constrain the volume of storage between 380000 and 420000 m^3 constraints.append((self.state('storage.V'), 380000, 420000)) return constraints # Run run_optimization_problem(Example)
To run this basic example in RTC-Tools, navigate to the basic example
directory in the RTC-Tools shell and run the example using
example.py. For more details about using RTC-Tools, see
The results from the run are found in
CSV-reading software can import it, but this is what the results look like when
plotted with the python library
This plot shows that the operator is able to keep the water level within the bounds over the entire time horizon and end with a full reservoir.
Feel free to experiment with this example. See what happens if you change the
Q_release (in the Modelica file) or if you make the objective
function negative (in the python script).