Co-Simulation Components

FMU Component

FMI 2.0 Co-Simulation FMU wrapper.

This module exposes FMUComponent, a CoSimComponent implementation backed by an FMI 2.0 co-simulation FMU via fmpy. The component derives input/output ports from the FMU model description, handles units for REAL signals, applies parameter starts during initialization, and supports direct feedthrough evaluation.

syssimx.components.fmu._require_fmpy()

Return type:

None

class syssimx.components.fmu.FMUComponent

Bases: CoSimComponent

FMU co-simulation wrapper implementing the CoSimComponent interface.

Supports FMI 2.0 co-simulation FMUs, typed input/output ports (REAL, INT, BOOL, STRING), and unit-aware REAL ports via pint.

state: dict[str, Any]

_vrs_in_bytes: dict[str, int]

_vrs_out_bytes: dict[str, int]

__init__(name, fmu_path, group=None)

Create the FMU component and derive port specifications.

Parameters:

• name (str) – Component name.

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

• group (str | None) – Optional component group for organization.

Raises:

• RuntimeError – If the FMU is not a co-simulation FMU.

• NotImplementedError – If the FMU uses an unsupported FMI version.

_md: ModelDescription

_md_vars: dict[str, ScalarVariable]

_instance: FMU2Slave | None

_unzipdir: str | None

direct_feedthrough: dict[str, set[str]]

_vrs_in_real: dict[str, int]

_vrs_in_int: dict[str, int]

_vrs_in_bool: dict[str, int]

_vrs_in_str: dict[str, int]

_vrs_out_real: dict[str, int]

_vrs_out_int: dict[str, int]

_vrs_out_bool: dict[str, int]

_vrs_out_str: dict[str, int]

get_default_parameters()

Return default parameter values from the FMU model description.

Returns:

Dict of parameter names to default values.

Return type:

dict[str, Any]

_build_port_specs()

Build input/output PortSpec objects from the model description.

Return type:

None

_build_value_reference_map()

Cache value references for fast typed access.

Return type:

None

_analyze_model_structure()

Populate model structure dependencies for outputs/derivatives/initials.

Return type:

None

_detect_direct_feedthrough()

Detect direct feedthrough dependencies for FMU outputs.

Return type:

dict[str, set[str]]

_require_instance()

Return the FMU instance or raise if not initialized.

Return type:

None

_initialize_component(t0)

Initialize and instantiate the FMU for simulation.

1. Extracts the FMU archive.

2. Creates the FMU2Slave instance.

3. Sets up the experiment with the start time.

4. Enters initialization mode.

5. Applies parameter start values.

6. Applies input start values from PortStates.

7. Exits initialization mode.

Parameters:

t0 (float) – Simulation start time.

Return type:

None

reinitialize_instance(t0)

Recreate the FMU instance and enter initialized state at t0.

This is intentionally different from FMI reset(). Some FMUs do not support reliable rollback through fmi2Reset after stepping, but can be restored by creating a fresh instance and applying reconstructed initial conditions through parameters.

Parameters:

t0 (float)

Return type:

None

_apply_parameters_starts()

Apply parameter start values to the FMU instance.

Return type:

None

_apply_input_starts()

Push initial input values from PortStates into the FMU.

Return type:

None

set_parameters(**parameters)

Set parameter values with validation and unit handling.

Parameters:

**parameters – Parameter name/value pairs.

Raises:

• KeyError – If a parameter name is unknown.

• TypeError – If a value does not match the parameter type or unit.

Return type:

None

get_parameters(*names)

Return parameter values, optionally limited to specific names.

Parameters:

*names (str) – Optional parameter names to fetch.

Raises:

KeyError – If a requested parameter name is unknown.

Return type:

dict[str, Any]

_abc_impl = <_abc._abc_data object>

set_inputs(signals, t=None)

Set input port values and push them to the FMU.

Parameters:

• signals (dict[str, Any]) – Mapping of input names to values.

• t (float | None) – Optional timestamp to record with inputs.

Raises:

• KeyError – If an input name is unknown.

• TypeError – If a value type does not match the port type.

• ValueError – If a REAL input is missing a value after unit conversion.

Return type:

None

get_outputs()

Return current output values as a dict of name to value.

Return type:

dict[str, Any]

_update_output_states(t=None, event_names=None)

Refresh output PortStates from the FMU instance.

Parameters:

• t (float | None) – Optional timestamp to record with outputs.

• event_names (list[str] | None) – Reserved for event-based updates (unused).

Return type:

None

_do_step_internal(t, dt)

Perform a single time step in the FMU.

Parameters:

• t (float) – Current communication point.

• dt (float) – Communication step size.

Return type:

None

set_state(state, t)

Restore FMU state from a serialized variable dictionary.

Parameters:

• state (dict[str, Any]) – Mapping of variable names to stored attributes/values.

• t (float) – Time to reinitialize the FMU at.

Return type:

None

get_state()

Return FMU variables as a serialized dictionary.

The dictionary includes variables that are not fixed and not local, along with their units and current values pulled from the FMU instance.

Returns:

Dict mapping variable names to unit/value attributes.

Return type:

dict[str, dict[str, Any]]

evaluate_outputs(inputs, t=None)

