# 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](https://gitlab.sintef.no/energy/prodrisk/pyprodrisk).

A Prodrisk session has the following member functions:

- [ProdriskSession (constructor)](functions:prodrisksession-constructor)
- [set_optimization_period](functions:set-optimization-period)
- [dump_model_yaml](functions:dump-model-yaml)
- [dump_data_h5](functions:dump-data-h5)
- [dump_cuts_h5](functions:dump-cuts-h5)
- [load_model_yaml](functions:load-model-yaml)
- [load_data_h5](functions:load-data-h5)
- [load_cuts_h5](functions:load-cuts-h5)
- [run](functions:run)
- [destructor](functions:destructor)

Further functions are available through member objects:
- [add_object](functions:add_object) (object type)
- [get_object_names](functions:get_object_names) (object type)
- [set](functions:set_attribute) (attribute)
- [get](functions:get_attribute) (attribute)
- [info](functions:attribute_info) (attribute)
- [help](functions:attribute_help) (attribute)
- [build_connection_tree](functions:build-connection-tree) (model)

In addition, in some special cases, you may have use for low-level [advanced functions](api_core_functions).

(functions:prodrisksession-constructor)=
## 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:<br>
  ```
  ps = ProdriskSession(solver_path=r'C:\Users\username\Prodrisk\Prodrisk_API\pyprodrisk_r',
                       license_path=r'C:\Users\username\Prodrisk',
                       silent=False)
  ```

(functions:set-optimization-period)=
## 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.
- 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)

(functions:dump-model-yaml)=
## 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](functions:dump-data-h5) and [dump_cuts_h5](functions: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`

(functions:dump-data-h5)=
## 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](functions:dump-model-yaml) and [dump_cuts_h5](functions: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`

(functions:dump-cuts-h5)=
## dump_cuts_h5
Dump all cuts from the session to an HDF5 file. Use this function together with [dump_model_yaml](functions:dump-model-yaml) and [dump_data_h5](functions: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)

(functions:load-model-yaml)=
## load_model_yaml
Load the static model from a yaml file which was created by [dump_model_yaml](functions:dump-model-yaml). Use this function together with [load_data_h5](functions:load-data-h5) and [load_cuts_h5](functions: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`

(functions:load-data-h5)=
## 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](functions:dump-data-h5). Use this function together with [load_model_yaml](functions:load-model-yaml) and [load_cuts_h5](functions: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`

(functions:load-cuts-h5)=
## load_cuts_h5
Load all cuts from the session to an HDF5 file which was created by [dump_cuts_h5](functions:dump-cuts-h5). Use this function together with [load_model_yaml](functions:load-model-yaml) and [load_data_h5](functions: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`

(functions:run)=
## 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

(functions:destructor)=
## 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.

(functions:add_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')`

(functions:get_object_names)=
## 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()`

(functions:set_attribute)=
## 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.

(functions:get_attribute)=
## 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`.

(functions:attribute_info)=
## 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'}`.

(functions:attribute_help)=
## 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"`.

(functions:build-connection-tree)=
## 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`](functions:set-optimization-period)
- `end_time : pandas.Timestamp` end time of the simulation; read-only, set by [`set_optimization_period`](functions:set-optimization-period)
- `n_weeks : int` number of weeks in the simulation period; read-only, set by [`set_optimization_period`](functions:set-optimization-period)
- `keep_working_directory : bool` If `True`, do not delete the run directory when the ProdriskSession [expires](functions:destructor).
- `n_scenarios : int`: number of scenarios

(api_core_functions)=
# 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()`