diff --git a/docs/user/examples/examples.drawio b/docs/user/examples/examples.drawio index a7c745341..20565303e 100755 --- a/docs/user/examples/examples.drawio +++ b/docs/user/examples/examples.drawio @@ -1,13 +1,13 @@ - + - + - + @@ -43,9 +43,162 @@ - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/examples/water_tank_FI/README.md b/docs/user/examples/water_tank_FI/README.md new file mode 100644 index 000000000..f3673931f --- /dev/null +++ b/docs/user/examples/water_tank_FI/README.md @@ -0,0 +1,80 @@ +# Water Tank Fault Injection + +## Overview + +The co-simulation is composed of a water-tank, +and a controller, which aims to maintain the level +in the water-tank between ```1``` and ```2```. +More details on this case-study can be found +[here](https://github.com/INTO-CPS-Association/example-single_watertank). + +To run an experiment with fault-injection, +we inject a fault in the input of the tank +(control signal from controller to open or close), +such that between time 12 and 20, this signal is +always closed, irrespective of the actual level +in the tank. + +## Example Diagram + +![Water Tank System](watertank.png) + +## Example Structure + +![Water Tank Structure](dt_structure.png) + +## Configuration of assets + +This example uses two models and one tool. +The specific assets used are: + +| Asset Type | Names of Assets | Visibility | Reuse in Other Examples | +|:---|:---|:---|:---| +| Models | watertankcontroller-c.fmu | Private | Yes | +| | singlewatertank-20sim.fmu | Private | Yes | +| Tool | maestro-2.3.0-jar-with-dependencies.jar | Common | Yes | + +## Lifecycle Phases + +| Lifecycle Phase | Completed Tasks | +| -------- | ------- | +| Create | Installs Java Development Kit for Maestro tool | +| Execute | Produces and stores output in data/water_tank_FI/output directory| +| Clean | Clears run logs and outputs | + +## Run the example + +To run the example, change your present directory. + +```bash +cd workspace/examples/digital_twins/water_tank_FI +``` + +If required, change the permission of files you +need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +Now, run the following scripts: + +### Create + +```bash +lifecycle/create +``` + +### Execute + +```bash +lifecycle/execute +``` + +## Examine the results + +The results can be found in the +_workspace/examples/data/water_tank_FI/output directory_. + +You can also view run logs in the +_workspace/examples/digital_twins/water_tank_FI_. \ No newline at end of file diff --git a/docs/user/examples/water_tank_FI/dt_structure.png b/docs/user/examples/water_tank_FI/dt_structure.png new file mode 100644 index 000000000..ba6dae023 Binary files /dev/null and b/docs/user/examples/water_tank_FI/dt_structure.png differ diff --git a/docs/user/examples/water_tank_FI/watertank.png b/docs/user/examples/water_tank_FI/watertank.png new file mode 100644 index 000000000..15dcd01cd Binary files /dev/null and b/docs/user/examples/water_tank_FI/watertank.png differ diff --git a/docs/user/examples/water_tank_swap/README.md b/docs/user/examples/water_tank_swap/README.md new file mode 100644 index 000000000..ae3c355ad --- /dev/null +++ b/docs/user/examples/water_tank_swap/README.md @@ -0,0 +1,84 @@ +# Water Tank Swap + +## Overview + +This example is a water-tank model swap experiment for DTaaS. +The experiment uses the Maestro co-orchestration engine for +FMI-based co-simulation with the Model Swap feature including +a FaultInject extension. This demonstrates a Docker-less +version of the experiment at +https://github.com/lausdahl/fmiSwap +for use on the DTaaS platform. + +The model swap mechanism demonstrated by +the experiment is detailed in the paper "Dynamic Runtime +Integration of New Models in Digital Twins" +[H. Ejersbo, K. Lausdahl, M. Frasheri, L. Esterle] +presented at the +[SEAMS 2023 conference](https://conf.researchr.org/home/seams-2023). +The water-tank experiment is further detailed here: +[Ejersbo, H., Lausdahl, K., Frasheri, M., & Esterle, L. (2023). fmiSwap: Run-time Swapping of Models for Co-simulation and Digital Twins. arXiv preprint arXiv:2304.07328.](https://arxiv.org/abs/2304.07328). + +## Example Diagram + +![FMI Swap Diagram](fmi_swap.png) + +## Example Structure + +![FMI Swap Structure](dt-structure.png) + +## Configuration of assets + +This example uses four models and one tool. The specific assets used are: + +| Asset Type | Names of Assets | Visibility | Reuse in Other Examples | +|:---|:---|:---|:---| +| Models | watertankcontroller-c.fmu | Private | Yes | +| | singlewatertank-20sim.fmu | Private | Yes | +| | leak_detector.fmu | Private | Yes | +| | leak_controller.fmu | Private | Yes | +| Tool | maestro-2.3.0-jar-with-dependencies.jar | Common | Yes | + +## Lifecycle Phases + +| Lifecycle Phase | Completed Tasks | +| -------- | ------- | +| Create | Installs Java Development Kit for Maestro tool | +| Execute | Produces and stores output in data/water_tank_swap/output directory| +| Clean | Clears run logs and outputs | + +## Run the example + +To run the example, change your present directory. + +```bash +cd workspace/examples/digital_twins/water_tank_swap +``` + +If required, change the permission of files you need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +Now, run the following scripts: + +### Create + +```bash +lifecycle/create +``` + +### Execute + +```bash +lifecycle/execute +``` + +## Examine the results + +The results can be found in the +_workspace/examples/data/water_tank_swap/output directory_. + +You can also view run logs in the +_workspace/examples/digital_twins/water_tank_swap_. diff --git a/docs/user/examples/water_tank_swap/dt_structure.png b/docs/user/examples/water_tank_swap/dt_structure.png new file mode 100644 index 000000000..2ecd1ebb4 Binary files /dev/null and b/docs/user/examples/water_tank_swap/dt_structure.png differ diff --git a/docs/user/examples/water_tank_swap/fmi_swap.png b/docs/user/examples/water_tank_swap/fmi_swap.png new file mode 100644 index 000000000..d4fba0914 Binary files /dev/null and b/docs/user/examples/water_tank_swap/fmi_swap.png differ diff --git a/mkdocs-github.yml b/mkdocs-github.yml index 481dc9e75..61c62a7ff 100644 --- a/mkdocs-github.yml +++ b/mkdocs-github.yml @@ -43,6 +43,8 @@ nav: - Examples: - Overview: user/examples/index.md - Mass Spring Damper: user/examples/mass-spring-damper/README.md + - Water Tank Fault Injection: user/examples/water_tank_FI/README.md + - Water Tank Swap: user/examples/water_tank_swap/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/mkdocs.yml b/mkdocs.yml index 16ca86aca..162ed2e7f 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,8 @@ nav: - Examples: - Overview: user/examples/index.md - Mass Spring Damper: user/examples/mass-spring-damper/README.md + - Water Tank Fault Injection: user/examples/water_tank_FI/README.md + - Water Tank Swap: user/examples/water_tank_swap/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: