Functions

The pyprodrisk python package contains some functions and properties in addition to the objects and attributes defined in the inner layer of the API. The entire code of the python package can be viewed in the open pyprodrisk repository.

A Prodrisk session has the following member functions:

• ProdriskSession (constructor)

• set_optimization_period

• dump_model_yaml

• dump_data_h5

• dump_cuts_h5

• load_model_yaml

• load_data_h5

• load_cuts_h5

• plot_topology

• run

• destructor

Further functions are available through member objects:

• add_object (object type)

• get_object_names (object type)

• set (attribute)

• get (attribute)

• info (attribute)

• help (attribute)

• build_connection_tree (model)

In addition, in some special cases, you may have use for low-level advanced functions.

ProdriskSession (constructor)¶

A new ProdriskSession instance must be created for each simulation by calling the constructor:

• definition: ProdriskSession(license_path='', solver_path='', silent=True, suppress_log=False, log_gets=True, sim_id='', log_file='')

• arguments:

  • license_path The path to the license file. The file name is assumed to be ‘LTM_License.dat’.

  • solver_path The location of the folder containing the pybind file (*.pyd on Windows, *.so on Linux) for Prodrisk and some necessary libraries. This folder is part of the release packages on the Prodrisk portal.

  • silent If ‘True’, output from the Prodrisk core is written to both the log file and the console. If ‘False’, output is only written to the log file, but not printed on screen.

  • suppress_log If True, do not write a log file.

  • sim_id The identifier that is used as the name of the log file and the name of the temporary run directory. By default, the ID will be set to “session_” followed by a time stamp. If a directory with a name identical to the sim_id of your session already exists when you start the simulation, then “_extra” is automatically added at the end. Warning: If a logfile with a name identical to the sim_id exists, but no directory with that name, the log content is appended to the existing file. It is therefore recommended that you generate a unique id for each session, if you do not want to use the default.

  • log_file If set, the API will create a log of all internal (low-level) API function calls, i.e. python code that can be used to reproduce the complete session. This is a debugging tool that can be used to share a case with developers in case of errors. NB: This is not related to the ordinary log file with Prodrisk output.

• return value: a new ProdriskSession instance.

• example: create a new Prodrisk session called ps that will print output to the screen:
  

  ps = ProdriskSession(solver_path=r'C:\Users\username\Prodrisk\Prodrisk_API\pyprodrisk_r',
                       license_path=r'C:\Users\username\Prodrisk',
                       silent=False)

set_optimization_period¶

Set the start date and time and the horizon of the simulation. This function must be called before time-dependent input can be set. It is recommended to call this function immediately after the constructor. Afterwards, the properties start_time, end_time, and n_weeks are available. If the start date includes a timezone, this will automatically be the base timezone of the Prodrisk session.

• definition: ProdriskSession.set_optimization_period(start_time, n_weeks=52)

• arguments

  • start_time: start time of the simulation (pandas.Timestamp)

  • n_weeks: number of weeks in the simulation period (integer)

dump_model_yaml¶

Dump the static model to a yaml file. The routine loops over all objects and attributes and stores either input, output, or both input and output. All time series and large arrays (type xy_array) are ignored, as they are not suitable for storage in yaml format. Use this function together with dump_data_h5 and dump_cuts_h5 to dump the entire session.

• definition: ProdriskSession.dump_model_yaml(file_path='.', file_name= 'model', direction='both')

• arguments

  • file_path: directory where the file is created

  • file_name: name of the file, without the extension .yaml (overwrite existing file)

  • direction: what data to store, allowed values are input,output,both

dump_data_h5¶

Dump time series and large arrays (except cuts) from a session to an HDF5 file, where either input, output, or both input and output can be exported. Use this function together with dump_model_yaml and dump_cuts_h5 to dump the entire session.

• definition: ProdriskSession.dump_data_h5(file_path='.', file_name= 'model', direction='both')

• arguments

  • file_path: directory where the file is created

  • file_name: name of the file, without the extension .h5 (overwrite existing file)

  • direction: what data to store, allowed values are input,output,both

dump_cuts_h5¶

Dump all cuts from the session to an HDF5 file. Use this function together with dump_model_yaml and dump_data_h5 to dump the entire session.

• definition: ProdriskSession.dump_cuts_h5(file_path='.', file_name='cuts')

• arguments

  • file_path: directory where the file is created

  • file_name: name of the file, without the extension .h5 (overwrite existing file)

load_model_yaml¶

Load the static model from a yaml file which was created by dump_model_yaml. Use this function together with load_data_h5 and load_cuts_h5 to load an entire session.

• definition: ProdriskSession.load_model_yaml(file_path='.', file_name= 'model')

• arguments

  • file_path: directory where the file is located

  • file_name: name of the file, without the extension .yaml

load_data_h5¶

Load time series and large arrays (except cuts) from a session to an HDF5 file which was created by dump_data_h5. Use this function together with load_model_yaml and load_cuts_h5 to load an entire session.

• definition: ProdriskSession.load_data_h5(file_path='.', file_name= 'model', direction='both')

• arguments

  • file_path: directory where the file is located

  • file_name: name of the file, without the extension .h5

load_cuts_h5¶

