Datatypes#
The API has a defined set of internal datatypes to represent input and output data. Some are basic datatypes, and some are structured types to represent more complex data.
Integer#
A standard integer number. This type is also used for binary settings, where it is limited to 1 and 0.
Example: module ID number#
To set the module ID number for new_module in a prodrisk session called ps to 100:
ps.model.module['new_module'].number.set(100)
To get the module ID number of the module as a variable:
mod_number = ps.model.module['new_module'].number.get()
Float#
A standard 8-byte float value (i.e., double precision).
Example: reservoir volume#
To set the reservoir volume for new_module in a prodrisk session called ps to 65.3 Mm^3^:
ps.model.module['new_module'].rsvMax.set(65.3)
To get the reservoir volume of the module as a variable:
rsv_max = ps.model.module['new_module'].rsvMax.get()
String#
A standard string, with attribute-dependent maximum length.
Example: plant name#
To set the plant name for new_module in a prodrisk session called ps to ‘hydro_plant’:
ps.model.module['new_module'].plantName.set('hydro_plant')
To get the plant name of the module as a variable:
plant_name = ps.model.module['new_module'].plantName.get()
List of integer values#
Data consisting of multiple integer values is passed / returned as a python List object, where each element is an integer value. The length of the list depends on the attribute.
Example: module topology#
To set the topology for new_module in a prodrisk session called ps to modules with the ID numbers 101, 102, and 103:
ps.model.module['new_module'].plantName.set([101, 102, 103])
To get the topology of the module as a variable:
mod_topology = ps.model.module['new_module'].topology.get()
List of double values#
Data consisting of multiple integer values is passed / returned as a python List object, where each element is a float value. Input can also be given as a numpy array. The length of the list depends on the attribute.
Example: reservoir reference levels#
To set the reservoir reference levels for new_module in a prodrisk session called ps to the values 45.4 Mm^3^, 55.3 Mm^3^, and 62.7 Mm^3^:
ps.model.module['new_module'].reservoirReferenceLevels.set([45.4, 55.3, 62.7])
To get the reservoir reference levels as a variable:
rsv_ref_vol = ps.model.module['new_module'].reservoirReferenceLevels.get()
Table / xy curve#
Relation of two quantities given by discrete set of values. This datatype is represented as a pandas Series, where the two quantities are stored as index and data/values. Both index and data values are of type float and can be passed as a list or a numpy array. In addition, the name of the Series must be set. The name can be used as a label for this data set, but has no impact on the calculations.
Example: PQ curve#
We set the PQ curve for new_module in a prodrisk session called ps to the generated powers 0, 10, 20, 30 MW
at the corresponding flow rates 0, 8.1, 16.5, 25.5 m^3^/s. We can use, e.g., the head that this PQ curve is refering to as a label, say 138 m.
import numpy as np
import pandas as pd
...
P = np.array([0, 10, 20, 30])
Q = np.array([0, 8.1, 16.5, 25.5])
pq_curve = pd.Series(name=138, index=P, data=Q)
ps.model.module['new_module'].PQcurve.set(pq_curve)
To read out the PQ curve again:
pq_curve = ps.model.module['new_module'].PQcurve.get()
P = pq_curve.index
Q = pq_curve.values
Note that one has to set data in the pandas Series constructor, but use values to access this data later.
List of tables#
A list of tables is represented by a list of pandas Series. Each element of the list works as described above. This datatype is also used to manage lists of double arrays (e.g., cut coefficients), in which case only the values of each Series have a meaning, while the index is filled with zeros.
Example: end value tables#
To set the end values with a set of aggregated water value tables for the area my_area in a prodrisk session called ps, we create a list of pandas Series, assuming for simplicity that we have the water values in an array watervalue_1 for price level 1 etc.
import numpy as np
import pandas as pd
...
end_val_1 = pd.Series(name='price_level_1', index=np.linspace(100,0,51), data=watervalue_1)
...
end_val_7 = pd.Series(name='price_level_7', index=np.linspace(100,0,51), data=watervalue_7)
ps.area['my_area'].waterValue.set([end_val_1, end_val_2, end_val_3, end_val_4, end_val_5, end_val_6, end_val_7])
Time series#
This dataype describes deterministic time-dependent data. It is represented by a pandas Series, where the index contains the time as pandas Timestamp and the time-dependent values are given as data. It is recommended that the time axis is always set up relative to the start time of the simulation, using the sessions start_time property and pandas Timedelta.
Example: minimum flow restriction#
To set the minimum flow for new_module in a prodrisk session called ps to 3 m^3^/s from week 20 to week 34 in the simulation and 0 otherwise:
include pandas as pd
...
ps.model.module['new_module'].set(pd.Series(index=[ps.start_time + pd.Timedelta(weeks=w) for w in [1,20,35]], data=[0,3,0]))
Stochastic time series#
This dataype describes stochastic time-dependent data, i.e., one time series per scenario. It is represented by a pandas DataFrame, where the index contains the time as pandas Timestamp and the time-dependent values are given as data. It is recommended that the time axis is always set up relative to the start time of the simulation, using the sessions start_time property and pandas Timedelta. Each scenario is stored as one column in the DataFrame.
Example: calculated reservoir trajectories#
To get the reservoir filling of new_module in a prodrisk session called ps as a function of time for each scenario and access specifically results for the first scenario:
...
ps.run()
...
vol = ps.model.module['new_module'].reservoirVolume.get()
scenario_0 = vol[0] # this is a pandas Series