Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
e0f9f67
Re-structured project to the standard src/pythonfmu3/ structure and m…
eisDNV Aug 4, 2026
f8cb221
Fixed tests so that ============================= test session starts…
eisDNV Aug 4, 2026
c042b82
Added the PID-controller example to /examples. Needed fixes. Changed …
eisDNV Aug 4, 2026
914b037
Added the implementation of EnterEventMode fmi3 function to the Cpp c…
eisDNV Aug 6, 2026
4e078bb
Updated the documentation of ModelVariables class and added since th…
eisDNV Aug 6, 2026
65ab30d
Added a variable type 'Clock' to ModelVariables. Added some documenta…
eisDNV Aug 6, 2026
c3673ee
Implemented all event-related functions in cppfmu/ and pythonfmu/. Co…
eisDNV Aug 9, 2026
ae48cae
Added the function EnterStepMode, which was completely missing, such …
eisDNV Aug 14, 2026
200a59e
In order to receive results from UpdateDiscreteStates() a dedicated N…
eisDNV Aug 14, 2026
e78660d
Ensure all FMI3 model options, so that the system can work with FMI3 …
eisDNV Aug 18, 2026
bfc7144
Change in builder.py to include model options properly
eisDNV Aug 19, 2026
7432e2d
Corrected errors in fmi3slave.py and variables.py leading to errors i…
eisDNV Aug 19, 2026
bdc012a
Added an FMI3 FMU 'function'. Tested basic usage.
eisDNV Aug 19, 2026
1f96296
Adapted function signatures to be as close as possible to FMI3 standa…
eisDNV Aug 28, 2026
8581c7c
Added the arguments 'eventModeUsed' and 'earlyReturnAllowed' in Insta…
eisDNV Sep 7, 2026
fd4ab83
Some last changes as part of moving back to windows. Windows compilat…
eisDNV Oct 9, 2026
5075170
Added windows support to the package. The dynamic libraries and the g…
eisDNV Oct 9, 2026
44bada4
Minor updates within the example FMUs to support discrete_event mode
eisDNV Oct 12, 2026
77dec22
Added CHANGELOG.md to the package
eisDNV Oct 26, 2026
d3fc9a3
Fixed issues detected in verification + Python syntax for event_mode_…
eisDNV Oct 26, 2026
2425c61
Changed all argument names to python-style within PySlaveInstance.cpp…
eisDNV Oct 29, 2026
bd7c922
One step towards satisfying ruff, mypy and pyright. Still there are a…
eisDNV Nov 2, 2026
e7582d6
Needed to revert the pythonic model_results, since it caused problems…
eisDNV Nov 2, 2026
213a251
Added the other standard Int*, UInt* variable types. Added suitable t…
eisDNV Nov 6, 2026
36e9ee7
Updated CHANGELOG.md
eisDNV Nov 6, 2026
20187f2
Added two array variabels to examples/Variables3.fmu
eisDNV Nov 6, 2026
7ededb8
Fixed a misunderstanding in update_discrete_states, where it is impor…
eisDNV Nov 15, 2026
7f4862a
Made all imports into explicit imports and reduced src/pythonfmu3.__i…
eisDNV Nov 16, 2026
fe2bdc6
Removed _version.py and replaced pythonfmu3 version retrieval with re…
eisDNV Nov 16, 2026
26c6146
Updated CHANGELOG.md
eisDNV Nov 16, 2026
4a52060
Added the file PythonFMU23.rst with notes on how PythonFMU3 could be …
eisDNV Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@

# binaries
*.dll
*.dll.manifest
*.so
#*.dll
#*.dll.manifest
#*.so

# pythonfmu binaries folder
/**/pythonfmu3/resources/binaries
#/**/pythonfmu3/resources/binaries

# CLion
/**/cmake-build-debug
Expand All @@ -27,7 +27,7 @@ build/
# test and examples artifacts
/**/*_log.txt
/**/*_result.mat
/**/*.fmu
#/**/*.fmu

# Generated TensorFlow model
/examples/tensorflow-model-export/stored-model/
Expand Down
1 change: 1 addition & 0 deletions .python-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
3.13
48 changes: 48 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Changelog

All notable changes to the [PythonFMU3s] project from version 0.4.0 will be documented in this file.<br>
The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [Unreleased]

* -/-



## [0.4.0] - 2026-11
The main goal was the inclusion of event-related functions in the package.
In addition also other functions have been implemented, but there are still some pending FMI3 functions.
All changes where implemented in the branch *eis*

