# PythonFMU3
> A lightweight framework that enables the packaging of Python 3 code as FMUs (following FMI version 3.0).
[](https://opensource.org/licenses/MIT)
[](https://github.com/StephenSmith25/PythonFMU3/issues)
[](https://github.com/StephenSmith25/PythonFMU3/actions?query=workflow%3ACI)
[](https://pypi.org/project/pythonfmu3/)
[](https://pythonfmu3.readthedocs.io/)
This project is a fork of the original PythonFMU repository available at https://github.com/NTNU-IHB/PythonFMU, which was used as the basis for adding support for FMI 3.0. While we have made efforts to expand the functionality of this project, it currently has some limitations and does not support all the features of FMI 3.0. We would like to acknowledge and give credit to the original PythonFMU project for their contributions to this work.
### Support:
Please take a look at the examples to see the supported features.
We currently support both the Model exchange and Cosimulation Interfaces.
### How do I build an FMU from python code?
1. Install `pythonfmu3` package:
```bash
pip install pythonfmu3
```
2. Create a new class extending the `Fmi3Slave` class declared in the `pythonfmu3.fmi3slave` module (see below for an example).
3. Run `pythonfmu3 build` to create the fmu.
```
usage: pythonfmu3 build [-h] -f SCRIPT_FILE [-d DEST] [--doc DOCUMENTATION_FOLDER] [--terminals TERMINALS_FILE] [--no-external-tool]
[--no-variable-step] [--interpolate-inputs] [--only-one-per-process] [--handle-state]
[--serialize-state] [--use-memory-management]
[Project files [Project files ...]]
Build an FMU from a Python script.
positional arguments:
Project files Additional project files required by the Python script.
optional arguments:
-h, --help show this help message and exit
-f SCRIPT_FILE, --file SCRIPT_FILE
Path to the Python script.
-d DEST, --dest DEST Where to save the FMU.
--doc DOCUMENTATION_FOLDER
Documentation folder to include in the FMU.
--terminals TERMINALS_FILE
Terminals file (terminalsAndIcons.xml) to include in the FMU.
--no-external-tool If given, needsExecutionTool=false
--no-variable-step If given, canHandleVariableCommunicationStepSize=false
--interpolate-inputs If given, canInterpolateInputs=true
--only-one-per-process
If given, canBeInstantiatedOnlyOncePerProcess=true
--handle-state If given, canGetAndSetFMUstate=true
--serialize-state If given, canSerializeFMUstate=true
```
### How do I build an FMU from python code with third-party dependencies?
Often, Python scripts depends on non-builtin libraries like `numpy`, `scipy`, etc.
_PythonFMU_ does not package a full environment within the FMU.
However, you can package a `requirements.txt` or `environment.yml` file within your FMU following these steps:
1. Install _pythonfmu_ package: `pip install pythonfmu3`
2. Create a new class extending the `Fmi3Slave` class declared in the `pythonfmu3.fmi3slave` module (see below for an example).
3. Create a `requirements.txt` file (to use _pip_ manager) and/or a `environment.yml` file (to use _conda_ manager) that defines your dependencies.
4. Run `pythonfmu3 build -f myscript.py requirements.txt` to create the fmu including the dependencies file.
And using `pythonfmu3 deploy`, end users will be able to update their local Python environment. The steps to achieve that:
1. Install _pythonfmu_ package: `pip install pythonfmu3`
2. Be sure to be in the Python environment to be updated. Then execute `pythonfmu3 deploy -f my.fmu`
```
usage: pythonfmu3 deploy [-h] -f FMU [-e ENVIRONMENT] [{pip,conda}]
Deploy a Python FMU. The command will look in the `resources` folder for one of the following files:
`requirements.txt` or `environment.yml`. If you specify a environment file but no package manager, `conda` will be selected for `.yaml` and `.yml` otherwise `pip` will be used. The tool assume the Python environment in which the FMU should be executed is the current one.
positional arguments:
{pip,conda} Python packages manager
optional arguments:
-h, --help show this help message and exit
-f FMU, --file FMU Path to the Python FMU.
-e ENVIRONMENT, --env ENVIRONMENT
Requirements or environment file.
```
### Cosimulation Example:
#### Write the script
```python
from pythonfmu3 import Fmi3Causality, Fmi3Slave, Boolean, Int32, Float64, String
class PythonSlave(Fmi3Slave):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.author = "John Doe"
self.description = "A simple description"
self.time = 0.0
self.intOut = 1
self.realOut = 3.0
self.booleanVariable = True
self.stringVariable = "Hello World!"
self.register_variable(Float64("time", causality=Fmi3Causality.independent))
self.register_variable(Int32("intOut", causality=Fmi3Causality.output))
self.register_variable(Float64("realOut", causality=Fmi3Causality.output))
self.register_variable(Boolean("booleanVariable", causality=Fmi3Causality.local))
self.register_variable(String("stringVariable", causality=Fmi3Causality.local))
# Note:
# it is also possible to explicitly define getters and setters as lambdas in case the variable is not backed by a Python field.
# self.register_variable(Float64("myReal", causality=Fmi3Causality.output, getter=lambda: self.realOut, setter=lambda v: set_real_out(v))
def do_step(self, current_time, step_size):
return True
```
#### Create the FMU
```
pythonfmu3 build -f pythonslave.py myproject
```
In this example a python class named `PythonSlave` that extends `Fmi3Slave` is declared in a file named `pythonslave.py`,
where `myproject` is an optional folder containing additional project files required by the python script.
Project folders such as this will be recursively copied into the FMU. Multiple project files/folders may be added.
### Model Exchange Example
To create a model exchange FMU you must inherit from `Fmi3SlaveBase` and one of (or both) mixin classes `ModelExchange` or `CoSimulation`.
#### Write the script
```python
from pythonfmu3 import Fmi3Causality, Fmi3SlaveBase, Float64, ModelExchange
class PythonSlaveMX(Fmi3SlaveBase, ModelExchange):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.author = "John Doe"
self.description = "A simple description"
self.time = 0.0
self.mu = 1.0
self.x0 = 2
self.x1 = 0
self.derx0 = 0.0
self.derx1 = 0.0
self.register_variable(Float64("time", causality=Fmi3Causality.independent, variability=Fmi3Variability.continuous))
self.register_variable(Float64("x0", causality=Fmi3Causality.output, start=2, variability=Fmi3Variability.continuous, initial=Fmi3Initial.exact))
self.register_variable(Float64("x1", causality=Fmi3Causality.output, start=0, variability=Fmi3Variability.continuous, initial=Fmi3Initial.exact))
self.register_variable(Float64("derx0", causality=Fmi3Causality.local, variability=Fmi3Variability.continuous, derivative=1))
self.register_variable(Float64("derx1", causality=Fmi3Causality.local, variability=Fmi3Variability.continuous, derivative=2))
self.register_variable(Float64("mu", causality=Fmi3Causality.parameter, variability=Fmi3Variability.fixed))
def get_continuous_state_derivatives(self) -> List[float]:
self.derx0 = self.x1
self.derx1 = self.mu * ((1 - self.x0**2) * self.x1) - self.x0
return [self.derx0, self.derx1]
```
Note: There is a hard requirement that we have a `self.time` member in the derived class.
#### Create the FMU
```
pythonfmu3 build -f pythonslaveMX.py
```
Raw data
{
"_id": null,
"home_page": "https://github.com/stephensmith25/PythonFMU3",
"name": "pythonfmu3",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "FMI",
"author": "Stephen Smith",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/45/3c/749bd299ac93108ac1b29ab74258765fddfe1fa532fd34b917ae7f5d27d5/pythonfmu3-0.3.2.tar.gz",
"platform": null,
"description": "# PythonFMU3\n\n> A lightweight framework that enables the packaging of Python 3 code as FMUs (following FMI version 3.0).\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/StephenSmith25/PythonFMU3/issues)\n\n[](https://github.com/StephenSmith25/PythonFMU3/actions?query=workflow%3ACI)\n[](https://pypi.org/project/pythonfmu3/)\n[](https://pythonfmu3.readthedocs.io/)\n\n\nThis project is a fork of the original PythonFMU repository available at https://github.com/NTNU-IHB/PythonFMU, which was used as the basis for adding support for FMI 3.0. While we have made efforts to expand the functionality of this project, it currently has some limitations and does not support all the features of FMI 3.0. We would like to acknowledge and give credit to the original PythonFMU project for their contributions to this work.\n\n### Support:\n\nPlease take a look at the examples to see the supported features.\nWe currently support both the Model exchange and Cosimulation Interfaces.\n\n### How do I build an FMU from python code?\n\n1. Install `pythonfmu3` package:\n\n```bash\npip install pythonfmu3\n```\n\n2. Create a new class extending the `Fmi3Slave` class declared in the `pythonfmu3.fmi3slave` module (see below for an example).\n3. Run `pythonfmu3 build` to create the fmu.\n\n```\nusage: pythonfmu3 build [-h] -f SCRIPT_FILE [-d DEST] [--doc DOCUMENTATION_FOLDER] [--terminals TERMINALS_FILE] [--no-external-tool]\n [--no-variable-step] [--interpolate-inputs] [--only-one-per-process] [--handle-state]\n [--serialize-state] [--use-memory-management]\n [Project files [Project files ...]]\n\nBuild an FMU from a Python script.\n\npositional arguments:\n Project files Additional project files required by the Python script.\n\noptional arguments:\n -h, --help show this help message and exit\n -f SCRIPT_FILE, --file SCRIPT_FILE\n Path to the Python script.\n -d DEST, --dest DEST Where to save the FMU.\n --doc DOCUMENTATION_FOLDER\n Documentation folder to include in the FMU.\n --terminals TERMINALS_FILE\n Terminals file (terminalsAndIcons.xml) to include in the FMU.\n --no-external-tool If given, needsExecutionTool=false\n --no-variable-step If given, canHandleVariableCommunicationStepSize=false\n --interpolate-inputs If given, canInterpolateInputs=true\n --only-one-per-process\n If given, canBeInstantiatedOnlyOncePerProcess=true\n --handle-state If given, canGetAndSetFMUstate=true\n --serialize-state If given, canSerializeFMUstate=true\n```\n\n### How do I build an FMU from python code with third-party dependencies?\n\nOften, Python scripts depends on non-builtin libraries like `numpy`, `scipy`, etc.\n_PythonFMU_ does not package a full environment within the FMU.\nHowever, you can package a `requirements.txt` or `environment.yml` file within your FMU following these steps:\n\n1. Install _pythonfmu_ package: `pip install pythonfmu3`\n2. Create a new class extending the `Fmi3Slave` class declared in the `pythonfmu3.fmi3slave` module (see below for an example).\n3. Create a `requirements.txt` file (to use _pip_ manager) and/or a `environment.yml` file (to use _conda_ manager) that defines your dependencies.\n4. Run `pythonfmu3 build -f myscript.py requirements.txt` to create the fmu including the dependencies file.\n\nAnd using `pythonfmu3 deploy`, end users will be able to update their local Python environment. The steps to achieve that:\n\n1. Install _pythonfmu_ package: `pip install pythonfmu3`\n2. Be sure to be in the Python environment to be updated. Then execute `pythonfmu3 deploy -f my.fmu`\n\n```\nusage: pythonfmu3 deploy [-h] -f FMU [-e ENVIRONMENT] [{pip,conda}]\n\nDeploy a Python FMU. The command will look in the `resources` folder for one of the following files:\n`requirements.txt` or `environment.yml`. If you specify a environment file but no package manager, `conda` will be selected for `.yaml` and `.yml` otherwise `pip` will be used. The tool assume the Python environment in which the FMU should be executed is the current one.\n\npositional arguments:\n {pip,conda} Python packages manager\n\noptional arguments:\n -h, --help show this help message and exit\n -f FMU, --file FMU Path to the Python FMU.\n -e ENVIRONMENT, --env ENVIRONMENT\n Requirements or environment file.\n```\n\n### Cosimulation Example:\n\n#### Write the script\n\n```python\n\nfrom pythonfmu3 import Fmi3Causality, Fmi3Slave, Boolean, Int32, Float64, String\n\n\nclass PythonSlave(Fmi3Slave):\n\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n\n self.author = \"John Doe\"\n self.description = \"A simple description\"\n\n self.time = 0.0\n self.intOut = 1\n self.realOut = 3.0\n self.booleanVariable = True\n self.stringVariable = \"Hello World!\"\n self.register_variable(Float64(\"time\", causality=Fmi3Causality.independent))\n self.register_variable(Int32(\"intOut\", causality=Fmi3Causality.output))\n self.register_variable(Float64(\"realOut\", causality=Fmi3Causality.output))\n self.register_variable(Boolean(\"booleanVariable\", causality=Fmi3Causality.local))\n self.register_variable(String(\"stringVariable\", causality=Fmi3Causality.local))\n \n # Note:\n # it is also possible to explicitly define getters and setters as lambdas in case the variable is not backed by a Python field.\n # self.register_variable(Float64(\"myReal\", causality=Fmi3Causality.output, getter=lambda: self.realOut, setter=lambda v: set_real_out(v))\n\n def do_step(self, current_time, step_size):\n return True\n\n```\n\n#### Create the FMU\n\n```\npythonfmu3 build -f pythonslave.py myproject\n```\n\nIn this example a python class named `PythonSlave` that extends `Fmi3Slave` is declared in a file named `pythonslave.py`,\nwhere `myproject` is an optional folder containing additional project files required by the python script.\nProject folders such as this will be recursively copied into the FMU. Multiple project files/folders may be added.\n\n\n### Model Exchange Example\n\nTo create a model exchange FMU you must inherit from `Fmi3SlaveBase` and one of (or both) mixin classes `ModelExchange` or `CoSimulation`.\n\n#### Write the script\n\n```python\n\nfrom pythonfmu3 import Fmi3Causality, Fmi3SlaveBase, Float64, ModelExchange\n\n\nclass PythonSlaveMX(Fmi3SlaveBase, ModelExchange):\n\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n\n self.author = \"John Doe\"\n self.description = \"A simple description\"\n\n self.time = 0.0\n self.mu = 1.0\n self.x0 = 2\n self.x1 = 0\n self.derx0 = 0.0\n self.derx1 = 0.0\n\n self.register_variable(Float64(\"time\", causality=Fmi3Causality.independent, variability=Fmi3Variability.continuous))\n self.register_variable(Float64(\"x0\", causality=Fmi3Causality.output, start=2, variability=Fmi3Variability.continuous, initial=Fmi3Initial.exact))\n self.register_variable(Float64(\"x1\", causality=Fmi3Causality.output, start=0, variability=Fmi3Variability.continuous, initial=Fmi3Initial.exact))\n self.register_variable(Float64(\"derx0\", causality=Fmi3Causality.local, variability=Fmi3Variability.continuous, derivative=1))\n self.register_variable(Float64(\"derx1\", causality=Fmi3Causality.local, variability=Fmi3Variability.continuous, derivative=2))\n self.register_variable(Float64(\"mu\", causality=Fmi3Causality.parameter, variability=Fmi3Variability.fixed))\n\n\n def get_continuous_state_derivatives(self) -> List[float]:\n self.derx0 = self.x1\n self.derx1 = self.mu * ((1 - self.x0**2) * self.x1) - self.x0\n return [self.derx0, self.derx1]\n \n\n```\n\nNote: There is a hard requirement that we have a `self.time` member in the derived class.\n\n#### Create the FMU\n\n```\npythonfmu3 build -f pythonslaveMX.py\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight framework that enables the packaging of Python3.x code as co-simulation FMUs.",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/stephensmith25/PythonFMU3"
},
"split_keywords": [
"fmi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "847ea1a84cfe7c1550942d86abe654f53e93ff25c725273e5eb682e1ca9fb551",
"md5": "20c3c824e3b4fea5796b258cce2797c4",
"sha256": "80c7304c7d5b6a8535571efb632da1c029af38807a8df49d87b84d4986ae1b1f"
},
"downloads": -1,
"filename": "pythonfmu3-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20c3c824e3b4fea5796b258cce2797c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 361715,
"upload_time": "2025-07-28T17:43:45",
"upload_time_iso_8601": "2025-07-28T17:43:45.615315Z",
"url": "https://files.pythonhosted.org/packages/84/7e/a1a84cfe7c1550942d86abe654f53e93ff25c725273e5eb682e1ca9fb551/pythonfmu3-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "453c749bd299ac93108ac1b29ab74258765fddfe1fa532fd34b917ae7f5d27d5",
"md5": "ac49a9b8b2371aa67931f0cae52c51e2",
"sha256": "b863ad6674720b4db13c6060038c7a758a1abcbd5d9841094a07264d17058b51"
},
"downloads": -1,
"filename": "pythonfmu3-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "ac49a9b8b2371aa67931f0cae52c51e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 345758,
"upload_time": "2025-07-28T17:43:46",
"upload_time_iso_8601": "2025-07-28T17:43:46.697028Z",
"url": "https://files.pythonhosted.org/packages/45/3c/749bd299ac93108ac1b29ab74258765fddfe1fa532fd34b917ae7f5d27d5/pythonfmu3-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 17:43:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stephensmith25",
"github_project": "PythonFMU3",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fmpy",
"specs": []
},
{
"name": "pytest",
"specs": []
}
],
"lcname": "pythonfmu3"
}
JSON
