eta_ctrl.simulators.fmu module

The FMUSimulator class enables easy simulation of FMU files.

class eta_ctrl.simulators.fmu.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)[source]

Bases: object

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.

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

input_mapping: Mapping of input names to model references

output_mapping: Mapping of output names to model references

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.

property parameter_vars: list[str]

Get names of all available parameters in the FMU.

Returns:: List of parameter variable names.

read_values(names: Sequence[str] | None = None) → dict[str, float][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.
Returns:: Read values from the FMU mapped with their names.

set_values(values: 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.

step(input_values: Mapping[str, float] | None = None, output_names: Sequence[str] | None = None, advance_time: bool = True, nr_substeps: int | None = None) → dict[str, float][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.
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.

classmethod inspect(fmu_path: pathlib.Path | str) → Iterator[FMUContext][source]

Context manager for inspecting an FMU to extract metadata.

Initializes a temporary FMU simulation environment to extract information such as input/output variable names, parameter start values, and variable bounds. Returns this data as a dictionary for use in TOML export or further analysis.

This method handles FMU loading, parsing, and cleanup internally, and is safe to use with with blocks. If initialization fails, it yields None.

Parameters:

fmu_path – Path to the FMU file (.fmu) as a string or Path.
output_path – Optional output path for the resulting file or reference.

Yield:

A dictionary with FMU metadata, or None on failure.

class eta_ctrl.simulators.fmu.VariableDict[source]

Bases: TypedDict

name: str

is_ext_input: bool

is_ext_output: bool

low_value: Number

high_value: Number

class eta_ctrl.simulators.fmu.FMUContext[source]

Bases: TypedDict

fmu_name: str

fmu_path: Path

actions: list[VariableDict]

observations: list[VariableDict]

parameters: dict[str, str | None]

class eta_ctrl.simulators.fmu.FMU2MESlave(**kwargs: Any)[source]

Bases: FMU2Model

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.