Simulate Functional Mock-up Units (FMUs) in Python

Common errors

• Function fmi3InstantiateModelExchange is missing in shared library

  cause An FMI 3.0 FMU does not implement all API functions required by the FMI 3.0.1 specification, even those for interface types or optional capabilities the FMU doesn't support.
  fix Contact the FMU vendor to request a compliant FMU that includes all necessary FMI API function implementations. Alternatively, try to use an FMI 2.0 version of the FMU if available.

• Unable to change tunable parameters using either apply_starting_values, setReal() or start_values.

  cause This error occurs when attempting to modify FMU parameters, which may not be accessible for scripting or might be incorrectly set as non-tunable.
  fix Ensure the parameters you are trying to change are correctly defined as tunable in the FMU's `modelDescription.xml`. Use the `dump()` function to inspect the FMU's variables and their causality/variability. If the parameter is not tunable, it cannot be changed at runtime. Consult the FMU's documentation or creator. For initial values, ensure you are passing a `start_values` dictionary correctly to `simulate_fmu`.

• Plot in generated jupyter notebook not visible

  cause Generated Jupyter notebooks may sometimes fail to display plots, potentially due to missing or conflicting plotting dependencies or environment issues within Jupyter.
  fix Ensure `plotly` and `jupyter-nbformat` (if generating notebooks) are correctly installed (`pip install plotly jupyter-nbformat`). Restart the Jupyter kernel. Verify that the output of `plot_result` is displayed if run directly in a Python script, as a troubleshooting step.

Warnings

• gotcha FMPy's full functionality often relies on optional dependencies (e.g., for plotting or GUI). Using `pip install fmpy[complete]` is recommended for a full-featured experience, otherwise, you might miss certain tools.
  Fix: Install with `pip install fmpy[complete]` or manually install needed extras like `matplotlib`, `plotly`, `pyqt`.
• breaking FMI 3.0 FMUs might not always implement all API functions declared in `fmi3Functions.h`, leading to errors like 'Function fmi3InstantiateModelExchange is missing in shared library' during initialization. This is due to strict FMI 3.0.1 specification regarding API implementation.
  Fix: Ensure the FMU vendor provides a compliant FMU that implements all specified FMI API functions, even if unused, or report the issue to the FMU vendor. Consider downgrading the FMI version of the FMU if possible.
• gotcha The plotting backend for the FMPy GUI is transitioning. Older versions primarily used `pyqtgraph` and `matplotlib`, but recent updates are moving towards `plotly`. This might lead to unexpected plot rendering issues or require different dependencies.
  Fix: If experiencing plotting issues, ensure `plotly` is installed (`pip install plotly`) and check FMPy's latest documentation or release notes for the recommended plotting backend. If using the GUI, ensure `pyqt` is also installed (`pip install pyqt`).
• gotcha On Windows, the `pywin32` package is an optional dependency for some functionalities. Without it, certain platform-specific features or behaviors might not work as expected.
  Fix: Ensure `pywin32` is installed on Windows systems using `pip install pywin32` or by installing `fmpy[complete]`.

Install

• pip install fmpy Minimal installation
• pip install fmpy[complete] Full installation with all optional dependencies
• conda install -c conda-forge fmpy Install with Conda (from conda-forge)

Imports

• *

  from fmpy import *

  Common for quick scripts to get all top-level FMPy functions
• simulate_fmu

  from fmpy import simulate_fmu

  Direct import for the main simulation function
• read_model_description

  from fmpy.model_description import read_model_description

  For inspecting FMU metadata
• plot_result

  from fmpy.util import plot_result

  Utility for plotting simulation results

Quickstart

This quickstart demonstrates how to load an FMU, retrieve its metadata, simulate it for a specified duration, and then plot selected simulation results using FMPy. It highlights the core `simulate_fmu` and `plot_result` functions. Users need to provide an actual FMU file (e.g., 'Rectifier.fmu') for the code to run successfully.

import os
from fmpy import simulate_fmu, dump
from fmpy.util import plot_result

# NOTE: FMPy requires an FMU file to operate. 
# For this example, you would typically download one, e.g., 'Rectifier.fmu'
# from the FMPy GitHub repository or create your own.
# For demonstration, we'll assume 'Rectifier.fmu' is in the current directory.

fmu_path = 'Rectifier.fmu' # Replace with actual path to your FMU file

if not os.path.exists(fmu_path):
    print(f"Error: FMU file '{fmu_path}' not found. Please provide a valid FMU file.")
    # Example of how you might download one for a real quickstart:
    # from fmpy.util import download_file
    # download_file('https://github.com/CATIA-Systems/FMPy/raw/main/FMPy/fmus/Rectifier.fmu', fmu_path)
    exit()

# Get information about the FMU
print(f"\nFMU Information for {fmu_path}:")
dump(fmu_path)

# Simulate the FMU
print(f"\nSimulating {fmu_path}...")
result = simulate_fmu(fmu_path, stop_time=1.0)

# Plot the results
print("\nPlotting results...")
plot_result(result, variables=['Rectifier1.Capacitor1.v', 'Rectifier1.Diode1.i'])
print("Plot generated (a new window should appear).")