Evaluate outputs for a given input set without advancing time.

Parameters:

• inputs (dict[str, Any]) – Input values to apply.

• t (float | None) – Optional time to use for evaluation.

Returns:

Mapping of output names to raw (unitless) values.

Return type:

dict[str, Any]

reset()

Reset the component and release the FMU instance.

After reset, the component can be reinitialized via initialize().

Return type:

None

soft_reset(t0=0.0)

Reset the FMU to initial state without releasing the instance.

Uses FMI reset() to return to the instantiated state, then reinitializes with parameter and input starts.

Parameters:

t0 (float) – New start time for the simulation.

Return type:

None

_validate_parameter(name, value)

Validate and normalize a parameter value.

Parameters:

• name (str) – Parameter name.

• value (Any) – Proposed parameter value.

Returns:

Validated value, converted to the expected type/unit.

Raises:

TypeError – If the value is incompatible with the parameter type or unit.

Return type:

Quantity | float | int | bool | str

syssimx.components.fmu._port_type_from_var(var)

Determine PortType from ScalarVariable type.

Parameters:

var (ScalarVariable) – The model variable to determine the port type for.

Returns:

The corresponding PortType.

Return type:

PortType

Raises:

NotImplementedError – If the variable type is unsupported.

syssimx.components.fmu._convert_start_value(start, port_type, unit)

Convert start value string to appropriate type based on PortType and unit.

Parameters:

• start (str | None) – The start value as a string.

• port_type (PortType) – The type of the port.

• unit (str | None) – The unit of the port, if applicable.

Returns:

The converted start value in the appropriate type.

Return type:

Union[float, int, bool, str, None]

syssimx.components.fmu._in_vr_map_for_type(comp, pt)

Return the input value-reference map for a port type.

Parameters:

• comp (FMUComponent)

• pt (PortType)

Return type:

dict[str, int]

FEM Component

class syssimx.components.fem.FEMComponent

Bases: CoSimComponent

Minimal abstract base for FEM co-simulation components.

• No direct dependency on a specific FEM library (ngsolve/netgen, etc.).

• Subclasses implement backend specifics (mesh, FE spaces, solvers, visualization).

__init__(name, label=None, group=None)

Initialize a new co-simulation component.

Parameters:

• name (str) – Unique identifier for this component. Must be unique within the containing System. Used for connection definitions and graph construction.

• label (str | None) – Human-readable display name for visualization and logging. Defaults to name if not provided.

• group (str | None) – Optional category for grouping related components (e.g., ‘sensors’, ‘actuators’, ‘controllers’). Used for filtering and organization in large systems.

Example

>>> comp = MyComponent("pid_1", label="PID Controller", group="controllers")
>>> comp.name
'pid_1'
>>> comp.label
'PID Controller'

abstractmethod _initialize_component(t0)

Setup mesh, FE spaces, solver, material laws, initial conditions.

Parameters:

t0 (float)

Return type:

None

abstractmethod _do_step_internal(t, dt)

Advance FEM solver from t to t+dt.

Parameters:

• t (float)

• dt (float)

Return type:

None

load_mesh_from_file(path)

Optional: load mesh from file (GMSH, VTK, XDMF, etc.).

Parameters:

path (Path)

Return type:

None

export_results(path, format='vtk')

Optional: export time series to file.

Parameters:

• path (Path)

• format (str)

Return type:

None

visualize_state()

Optional: library-specific visualization (NGSolve Draw, matplotlib, etc.).

Return type:

None

_abc_impl = <_abc._abc_data object>

OpenSim Component

class syssimx.components.opensim.OpenSimComponent

Bases: CoSimComponent

Wrapper around an OpenSim model to implement the CoSimComponent interface.

parameters: dict[str, Any] = {}

__init__(name, osim_model_path, group=None)

Constructor for the OpenSimComponent class.

Parameters:

• name (str)

• osim_model_path (str)

• group (str | None)

model: opensim.Model

state: opensim.State

manager: opensim.Manager

_finalize_model(t0)

Complete OpenSim initialization after model is built/loaded. Call this at the end of subclass _initialize_component().

Parameters:

t0 (float)

Return type:

None

realize()

Realizes the stage: Position, Velocity, Dynamics, Acceleration

Return type:

None

reset()

Reset the component to a clean state before (before initialization).

Return type:

None

get_coordinate_value(coord_name)

Get current value of named coordinate (generalized position).

Parameters:

coord_name (str)

Return type:

float

get_coordinate_speed(coord_name)

Get current speed of named coordinate (generalized velocity).

Parameters:

coord_name (str)

Return type:

float

get_coordinate_acceleration(coord_name)

Get current acceleration of named coordinate.

Parameters:

coord_name (str)

Return type:

float

_abc_impl = <_abc._abc_data object>

set_coordinate_value(coord_name, value)

Set value of named coordinate.

Parameters:

• coord_name (str)

• value (float)

Return type:

None

set_coordinate_speed(coord_name, value)

Set speed of named coordinate.

Parameters:

• coord_name (str)

• value (float)

Return type:

None

_find_coordinate(name)

Find coordinate by name in model.

Parameters:

name (str)

Return type:

opensim.Coordinate