sofirpy.rdm.run module

This module allows to create, interact with and store a simulation run.

class sofirpy.rdm.run.ConfigDict[source]: Bases: TypedDict

class sofirpy.rdm.run.ConfigKeyType(value)[source]

Bases: Enum

An enumeration.

class sofirpy.rdm.run.Fmu(name: 'str', connections: 'co.Connections | None', start_values: 'dict[str, co.StartValue] | None', parameters_to_log: 'list[str] | None', fmu_path: 'Path')[source]: Bases: Model

class sofirpy.rdm.run.MetaConfigDict[source]: Bases: TypedDict

class sofirpy.rdm.run.Model(name: 'str', connections: 'co.Connections | None', start_values: 'dict[str, co.StartValue] | None', parameters_to_log: 'list[str] | None')[source]: Bases: object

class sofirpy.rdm.run.ModelConfigDict[source]: Bases: TypedDict

class sofirpy.rdm.run.Models(fmus: 'dict[str, Fmu]', python_models: 'dict[str, PythonModel]', can_simulate_fmu: 'bool' = True, can_simulate_python_model: 'bool' = True)[source]: Bases: object

class sofirpy.rdm.run.PythonModel(name: 'str', connections: 'co.Connections | None', start_values: 'dict[str, co.StartValue] | None', parameters_to_log: 'list[str] | None', code: 'str | None' = None, model_class: 'type[SimulationEntity] | None' = None)[source]: Bases: Model

class sofirpy.rdm.run.Results(time_series: 'pd.DataFrame', units: 'co.Units | None')[source]: Bases: object

class sofirpy.rdm.run.Run(run_name: str, _run_meta: RunMeta, _models: Models, _simulation_config: SimulationConfig, _results: Results | None = None)[source]

Bases: object

Run object representing a simulation Run.

A Run can be initiated from a config file or loaded from a hdf5 file. It provides several methods for updating the configuration of the run. A Run can be serialized and stored inside a hdf5 file.

add_fmu(fmu_name: str, fmu_path: Path | str, connections: list[co.Connection] | None = None, start_values: dict[str, co.StartValue] | None = None, parameters_to_log: list[str] | None = None) → None[source]

Add a fmu.

Parameters:

fmu_name (str) – Name of the fmu.
fmu_path (Path | str) – Path to the fmu.
connections (list[_Connection] | None, optional) – Connection config for the fmu. Defaults to None.
start_values (StartValues | None, optional) – Start value for the fmu. Defaults to None.
parameters_to_log (list[str] | None, optional) – Parameters of the fmu that should be logged . Defaults to None.

add_keyword(keyword: str) → None[source]

Add a keywords to the list of keywords.

Parameters:: keyword (str) – Keyword to be added.

add_python_model(model_name: str, model_class: type[SimulationEntity], connections: list[co.Connection] | None = None, start_values: dict[str, co.StartValue] | None = None, parameters_to_log: list[str] | None = None) → None[source]

Add a python model.

Parameters:

model_name (str) – Name of the python model.
model_class (type[SimulationEntity]) – Model class.
connections (list[_Connection] | None, optional) – Connection config for the python model. Defaults to None.
start_values (StartValues | None, optional) – Start value for the python model. Defaults to None.
parameters_to_log (list[str] | None, optional) – Parameters of the python model that should be logged . Defaults to None.

Raises:

TypeError – ‘model_class’ is not subclass of SimulationEntity

append_parameter_to_log(model_name: str, parameter_name: str) → None[source]

Append a parameter that should be logged in the specified model.

Parameters:

model_name (str) – Name of the model.
parameter_name (str) – Name of the parameter.

change_model_name(prev_model_name: str, new_model_name: str) → None[source]

Change the name of a model.

Parameters:

prev_model_name (str) – Name of the model to be changed.
new_model_name (str) – New model name.

property connections: co.ConnectionsConfig | None

Connection configuration for the simulation.

Returns:: Connection configuration for the simulation.
Return type:: ConnectionsConfig | None

create_file_from_source_code(model_name: str, target_path: str | Path) → None[source]

Create a python file from the source code of a python model.

Parameters:

model_name (str) – Name of the python model.
target_path (str | Path) – Target path.

property date: datetime

Date and time run was created.

Returns:: Date and time run was created.
Return type:: datetime

property dependencies: dict[str, str]

