FMU Module

class corrai.fmu.ModelicaFmuModel(fmu_path, simulation_dir=None, output_list=None, boundary_table_name=None)

Bases: Model

Wrapper for a Modelica FMU (Functional Mock-up Unit) in the corrai Model formalism.

Provides functionality to: - Load an FMU and its metadata. - Query property initial values. - Run simulations with configurable options. - Handle boundary conditions using a CombiTimeTable if defined.

Parameters:

• fmu_path (Path | str) – Path to the FMU file.

• simulation_dir (Path) – Directory for simulation files. A temporary directory is created if not provided.

• output_list (list[str]) – Names of FMU variables to record during simulation.

• boundary_table_name (str | None) – Name of the CombiTimeTable object in the FMU used for boundary conditions. If provided, boundary data can be passed through simulation_options["boundary"] or property_dict["boundary"]. If None (default), boundaries are ignored. Boundaries specified in property_dict will always override simulation_options boundaries

Examples

>>> import pandas as pd
>>> from corrai.fmu import ModelicaFmuModel

>>> simu = ModelicaFmuModel(
...     fmu_path=fmu_path,
...     output_list=["Boundaries.y[1]", "Boundaries.y[2]"],
...     boundary_table_name="Boundaries",
... )

>>> new_bounds = pd.DataFrame(
...     {"Boundaries.y[1]": [1, 2, 3], "Boundaries.y[2]": [3, 4, 5]},
...     index=range(3, 6),
... )

>>> res = simu.simulate(
...     simulation_options={
...         "solver": "CVode",
...         "startTime": 3,
...         "stopTime": 5,
...         "stepSize": 1,
...         "boundary": new_bounds,
...     },
...     solver_duplicated_keep="last",
... )

Boundaries.y[1] Boundaries.y[2]

time 3.0 1.0 3.0 4.0 2.0 4.0 5.0 3.0 5.0

__init__(fmu_path, simulation_dir=None, output_list=None, boundary_table_name=None)

get_property_values(property_list)

Retrieve initial values of FMU properties.

Parameters:

property_list (str | tuple[str, ...] | list[str]) – Name(s) of FMU properties to query.

Returns:

List of default values or None if unavailable.

Return type:

list[str | int | float | None]

Examples

>>> from corrai.fmu import ModelicaFmuModel
>>> model = ModelicaFmuModel("rosen.fmu", output_list=["res.showNumber"])
>>> model.get_property_values("x.k")
['2.0']
>>> model.get_property_values(["x.k", "y.k"])
['2.0', '2.0']

set_property_values(property_dict)

simulate(property_dict=None, simulation_options=None, solver_duplicated_keep='last', post_process_pipeline=None, debug_param=False, debug_logging=False, logger=None)

Run an FMU simulation with properties and boundary configuration.

Parameters:

• property_dict (dict[str, float | int | str]) – Dictionary of FMU parameter values to set before simulation. May include a key "boundary" with a DataFrame of boundary conditions. If both property_dict and simulation_options specify boundaries, the one in property_dict takes precedence.

• simulation_options (dict) –

  Simulation settings. Supported keys include:

  • startTime : float or pandas.Timestamp

  • stopTime : float or pandas.Timestamp

  • stepSize : float or pandas.TimeDelta

  • outputIntervalfloat or pandas.TimeDelta. If not provided, it will

    be set equal to stepSize

  • solver : str

  • tolerance : float

  • fmi_type : {“CoSimulation”, “ModelExchange”}

  • boundary : pandas.DataFrame of boundary conditions

• solver_duplicated_keep (str) – Which entry to keep if solver outputs duplicated indices.

• post_process_pipeline (Pipeline) – Transformation pipeline applied to simulation results before returning.

• debug_param (bool) – If True, prints the property dictionary before simulation.

• debug_logging (bool) – Enable verbose logging from fmpy.

• logger (callable, optional) – Custom logger for fmpy.

Returns:

Simulation results indexed by time. If startTime is a pandas.Timestamp, the index is a DateTimeIndex; otherwise, a numeric index is used.

Return type:

DataFrame

Raises:

ValueError – If startTime or stopTime are outside the boundary DataFrame.

Notes

• Duplicate time indices are resolved using solver_duplicated_keep.

Examples

Run a basic simulation with default options:

>>> model = ModelicaFmuModel("simple.fmu", output_list=["y"])
>>> res = model.simulate(
...     simulation_options={"startTime": 0, "stopTime": 10, "stepSize": 1}
... )
>>> res.head()
   y
0.0  0.0
1.0  1.1
2.0  2.3
...

Run a simulation with boundary conditions:

>>> import pandas as pd
>>> x = pd.DataFrame({"Boundaries.y[1]": [1, 2, 3]}, index=[0, 1, 2])
>>> model = ModelicaFmuModel(
...     "boundary_test.fmu",
...     output_list=["Boundaries.y[1]"],
...     boundary_table_name="Boundaries",
... )
>>> res = model.simulate(
...     simulation_options={
...         "boundary": x,
...         "startTime": 0,
...         "stopTime": 2,
...         "stepSize": 1,
...     }
... )
>>> res.head()
      Boundaries.y[1]
time
0.0               1.0
1.0               2.0
2.0               3.0

save(file_path)

Save the FMU file to a new location.

Parameters:

file_path (Path) – Destination path.

__repr__()

Return a string representation of the FMU model.

Returns:

A formatted string containing FMU name, description, version, and available parameters.

Return type:

str

Examples

>>> print(model)
Model Name: rosen
Description: ModelDescription(
    fmiVersion='2.0', modelName='rosen',
    coSimulation=CoSimulation(modelIdentifier='rosen'),
    modelExchange=ModelExchange(modelIdentifier='rosen'),
    scheduledExecution=None
)
Version: 2.0
Parameters:
  Name: x.k, Default Value: 2.0, Description: Constant output value
  Name: y.k, Default Value: 2.0, Description: Constant output value
  Name: res.significantDigits, Default Value: 2,
  Description: Number of significant digits to be shown