Tracking a Setpoint¶
The purpose of this example is to understand the technical setup of an RTC- Tools simulation model, how to run the model, and how to access the results.
The scenario is the following: A reservoir operator is trying to keep the reservoir’s volume close to a given target volume. They are given a six-day forecast of inflows given in 12-hour increments. To keep things simple, we ignore the waterlevel-storage relation of the reservoir and head-discharge relationships in this example. To make things interesting, the reservoir operator is only able to release water at a few discrete flow rates, and only change the discrete flow rate every 12 hours. They have chosen to use the RTC- Tools simulator to see if a simple proportional controller will be able to keep the system close enough to the target water volume.
contains a complete RTC-Tools simulation 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.
Make sure to load the Deltares library before loading the example:
- 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 15 16 17 18
model Example // Elements Deltares.ChannelFlow.SimpleRouting.BoundaryConditions.Inflow inflow(Q = Q_in); Deltares.ChannelFlow.SimpleRouting.Storage.Storage storage(Q_release = P_control, V(start=storage_V_init, fixed=true, nominal=4e5)); Deltares.ChannelFlow.SimpleRouting.BoundaryConditions.Terminal outfall; // Initial States parameter Modelica.SIunits.Volume storage_V_init; // Inputs input Modelica.SIunits.VolumeFlowRate P_control(fixed = true); input Modelica.SIunits.VolumeFlowRate Q_in(fixed = true); input Modelica.SIunits.VolumeFlowRate storage_V_target(fixed = true); // Outputs output Modelica.SIunits.Volume storage_V = storage.V; output Modelica.SIunits.VolumeFlowRate Q_release = P_control; equation connect(inflow.QOut, storage.QIn); connect(storage.QOut, outfall.QIn); 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 and assigning the inputs to the appropriate
element variables. For example,
inflow(Q = Q_in) sets the
inflow element equal to
In addition to elements, the input variables
Q_in is determined by the forecast and the operator cannot
control it, so we set
Q_in(fixed = true). The actual values of
are stored in
P_control is not defined anywhere
in the model or inputs- we will dynamically assign its value every timestep in
the python script,
Because we want to view the water volume in the storage element in the output
file, we also define an output variable
storage_V and set it equal to the
corresponding state variable
storage.V. Dito for
Q_release = P_control.
The Simulation 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 simulation problem class
- Any additional configuration (e.g. overriding methods)
- 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_simulation_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 6 7 8
import logging from rtctools.simulation.csv_mixin import CSVMixin from rtctools.simulation.simulation_problem import SimulationProblem from rtctools.util import run_simulation_problem logger = logging.getLogger("rtctools")
The next step is to define the simulation 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 running the simulation problem. Each imported class makes a set of methods available to the our simulation class.
class Example(CSVMixin, SimulationProblem):
The next, we override any methods where we want to specify non-default
behaviour. In our simulation problem, we want to define a proportional
controller. In its simplest form, we load the current values of the volume and
target volume variables, calculate their difference, and set
P_control to be
as close as possible to eliminating that difference during the upcoming timestep.
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
def update(self, dt): # Get the time step if dt < 0: dt = self.get_time_step() # Get relevant model variables volume = self.get_var('storage.V') target = self.get_var('storage_V_target') # Calucate error in storage.V error = target - volume # Calculate the desired control control = -error / dt # Get the closest feasible setting. bounded_control = min(max(control, self.min_release), self.max_release) # Set the control variable as the control for the next step of the simulation self.set_var('P_control', bounded_control) # Call the super class so that everything else continues as normal super().update(dt)
Run the Simulation Problem¶
To make our script run, at the bottom of our file we just have to call
run_simulation_problem() method we imported on the simulation
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 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
import logging from rtctools.simulation.csv_mixin import CSVMixin from rtctools.simulation.simulation_problem import SimulationProblem from rtctools.util import run_simulation_problem logger = logging.getLogger("rtctools") class Example(CSVMixin, SimulationProblem): """ A basic example for introducing users to RTC-Tools 2 Simulation """ def initialize(self): self.set_var('P_control', 0.0) super().initialize() # Min and Max flow rate that the storage is capable of releasing min_release, max_release = 0.0, 8.0 # m^3/s # Here is an example of overriding the update() method to show how control # can be build into the python script def update(self, dt): # Get the time step if dt < 0: dt = self.get_time_step() # Get relevant model variables volume = self.get_var('storage.V') target = self.get_var('storage_V_target') # Calucate error in storage.V error = target - volume # Calculate the desired control control = -error / dt # Get the closest feasible setting. bounded_control = min(max(control, self.min_release), self.max_release) # Set the control variable as the control for the next step of the simulation self.set_var('P_control', bounded_control) # Call the super class so that everything else continues as normal super().update(dt) # Run run_simulation_problem(Example, log_level=logging.DEBUG)
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. Here we used matplotlib to generate this plot.
This plot shows that the operator is not able to keep the water level within the bounds over the entire time horizon. They may need to increase the controller timestep, use a more complete PID controller, or use model predictive control such as the RTC-Tools optimization library to get the results they want.