v0.14.0 (#221)

* preparation for FMIBase and FMI3 * docu * updated readme, relaxed compat * modified project.tomlx * removed num_downloads badge, added new doc-strings to manual (#227) (api for badge currently down since 01-2024, screws up link-checking of documenter, markdown comment is not possible with documenter -> deletion) Co-authored-by: ThummeTo <[email protected]> * fixed cross checks (FMI2) * cross checks fix * fixed tests * added formatter action * code styling * updated actions * updated actions further --------- Co-authored-by: Simon Exner <[email protected]>
ThummeTo · Aug 19, 2024 · 3cd20ee · 3cd20ee
1 parent 765a88c
commit 3cd20ee
Show file tree

Hide file tree

Showing 60 changed files with 1,949 additions and 9,695 deletions.
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -28,7 +28,7 @@ jobs:
       - name: "Set up Julia"
         uses: julia-actions/setup-julia@v1
         with:
-          version: '1.9'
+          version: '1'
           arch: x64
 
       - name: "Copy examples, readme"

diff --git a/.github/workflows/Eval.yml b/.github/workflows/Eval.yml
@@ -56,4 +56,4 @@ jobs:
             Pkg.instantiate();
             Pkg.add("Test");
             Pkg.add(path="./PkgEval.jl")'
-          julia --project=. ./test/FMI2/eval.jl
+          julia --project=. ./test/eval.jl
diff --git a/.github/workflows/Example.yml b/.github/workflows/Example.yml
@@ -20,7 +20,7 @@ jobs:
       matrix:
         os: [windows-latest] # ubuntu-latest
         file-name: [manipulation, modelica_conference_2021, multiple_instances, multiprocessing, multithreading, parameterize, simulate, parameter_optimization]
-        julia-version: ['1.8']
+        julia-version: ['1']
         julia-arch: [x64]
         experimental: [false]
 

diff --git a/.github/workflows/Formatter.yml b/.github/workflows/Formatter.yml
@@ -0,0 +1,14 @@
+name: Format suggestions
+on:
+  pull_request:
+    # this argument is not required if you don't use the `suggestion-label` input
+    types: [ opened, reopened, synchronize, labeled, unlabeled ]
+jobs:
+  code-style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: julia-actions/julia-format@v3
+        with:
+          version: '1' # Set `version` to '1.0.54' if you need to use JuliaFormatter.jl v1.0.54 (default: '1')
+          suggestion-label: 'format-suggest' # leave this unset or empty to show suggestions for all PRs
+
diff --git a/Project.toml b/Project.toml
@@ -1,25 +1,15 @@
 name = "FMI"
 uuid = "14a09403-18e3-468f-ad8a-74f8dda2d9ac"
 authors = ["TT <[email protected]>", "LM <[email protected]>", "JK <[email protected]>"]
-version = "0.13.3"
+version = "0.14.0"
 
 [deps]
-DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
-Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 FMIExport = "31b88311-cab6-44ed-ba9c-fe5a9abbd67a"
 FMIImport = "9fcbc62e-52a0-44e9-a616-1359a0008194"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
-Requires = "ae029012-a4dd-5104-9daa-d747884805df"
-ThreadPools = "b189fb0b-2eb5-4ed4-bc0c-d34c51242431"
 
 [compat]
-DifferentialEquations = "7.7.0 - 7.13"
-Downloads = "1"
-FMIExport = "0.3.0"
-FMIImport = "0.16.0"
+FMIExport = "0.4.0"
+FMIImport = "1.0.0"
 LinearAlgebra = "1"
-ProgressMeter = "1.7.0 - 1.9"
-Requires = "1.3.0"
-ThreadPools = "2.1.1"
 julia = "1.6"
diff --git a/README.md b/README.md
@@ -2,20 +2,43 @@
 # FMI.jl
 
 ## What is FMI.jl?
-[*FMI.jl*](https://github.com/ThummeTo/FMI.jl) is a free-to-use software library for the Julia programming language which integrates the **F**unctional **M**ock-Up **I**nterface ([fmi-standard.org](https://fmi-standard.org/)): load or create, parameterize, differentiate, simulate and plot FMUs seamlessly inside the Julia programming language!
+[*FMI.jl*](https://github.com/ThummeTo/FMI.jl) is a free-to-use software library for the Julia programming language which integrates the **F**unctional **M**ock-Up **I**nterface ([fmi-standard.org](https://fmi-standard.org/)): load or create, parameterize, differentiate, linearize, simulate and plot FMUs seamlessly inside the Julia programming language!
 
-[![Dev Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://ThummeTo.github.io/FMI.jl/dev) 
-[![Test (latest)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLatest.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLatest.yml)
-[![Test (LTS)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLTS.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLTS.yml)
-[![FMI2 Cross Checks (latest)](https://github.com/ThummeTo/FMI.jl/actions/workflows/CrossChecks.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/CrossChecks.yml)
-[![Examples (latest)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Example.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Example.yml)
-[![Build Docs](https://github.com/ThummeTo/FMI.jl/actions/workflows/Documentation.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Documentation.yml)
-[![Run PkgEval](https://github.com/ThummeTo/FMI.jl/actions/workflows/Eval.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Eval.yml)
-[![Coverage](https://codecov.io/gh/ThummeTo/FMI.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ThummeTo/FMI.jl)
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
-[![FMI Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/FMI)](https://pkgs.genieframework.com?packages=FMI)
-[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+| | |
+|---|---|
+| Documentation | [![Build Docs](https://github.com/ThummeTo/FMI.jl/actions/workflows/Documentation.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Documentation.yml) [![Dev Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://ThummeTo.github.io/FMI.jl/dev) |
+| Examples | [![Examples (latest)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Example.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Example.yml) |
+| Tests | [![Test (latest)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLatest.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLatest.yml) [![Test (LTS)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLTS.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/TestLTS.yml) [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl) |
+| FMI cross checks| [![FMI2 Cross Checks](https://github.com/ThummeTo/FMI.jl/actions/workflows/CrossChecks.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/CrossChecks.yml) |
+| Package evaluation| [![Run PkgEval](https://github.com/ThummeTo/FMI.jl/actions/workflows/Eval.yml/badge.svg)](https://github.com/ThummeTo/FMI.jl/actions/workflows/Eval.yml) |
+| Code coverage | [![Coverage](https://codecov.io/gh/ThummeTo/FMI.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ThummeTo/FMI.jl) |
+| Collaboration | [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) |
+| Formatting | [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle) |
 
+## 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*](https://github.com/ThummeTo/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*](https://github.com/ThummeTo/FMICore.jl) and [*FMIImport.jl*](https://github.com/ThummeTo/FMIImport.jl) were divided into [*FMICore.jl*](https://github.com/ThummeTo/FMICore.jl), [*FMIImport.jl*](https://github.com/ThummeTo/FMIImport.jl) and [*FMIBase.jl*](https://github.com/ThummeTo/FMIBase.jl). [*FMICore.jl*](https://github.com/ThummeTo/FMICore.jl) now holds the pure standard definition (C-types and -functions), while [*FMIBase.jl*](https://github.com/ThummeTo/FMIBase.jl) holds everything that is needed on top of that in [*FMIImport.jl*](https://github.com/ThummeTo/FMIImport.jl) as well as in [*FMIExport.jl*](https://github.com/ThummeTo/FMIExport.jl).
+
+- [ ] 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.
+
+- [ ] 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.
@@ -37,16 +60,16 @@
 using FMI, Plots
 
 # load and instantiate a FMU
-fmu = fmiLoad(pathToFMU) 
+fmu = loadFMU(pathToFMU) 
 
 # simulate from t=0.0s until t=10.0s and record the FMU variable named "mass.s"
-simData = fmiSimulate(fmu, (0.0, 10.0); recordValues=["mass.s"])
+simData = simulate(fmu, (0.0, 10.0); recordValues=["mass.s"])
 
 # plot it!
 plot(simData)
 
 # free memory
-fmiUnload(myFMU)
+unloadFMU(myFMU)
 ```
 
 ## What is currently supported in FMI.jl?
@@ -57,21 +80,21 @@ fmiUnload(myFMU)
 |                                   | **FMI2.0.3** |        | **FMI3.0** |        | **SSP1.0** |        |
 |-----------------------------------|--------------|--------|------------|--------|------------|--------|
 |                                   | Import       | Export | Import     | Export | Import     | Export |
-| CS                                | ✔️✔️         | 🚧     | ✔️          | 📅     | 📅         | 📅      |
-| ME (continuous)                   | ✔️✔️         | ✔️✔️   | 🚧          | 📅     | 📅         | 📅      |
-| ME (discontinuous)                | ✔️✔️         | ✔️✔️   | 🚧          | 📅     | 📅         | 📅      |
+| CS                                | ✔️✔️         | 🚧     | ✔️✔️        | 📅     | 📅         | 📅      |
+| ME (continuous)                   | ✔️✔️         | ✔️✔️   | ✔️✔️        | 📅     | 📅         | 📅      |
+| ME (discontinuous)                | ✔️✔️         | ✔️✔️   | ✔️✔️        | 📅     | 📅         | 📅      |
 | SE                 		    | 🚫           | 🚫     | 🚧          | 📅     | 🚫         | 🚫     |
-| Explicit solvers                  | ✔️✔️         | ✔️✔️   | ✔️          | 📅     | 📅         | 📅      |
-| Implicit solvers (autodiff=false) | ✔️✔️         | 🚧     | ✔️          | 📅     | 📅         | 📅      |
-| Implicit solvers (autodiff=true)  | ✔️✔️         | 🚧     | 🚧          | 📅     | 📅         | 📅      |
-| get/setState                      | ✔️✔️         | 📅     | ✔️          | 📅     | 🚫         | 🚫      |
-| getDirectionalDerivatives         | ✔️✔️         | 📅     | ✔️          | 📅     | 🚫         | 🚫      |
-| getAdjointDerivatives             | 🚫           | 🚫     | ✔️          | 📅     | 🚫         | 🚫     |
+| Explicit solvers                  | ✔️✔️         | ✔️✔️   | ✔️✔️        | 📅     | 📅         | 📅      |
+| Implicit solvers (autodiff=false) | ✔️✔️         | ✔️✔️   | ✔️✔️        | 📅     | 📅         | 📅      |
+| Implicit solvers (autodiff=true)  | ✔️           | ✔️✔️   | ✔️          | 📅     | 📅         | 📅      |
+| get/setState                      | ✔️✔️         | 📅     | ✔️✔️        | 📅     | 🚫         | 🚫      |
+| getDirectionalDerivatives         | ✔️✔️         | 📅     | ✔️✔️        | 📅     | 🚫         | 🚫      |
+| getAdjointDerivatives             | 🚫           | 🚫     | ✔️✔️        | 📅     | 🚫         | 🚫     |
 | FMI Cross Checks                  | ✔️✔️         | 📅     | 📅          | 📅     | 🚫         | 🚫      |
 
-✔️✔️ supported & tested
+✔️✔️ supported & CI-tested
 
-✔️  beta supported (implemented), but untested
+✔️  beta supported: implemented, but not CI-tested
 
 🚧 work in progress
 
@@ -87,14 +110,15 @@ To keep dependencies nice and clean, the original package [*FMI.jl*](https://git
 - [*FMI.jl*](https://github.com/ThummeTo/FMI.jl): High level loading, manipulating, saving or building entire FMUs from scratch
 - [*FMIImport.jl*](https://github.com/ThummeTo/FMIImport.jl): Importing FMUs into Julia
 - [*FMIExport.jl*](https://github.com/ThummeTo/FMIExport.jl): Exporting stand-alone FMUs from Julia Code
+- [*FMIBase.jl*](https://github.com/ThummeTo/FMIBase.jl): Common concepts for import and export of FMUs
 - [*FMICore.jl*](https://github.com/ThummeTo/FMICore.jl): C-code wrapper for the FMI-standard
 - [*FMISensitivity.jl*](https://github.com/ThummeTo/FMISensitivity.jl): Static and dynamic sensitivities over FMUs
 - [*FMIBuild.jl*](https://github.com/ThummeTo/FMIBuild.jl): Compiler/Compilation dependencies for FMIExport.jl
 - [*FMIFlux.jl*](https://github.com/ThummeTo/FMIFlux.jl): Machine Learning with FMUs
 - [*FMIZoo.jl*](https://github.com/ThummeTo/FMIZoo.jl): A collection of testing and example FMUs
 
 ## What Platforms are supported?
-[*FMI.jl*](https://github.com/ThummeTo/FMI.jl) is tested (and testing) under Julia Versions *1.6 LTS* (64-bit) and *latest* (64-bit) on Windows *latest* (64-bit) and Ubuntu *latest* (64-bit). Mac and Julia (32-bit) should work, but untested. For the best performance, we recommend using Julia >= 1.7.
+[*FMI.jl*](https://github.com/ThummeTo/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-bit). Mac (64-bit, 32-bit) and Ubuntu (32-bit) should work, but untested. For the best performance, we recommend using Julia >= 1.7, even if we support and test for the official LTS (1.6.7).
 
 ## How to cite?
 Tobias Thummerer, Lars Mikelsons and Josef Kircher. 2021. **NeuralFMU: towards structural integration of FMUs into neural networks.** Martin Sjölund, Lena Buffoni, Adrian Pop and Lennart Ochel (Ed.). Proceedings of 14th Modelica Conference 2021, Linköping, Sweden, September 20-24, 2021. Linköping University Electronic Press, Linköping (Linköping Electronic Conference Proceedings ; 181), 297-306. [DOI: 10.3384/ecp21181297](https://doi.org/10.3384/ecp21181297)
@@ -109,7 +133,4 @@ Contributors are welcome. Before contributing, please read, understand and follo
 During development of new implementations or optimizations on exisitng code, one will have to make design decissions that influence the library performance and usability. The following priorization should be the basis for decision-making:
 - **#1 Compliance with standard:** It is the highest priority to be compliant with the FMI standard ([fmi-standard.org](https://fmi-standard.org/)). Identifiers described in the standard must be used. Topologies should follow the specification as far as the possibilities of the Julia programming language allows.
 - **#2 Performance:** Because [*FMI.jl*](https://github.com/ThummeTo/FMI.jl) is a simulation tool, performance is very important. This applies to the efficient use of CPU and GPU, but also the conscientious use of RAM and disc space.
-- **#3 Usability:** The library should be as usable as possible, as long as being fully compliant with the FMI standard.
-
-## Interested in Hybrid Modelling in Julia using FMUs?
-See [*FMIFlux.jl*](https://github.com/ThummeTo/FMIFlux.jl).
+- **#3 Usability:** The library should be as usable as possible and feel "the Julia way" (e.g. by using multiple dispatch instead of the "C coding style"), as long as being fully compliant with the FMI standard.
diff --git a/cross_checks/README.md b/cross_checks/README.md
@@ -8,17 +8,17 @@ More information: https://github.com/modelica/fmi-cross-check
 
 ### Automated run using github actions
 
-The `..\.github\workflow` folder contains a `CrossChecks.yml` file that configures the excecution of the fmi cross checks using a github action.
+The `..\.github\workflow` folder contains a `CrossChecks.yml` file that configures the execution of the FMI cross checks using a github action.
 
-This action pulls the fmi cross checks from a repository, excecutes them and pushes the result files back to the repository. These specified repository needs to be forked before from https://github.com/modelica/fmi-cross-check. After forking the fmi-cross-check repository, a access token with repo rights needs to be generated (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+This action pulls the FMI cross checks from a repository, executes them and pushes the result files back to the repository. These specified repository needs to be forked before from https://github.com/modelica/fmi-cross-check. After forking the fmi-cross-check repository, a access token with repo rights needs to be generated (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
 
 In order to use the action you need to be set the following information about your fmi-cross-check repository the FMI.jl repository as secrets and variables.
 
 * (Variable) `CROSS_CHECK_REPO_URL`: The url (without protocol) to your fmi-cross-check repository. (Example: `github.com/johndoe/fmi-cross-check`)
 * (Variable) `CROSS_CHECK_REPO_USER`: The user that has write access to the fmi-cross-check repository and for which the token was created. (Example: `johndoe`)
 * (Secret) `CROSS_CHECK_REPO_TOKEN`: The github token that was created for the fmi-cross-check repository (Example: `ghp_IqHJF673SD...`)
 
-Not setting these values correctly will prevent the results to be pushed to your fmi-cross-check repositoy. However you will still be able to see the result summary of your run in the github action logs.
+Not setting these values correctly will prevent the results to be pushed to your fmi-cross-check repository. However you will still be able to see the result summary of your run in the github action logs.
 
 ### Manual run