Skip to content

Commit

Permalink
started updating examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@ThummeTo
ThummeTo committed Aug 8, 2023
1 parent 8e25b07 commit ce45ad9
Show file tree
Hide file tree
Showing 6 changed files with 64 additions and 89 deletions.
1 change: 1 addition & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
[![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?
Expand Down
3 changes: 2 additions & 1 deletion docs/src/examples/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down
41 changes: 23 additions & 18 deletions examples/src/inputs.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
Expand All @@ -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"
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand All @@ -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\")"
]
},
{
Expand All @@ -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."
]
},
{
Expand All @@ -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)"
]
},
{
Expand All @@ -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)"
]
},
{
Expand All @@ -193,7 +198,7 @@
},
"outputs": [],
"source": [
"fmiUnload(myFMU)"
"fmiUnload(fmu)"
]
}
],
Expand All @@ -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"
Expand Down
56 changes: 17 additions & 39 deletions examples/src/manipulation.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
Expand Down Expand Up @@ -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. "
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand All @@ -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)"
]
},
{
Expand All @@ -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)"
]
},
{
Expand All @@ -201,7 +179,7 @@
},
"outputs": [],
"source": [
"fig = fmiPlot(simData, states=false)"
"fig = plot(simData, states=false)"
]
},
{
Expand All @@ -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"
]
},
{
Expand Down Expand Up @@ -293,7 +271,7 @@
"outputs": [],
"source": [
"# no we overwrite the original function\n",
"fmiSetFctGetReal(myFMU, myGetReal!)"
"fmiSetFctGetReal(fmu, myGetReal!)"
]
},
{
Expand All @@ -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)"
]
},
{
Expand Down Expand Up @@ -351,7 +329,7 @@
},
"outputs": [],
"source": [
"fmiUnload(myFMU)"
"fmiUnload(fmu)"
]
},
{
Expand All @@ -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."
]
}
],
Expand All @@ -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"
Expand Down
42 changes: 12 additions & 30 deletions examples/src/modelica_conference_2021.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Advanced Simulation of an FMU\n",
"# Example from the Modelica Conference 2021\n",
"Tutorial by Johannes Stoljar, Tobias Thummerer\n",
"\n",
"This example was updated over time to keep track with developments and changes in *FMI.jl*.\n",
"\n",
"## License"
]
},
Expand All @@ -33,33 +35,13 @@
"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",
"In this example we would like to show that besides the simple simulation of an FMU there is also a more advanced version of the simulation. The advantage of the more advanced variant is that there are more possibilities to intervene in the simulation to make changes. After the FMU has been simulated, the simulation results are displayed in a graph. The used model 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/modelica_conference_2021.ipynb) there is also a [Julia file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/modelica_conference_2021.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/modelica_conference_2021.md) corresponding to the notebook. \n",
"\n",
"\n",
"## Getting started\n",
"\n",
"### Installation prerequisites\n",
"\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 Plots via | add Plots | |"
"Besides, this [Jupyter Notebook](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/modelica_conference_2021.ipynb) there is also a [Julia file](https://github.com/thummeto/FMI.jl/blob/examples/examples/src/modelica_conference_2021.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/modelica_conference_2021.md) corresponding to the notebook. "
]
},
{
Expand Down Expand Up @@ -143,10 +125,10 @@
"outputs": [],
"source": [
"# we use an FMU from the FMIZoo.jl\n",
"pathToFMU = get_model_filename(\"SpringFrictionPendulum1D\", \"Dymola\", \"2022x\")\n",
"pathToFMU = get_model_filename()\n",
"\n",
"myFMU = fmiLoad(pathToFMU)\n",
"fmiInfo(myFMU)"
"fmu = fmiLoad(\"SpringFrictionPendulum1D\", \"Dymola\", \"2022x\")\n",
"fmiInfo(fmu)"
]
},
{
Expand All @@ -170,7 +152,7 @@
},
"outputs": [],
"source": [
"simData = fmiSimulate(myFMU, (tStart, tStop); recordValues=[\"mass.s\"], saveat=tSave)\n",
"simData = fmiSimulate(fmu, (tStart, tStop); recordValues=[\"mass.s\"], saveat=tSave)\n",
"fmiPlot(simData)"
]
},
Expand All @@ -194,7 +176,7 @@
},
"outputs": [],
"source": [
"fmiUnload(myFMU)"
"fmiUnload(fmu)"
]
},
{
Expand All @@ -219,7 +201,7 @@
},
"outputs": [],
"source": [
"myFMU = fmiLoad(pathToFMU);"
"fmu = fmiLoad(pathToFMU);"
]
},
{
Expand All @@ -242,7 +224,7 @@
},
"outputs": [],
"source": [
"instanceFMU = fmiInstantiate!(myFMU)"
"instanceFMU = fmiInstantiate!(fmu)"
]
},
{
Expand Down Expand Up @@ -323,7 +305,7 @@
"source": [
"fmiTerminate(instanceFMU)\n",
"fmiFreeInstance!(instanceFMU)\n",
"fmiUnload(myFMU)"
"fmiUnload(fmu)"
]
},
{
Expand Down
Loading

0 comments on commit ce45ad9

Please sign in to comment.