Updates documentation (#383)

  - Adds new three water tank example
  - Adds docs on localhost install
  - Updates docs on authentication demo

CITATION.cff

@@ -0,0 +1,35 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Talasila"
+  given-names: "Prasad"
+  orcid: "https://orcid.org/0000-0002-8973-2640"
+title: "Digital Twin as a Service"
+version: 0.3.0
+date-released: 2023-11-08
+url: "https://github.com/into-cps-association/DTaaS"
+preferred-citation:
+  type: article
+  authors:
+  - family-names: "Talasila"
+    given-names: "Prasad"
+    orcid: "https://orcid.org/0000-0002-8973-2640"
+  - family-names: "Gomes"
+    given-names: "Cláudio"
+    orcid: "https://orcid.org/0000-0000-0000-0000"
+  - family-names: "Mikkelsen"
+    given-names: "Peter Høgh"
+    orcid: "https://orcid.org/0000-0003-2321-758X"
+  - family-names: "Gil"
+    given-names: "Santiago"
+    orcid: "https://orcid.org/0000-0002-1789-531X"
+  - family-names: "Kamburjan"
+    given-names: "Eduard"
+    orcid: "https://orcid.org/0000-0002-0996-2543"
+  - family-names: "Larsen"
+    given-names: "Peter Gorm"
+    orcid: "https://orcid.org/0000-0002-4589-1500"
+  conference-paper: "The 2023 IEEE International Conference on Digital Twin"
+  month: 8
+  title: "Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users"
+  year: 2023

docs/user/examples/index.md

@@ -26,5 +26,6 @@ to use the examples in the following order.
 1. [Water Tank Fault Injection](./water_tank_FI/README.md)
 1. [Water Tank Model Swap](./water_tank_swap/README.md)
 1. [Desktop Robotti and RabbitMQ](./drobotti-rmqfmu/README.md)
+1. [Three Water Tanks with DT Manager Framework](./three-tank/README.md)
 
 :material-download: [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples)

docs/user/examples/three-tank/README.md

@@ -0,0 +1,153 @@
+# Three-Tank System Digital Twin
+
+## Overview
+
+The three-tank system is a simple case study allows us to represent a system
+that is composed of three individual components that are coupled in
+a cascade as follows: The first tank is connected to the input of
+the second tank, and the output of the second tank is connected to
+the input of the third tank.
+
+![Three-tank graphical representation](./three-tank.png)
+
+This example contains only the simulated components for
+demonstration purposes; therefore, there is no configuration for
+the connection with the physical system.
+
+The three-tank system case study is managed using the ```DTManager```,
+which is packed as a jar library in the tools, and run from a java main file.
+The ```DTManager``` uses Maestro as a slave for co-simulation,
+so it generates the output of the co-simulation.
+
+The main file can be changed according to the application scope, i.e.,
+the ```/workspace/examples/tools/three-tank/TankMain.java```
+can be manipulated to get a different result.
+
+The ```/workspace/examples/models/three-tank/``` folder contains
+the ```Linear.fmu``` file, which is a non-realistic model for a tank
+with input and output and the ```TankSystem.aasx``` file for
+the schema representation with Asset Administration Shell.
+The three instances use the same ```.fmu``` file and the same schema
+due to being of the same object class.
+The ```DTManager``` is in charge of reading the values from
+the co-simulation output.
+
+## Example Structure
+
+![Three-tank system architecture with DT Manager](./dt-structure.png)
+
+## Digital Twin Configuration
+
+This example uses two models, two tools, one data, and one script.
+The specific assets used are:
+
+| Asset Type | Names of Assets | Visibility | Reuse in Other Examples |
+|:---|:---|:---|:---|
+| Model | Linear.fmu | Private | No |
+|  | TankSystem.aasx | Private | No |
+| Tool | DTManager-0.0.1-Maestro.jar (wraps Maestro) | Common | Yes |
+|  | maestro-2.3.0-jar-with-dependencies.jar (used by DTManager) | Common | Yes |
+|  | TankMain.java (main script) | Private | No |
+| Data | outputs.csv | Private | No |
+
+This DT has multiple configuration files. The _coe.json_ and
+_multimodel.json_ are used by Maestro tool. The _tank1.conf_, _tank2.conf_
+and _tank3.conf_ are the config files for three different instances of
+one model (Linear.fmu).
+
+## Lifecycle Phases
+
+The lifecycles that are covered include:
+
+| Lifecycle Phase    | Completed Tasks |
+| --------- | ------- |
+| Create    | Installs Java Development Kit for Maestro tool                                                                    |
+| Execute   | The DT Manager executes the three-tank digital twin and produces output in ```data/three-tank/output``` directory |
+| Terminate | Terminating the background processes and cleaning up the output                                                   |
+
+## Run the example
+
+To run the example, change your present directory.
+
+```bash
+cd /workspace/examples/digital twins/three-tank
+```
+
+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 11 and pip dependencies.
+Also creates ```DTManager``` tool (DTManager-0.0.1-Maestro.jar) from source code.
+
+```bash
+lifecycle/create
+```
+
+### Execute
+
+Execute the three-tank digital twin using DTManager. DTManager in-turn runs
+the co-simulation using Maestro. Generates the co-simulation output.csv file
+at `/workspace/examples/data/three-tank/output`.
+
+```bash
+lifecycle/execute
+```
+
+### Terminate
+
+Stops the Maestro running in the background. Also stops any other
+jvm process started during **execute** phase.
+
+```bash
+lifecycle/terminate
+```
+
+### Clean
+
+Removes the output generated during execute phase.
+
+```bash
+lifecycle/terminate
+```
+
+## Examining the results
+
+Executing this Digital Twin will generate a co-simulation output,
+but the results can also be monitored from updating
+the```/workspace/examples/tools/three-tank/TankMain.java``` with
+a specific set of ```getAttributeValue``` commands, such as shown in
+the code.
+
+That main file enables the online execution of the Digital Twin and
+its internal components.
+
+The output of the co-simulation is generated to
+the ```/workspace/examples/data/three-tank/output``` folder.
+
+In the default example, the co-simulation is run for 10 seconds in
+steps of 0.5 seconds.
+This can be modified for a longer period and different step size.
+The output stored in ```outputs.csv``` contains the level, in/out flow,
+and leak values.
+
+No data from the physical twin are generated/used.
+
+## References
+
+More information about the DT Manager is available at:
+
+```txt
+D. Lehner, S. Gil, P. H. Mikkelsen, P. G. Larsen and M. Wimmer,
+"An Architectural Extension for Digital Twin Platforms to Leverage
+Behavioral Models," 2023 IEEE 19th International Conference on
+Automation Science and Engineering (CASE), Auckland, New Zealand,
+2023, pp. 1-8, doi: 10.1109/CASE56687.2023.10260417.
+```

mkdocs-github.yml

@@ -54,6 +54,7 @@ nav:
           - Water Tank Fault Injection: user/examples/water_tank_FI/README.md
           - Water Tank Model Swap: user/examples/water_tank_swap/README.md
           - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md
+          - Three Water Tanks: user/examples/three-tank/README.md
           - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples
   - FAQ: FAQ.md
   - Developer: 

mkdocs.yml

@@ -54,6 +54,7 @@ nav:
           - Water Tank Fault Injection: user/examples/water_tank_FI/README.md
           - Water Tank Model Swap: user/examples/water_tank_swap/README.md
           - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md
+          - Three Water Tanks: user/examples/three-tank/README.md
           - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples
   - FAQ: FAQ.md
   - Developer: 

script/docs.sh

@@ -50,4 +50,4 @@ mv site/index.html .
 rm -rf site
 
 git add .
-git commit -m "docs for ${COMMIT_HASH} commit"
+git commit --no-verify -m "docs for ${COMMIT_HASH} commit"