Dependencies installed in the Python environment when the run is created.

Returns:: key -> name of the package; value -> version
Return type:: dict[str, str]

property description: str

Description of the Run.

Returns:: Description of the Run.
Return type:: str

classmethod from_config(run_name: str, stop_time: float, step_size: float, keywords: list[str] | None = None, description: str | None = None, fmu_paths: co.FmuPaths | None = None, model_classes: co.ModelClasses | None = None, connections_config: co.ConnectionsConfig | None = None, start_values: co.StartValues | None = None, parameters_to_log: co.ParametersToLog | None = None, logging_step_size: float | None = None) → Self[source]

Initialize a run from a configuration.

Parameters:

run_name (str) – Name of the run.
stop_time (float) – stop time for the simulation
step_size (float) – step size for the simulation
keywords (list[str] | None, optional) – Keywords describing the simulation. Defaults to None.
description (str, optional) – Description of the run. Defaults to None.
fmu_paths (FmuPaths | None, optional) –
Dictionary which defines which fmu should be simulated. key -> name of the fmu; value -> path to the fmu
```
>>> fmu_paths = {
...    "<name of the fmu 1>": "path/to/fmu1",
...    "<name of the fmu 2>": "path/to/fmu2",
... }
```
Note: The name of the fmus can be chosen arbitrarily, but each name in ‘fmu_paths’ and ‘model_classes’ must occur only once. Defaults to None.
model_classes (ModelClasses | None, optional) –
Dictionary which defines which Python Models should be simulated. key -> name of the model; value -> Instance of th model. The class that defines the model must inherit from the abstract class SimulationEntity
```
>>> model_classes = {
...    "<name of the model 1>": <Instance of the model1>
...    "<name of the model 2>": <Instance of the model2>
... }
```
Note: The name of the models can be chosen arbitrarily, but each name in ‘fmu_paths’ and ‘model_classes’ must occur only once. Defaults to None..

connections_config (ConnectionsConfig | None, optional) –

Dictionary which defines how the inputs and outputs of the systems (fmu or python model) are connected. key -> name of the system; value -> list of connections

>>> connections_config = {
...     "<name of the system 1>": [
...         {
...             "parameter_name":       "<name of the input"
...                                     "parameter of the system>",
...             "connect_to_system":    "<name of the system the input"
...                                     "parameter should be connected to>",
...             "connect_to_external_parameter":    "<name of the output"
...                                                 "parameter in the"
...                                                 "connected system the"
...                                                 "input parameter should"
...                                                 "be connected to>"
...         },
...         {
...             "parameter_name":       "<name of the input"
...                                     "parameter of the system>",
...             "connect_to_system":    "<name of the system the input"
...                                     "parameter should be connected to>",
...             "connect_to_external_parameter":    "<name of the output"
...                                                 "parameter in the"
...                                                 "connected system the"
...                                                 "input parameter should"
...                                                 "be connected to>"
...         }
...     ],
...     "<name of the system 2>": [
...         {
...             "parameter_name":       "<name of the input"
...                                     "parameter of the system>",
...             "connect_to_system":    "<name of the system the input"
...                                     "parameter should be connected to>",
...             "connect_to_external_parameter":    "<name of the output"
...                                                 "parameter in the"
...                                                 "connected system the"
...                                                 "input parameter should"
...                                                 "be connected to>"
...         }
...     ]
... }

Defaults to None.

start_values (StartValues | None, optional) –

Dictionary which defines start values for the systems. For Fmus the unit can also be specified as a string. key -> name of the system; value -> dictionary (key -> name of the parameter; value -> start value)

>>> start_values = {
...     "<name of system 1>":
...     {
...         "<name of parameter 1>": <start value>,
...         "<name of parameter 2>", (<start value>, unit e.g 'kg.m2')
...     },
...     "<name of system 2>":
...     {
...         "<name of parameter 1>": <start value>,
...         "<name of parameter 2>": <start value>
...     }
... }

Defaults to None.

parameters_to_log (ParametersToLog | None, optional) –

Dictionary that defines which parameters should be logged. key -> name of the system; value -> list of parameters names to be logged

>>> parameters_to_log = {
...     "<name of system 1>":
...     [
...         "<name of parameter 1>",
...         "<name of parameter 2>",
...     ],
...     "<name of system 2>":
...     [
...         "<name of parameter 1>",
...         "<name of parameter 2>",
...     ]
... }

Defaults to None.

logging_step_size (float | None, optional) – step size for logging. It must be a multiple of the chosen simulation step size. Example: If the simulation step size is set to 1e-3 and logging step size is set to 2e-3, every second time step is logged. Defaults to None.

Returns:

Run instance.

Return type:

Run

classmethod from_config_file(run_name: str, config_file_path: str | Path, fmu_paths: co.FmuPaths | None = None, model_classes: co.ModelClasses | None = None) → Self[source]

Initialize a run from a config file.

Parameters:

run_name (str) – Name of the run.
config_file_path (Path | str) – Path to the config file.
fmu_paths (FmuPaths | None, optional) –
Dictionary which defines which fmu should be simulated. key -> name of the fmu; value -> path to the fmu
```
>>> fmu_paths = {
...    "<name of the fmu 1>": "path/to/fmu1",
...    "<name of the fmu 2>": "path/to/fmu2",
... }
```
Note: The name of the fmus can be chosen arbitrarily, but each name in ‘fmu_paths’ and ‘model_classes’ must occur only once. Defaults to None.
model_classes (ModelClasses | None, optional) –
Dictionary which defines which Python Models should be simulated. key -> name of the model; value -> Instance of th model. The class that defines the model must inherit from the abstract class SimulationEntity
```
>>> model_classes = {
...    "<name of the model 1>": <Instance of the model1>
...    "<name of the model 2>": <Instance of the model2>
... }
```
Note: The name of the models can be chosen arbitrarily, but each name in ‘fmu_paths’ and ‘model_classes’ must occur only once. Defaults to None.

Returns:

Run instance.

Return type:

Run

classmethod from_hdf5(run_name: str, hdf5_path: Path | str) → Run[source]

Load a run from a hdf5 file.

Parameters:

run_name (str) – Name of the run.
hdf5_path (Path | str) – Path to the hdf5 file.

Returns:

Run instance.

Return type:

Run

get_config() → ConfigDict[source]

Get the configuration for the run.

Returns:: Configuration for the run.
Return type:: ConfigDict

get_connection(model_name: str, input_name: str) → co.Connection | None[source]

Get the connection of an input parameter.

Parameters:

model_name (str) – Name of the model.
input_name (str) – Name of the input parameter.

Returns:

The connection of the input parameter.

Return type:

_Connection | None

get_connections_of_model(model_name: str) → co.Connections | None[source]

Get the connections of a model.

Parameters:: model_name (str) – Name of the model.
Returns:: Connections of the model.
Return type:: co.Connections | None

get_fmu_path(fmu_name: str) → Path[source]

Get the path of a fmu.

Parameters:: fmu_name (str) – Name of the fmu.
Returns:: Path of the fmu.
Return type:: Path

get_model_class(model_name: str) → type[SimulationEntity] | None[source]

Get the instance of a python model.

Parameters:: model_name (str) – Name of the model.
Returns:: Model instance.
Return type:: type[SimulationEntity] | None

get_parameters_to_log_of_model(model_name: str) → list[str] | None[source]

Get the parameters that are logged in the specified model.

Parameters:: model_name (str) – Name of the model.
Returns:: Parameters that are logged in the specified model.
Return type:: list[str] | None

get_source_code_of_python_model(model_name: str) → str[source]

Get the class source code of a python model.

Parameters:: model_name (str) – Name of the python model.
Returns:: Source code of the class.
Return type:: str

get_start_value(model_name: str, parameter_name: str) → co.StartValue | None[source]

Get a start value from a model.

Parameters:

model_name (str) – Name of the model.
parameter_name (str) – Name of the parameter inside the model.

Returns:

Start value

Return type:

StartValue | None

get_start_values_of_model(model_name: str) → dict[str, co.StartValue] | None[source]

Get the start values of a model.

Parameters:: model_name (str) – Name of the model.
Returns:: Start values of the model.
Return type:: dict[str, co.StartValue] | None

property keywords: list[str]

Keywords describing the run.

Returns:: Keywords describing the run.
Return type:: list[str]

property logging_step_size: float

Logging step size of the simulation.

Returns:: Logging step size of the simulation.
Return type:: float

property models: dict[str, Model]

Models of the run. key -> name of the model; value -> Model object

