diff --git a/docs/user/digital-twins/create.md b/docs/user/digital-twins/create.md index 119e26da1..2cc745296 100644 --- a/docs/user/digital-twins/create.md +++ b/docs/user/digital-twins/create.md @@ -41,15 +41,12 @@ or desktop. have distinct digital twin assets. You are likely to have one directory of everything in which you run your digital twin. In such a case we recommend that you upload this monolithic digital twin into - **digital twin/your_digital_twin_name** directory. + **digital_twin/your_digital_twin_name** directory. ## Example The [Examples](https://github.com/INTO-CPS-Association/DTaaS-examples) repository contains a co-simulation setup for mass spring damper. -The complete details on this example are available on -[github](https://github.com/INTO-CPS-Association/example-mass_spring_damper). - This example illustrates the potential of using co-simulation for digital twins. @@ -62,7 +59,7 @@ workspace/ input/ output/ - digital twins/ + digital_twins/ mass-spring-damper/ cosim.json time.json @@ -81,7 +78,6 @@ workspace/ MassSpringDamper2.fmu tools/ - common/ data/ functions/ @@ -132,21 +128,13 @@ The [lifecycle page](lifecycle.md) provides more explanation on these programs. You are now connected to the Linux Desktop of your workspace. 1. Open a Terminal (black rectangular icon in the top left region of your tab) and type the following commands. -1. Download the - [example files](https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip) - - ```sh - wget https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip - unzip main.zip - ``` +1. Download the example files by following the instructions given on + [examples overview](../examples/index.md). -1. Open a file browser and copy the files from this uncompressed folder - into your workspace folder (`/workspace`). Make sure that the file placement - matches the one given above. 1. Go to the digital twin directory and run ```sh - cd /workspace/digital twins/mass-spring-damper + cd /workspace/examples/digital_twins/mass-spring-damper lifecycle/execute ``` diff --git a/docs/user/digital-twins/lifecycle.md b/docs/user/digital-twins/lifecycle.md index 45c05b17c..9b70fb41d 100644 --- a/docs/user/digital-twins/lifecycle.md +++ b/docs/user/digital-twins/lifecycle.md @@ -56,7 +56,7 @@ It is recommended to have the following structure: ```text workspace/ - digital twins/ + digital_twins/ digital-twin-1/ lifecycle/ analyze @@ -73,7 +73,7 @@ to a live digital twin. ## Examples -Here are the programs / scripts to manage three phases in +Here are the example programs / scripts to manage three phases in the lifecycle of **mass-spring-damper DT**. ```bash title="lifecycle/execute" diff --git a/docs/user/examples/examples.drawio b/docs/user/examples/examples.drawio index a7c745341..06e57a711 100755 --- a/docs/user/examples/examples.drawio +++ b/docs/user/examples/examples.drawio @@ -1,14 +1,14 @@ - + - + - + - - + + @@ -43,9 +43,225 @@ - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 64b603316..71462cf8a 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -1,10 +1,7 @@ # DTaaS Examples There are some example digital twins created for the DTaaS software. -These examples are hosted in a dedicated -[DTaaS examples github repository](https://github.com/INTO-CPS-Association/DTaaS-examples). - -Use the examples and follow the steps given in the **Examples** section to experience +Use these examples and follow the steps given in the **Examples** section to experience features of the DTaaS software platform and understand best practices for managing digital twins within the platform. @@ -30,3 +27,7 @@ The digital twins provided in examples vary in their complexity. It is best to use the examples in the following order. 1. [Mass Spring Damper](./mass-spring-damper/README.md) +1. [Water Tank Fault Injection](./water_tank_FI/README.md) +1. [Water Tank Model Swap](./water_tank_swap/README.md) + +:material-download: [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples) diff --git a/docs/user/examples/mass-spring-damper/README.md b/docs/user/examples/mass-spring-damper/README.md index b5b2fb4d6..f9e2290eb 100644 --- a/docs/user/examples/mass-spring-damper/README.md +++ b/docs/user/examples/mass-spring-damper/README.md @@ -2,11 +2,8 @@ ## Overview -The mass spring damper study comprises two mass spring dampers -and demonstrates how the sucessive substitution technique can -be used to ensure that a co-simulation is stable. More information -about successive substitution and other co-simulation stabilization -techniques, please see [this paper](https://arxiv.org/pdf/1702.00686v1). +The mass spring damper digital twin (DT) comprises two mass spring dampers +and demonstrates how a co-simulation based DT can be used within DTaaS. ## Example Diagram @@ -33,8 +30,8 @@ This example uses two models and one tool. The specific assets used are: | | MassSpringDamper2.fmu | Private | Yes | | Tool | maestro-2.3.0-jar-with-dependencies.jar | Common | Yes | -This is a co-simulation based digital twin. The `co-sim.json` and `time.json` -are two configuration files used for executing the digital twin. +The `co-sim.json` and `time.json` +are two DT configuration files used for executing the digital twin. ## Lifecycle Phases @@ -52,7 +49,8 @@ To run the example, change your present directory. cd workspace/examples/digital_twins/mass-spring-damper ``` -If required, change the permission of files you need to execute, for example: +If required, change the execute permission of lifecycle scripts +you need to execute, for example: ```bash chmod +x lifecycle/create @@ -62,20 +60,46 @@ Now, run the following scripts: ### Create +Installs Open Java Development Kit 17 in the workspace. + ```bash lifecycle/create ``` ### Execute +Run the co-simulation. Generate the co-simulation output.csv file +at `data/mass-spring-damper/output/output.csv`. + +There are also debug and maestro log files stored in +`data/mass-spring-damper/output` directory. + ```bash lifecycle/execute ``` -## Examine the results +#### Examine the results The results can be found in the _workspace/examples/data/mass-spring-damper/output directory_. You can also view run logs in the _workspace/examples/digital_twins/mass-spring-damper_. + +### Terminate phase + +Terminate to clean up the debug files and co-simulation output files. + +```bash +lifecycle/terminate +``` + +## References + +More information about co-simulation techniques and mass spring damper +case study are available in: + +```txt +Gomes, Cláudio, et al. "Co-simulation: State of the art." +arXiv preprint arXiv:1702.00686 (2017). +``` 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..73ded5492 --- /dev/null +++ b/docs/user/examples/water_tank_FI/README.md @@ -0,0 +1,120 @@ +# Water Tank Fault Injection + +## Overview + +This example shows a fault injection (FI) enabled digital twin (DT). +A live DT is subjected to simulated faults received from the environment. +The simulated faults is specified as part of DT configuration and can be +changed for new instances of DTs. + +In this co-simulation based DT, a watertank case-study is used; co-simulation +consists of a tank and controller. The goal of which is to keep +the level of water in the tank between ```Level-1``` and ```Level-2```. +The faults are injected into output of the water tank +controller (**Watertankcontroller-c.fmu**) +from 12 to 20 time units, such that +the tank output is closed for a period of time, leading to the water level +increasing in the tank beyond the desired level (```Level-2```). + +## 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 | + +The `multimodelFI.json` and `simulation-config.json` +are two DT configuration files used for executing the digital twin. + +:fontawesome-solid-circle-info: The faults are defined in **wt_fault.xml**. + +## 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 execute permission of lifecycle scripts +you need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +Now, run the following scripts: + +### Create + +Installs Open Java Development Kit 17 and pip dependencies. +The pandas and matplotlib are the pip dependencies installated. + +```bash +lifecycle/create +``` + +### Execute + +Run the co-simulation. Generates the co-simulation output.csv file +at `/workspace/examples/data/water_tank_FI/output`. + +```bash +lifecycle/execute +``` + +### Analyze phase + +Process the output of co-simulation to produce a plot at: +`/workspace/examples/data/water_tank_FI/output/plots/`. + +```bash +lifecycle/analyze +``` + +#### 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_. + +### Terminate phase + +Clean up the temporary files and delete output plot + +```bash +lifecycle/terminate +``` + +## References + +More details on this case-study can be found in the paper: + +```txt +M. Frasheri, C. Thule, H. D. Macedo, K. Lausdahl, P. G. Larsen and +L. Esterle, "Fault Injecting Co-simulations for Safety," +2021 5th International Conference on System Reliability and Safety (ICSRS), +Palermo, Italy, 2021. +``` 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..863899f22 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..363a5ab8b 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..494d8a02e --- /dev/null +++ b/docs/user/examples/water_tank_swap/README.md @@ -0,0 +1,142 @@ +# Water Tank Model Swap + +## Overview + +This example shows multi-stage execution and dynamic reconfiguration +of a digital twin (DT). Two features of DTs are demonstrated here: + +* Fault injection into live DT +* Dynamic auto-reconfiguration of live DT + +The co-simulation methodology is used to construct this DT. + +## 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 | No | +| | Leak_controller.fmu | Private | No | +| Tool | maestro-2.3.0-jar-with-dependencies.jar | Common | Yes | + +This DT has many configuration files. The DT is executed in two stages. +There exist separate DT configuration files for each stage. +The following table shows the configuration files and their purpose. + +| Configuration file name | Execution Stage | Purpose | +|:---|:---|:---| +| mm1. json | stage-1 | DT configuration | +| wt_fault.xml, FaultInject.mabl | stage-1 | faults injected into DT during stage-1 | +| mm2.json | stage-2 | DT configuration | +| simulation-config.json | Both stages | Configuration for specifying DT execution time and output logs | + +## 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 | +| Analyze | Process the co-simulation output and produce plots | +| Clean | Clears run logs, outputs and plots | + +## 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 + +Installs Open Java Development Kit 17 and pip dependencies. +The matplotlib pip package is also installated. + +```bash +lifecycle/create +``` + +### Execute + +This DT has two-stage execution. In the first-stage, a co-simulation is +executed. The Watertankcontroller-c.fmu and Singlewatertank-20sim.fmu +models are used to execute the DT. +During this stage, faults are injected into one of the models +(Watertankcontroller-c.fmu) and the system performance is checked. + +In the second-stage, another co-simulation is run in which three FMUs +are used. The FMUs used are: watertankcontroller, singlewatertank-20sim, +and leak_detector. There is an in-built monitor in the Maestro tool. +This monitor is enabled during the stage and a swap condition is set +at the beginning of the second-stage. +When the swap condition is satisfied, the Maestro swaps out +Watertankcontroller-c.fmu model and swaps in Leakcontroller.fmu model. +This swapping of FMU models demonstrates the dynamic reconfiguration +of a DT. + +The end of execution phase generates the co-simulation output.csv file +at `/workspace/examples/data/water_tank_swap/output`. + +```bash +lifecycle/execute +``` + +### Analyze phase + +Process the output of co-simulation to produce a plot at: +`/workspace/examples/data/water_tank_FI/output/plots/`. + +```bash +lifecycle/analyze +``` + +#### 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_. + +### Terminate phase + +Clean up the temporary files and delete output plot + +```bash +lifecycle/terminate +``` + +## References + +The runtime model (FMU) swap mechanism demonstrated by the experiment +is detailed in the paper: + +```txt +Ejersbo, Henrik, et al. "fmiSwap: Run-time Swapping of Models for +Co-simulation and Digital Twins." arXiv preprint arXiv:2304.07328 (2023). +``` + +The runtime reconfiguration of co-simulation by modifying the Functional +Mockup Units (FMUs) used is further detailed in the paper: + +```txt +Ejersbo, Henrik, et al. "Dynamic Runtime Integration of +New Models in Digital Twins." 2023 IEEE/ACM 18th Symposium on +Software Engineering for Adaptive and Self-Managing Systems +(SEAMS). IEEE, 2023. +``` 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..10e46fad2 Binary files /dev/null and b/docs/user/examples/water_tank_swap/dt-structure.png differ diff --git a/docs/user/servers/lib/assets.md b/docs/user/servers/lib/assets.md index 6354f84a6..bbf38a137 100644 --- a/docs/user/servers/lib/assets.md +++ b/docs/user/servers/lib/assets.md @@ -82,14 +82,14 @@ workspace/ data2/ (ex: turbine) README.md (remote source; no local file) ... - digital twins/ - digital twin-1/ (ex: incubator) + digital_twins/ + digital_twin-1/ (ex: incubator) code and config README.md (usage instructions) - digital twin-2/ (ex: mass spring damper) + digital_twin-2/ (ex: mass spring damper) code and config README.md (usage instructions) - digital twin-3/ (ex: model swap) + digital_twin-3/ (ex: model swap) code and config README.md (usage instructions) ... diff --git a/mkdocs-github.yml b/mkdocs-github.yml index 59a39f365..23f303789 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 Model 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 069c535aa..53cb2ceb9 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 Model Swap: user/examples/water_tank_swap/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: