FMI 3.0 & FMPy Cheatsheet

1. FMI 3.0 Overview

The Functional Mock-up Interface (FMI) is an open standard for exchanging simulation models as Functional Mock-up Units (FMUs). An FMU is a zip file containing a model description (XML) and compiled binaries (or C source) that any FMI-compatible tool can import and simulate.

FMI 3.0 — What's New vs. 2.0

Three Interface Types

FMU Lifecycle — State Machine (Simplified)

2. FMU Anatomy & modelDescription.xml

FMU File Structure

An FMU is a zip file (renamed to .fmu) with a standardized internal layout:

modelDescription.xml — Key Elements

Root Element

<fmiModelDescription
  fmiVersion="3.0"
  modelName="HeatExchanger"
  instantiationToken="{8c4e810f-...}"  <!-- was 'guid' in FMI 2.0 -->
  description="Counter-flow heat exchanger model"
  generationTool="MyTool 4.2">

  <CoSimulation modelIdentifier="HeatExchanger"
    canHandleVariableCommunicationStepSize="true"
    canReturnEarlyAfterIntermediateUpdate="true" />  <!-- capabilities -->

  <!-- and/or: <ModelExchange .../>, <ScheduledExecution .../> -->

Variable Declarations (FMI 3.0 — Typed Elements)

<ModelVariables>
  <Float64 name="T_inlet" valueReference="1"
    causality="input" start="293.15"
    description="Inlet temperature [K]" />

  <Float64 name="T_outlet" valueReference="2"
    causality="output"
    description="Outlet temperature [K]" />

  <Float64 name="k" valueReference="3"
    causality="parameter" variability="fixed"
    start="500.0" description="Heat transfer coeff [W/(m²K)]" />

  <!-- FMI 3.0: Array variable -->
  <Float64 name="T_profile" valueReference="10"
    causality="output">
    <Dimension start="20" />  <!-- array of 20 elements -->
  </Float64>

  <!-- FMI 3.0: Clock variable -->
  <Clock name="samplingClock" valueReference="100"
    causality="input" intervalVariability="fixed"
    intervalDecimal="0.01" />
</ModelVariables>

Causality × Variability

Inspecting an FMU with FMPy

from fmpy import read_model_description, dump

# Quick summary of FMU contents
dump('HeatExchanger.fmu')

# Detailed programmatic access
md = read_model_description('HeatExchanger.fmu')
print(f"Model: {md.modelName}, FMI: {md.fmiVersion}")
print(f"GUID: {md.guid}")
print(f"CS: {md.coSimulation is not None}")
print(f"ME: {md.modelExchange is not None}")

# List all variables
for var in md.modelVariables:
    print(f"  {var.name:30s}  causality={var.causality:20s}  start={var.start}")

# Filter inputs and outputs
inputs  = [v for v in md.modelVariables if v.causality == 'input']
outputs = [v for v in md.modelVariables if v.causality == 'output']
params  = [v for v in md.modelVariables if v.causality == 'parameter']

3. Co-Simulation (CS) CS

How It Works

In Co-Simulation, the FMU contains its own ODE/DAE solver. The master algorithm:

1. Sets inputs at the current communication point
2. Tells the FMU to advance by stepSize
3. Reads outputs at the new communication point
4. Repeats until tEnd

FMPy — Quick Simulation (High-Level API)

from fmpy import simulate_fmu
from fmpy.util import plot_result

# Simplest possible simulation
result = simulate_fmu(
    'HeatExchanger.fmu',
    stop_time=10.0,
    output_interval=0.01
)
plot_result(result)

# With parameters and input signals
result = simulate_fmu(
    'HeatExchanger.fmu',
    stop_time=100.0,
    step_size=0.1,            # communication step size
    output_interval=0.1,       # output recording interval
    start_values={
        'k': 750.0,              # parameter override
        'T_inlet': 350.0,        # initial input value
    },
    output=['T_outlet', 'Q_flow'],  # variables to record
)

# Access results (structured NumPy array)
time = result['time']
T_out = result['T_outlet']

Providing Input Signals

import numpy as np

# Option 1: NumPy structured array
dtype = np.dtype([('time', np.float64), ('T_inlet', np.float64)])
input_signals = np.array([
    (0.0,  293.15),
    (10.0, 293.15),
    (10.0, 350.00),   # step change at t=10
    (50.0, 350.00),
    (50.0, 320.00),   # step change at t=50
    (100.0, 320.00),
], dtype=dtype)

result = simulate_fmu(
    'HeatExchanger.fmu',
    stop_time=100.0,
    input=input_signals,       # FMPy interpolates between points
    output=['T_outlet'],
)

# Option 2: Read from CSV file
from fmpy.util import read_csv
input_signals = read_csv('inputs.csv')   # columns: time, T_inlet, ...

FMPy — Low-Level API (Full Control)

from fmpy import read_model_description, extract
from fmpy.fmi3 import FMU3Slave

md = read_model_description('HeatExchanger.fmu')
unzipdir = extract('HeatExchanger.fmu')

fmu = FMU3Slave(
    instanceName='instance1',
    unzipDirectory=unzipdir,
    modelIdentifier=md.coSimulation.modelIdentifier,
)

# Lifecycle: Instantiate → Configure → Initialize → Step → Terminate → Free
fmu.instantiate()
fmu.enterInitializationMode()
fmu.setFloat64([3], [750.0])   # set parameter k (valueReference=3)
fmu.exitInitializationMode()

# Simulation loop
time, step_size = 0.0, 0.1
while time < 10.0:
    fmu.setFloat64([1], [350.0])   # set input T_inlet
    fmu.doStep(
        currentCommunicationPoint=time,
        communicationStepSize=step_size
    )
    T_out = fmu.getFloat64([2])     # get output T_outlet
    print(f"t={time:.1f}  T_out={T_out[0]:.2f}")
    time += step_size

fmu.terminate()
fmu.freeInstance()

FMI 3.0 CS Additions

4. Model Exchange (ME) ME

How It Works

The FMU provides the model equations — derivatives, algebraic outputs, event indicators. An external ODE solver (provided by the master / tool) drives the integration.

ME vs CS — When to Use Which

FMPy — Model Exchange Simulation

from fmpy import simulate_fmu

# FMPy automatically uses CVode solver for ME
result = simulate_fmu(
    'HeatExchanger.fmu',
    fmi_type='ModelExchange',     # default is 'CoSimulation'
    stop_time=10.0,
    output_interval=0.01,
    solver='CVode',                # CVode (default), Euler
    start_values={'k': 750.0},
    output=['T_outlet'],
)

Low-Level ME API (Manual Solver Loop)

from fmpy.fmi3 import FMU3ModelExchange

# ... (instantiate, extract as before)
fmu = FMU3ModelExchange(...)
fmu.instantiate()
fmu.enterInitializationMode()
fmu.exitInitializationMode()
fmu.enterContinuousTimeMode()

# Get initial states
n_states = md.numberOfContinuousStates
n_events = md.numberOfEventIndicators
x = fmu.getContinuousStates()

# Simple forward Euler (for illustration — use CVode in practice!)
time, dt = 0.0, 1e-3
while time < 10.0:
    fmu.setTime(time)
    fmu.setContinuousStates(x)

    # Check for events
    event_indicators = fmu.getEventIndicators()

    # Get derivatives: dx/dt = f(x, u, t)
    dx = fmu.getDerivatives()

    # Euler step
    x = [x[i] + dt * dx[i] for i in range(n_states)]
    time += dt

fmu.terminate()
fmu.freeInstance()

5. FMPy Practical Reference FMPy

Installation

# Install FMPy as tool
uv tool install fmpy[complete]

# In virtual environment
# Minimal dependencies install of FMPy
uv add fmpy

# With optional dependencies (plotting, GUI)
uv add fmpy[complete]

# Verify installation
python -c "import fmpy; print(fmpy.__version__)"

# Command-line tools
fmpy --help
fmpy info HeatExchanger.fmu      # dump model description
fmpy validate HeatExchanger.fmu  # check FMU compliance
fmpy simulate HeatExchanger.fmu  # run from command line
fmpy gui                         # launch graphical interface

Key Functions

Function	Purpose	Returns
fmpy.dump(fmu_path)	Print FMU summary to console	None (prints)
fmpy.read_model_description(fmu_path)	Parse modelDescription.xml	ModelDescription object
fmpy.simulate_fmu(fmu_path, ...)	High-level simulation (CS or ME)	NumPy structured array
fmpy.extract(fmu_path)	Extract FMU zip to temp dir	Path to extracted directory
fmpy.instantiate_fmu(unzipdir, md, fmi_type)	Create FMU instance for low-level API	FMU instance object
fmpy.util.plot_result(result)	Plot simulation results	Plotly figure
fmpy.util.read_csv(path)	Read input signal CSV	NumPy structured array
fmpy.util.write_csv(path, result)	Write results to CSV	None
fmpy.validation.validate_fmu(fmu_path)	Validate FMU compliance	List of issues

simulate_fmu() — Full Parameter Reference

result = simulate_fmu(
    filename,                     # path to .fmu file
    fmi_type='CoSimulation',      # 'CoSimulation' or 'ModelExchange'
    start_time=0.0,              # simulation start time
    stop_time=1.0,               # simulation end time
    step_size=None,              # CS communication step (None = auto)
    output_interval=None,        # recording interval (None = step_size)
    solver='CVode',              # ME solver: 'CVode' or 'Euler'
    relative_tolerance=None,     # solver tolerance (ME)
    start_values={},             # dict: variable_name → value
    input=None,                  # input signals (NumPy array or CSV path)
    output=None,                 # list of variable names to record (None = all)
    timeout=None,                # max simulation time in seconds
    fmu_instance=None,           # re-use existing FMU instance
    validate=True,               # validate FMU before simulation
    debug_logging=False,         # enable FMU debug output
    set_input_derivatives=False, # enable input interpolation (CS)
)

Batch Simulation / Parameter Sweeps

import numpy as np
import matplotlib.pyplot as plt
from fmpy import simulate_fmu

# Parameter sweep over heat transfer coefficient
k_values = [100, 500, 1000, 2000, 5000]
results = {}

for k in k_values:
    results[k] = simulate_fmu(
        'HeatExchanger.fmu',
        stop_time=60.0,
        start_values={'k': k},
        output=['T_outlet'],
    )

# Plot comparison
fig, ax = plt.subplots()
for k, r in results.items():
    ax.plot(r['time'], r['T_outlet'], label=f'k={k}')
ax.legend(); ax.set_xlabel('Time [s]'); ax.set_ylabel('T_outlet [K]')
plt.show()

Saving & Loading Results

from fmpy.util import write_csv, read_csv
import pandas as pd

# Save to CSV
write_csv('results.csv', result)

# Or convert to pandas DataFrame for analysis
df = pd.DataFrame(result)
df.to_csv('results.csv', index=False)

# Load back
df = pd.read_csv('results.csv')

FMPy GUI

🔍 FMPy Graphical Interface

FMPy includes a Qt-based GUI for interactive FMU exploration:

You can inspect variables, configure a run, and view the resulting plot in one place.

• fmpy gui — launch empty GUI, open FMU via File menu
• fmpy gui HeatExchanger.fmu — open specific FMU directly
• Features: variable browser, parameter editing, simulation, result plotting
• Requires: pip install fmpy[complete] (installs PyQt)
• Limitation: only supports one FMU at a time

Open an FMU, browse variables, and configure the simulation.

Select a variable to plot and inspect the result directly in the GUI.

Containers — Nested / Composite FMUs

📦 FMPy Containers (Nested FMUs)

FMPy supports containers — packaging multiple FMUs into a single composite FMU. This allows you to:

• Combine several FMUs into one redistributable .fmu file
• Define internal connections between sub-FMUs
• Expose selected inputs/outputs to the outside
• Simplify deployment — ship one FMU instead of many

Create a container FMU via the FMPy GUI or programmatically. See fmpy.container module and FMPy documentation for details.