* Re-structured project to the standard src/pythonfmu3/ structure and moving tests/ out. Ran ruff check --fix and ruff format on project
* Fixed tests so that ============================= test session starts ==============================
* Added the PID-controller example to /examples. Needed fixes. Changed therefore docs/usage.md and adapted the documentation build process (adding conf.py, /_static and /_templates)
* Added the implementation of EnterEventMode fmi3 function to the Cpp code. Successfull compilation. Added a basic discrete event example.
* Updated the documentation of ModelVariables class and added since this is not only in use for ME, but also for CS in event mode. It is set to True per default as per FMI spec
* Added a variable type 'Clock' to ModelVariables. Added some documentation also to other variable types and added ModelVariables.to_str as formatter for python types to xml strings
* Implemented all event-related functions in cppfmu/ and pythonfmu/. Code compiles, but is so far not yet tested.
* Added the function EnterStepMode, which was completely missing, such that no switch back to step mode was possible. Compilation ok.
* In order to receive results from UpdateDiscreteStates() a dedicated NamedTuple needs to be defined and used.
* Ensure all FMI3 model options, so that the system can work with FMI3 features. Options are now implemented as dataclass and it is possible to provide options directly to the Slave (not only through cli). Tested features.
* Change in builder.py to include model options properly
* Corrected errors in fmi3slave.py and variables.py leading to errors in FMU building and FMU usage with respect to variables with dimensions
* Added an FMI3 FMU 'function' as an example for a *pass-through* event-based FMU. Tested basic usage.
* Adapted function signatures to be as close as possible to FMI3 standard. SetupExperiment deprecated, EnterInitializationMode updated, EnterContinuousTimeMode and CompletedIntegratorStep added. Recompiled and basic tests.
* Added the arguments 'eventModeUsed' and 'earlyReturnAllowed' in InstantiateCosimulation, which where so far not included. Related changes in fmi3slave are also implemented. Compiles and test works. IntermediateUpdate management is still not included.
* Some last changes as part of moving back to windows. Windows compilation not yet included.
* Added windows support to the package. The dynamic libraries and the generated FMUs have been added to the git package (.gitignore changed).
* Minor updates within the example FMUs to support discrete_event mode
* Added a CHANGELOG.md file to the package and included this point list from the git commit messages.
* Fixed findings from verification. Mainly PySlaveInstance.cpp fixes and adaptations in some .py files. test_cli.py has been removed, since it needs complete re-write
* One step towards satisfying ruff, mypy and pyright. Still there are a lot of comments. All tests are working.
* Added the remaining Int* and UInt* standard FMI3 variable types. Added suitable tests and the FMU Variables3.fmu containing all variable types
Clock variables are still missing and Enumeration variables are untested.
* Added two array variabels to examples/Variables3.fmu
* Fixed a misunderstanding in update_discrete_states, where it is important to not use discreteStatesNeedsUpdate=True as way to signal that outputs are updated. Use it only to stay in event mode!
* Made all imports into explicit imports and reduced src/pythonfmu3.__init__.py to nothing.
* Removed _version.py and replaced pythonfmu3 version retrieval with retrieval from pyproject.toml as single source





87 changes: 87 additions & 0 deletions PythonFMU23.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
########################
PythonFMU for FMI2 and 3
########################
Notes on how to make PythonFMU3 work for both FMI2 and FMI3.

