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)

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(systems: dict[str, System], connections: list[Connection], parameters_to_log: list[SystemParameter])

Bases: object

Object that performs the simulation.

Parameters:

• systems (list[System]) – list of systems which are to be simulated

• connections (list[Connection]) – list of connections between the systems

• parameters_to_log (list[SystemParameter]) – List of Parameters that should be logged.

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

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]

conclude_simulation() → None

Conclude the simulation for all simulation entities.

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

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

do_step(time: float) → None

Perform a calculation in all systems.

Parameters:

• time (float) – current simulation time

• step_size (float) – step size of the simulation

get_dtypes_of_logged_parameters() → VoidDType

Get the dtypes of the logged parameters.

Returns:

dtypes of the logged parameters

Return type:

np.dtypes.VoidDType

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

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

Log parameter values that are set to be logged.

Parameters:

• time (float) – current simulation time

• log_step (int) – current time step

set_systems_inputs() → None

Set inputs for all systems.

simulate(stop_time: float, step_size: float, logging_step_size: float, start_time: float = 0.0) → DataFrame

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.

Parameters:

• stop_time (float) – stop time for the simulation

• step_size (float) – step size for the simulation

• logging_step_size (float) – logging step size for the simulation

• start_time (float, optional) – start time of the simulation. Defaults to 0.0.

Returns:

result DataFrame with times series of logged parameters

Return type:

pd.DataFrame

class sofirpy.simulation.simulation.System(simulation_entity: SimulationEntity, name: str)

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)

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]

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_fmus(fmu_paths: Mapping[str, str | Path], step_size: float, start_values: dict[str, dict[str, bool | float | int | str | object | tuple[bool | float | int | str | object, str]]]) → dict[str, System]

Initialize fmus as a System object and store them in a dictionary.

Parameters:

• fmu_paths (FmuPaths) – Dictionary which defines which fmu should be simulated. key -> name of the fmu; value -> path to the fmu

• step_size (float) – step size of the simulation

• start_values (StartValues) – Dictionary which defines start values for the systems.

Returns:

key -> fmu name; value -> System instance

Return type:

dict[str, System]

sofirpy.simulation.simulation.init_models(model_classes: Mapping[str, type[SimulationEntity]], start_values: dict[str, dict[str, bool | float | int | str | object | tuple[bool | float | int | str | object, str]]]) → dict[str, System]

Initialize python models as a System object and store them in a dictionary.

Parameters:

• model_classes (ModelClasses) – Dictionary which defines which Python Models should be simulated.

• start_values (StartValues) – Dictionary which defines start values for the systems.

Returns:

key -> python model name; value -> System instance

Return type:

dict[str, System]

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

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: 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, *, get_units: Literal[True]) → tuple[DataFrame, dict[str, str | None]]

sofirpy.simulation.simulation.simulate(stop_time: float, step_size: float, 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, *, get_units: Literal[False]) → DataFrame

sofirpy.simulation.simulation.simulate(stop_time: float, step_size: float, 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) → 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.

• 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.

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

Raises:

• TypeError – start_time type was invalid

• TypeError – step_size type was invalid

• TypeError – fmu_paths type was invalid

• TypeError – model_classes type was invalid

• ValueError – fmu_paths and model_classes were ‘None’

• ValueError – start_time value was invalid

• ValueError – step_size value was invalid

Returns:

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

Return type:

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