{"id":8178,"library":"fmpy","title":"Simulate Functional Mock-up Units (FMUs) in Python","description":"FMPy is a free Python library to simulate Functional Mock-up Units (FMUs), supporting FMI 1.0, 2.0, and 3.0 for both Co-Simulation and Model Exchange. It runs on Windows, Linux, and macOS, offering a command-line interface, a graphical user interface, and a web app. Additionally, FMPy facilitates creating Jupyter Notebooks and compiling C code FMUs, making it a versatile tool for system simulation. The library is actively maintained by Dassault Systèmes, with the current version being 0.3.29.","status":"active","version":"0.3.29","language":"en","source_language":"en","source_url":"https://github.com/CATIA-Systems/FMPy","tags":["FMI","FMU","simulation","model-exchange","co-simulation","systems-engineering","modelica"],"install":[{"cmd":"pip install fmpy","lang":"bash","label":"Minimal installation"},{"cmd":"pip install fmpy[complete]","lang":"bash","label":"Full installation with all optional dependencies"},{"cmd":"conda install -c conda-forge fmpy","lang":"bash","label":"Install with Conda (from conda-forge)"}],"dependencies":[{"reason":"Required for parsing modelDescription.xml","package":"lxml","optional":false},{"reason":"Required for simulating FMUs","package":"numpy","optional":false},{"reason":"Optional, required for full functionality on Windows systems","package":"pywin32","optional":true},{"reason":"Optional, for plotting results (part of `[plot]` extra)","package":"matplotlib","optional":true},{"reason":"Optional, increasingly used for GUI plots, replacing `pyqtgraph` and `matplotlib` in some contexts","package":"plotly","optional":true},{"reason":"Optional, part of the `[plot]` extra","package":"scipy","optional":true},{"reason":"Optional, for parallelization examples","package":"dask","optional":true},{"reason":"Optional, for downloading example FMUs","package":"requests","optional":true},{"reason":"Optional, required for the graphical user interface","package":"pyqt","optional":true}],"imports":[{"note":"Common for quick scripts to get all top-level FMPy functions","symbol":"*","correct":"from fmpy import *"},{"note":"Direct import for the main simulation function","symbol":"simulate_fmu","correct":"from fmpy import simulate_fmu"},{"note":"For inspecting FMU metadata","symbol":"read_model_description","correct":"from fmpy.model_description import read_model_description"},{"note":"Utility for plotting simulation results","symbol":"plot_result","correct":"from fmpy.util import plot_result"}],"quickstart":{"code":"import os\nfrom fmpy import simulate_fmu, dump\nfrom fmpy.util import plot_result\n\n# NOTE: FMPy requires an FMU file to operate. \n# For this example, you would typically download one, e.g., 'Rectifier.fmu'\n# from the FMPy GitHub repository or create your own.\n# For demonstration, we'll assume 'Rectifier.fmu' is in the current directory.\n\nfmu_path = 'Rectifier.fmu' # Replace with actual path to your FMU file\n\nif not os.path.exists(fmu_path):\n    print(f\"Error: FMU file '{fmu_path}' not found. Please provide a valid FMU file.\")\n    # Example of how you might download one for a real quickstart:\n    # from fmpy.util import download_file\n    # download_file('https://github.com/CATIA-Systems/FMPy/raw/main/FMPy/fmus/Rectifier.fmu', fmu_path)\n    exit()\n\n# Get information about the FMU\nprint(f\"\\nFMU Information for {fmu_path}:\")\ndump(fmu_path)\n\n# Simulate the FMU\nprint(f\"\\nSimulating {fmu_path}...\")\nresult = simulate_fmu(fmu_path, stop_time=1.0)\n\n# Plot the results\nprint(\"\\nPlotting results...\")\nplot_result(result, variables=['Rectifier1.Capacitor1.v', 'Rectifier1.Diode1.i'])\nprint(\"Plot generated (a new window should appear).\")","lang":"python","description":"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."},"warnings":[{"fix":"Install with `pip install fmpy[complete]` or manually install needed extras like `matplotlib`, `plotly`, `pyqt`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"FMPy versions interacting with FMI 3.0 FMUs."},{"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`).","message":"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.","severity":"gotcha","affected_versions":"0.3.x (especially newer minor releases)"},{"fix":"Ensure `pywin32` is installed on Windows systems using `pip install pywin32` or by installing `fmpy[complete]`.","message":"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.","severity":"gotcha","affected_versions":"All versions on Windows"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Function fmi3InstantiateModelExchange is missing in shared library"},{"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`.","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.","error":"Unable to change tunable parameters using either apply_starting_values, setReal() or start_values."},{"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.","cause":"Generated Jupyter notebooks may sometimes fail to display plots, potentially due to missing or conflicting plotting dependencies or environment issues within Jupyter.","error":"Plot in generated jupyter notebook not visible"}]}