Load all cuts from the session to an HDF5 file which was created by dump_cuts_h5. Use this function together with load_model_yaml and load_data_h5 to dump the entire session.

• definition: ProdriskSession.load_cuts_h5(file_path='.', file_name='cuts')

• arguments

  • file_path: directory where the file is located

  • file_name: name of the file, without the extension .h5

plot_topology¶

Create a graph that schematically visualizes the watercourse, including some key numbers for the modules. This function depends on matplotlib and scipy and requires the installation of pyprodrisk with the [full] option.

• definition: ProdriskSession.plot_topology(to_file="")

• arguments

  • to_file: The name of the file where the plot will be saved. If this argument is an empty string (default), the plot will be displayed. NB: In the latter case, the function matplotlib.pyplot.show() is called, which will also display any other figures that you may have created in your script.

run¶

Run the Prodrisk simulation:

1. The files needed by the Prodrisk core are written to the temporary run directory of the session.

2. Genpris is executed in the temporary run directory.

3. Prodrisk is executed in the temporary run directory.

4. Results are read from the result files created by the Prodrisk core inside the temporary run directory.

• definition: ProdriskSession.run()

• arguments: none

• return value: boolean specifying success or failure

Destructor¶

When a ProdriskSession instance is destructed, the temporary run directory is deleted, unless keepWorkingDirectory was set to True. Python handles the destruction of expired objects automatically, so you will never call the destructor yourself. Just be aware that the lifetime of temporary files is linked to the session object.

add_object¶

Add a new object to the session.

• definition: ProdriskSession.model.<objecttype>.add_object(name)

• arguments:

  • name The name of the created object (string).

• return value: The new object.

• example: create a new module in a Prodrisk session called ps: mod = ps.model.module.add_object('big_reservoir')

get_object_names¶

Get a list of all names of objects of a certain type.

• definition: ProdriskSession.model.<object_type>.get_object_names()

• arguments: none

• return value: a List of string values containing the object names for the object type

• example: all_modules = ps.model.module.get_object_names()

set¶

Set the value of an input attribute.

• definition: ProdriskSession.model.<object_type>['object_name'].<attribute_name>.set(value)

• arguments: the new attribute value, with datatype and units depending on the attribute.

• return value: none

• example: ps.model.module['Lake_example'].rsvMax.set(70) to set the reservoir volume of “Lake example” to 70Mm3.

get¶

Get the current value of any attribute.

• definition: ProdriskSession.model.<object_type>['object_name'].<attribute_name>.set(value)

• arguments: the new attribute value, with datatype and units depending on the attribute.

• return value: none

• example: max_vol = ps.model.module['Lake_example'].rsvMax.get() to store the reservoir volume of “Lake example” in the variable max_vol.

info¶

Get meta data of an attribute. The same information can also be found in the attribute table.

• definition: ProdriskSession.model.<object_type>['object_name'].<attribute_name>.info()

• arguments: none

• return value: a dictionary containing meta information with the following keys

  • 'is_input' with value 'True' or 'False'

  • 'is_output' with value 'True' or 'False'

  • 'datatype' internal API datatype, e.g. 'stxy'

  • 'xUnit'

  • 'yUnit'

• example: ps.model.module["my_module"].rsvMax.info() will return {'isInput': 'True', 'isOutput': 'False', 'datatype': 'double', 'xUnit': '', 'yUnit': 'Mm3'}.

help¶

Get the description of an attribute. The same information can also be found in the attribute table.

• definition: ProdriskSession.model.<object_type>['object_name'].<attribute_name>.help()

• arguments: none

• return value: a string containing a short description of the attribute

• example: ps.model.module["my_module"].rsvMax.help() will return "Max reservoir volume".

build_connection_tree¶

A rudimentary tool to visualize the topology of the watercourse.

• definition: ProdriskSession.model.build_connection_tree(filename='topology', write_file=False)

• arguments:

  • filename name of the pdf file to be created

  • write_file whether a pdf file will be created

• return value: a graphviz.Digraph object

Properties¶

• start_time : pandas.Timestamp start time of the simulation; read-only, set by set_optimization_period

• end_time : pandas.Timestamp end time of the simulation; read-only, set by set_optimization_period

• n_weeks : int number of weeks in the simulation period; read-only, set by set_optimization_period

• keep_working_directory : bool If True, do not delete the run directory when the ProdriskSession expires.

• n_scenarios : int: number of scenarios

API core functions¶

These are “expert functions” from the API core. You will typically not need those, but we list some of them that provide functionality that is not yet accessible on the level of the ProdriskSession.

• ProdriskSession._pb_api.GetSessionID()

• ProdriskSession._pb_api.SetCutTime(cutTime : string)

• ProdriskSession._pb_api.ReadCutResults()

• ProdriskSession._pb_api.WriteCutResults()

• ProdriskSession._pb_api.GetObjectTypeNames()

• ProdriskSession._pb_api.GetObjectTypeAttributeNames()

• ProdriskSession._pb_api.GetValidAttributeInfoKeys()

• ProdriskSession._pb_api.GetAttributeInfo(object_type, attribute_name, info_key)

• ProdriskSession._pb_api.GenerateProdriskFiles()

• ProdriskSession._pb_api.RunProdrisk()

• ProdriskSession._pb_api.RunGenpris()