FMI.jl

What is FMI.jl?

FMI.jl is a free-to-use software library for the Julia programming language which integrates the Functional Mock-Up Interface (fmi-standard.org): load or create, parameterize, differentiate, linearize, simulate and plot FMUs seamlessly inside the Julia programming language!

| | | |---|---| | Documentation | | | Examples | | | Tests | | | FMI cross checks| | | Package evaluation| | | Code coverage | | | Collaboration | | | Formatting | |

Breaking Changes in FMI.jl (starting from v0.14.0 until release of v1.0.0)

If you want to migrate your project from FMI.jl < v1.0.0 to >= v1.0.0, you will face some breaking changes - but they are worth it as you will see! We decided to do multiple smaller breaking changes starting with v0.14.0, instead of one big one. Some of them are already implemented (checked), some are still on the todo (unchecked) but will be implemented before releasing v1.0.0.

• [x] Many functions, that are not part of the FMI-standard, had the prefix fmi2... or fmi3.... This was corrected. Now, only functions that are defined by the standard itself, like e.g. fmi2Instantiate are allowed to keep the prefix. Other methods, like fmi2ValueReferenceToString, that where added to make this library more comfortable, are now cleaned to be more the Julia way: valueReferenceToString. If your code errors, the corresponding function might have lost it's prefix, so try this first.

• [x] Wrapper functions where removed, because that is not the Julia way. In most cases, this will not affect your code.

• [x] FMICore.jl and FMIImport.jl were divided into FMICore.jl, FMIImport.jl and FMIBase.jl. FMICore.jl now holds the pure standard definition (C-types and -functions), while FMIBase.jl holds everything that is needed on top of that in FMIImport.jl as well as in FMIExport.jl.

• [ ] Updated all library examples.

• [ ] Updated all library tests for a better code coverage.

• [ ] We tried to document every function, if you find undocumented user-level functions, please open an issue or PR.

• [ ] Allocations, type stability and code format where optimized and are monitored by CI now.

• [ ] Dependencies are reduced a little, to make the libraries more light-weight.

• [ ] RAM for allocated FMUs, their instances and states, is now auto-released. For maximum performance/safety you can use FMUs in blocks (like file reading/writing).

• [ ] New low-level interfaces are introduced, that fit the SciML-ecosystem. For example, a FMU can still be simulated with simulate(fmu), but one can also decide to create a prob = FMUProblem(fmu) (like an ODEProblem) and use solve(prob) to obtain a solution. Keywords will be adapted to have a fully consistent interface with the remaining SciML-ecosystem.

• [x] Optimization for new Julia LTS v1.10, removing code to keep downward compatibility with old LTS v1.6.

🎉 After all listed features are implemented, v1.0.0 will be released! 🎉

How can I use FMI.jl?

1. Open a Julia-REPL, switch to package mode using ], activate your preferred environment.

2. Install FMI.jl:

(@v1) pkg> add FMI

3. If you want to check that everything works correctly, you can run the tests bundled with FMI.jl:

(@v1) pkg> test FMI

4. Have a look inside the examples folder in the examples branch or the examples section of the documentation. All examples are available as Julia-Script (.jl), Jupyter-Notebook (.ipynb) and Markdown (.md).

How can I simulate a FMU and plot values?

using FMI, Plots

# load and instantiate a FMU
fmu = loadFMU(pathToFMU) 

# simulate from t=0.0s until t=10.0s and record the FMU variable named "mass.s"
simData = simulate(fmu, (0.0, 10.0); recordValues=["mass.s"])

# plot it!
plot(simData)

# free memory
unloadFMU(myFMU)

What is currently supported in FMI.jl?

• importing the full FMI 2.0.3 and FMI 3.0.0 command set, including optional specials like fmi2GetFMUstate, fmi2SetFMUstate and fmi2GetDirectionalDerivatives
• parameterization, simulation & plotting of CS- and ME-FMUs
• event-handling for imported discontinuous ME-FMUs

| | FMI2.0.3 | | FMI3.0 | | SSP1.0 | | |-----------------------------------|--------------|--------|------------|--------|------------|--------| | | Import | Export | Import | Export | Import | Export | | CS | ✔️✔️ | 🚧 | ✔️✔️ | 📅 | 📅 | 📅 | | ME (continuous) | ✔️✔️ | ✔️✔️ | ✔️✔️ | 📅 | 📅 | 📅 | | ME (discontinuous) | ✔️✔️ | ✔️✔️ | ✔️✔️ | 📅 | 📅 | 📅 | | SE | 🚫 | 🚫 | 🚧 | 📅 | 🚫 | 🚫 | | Explicit solvers | ✔️✔️ | ✔️✔️ | ✔️✔️ | 📅 | 📅 | 📅 | | Implicit solvers (autodiff=false) | ✔️✔️ | ✔️✔️ | ✔️✔️ | 📅 | 📅 | 📅 | | Implicit solvers (autodiff=true) | ✔️ | ✔️✔️ | ✔️ | 📅 | 📅 | 📅 | | get/setFMUstate | ✔️✔️ | 📅 | ✔️✔️ | 📅 | 🚫 | 🚫 | | getDirectionalDerivatives | ✔️✔️ | 📅 | ✔️✔️ | 📅 | 🚫 | 🚫 | | getAdjointDerivatives | 🚫 | 🚫 | ✔️✔️ | 📅 | 🚫 | 🚫 | | FMI Cross Checks | ✔️✔️ | 📅 | 📅 | 📅 | 🚫 | 🚫 | | 64-bit binaries in FMUs | ✔️✔️ | ✔️✔️ | ✔️✔️ | 📅 | 🚫 | 🚫 | | 32-bit binaries in FMUs | ✔️ | 📅 | 📅 | 📅 | 🚫 | 🚫 |

✔️✔️ supported & CI-tested

✔️ beta supported: implemented, but not CI-tested

🚧 work in progress

📅 planned

🚫 not supported by the corresponding FMI standard (not applicable)

❌ not planned

What FMI.jl-Library to use?

To keep dependencies nice and clean, the original package FMI.jl had been split into new packages:

• FMI.jl: High level loading, manipulating, saving or building entire FMUs from scratch
• FMIImport.jl: Importing FMUs into Julia
• FMIExport.jl: Exporting stand-alone FMUs from Julia Code
• FMIBase.jl: Common concepts for import and export of FMUs
• FMICore.jl: C-code wrapper for the FMI-standard
• FMISensitivity.jl: Static and dynamic sensitivities over FMUs
• FMIBuild.jl: Compiler/Compilation dependencies for FMIExport.jl
• FMIFlux.jl: Machine Learning with FMUs
• FMIZoo.jl: A collection of testing and example FMUs

What Platforms are supported?

FMI.jl is tested (and testing) under Julia Versions 1.6 LTS (64-bit) and latest (64-bit) on Windows latest (64-bit, 32-bit) and Ubuntu latest (64