* Folder `src/pythonfmu3` should be renamed to `src/pythonfmu`
* Folder `src/pythonfmu3/pythonfmu-export` should be renamed to src/pythonfmu/pythonfmu3-export`
* Folder `src/pythonfmu/pythonfmu2-export` should be added with content from the `PythonFMU` repository.

Files in src/pythonfmu3/
========================

builder.py
----------
* `get_model_description()`: should work, but should probably be replaced by the more flexible version from PythonFMU. Requires also that the related c-code (adapted) is replaced.
* **FmuBuilder.build_FMU()** should be simplified in any case and needs adaptation.
Add also a parameter telling the builder which FMI version to use - or make automatic??
Change also _FMU to _fmu.
* `create_command_parser`: needs to be changed in relation to changes in build_FMU

cosimulation.py
---------------
* **CoSimulation(ABC)**: need to decide how to handle the method `do_step()` and `enter_initialization_mode()`,
which have a different signature in FMI2 and FMI3.

modelexchange.py
----------------
* **ModelExchange(ABC,...)**: some of the methods do not exist in FMI2

default_experiment.py
---------------------
* keep as is. Note that this is used differently in FMI2 (`setup_experiment()`) and FMI3 (`enter_initialization_mode()`)

deploy.py
---------
* keep as is

enums.py
--------
* all enums are defined as **Fmi3...**. Need to decide whether to make equivalent fmi2 enums or make the classes neutral with respect to FMI version. Note that a few minor changes between FMI2 and FMI3 must be handled and the Fmi3Type enum seems both wrong and unused.

fmi3slave.py
------------
* **Fmi3Slave** and **Fmi3SlaveBase** are made for FMI3. Make a similar fmi2slave.py for FMI2.

logmsg.py
---------
* keep as is. Check whether the logging strategy is aligned with the FMI standard.

model_options.py
----------------
* all class names are **Fmi3...**. Need to decide whether to make equivalent fmi2 classes or make the classes neutral with respect to FMI version. Some properties do not exist in FMI2, which would need to be managed, so that they are not listed in modelDescription.xml

model_returns.py
----------------
* only relevant for FMI3, since FMI2 does not use these more comåplex returns.

osutil.py
---------
* keep as is. The file should probably be **moved to a utils/ folder**.

unit.py
-------
* keep as is. **Check** whether there are no changes in the handling of units between FMI2 and FMI3

variables.py
------------
* `py_types`: FMI2 types `Real`and `Integer`are included. Can use `fmi_type_version()` to check whether type is allowed in FMI version used.
* `fmi_type_version()`: useful to whether type is allowed in FMI version used.
* `fmi_type`: ok
* `ModelVariable`: name of the class changed from ScalarVariable to ModelVariable. The signature is still compatible with both FMI2 and FMI3. Can probably live with the FMI3 name, making sure that **ScalarVariable** is used when generating the modelDescription in FMI2. See `to_xml()` and `to_str()` methods.
* `Start`: ok
* `Dimension`: does not exist in FMI2. Either make sure that it is **not used in FMI2** or **automatically translate** to a set of ScalarVariable, using the structured variableNamingConvention.
* `Arrayable`. See `Dimension`.
* `Float64 ...`: do not exist in FMI2. **Add** `Real` and `Integer` classes. We could choose to **automatically translate** `Float64` and `Int32` into `Real`and `Integer` classes when building FMI2.
* Clock: does not exist in FMI2. **Check** that it is not used when building FMI2.

variable_types.py
-----------------
* the defined classes should be ok under FMI2 also. **Float64Type** shall not be used under FMI2.







100 changes: 70 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@

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:
## 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?
## How do I build an FMU from python code?

1. Install `pythonfmu3` package:

Expand All @@ -30,9 +30,9 @@ pip install pythonfmu3

```
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 ...]]
[--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.

Expand All @@ -57,7 +57,7 @@ optional arguments:
--serialize-state If given, canSerializeFMUstate=true
```

### How do I build an FMU from python code with third-party dependencies?
## 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.
Expand Down Expand Up @@ -89,17 +89,18 @@ optional arguments:
Requirements or environment file.
```

### Cosimulation Example:
## Cosimulation Example:

#### Write the script
### Write the script

```python

from pythonfmu3 import Fmi3Causality, Fmi3Slave, Boolean, Int32, Float64, String
from pythonfmu3.enums import Fmi3Causality
from pythonfmu3.fmi3slave import Fmi3Slave
from pythonfmu3.model_returns import Fmi3StepResult
from pythonfmu3.variables import Boolean, Int32, Float64, String


class PythonSlave(Fmi3Slave):

def __init__(self, **kwargs):
super().__init__(**kwargs)

Expand All @@ -116,17 +117,16 @@ class PythonSlave(Fmi3Slave):
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

return Fmi3StepResult()
```

#### Create the FMU
### Create the FMU

```
pythonfmu3 build -f pythonslave.py myproject
Expand All @@ -137,20 +137,21 @@ where `myproject` is an optional folder containing additional project files requ
Project folders such as this will be recursively copied into the FMU. Multiple project files/folders may be added.


### Model Exchange Example
## 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
### Write the script

```python

from pythonfmu3 import Fmi3Causality, Fmi3SlaveBase, Float64, ModelExchange
from pythonfmu3.enums import Fmi3Causality
from pythonfmu3.fmi3slave import Fmi3SlaveBase
from pythonfmu3.modelexchange import ModelExchange
from pythonfmu3.variables import Float64
from typing import List


class PythonSlaveMX(Fmi3SlaveBase, ModelExchange):

def __init__(self, **kwargs):
super().__init__(**kwargs)

Expand All @@ -164,25 +165,64 @@ class PythonSlaveMX(Fmi3SlaveBase, ModelExchange):
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))

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
### Create the FMU

```
pythonfmu3 build -f pythonslaveMX.py
Expand Down
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Loading
Loading