Functional Mockup Units

Functional Mockup Units (FMUs) are packaged simulation models. The standard makes it quite easy to use simulation models and it can be exported by many different simulation software packages. More information about the standard can be found on the FMI Homepage. The simulators in eta_utility are based on the fmpy package.

fmpy is a Python implementation of the standard and offers limited additional functionality. For this reason and because the standard is written for C, fmpy is neither very Pythonic nor very easy to use. Therefore, eta_utility implements wrappers which allow for the simulation of both ModelExchange and Co-Simulation FMU models. The wrappers have an interface similar to LiveConnect with regard to the step function. This enables easy substitution of simulation models with direct connections to actual devices.

class eta_utility.simulators.FMUSimulator(_id: int, fmu_path: Path, start_time: TimeStep = 0, stop_time: TimeStep = 1, step_size: TimeStep = 1, names_inputs: Sequence[str] | None = None, names_outputs: Sequence[str] | None = None, init_values: Mapping[str, float] | None = None, *, return_type: str | None = None)[source]

FMU simulator object.

Parameters:

  • _id – FMU instance ID.

  • fmu_path – Path to the FMU file.

  • start_time – Simulation start time in seconds.

  • stop_time (float) – Simulation stop time in seconds.

  • step_size – Simulation step size in seconds.

  • names_inputs – List of input names that correspond to names used in the FMU file (e.g. [‘u’, ‘p’]). If the step function is going to be used with lists as input values, this list will be used to translate between the list position and the variable name in the FMU.

  • names_outputs – List of output names that correspond to names used in the FMU file (e.g. [‘y’, ‘th’, ‘thdot’]). If the step function should return only specific values instead of all results as a dictionary, this parameter can be specified to determine, which parameters should be returned.

  • init_values – Starting values for parameters that should be pushed to the FMU with names corresponding to variables in the FMU.

  • return_type (str) – “dict” or “list”. Alter the standard behavior, which is to return lists from the step and get_values functions only if both, “names_inputs” and “names_outputs” are specified. This parameter will force the step and get_values functions to always return either dictionaries or lists.

fmu_path

Path to the FMU model.

start_time

Start time for the simulation in time increments.

stop_time

Stopping time for the simulation in time increments (only relevant if run in simulation loop).

step_size

Step size (time) for the simulation in time increments.

model_description: ModelDescription

Model description from the FMU (contains variable names, types, references and more).

fmu: FMU2Slave

Instance of the FMU Slave object.

time

Current simulation time.

property input_vars: list[str]

Ordered list of all available input variable names in the FMU.

property output_vars: list[str]

Ordered list of all available output variable names in the FMU.

read_values(names: Sequence[str] | None = None) → dict[str | int, Any] | list[source]

Return current values of the simulation without advancing a simulation step or the simulation time.

Parameters:

names – Sequence of values to read from the FMU. If this is None (default), all available values will be read.

set_values(values: Sequence[Number | bool] | Mapping[str, Number | bool]) → None[source]

Set values of simulation variables without advancing a simulation step or the simulation time.

Parameters:

values – Values that should be pushed to the FMU. Names of the input_values must correspond to variables in the FMU. If passing as a Sequence, make sure the order corresponds to the order of the input_vars property.

step(input_values: Sequence[Number | bool] | Mapping[str, Number | bool] | None = None, output_names: Sequence[str] | None = None, advance_time: bool = True, nr_substeps: int | None = None) → dict[str | int, Any] | list[Any][source]

Simulate next time step in the FMU with defined input values and output values.

Parameters:

  • input_values – Current values that should be pushed to the FMU. Names of the input_values must correspond to variables in the FMU. If passing as a Sequence, make sure the order corresponds to the order of the input_vars property.

  • advance_time – Decide if the FMUsimulator should add one timestep to the simulation time or not. This can be deactivated, if you just want to look at the result of a simulation step beforehand, without actually advancing simulation time.

  • nr_substeps – if simulation steps are divided into substeps, this value will let the simulator know that no time violation warning is necessary.

Returns:

Resulting input and output values from the FMU with the keys named corresponding to the variables in the FMU.

classmethod simulate(fmu_path: Path, start_time: TimeStep = 0, stop_time: TimeStep = 1, step_size: TimeStep = 1, init_values: Mapping[str, float] | None = None) → np.ndarray[source]

Instantiate a simulator with the specified FMU, perform simulation and return results.

Parameters:

  • fmu_path – Path to the FMU file.

  • start_time – Simulation start time in seconds.

  • stop_time (float) – Simulation stop time in seconds.

  • step_size – simulation step size in seconds.

  • init_values – Starting values for parameters that should be pushed to the FMU with names corresponding to variables in the FMU.

reset(init_values: Mapping[str, float] | None = None) → None[source]

Reset FMU to specified initial condition.

Parameters:

init_values – Values for initialization.

close() → None[source]

Close the FMU and tidy up the unzipped files.

The FMU2MESlave is a wrapper for ModelExchange FMUs which provides similar functionality to Co-Simulation FMUs while using the Cvode solver from fmpy.

class eta_utility.simulators.FMU2MESlave(**kwargs: Any)[source]

Helper class for simulation of FMU2 FMUs. This is as wrapper for FMU2Model. It can be used to wrap model exchange FMUs such that they can be simulated similar to a co-simulation FMU. This is especially helpful for testing model exchange FMUs.

It exposes an interface that emulates part of the original FMU2Slave class from fmpy.

fmi2True: int = 1
fmi2False: int = 0
fmi2OK: int = 0
fmi2Warning: int = 1
fmi2Discard: int = 2
fmi2Error: int = 3
fmi2Fatal: int = 4
fmi2Pending: int = 5
setupExperiment(tolerance: float | None = None, startTime: float = 0.0, stopTime: float | None = None, **kwargs: Any) → int[source]

Experiment setup and storage of required values.

Parameters:

  • tolerance – Solver tolerance, default value is 1e-5.

  • startTime – Starting time for the experiment.

  • stopTime – Ending time for the experiment.

  • kwargs – Other keyword arguments that might be required for FMU2Model.setupExperiment in the future.

Returns:

FMI2 return value.

exitInitializationMode(**kwargs: Any) → int[source]

Exit the initialization mode and set up the cvode solver.

See also: fmpy.fmi2.FMU2Model.exitInitializationMode

Parameters:

kwargs – Keyword arguments accepted by FMU2Model.exitInitializationMode.

Returns:

FMI2 return value.

doStep(currentCommunicationPoint: float, communicationStepSize: float, noSetFMUStatePriorToCurrentPoint: int | None = None) → int[source]

Perform a simulation step. Advance simulation from currentCommunicationPoint by communicationStepSize.

Also refer to the FMI2 Standard documentation.

Parameters:

  • currentCommunicationPoint – Current time stamp (starting point for simulation step).

  • communicationStepSize – Time step size.

  • noSetFMUStatePriorToCurrentPoint – Determine whether a reset before currentCommunicationPoint is possible. Must be either fmi2True or fmi2False.

Returns:

FMU2 return value.