Adds examples documentation (INTO-CPS-Association#193 and INTO-CPS-As…

…sociation#212) - Adds documentation for Mass Spring Damper, Water Tank Fault Inject and Water Tank Model Swap examples - Adds new diagrams for each of the examples --------- Co-authored-by: Asti <[email protected]>
astitva1905 · Oct 23, 2023 · 3591b53 · 3591b53
1 parent 04b6e4e
commit 3591b53
Show file tree

Hide file tree

Showing 13 changed files with 537 additions and 42 deletions.
diff --git 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
@@ -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
diff --git 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
@@ -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
@@ -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
diff --git a/docs/user/examples/water_tank_FI/watertank.png b/docs/user/examples/water_tank_FI/watertank.png