sofirpy.simulation.simulation module#

This module allows to co-simulate multiple fmus and models written in python.

class sofirpy.simulation.simulation.Connection(input_point: SystemParameter, output_point: SystemParameter)[source]#

Bases: object

Representing a connection between two systems.

Parameters:

  • input_point (SystemParameter) – SystemParameter object that represents an input of a system

  • output_point (SystemParameter) – SystemParameter object that represents an output of a system

class sofirpy.simulation.simulation.Simulator(stop_time: float, step_size: float, logging_step_size: float | None = None, fmu_paths: dict[str, str | PathLike[Any]] | None = None, model_classes: dict[str, type[SimulationEntity]] | None = None, connections_config: dict[str, list[Connection]] | None = None, init_configs: dict[str, dict[str, Any]] | None = None, parameters_to_log: dict[str, list[str]] | None = None)[source]#

Bases: BaseSimulator

Object that performs the simulation.

compute_time_array(stop_time: float, step_size: float, start_time: float) → ndarray[Any, dtype[float64]][source]#

Compute the time array for the simulation.

Parameters:

  • stop_time (float) – stop time for the simulation

  • step_size (float) – step size for the simulation

  • start_time (float) – start time of the simulation.

Returns:

time array

Return type:

npt.NDArray[np.float64]

convert_to_data_frame(results: ndarray[Any, dtype[void]]) → DataFrame[source]#

Covert result numpy array to DataFrame.

Parameters:

results (npt.NDArray[np.void]) – Results of the simulation.

Returns:

Results as DataFrame. Columns are named as follows: ‘<system_name>.<parameter_name>’.

Return type:

pd.DataFrame

get_dtypes_of_logged_parameters() → dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any][source]#

Get the dtypes of the logged parameters.

Returns:

dtypes of the logged parameters

Return type:

np.dtypes.VoidDType

get_units() → dict[str, str | None][source]#

Get a dictionary with units of all logged parameters.

Returns:

keys: parameter name, values: unit. If the unit can not be obtained it is set to None.

Return type:

Units

log_values(time: float, log_step: int) → None[source]#

Log parameter values that are set to be logged.

Parameters:

  • time (float) – current simulation time

  • log_step (int) – current time step

simulate() → DataFrame[source]#

Simulate the systems.

The following steps are performed.

  1. A time array is created starting from 0 to the specified stop time. The intervals have the size of the step size. If the last element in the array is greater than the stop time, it is deleted. Advancing in time this way, leads to less numerical errors in comparison than using a while loop and adding the step size in each iteration.

  2. The logging multiple is calculated from the logging step size. Since the logging step size needs to be a multiple of the step size, the logging multiple is an integer. Therefore a precise modulo operation inside the simulation loop can be performed. E.g if the step size 1e-3 and the logging step size is 1e-1, the logging multiple will be 100. Therefor every 100 time step will be logged.

  3. The numpy results object is initialized.

  4. The start values are logged.

  5. The simulation loop starts.

    5.1 A simulation step is performed.

    5.2 All system inputs are set.

    5.3 If the time step + 1 is a multiple of the logging multiple, values are logged.

  6. The simulation process is concluded.

  7. The numpy results object is converted to a pandas DataFrame.

Returns:

result DataFrame with times series of logged parameters

Return type:

pd.DataFrame

class sofirpy.simulation.simulation.System(simulation_entity: SimulationEntity, name: str)[source]#

Bases: object

System object representing a simulation entity.

Parameters:

  • simulation_entity (SimulationEntity) – fmu or python model

  • name (str) – name of the system

class sofirpy.simulation.simulation.SystemParameter(system_name: str, name: str)[source]#

Bases: object

SystemParameter object representing a parameter in a system.

Parameters:

  • system (str) – Name of the corresponding system

  • name (str) – name of the parameter

sofirpy.simulation.simulation.init_connections(connections_config: dict[str, list[Connection]]) → list[Connection][source]#

Initialize all the connections.

Parameters:

connections_config (ConnectionsConfig) – Defines how all systems are connected.

Returns:

List of Connections.

Return type:

list[Connection]

sofirpy.simulation.simulation.init_parameter_list(parameters_to_log: dict[str, list[str]]) → list[SystemParameter][source]#

Initialize all parameters that should be logged.

Parameters:

parameters_to_log (ParametersToLog) – Defines which parameters should be logged.

Returns:

List of system parameters that should be logged.

Return type:

list[SystemParameter]

sofirpy.simulation.simulation.simulate(stop_time: float, step_size: float, fmu_paths: dict[str, str | PathLike[Any]] | None = None, model_classes: dict[str, type[SimulationEntity]] | None = None, connections_config: dict[str, list[Connection]] | None = None, init_configs: dict[str, dict[str, Any]] | None = None, parameters_to_log: dict[str, list[str]] | None = None, logging_step_size: float | None = None, *, get_units: Literal[True]) → tuple[DataFrame, dict[str, str | None]][source]#
sofirpy.simulation.simulation.simulate(stop_time: float, step_size: float, fmu_paths: dict[str, str | PathLike[Any]] | None = None, model_classes: dict[str, type[SimulationEntity]] | None = None, connections_config: dict[str, list[Connection]] | None = None, init_configs: dict[str, dict[str, Any]] | None = None, parameters_to_log: dict[str, list[str]] | None = None, logging_step_size: float | None = None, *, get_units: Literal[False]) → DataFrame
sofirpy.simulation.simulation.simulate(stop_time: float, step_size: float, fmu_paths: dict[str, str | PathLike[Any]] | None = None, model_classes: dict[str, type[SimulationEntity]] | None = None, connections_config: dict[str, list[Connection]] | None = None, init_configs: dict[str, dict[str, Any]] | None = None, parameters_to_log: dict[str, list[str]] | None = None, logging_step_size: float | None = None) → DataFrame

Simulate fmus and models written in python.

Any number of python models and fmus can be simulated, but at least one python model or fmu has to be simulated.

Parameters:

  • stop_time (float) – stop time for the simulation

  • step_size (float) – step size for the simulation

  • 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 the fmu1>,
...    "<name of the fmu 2>": <Path to the 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 -> Class of the model. The class that defines the model must inherit from the abstract class SimulationEntity.

    >>> model_classes = {
...    "<name of the model 1>": <class of the model1>
...    "<name of the model 2>": <class 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.

  • init_configs (co.InitConfigs | None, optional) –

    Dictionary which defines initial configurations for the systems. Fmus can only have the key ‘start_values’ for specifying the start values. key -> name of the system; value -> dictionary (key -> config name; value -> config value)

    >>> init_configs = {
...     "<name of system 1>":
...     {
...         "<name of config 1>": <config value 1>,
...         "<name of config 2>", <config value 2>
...     },
...     "<name of fmu 1>":
...     {
...         "start_values": {
...             "<name of parameter 1>": (<start value>, unit e.g 'kg.m2'),
...             "<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.

  • get_units (bool, optional) – Determines whether the units of the logged parameter should be returned. Defaults to False.

Returns:

Result DataFrame with times series of logged parameters, units of logged parameters.

Return type:

pd.DataFrame | tuple[pd.DataFrame, co.Units]