Examples update 1.9 (#190)

* ci: use latest julia 1.9 (#189) * started updating examples * marked outdated tutorials, will be updated soon --------- Co-authored-by: Sathvik Bhagavan <[email protected]>
ThummeTo · Aug 9, 2023 · f93ebd4 · f93ebd4
1 parent 8e25b07
commit f93ebd4
Show file tree

Hide file tree

Showing 12 changed files with 172 additions and 173 deletions.
diff --git a/.github/workflows/Example.yml b/.github/workflows/Example.yml
@@ -18,9 +18,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [windows-latest, ubuntu-latest]
+        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.9']
         julia-arch: [x64]
         experimental: [false]
 

diff --git a/README.md b/README.md
@@ -13,19 +13,20 @@
 [![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).
 
 
 ## How can I use FMI.jl?
 1\. Open a Julia-REPL, switch to package mode using `]`, activate your preferred environment.
 
 2\. Install [*FMI.jl*](https://github.com/ThummeTo/FMI.jl):
 ```julia-repl
-(@v1.X) pkg> add FMI
+(@v1) pkg> add FMI
 ```
 
 3\. If you want to check that everything works correctly, you can run the tests bundled with [*FMI.jl*](https://github.com/ThummeTo/FMI.jl):
 ```julia-repl
-(@v1.X) pkg> test FMI
+(@v1) pkg> test FMI
 ```
 
 4\. Have a look inside the [examples folder](https://github.com/ThummeTo/FMI.jl/tree/examples/examples) in the examples branch or the [examples section](https://thummeto.github.io/FMI.jl/dev/examples/overview/) of the documentation. All examples are available as Julia-Script (*.jl*), Jupyter-Notebook (*.ipynb*) and Markdown (*.md*).
@@ -35,13 +36,13 @@
 using FMI, Plots
 
 # load and instantiate a FMU
-myFMU = fmiLoad(pathToFMU)
+fmu = fmiLoad(pathToFMU) 
 
 # simulate from t=0.0s until t=10.0s and record the FMU variable named "mass.s"
-simData = fmiSimulate(myFMU, (0.0, 10.0); recordValues=["mass.s"])
+simData = fmiSimulate(fmu, (0.0, 10.0); recordValues=["mass.s"])
 
 # plot it!
-fmiPlot(simData)
+plot(simData)
 
 # free memory
 fmiUnload(myFMU)

diff --git a/docs/src/examples/overview.md b/docs/src/examples/overview.md
@@ -2,7 +2,8 @@
 
 This section discusses the included examples of the FMI.jl library.
 If you require further information about the function calls, see the function sections of the [library](https://thummeto.github.io/FMI.jl/dev/library/).
-Examples are subdevided into *Basics*, *Advanced* and *Publication appendices*
+
+Examples are subdevided into *Basics*, *Advanced* and *Publication appendices*.
 
 
 **Basic examples:**

diff --git a/examples/src/inputs.ipynb b/examples/src/inputs.ipynb
@@ -6,7 +6,7 @@
    "metadata": {},
    "source": [
     "# Simulate an FMU with inputs\n",
-    "Tutorial (WIP) by Tobias Thummerer\n",
+    "Tutorial by Tobias Thummerer\n",
     "\n",
     "## License"
    ]
@@ -33,9 +33,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Code section\n",
+    "## Introduction to the example\n",
+    "This example shows how to add custom inputs to a FMU, that are used during simulation.\n",
     "\n",
-    "To run the example, the previously installed packages must be included. "
+    "## Other formats\n",
+    "Besides, this [Jupyter Notebook](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/inputs.ipynb) there is also a [Julia file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/inputs.jl) with the same name, which contains only the code cells and for the documentation there is a [Markdown file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/inputs.md) corresponding to the notebook.  \n",
+    "\n",
+    "## Code section"
    ]
   },
   {
@@ -93,7 +97,7 @@
    "source": [
     "### Import FMU\n",
     "\n",
-    "In the next lines of code the FMU model from *FMIZoo.jl* is loaded and the information about the FMU is shown."
+    "Next, the FMU model from *FMIZoo.jl* is loaded."
    ]
   },
   {
@@ -111,11 +115,7 @@
    "outputs": [],
    "source": [
     "# we use an FMU from the FMIZoo.jl\n",
-    "pathToFMU = get_model_filename(\"SpringPendulumExtForce1D\", \"Dymola\", \"2022x\")\n",
-    "\n",
-    "myFMU = fmiLoad(pathToFMU; type=:ME) # load FMU in ME-Mode (\"Model Exchange\")\n",
-    "\n",
-    "fmiInfo(myFMU)"
+    "fmu = fmiLoad(\"SpringPendulumExtForce1D\", \"Dymola\", \"2022x\"; type=:ME) # load FMU in ME-Mode (\"Model Exchange\")"
    ]
   },
   {
@@ -125,7 +125,7 @@
    "source": [
     "#### Simulate as Model-Exchange\n",
     "\n",
-    "In the function `fmiSimulateME()` the FMU is simulated in model-exchange mode (ME) with an adaptive step size but with fixed save points `tSave`. In addition, the start and end time are specified. Note, that the dynamics of the input variables are not considered by the steps ize control of the solver, so it is highly recommended to limit the solver step size with the keyword argument `dtmax` if the input is more dynamic than the system."
+    "In the function `fmiSimulate()` the FMU is simulated with an adaptive step size but with fixed save points `tSave`. In addition, the start and end time are specified. Note, that the dynamics of the input variables are not considered by the steps ize control of the solver, so it is highly recommended to limit the solver step size with the keyword argument `dtmax` if the input is more dynamic than the system."
    ]
   },
   {
@@ -147,8 +147,13 @@
     "end \n",
     "\n",
     "# simulate while setting inputs\n",
-    "data_extForce_t = fmiSimulateME(myFMU, (tStart, tStop); saveat=tSave, inputValueReferences=[\"extForce\"], inputFunction=extForce_t, dtmax=1e-2)\n",
-    "fmiPlot(data_extForce_t)"
+    "data_extForce_t = fmiSimulate(fmu, (tStart, tStop);                 # FMU, start and stop time\n",
+    "                              saveat=tSave,                         # timepoints for the ODE solution to be saved\n",
+    "                              inputValueReferences=[\"extForce\"],    # the value references that should be set (inputs)\n",
+    "                              inputFunction=extForce_t,             # the input function to be used\n",
+    "                              dtmax=1e-2,                           # limit max step size to capture inputs\n",
+    "                              showProgress=false)                   # disable progress bar\n",
+    "plot(data_extForce_t)"
    ]
   },
   {
@@ -167,8 +172,8 @@
     "end \n",
     "\n",
     "# simulate while setting inputs\n",
-    "data_extForce_cxt = fmiSimulateME(myFMU, (tStart, tStop); saveat=tSave, inputValueReferences=[\"extForce\"], inputFunction=extForce_cxt, dtmax=1e-2)\n",
-    "fmiPlot(data_extForce_cxt)"
+    "data_extForce_cxt = fmiSimulate(fmu, (tStart, tStop); saveat=tSave, inputValueReferences=[\"extForce\"], inputFunction=extForce_cxt, dtmax=1e-2, showProgress=false)\n",
+    "plot(data_extForce_cxt)"
    ]
   },
   {
@@ -193,7 +198,7 @@
    },
    "outputs": [],
    "source": [
-    "fmiUnload(myFMU)"
+    "fmiUnload(fmu)"
    ]
   }
  ],
@@ -207,15 +212,15 @@
    "notebook_metadata_filter": "-all"
   },
   "kernelspec": {
-   "display_name": "Julia 1.8.5",
+   "display_name": "Julia 1.9.1",
    "language": "julia",
-   "name": "julia-1.8"
+   "name": "julia-1.9"
   },
   "language_info": {
    "file_extension": ".jl",
    "mimetype": "application/julia",
    "name": "julia",
-   "version": "1.8.5"
+   "version": "1.9.1"
   },
   "nteract": {
    "version": "0.28.0"

diff --git a/examples/src/manipulation.ipynb b/examples/src/manipulation.ipynb
@@ -5,7 +5,7 @@
    "metadata": {},
    "source": [
     "# Manipulate a function\n",
-    "Tutorial by Johannes Stoljar, Tobias Thummerer\n",
+    "Tutorial by Tobias Thummerer, Johannes Stoljar\n",
     "\n",
     "## License"
    ]
@@ -33,33 +33,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Motivation\n",
-    "This Julia Package *FMI.jl* is motivated by the use of simulation models in Julia. Here the FMI specification is implemented. FMI (*Functional Mock-up Interface*) is a free standard ([fmi-standard.org](http://fmi-standard.org/)) that defines a container and an interface to exchange dynamic models using a combination of XML files, binaries and C code zipped into a single file. The user can thus use simulation models in the form of an FMU (*Functional Mock-up Units*). Besides loading the FMU, the user can also set values for parameters and states and simulate the FMU both as co-simulation and model exchange simulation.\n",
-    "\n",
     "## Introduction to the example\n",
-    "This example shows how to overwrite a library function with an own function. For this the FMU model is simulated first without changes. Then the function `fmi2GetReal()` is overwritten and simulated again. Both simulations are displayed in a graph to show the change caused by overwriting the function. The model used is a one-dimensional spring pendulum with friction. The object-orientated structure of the *SpringFrictionPendulum1D* can be seen in the following graphic.\n",
+    "This example shows how to overwrite a FMI function with a custom C-function. For this the FMU model is simulated first without changes. Then the function `fmi2GetReal()` is overwritten and simulated again. Both simulations are displayed in a graph to show the change caused by overwriting the function. The model used is a one-dimensional spring pendulum with friction. The object-orientated structure of the *SpringFrictionPendulum1D* can be seen in the following graphic.\n",
     "\n",
     "![svg](https://github.com/thummeto/FMI.jl/blob/main/docs/src/examples/pics/SpringFrictionPendulum1D.svg?raw=true)  \n",
     "\n",
     "\n",
-    "## Target group\n",
-    "The example is primarily intended for users who work in the field of simulations. The example wants to show how simple it is to use FMUs in Julia.\n",
-    "\n",
-    "\n",
     "## Other formats\n",
-    "Besides, this [Jupyter Notebook](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/manipulation.ipynb) there is also a [Julia file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/manipulation.jl) with the same name, which contains only the code cells and for the documentation there is a [Markdown file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/manipulation.md) corresponding to the notebook.  \n",
-    "\n",
-    "\n",
-    "## Getting started\n",
-    "\n",
-    "### Installation prerequisites\n",
-    "|     | Description                       | Command                   | Alternative                                    |   \n",
-    "|:----|:----------------------------------|:--------------------------|:-----------------------------------------------|\n",
-    "| 1.  | Enter Package Manager via         | ]                         |                                                |\n",
-    "| 2.  | Install FMI via                   | add FMI                   | add \" https://github.com/ThummeTo/FMI.jl \"     |\n",
-    "| 3.  | Install FMIZoo via                | add FMIZoo                | add \" https://github.com/ThummeTo/FMIZoo.jl \"  |\n",
-    "| 4.  | Install FMICore via               | add FMICore               | add \" https://github.com/ThummeTo/FMICore.jl \" |\n",
-    "| 5.  | Install Plots via                 | add Plots                 |                                                |"
+    "Besides, this [Jupyter Notebook](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/manipulation.ipynb) there is also a [Julia file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/manipulation.jl) with the same name, which contains only the code cells and for the documentation there is a [Markdown file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/manipulation.md) corresponding to the notebook.  "
    ]
   },
   {
@@ -126,7 +107,7 @@
    "source": [
     "### Import FMU\n",
     "\n",
-    "In the next lines of code the FMU model from *FMIZoo.jl* is loaded and the information about the FMU is shown."
+    "Next, the FMU model from *FMIZoo.jl* is loaded."
    ]
   },
   {
@@ -144,11 +125,7 @@
    "outputs": [],
    "source": [
     "# we use an FMU from the FMIZoo.jl\n",
-    "pathToFMU = get_model_filename(\"SpringFrictionPendulum1D\", \"Dymola\", \"2022x\")\n",
-    "\n",
-    "myFMU = fmiLoad(pathToFMU)\n",
-    "\n",
-    "fmiInfo(myFMU)"
+    "fmu = fmiLoad(\"SpringFrictionPendulum1D\", \"Dymola\", \"2022x\"; type=:ME)"
    ]
   },
   {
@@ -173,9 +150,10 @@
    },
    "outputs": [],
    "source": [
+    "# an array of value references... or just one\n",
     "vrs = [\"mass.s\"]\n",
     "\n",
-    "simData = fmiSimulateME(myFMU, (tStart, tStop); recordValues=vrs)"
+    "simData = fmiSimulate(fmu, (tStart, tStop); recordValues=vrs)"
    ]
   },
   {
@@ -201,7 +179,7 @@
    },
    "outputs": [],
    "source": [
-    "fig = fmiPlot(simData, states=false)"
+    "fig = plot(simData, states=false)"
    ]
   },
   {
@@ -227,7 +205,7 @@
    "outputs": [],
    "source": [
     "# save, where the original `fmi2GetReal` function was stored, so we can access it in our new function\n",
-    "originalGetReal = myFMU.cGetReal"
+    "originalGetReal = fmu.cGetReal"
    ]
   },
   {
@@ -293,7 +271,7 @@
    "outputs": [],
    "source": [
     "# no we overwrite the original function\n",
-    "fmiSetFctGetReal(myFMU, myGetReal!)"
+    "fmiSetFctGetReal(fmu, myGetReal!)"
    ]
   },
   {
@@ -318,8 +296,8 @@
    },
    "outputs": [],
    "source": [
-    "simData = fmiSimulateME(myFMU, (tStart, tStop); recordValues=vrs)\n",
-    "fmiPlot!(fig, simData; states=false, style=:dash)"
+    "simData = fmiSimulate(fmu, (tStart, tStop); recordValues=vrs)\n",
+    "plot!(fig, simData; states=false, style=:dash)"
    ]
   },
   {
@@ -351,7 +329,7 @@
    },
    "outputs": [],
    "source": [
-    "fmiUnload(myFMU)"
+    "fmiUnload(fmu)"
    ]
   },
   {
@@ -360,7 +338,7 @@
    "source": [
     "### Summary\n",
     "\n",
-    "In this tutorial it is shown how an existing function of the library can be replaced by an own implementation. Through this possibility, there are almost no limits for the user, whereby the user can customize the function to his liking."
+    "In this tutorial it is shown how an existing function of the library can be replaced by an own implementation."
    ]
   }
  ],
@@ -374,15 +352,15 @@
    "notebook_metadata_filter": "-all"
   },
   "kernelspec": {
-   "display_name": "Julia 1.8.2",
+   "display_name": "Julia 1.9.1",
    "language": "julia",
-   "name": "julia-1.8"
+   "name": "julia-1.9"
   },
   "language_info": {
    "file_extension": ".jl",
    "mimetype": "application/julia",
    "name": "julia",
-   "version": "1.8.2"
+   "version": "1.9.1"
   },
   "nteract": {
    "version": "0.28.0"