Returns:: Models of the run. key -> name of the model; value -> Model object
Return type:: dict[str, Model]

move_fmu(fmu_name: str, target_directory: str | Path) → None[source]

Move a fmu to a target directory.

Parameters:

fmu_name (str) – Name of the fmu.
target_directory (str | Path) – Target directory.

property os: str

Operating system the simulation was performed on.

Returns:: Operating system the simulation was performed on.
Return type:: str

property parameters_to_log: co.ParametersToLog | None

Parameters that are logged during the simulation.

Returns:: Parameters that are logged during the simulation.
Return type:: ParametersToLog | None

property python_version: str

Version of Python the run was performed with.

Returns:: Version of Python the run was performed with.
Return type:: str

remove_connection(model_name: str, input_name: str) → None[source]

Remove the connection of an input parameter.

Parameters:

model_name (str) – Name of the model.
input_name (str) – Name of the input parameter.

remove_connections_of_model(model_name: str) → None[source]

Remove the connections of a model.

Parameters:: model_name (str) – Name of the model.

remove_fmu(fmu_name: str) → None[source]

Remove a fmu.

Parameters:: fmu_name (str) – Name of the fmu that should be removed.

remove_keyword(keyword: str) → None[source]

Remove a keyword from the list of keywords.

Parameters:: keyword (str) – Keywords to be removed.

remove_parameter_to_log(model_name: str, parameter_name: str) → None[source]

Remove a parameter to be logged in the specified model.

Parameters:

model_name (str) – Name of the model.
parameter_name (str) – Name of the parameter.

remove_parameters_to_log_of_model(model_name: str) → None[source]

Remove the parameters that are logged in the specified model.

Parameters:: model_name (str) – Name of the model.

remove_python_model(model_name: str) → None[source]

Remove a python model.

Parameters:: model_name (str) – Name of the python model.

remove_start_value(model_name: str, parameter_name: str) → None[source]

Remove the start value of parameter inside a model.

Parameters:

model_name (str) – Name of the model.
parameter_name (str) – Name of the parameter.

remove_start_values_of_model(model_name: str) → None[source]

Remove all start values of a model.

Parameters:: model_name (str) – Name of the model.

set_connection(model_name: str, parameter_name: str, connect_to_system: str, connect_to_external_parameter: str) → None[source]

Set the connection of an input parameter.

Parameters:

model_name (str) – Name of the model.
connection (_Connection) – Connection to be set.

set_connections_of_model(model_name: str, connections: list[Connection]) → None[source]

Set the connections of a model.

Parameters:

model_name (str) – Name of the model.
connections (Connections) – Connections to be set.

set_parameters_to_log_of_model(model_name: str, parameters_to_log: list[str]) → None[source]

Set the parameter that are logged in the specified model.

Parameters:

model_name (str) – Name of the model.
parameters_to_log (list[str]) – Parameters that should be logged in the specified model.

Set a start value for a parameter inside a model.

Parameters:

model_name (str) – Name of the model.
parameter_name (str) – Name of the parameter.
value (StartValue) – Start value.

Set the start values of a model.

Parameters:

model_name (str) – Name of the model.
start_values (dict[str, StartValue]) – Start values for the model.

simulate() → None[source]: Simulate the run.

property sofirpy_version: str

Version of sofirpy the run was performed with.

Returns:: Version of sofirpy the run was performed with.
Return type:: str

property start_values: co.StartValues | None

Start values of the simulation.

Returns:: Start values of the simulation.
Return type:: co.StartValues | None

property step_size: float

Step size of the simulation.

Returns:: Step size of the simulation.
Return type:: float

property stop_time: float

Stop time for the simulation.

Returns:: Stop time for the simulation.
Return type:: float

property time_series: DataFrame

Time series results of the simulation.

Raises:: AttributeError – No simulation was performed.
Returns:: Time series results of the simulation.
Return type:: pd.DataFrame

to_hdf5(hdf5_path: Path | str) → None[source]

Store the run inside a hdf5 file.

Parameters:: hdf5_path (Path | str) – Path to the hdf5 file.

property units: co.Units | None

Units of the logged parameters.

Raises:: AttributeError – No simulation was performed.
Returns:: Units of the logged parameters.
Return type:: Units | None

class sofirpy.rdm.run.SimulationConfigDict[source]: Bases: TypedDict