Merge branch 'develop' into 'develop'

feat: add more documentation

See merge request !438

.gitlab-ci.yml

@@ -174,6 +174,10 @@ gcc_12_python:
       - pybuild/ # build in separate folder to avoid conflicts with c++ build
 
   before_script:
+    - export CC=gcc
+    - export CXX=g++
+    - $CXX --version
+    - $CC --version
     - export CCACHE_BASEDIR=$CI_PROJECT_DIR
     - export CCACHE_DIR=$CI_PROJECT_DIR/cache
 

docs/doxygen/DoxygenLayout.xml

@@ -10,12 +10,16 @@
         <tab type="user" url="@ref getting-started-with-docker" visible="yes" title="Getting Started with Docker" intro=""/>
         <tab type="user" url="@ref getting-started-not-using-docker" visible="yes" title="Getting Started Not Using Docker" intro=""/>
         <tab type="user" url="@ref build-and-run" visible="yes" title="Build and Run" intro=""/>
-        <tab type="user" url="@ref how-to-document-code" visible="yes" title="How To Document Code" intro=""/>
         <tab type="user" url="@ref debugging-with-vscode" visible="yes" title="Debugging with VSCode" intro=""/>
         <tab type="user" url="@ref unit-tests" visible="yes" title="Unit Tests" intro=""/>
         <tab type="user" url="@ref regression-tests" visible="yes" title="Regression Tests" intro=""/>
         <tab type="user" url="@ref performance-tests" visible="yes" title="Performance Tests" intro=""/>
+        <tab type="user" url="@ref how-to-document-code" visible="yes" title="How To Document Code" intro=""/>
+        <tab type="user" url="@ref review-merge-request" visible="yes" title="Review Merge Request" intro=""/>
         <tab type="user" url="@ref release" visible="yes" title="Release" intro=""/>
+        <tab type="user" url="@ref how-to-license" visible="yes" title="How to License" intro=""/>
+        <tab type="user" url="@ref docker-virtualisation" visible="yes" title="Virtualisation" intro=""/>
+        <tab type="user" url="@ref gitlab-ci" visible="yes" title="GitLab CI" intro=""/>
         <tab type="usergroup" title="Coding Guidelines" url="@ref coding-guidelines">
             <tab type="user" url="@ref layout" visible="yes" title="Layout" intro=""/>
             <tab type="user" url="@ref names" visible="yes" title="Names" intro=""/>

docs/pages/Docker-Virtualisation.md

+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder -->
+
+# Docker Virtualisation
+
+The development environment for VirtualFluids is based on Docker. Docker is a tool that allows you to run applications in containers. A container is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries, and settings.
+
+The description of the VirtualFluids Docker image can be found in the folder `Containers` in the root folder of the repository. The newest Docker image is based on the `ubuntu:22.04` image and contains all dependencies to run VirtualFluids. 
+
+Every user of VirtualFluids can use the Dockerfile to create a new Docker image. However, a prebuild Docker image is available in the Gitlab CI Docker Registry here: [https://git.rz.tu-bs.de/irmb/VirtualFluids/container_registry](https://git.rz.tu-bs.de/irmb/VirtualFluids/container_registry).
+
+The devcontainer for Visual Studio Code and most oft the GitLab-CI jobs are based on the prebuild Docker image.
+
+## Update the prebuild image
+To update the prebuild image one need to have at least Maintainer rights in the Gitlab project. Additionally, at this point in time it is only possible to push to the registry from our Linux Gitlab Runner!!
+
+First login to the Gitlab registry with the following command:
+```bash
+docker login git.rz.tu-bs.de:4567
+```
+To authenticate you need a personal access token. The token can be created in the Gitlab settings under `Access Tokens`. The token needs the `read_registry` and `write_registry` scope.
+
+A new image with the tag name `vf_base' can be created from the Containers folder with the following command:
+```bash
+docker build -t vf_base -f Ubuntu22_04.Dockerfile .
+```
+
+We recommend to use the `vf_base` tag name for the first prebuild image and to create two new tags for the new image. To push the tags afterwards, the URL of the registry needs to part of the tag. Additionally, the first tag should be contain new version and the second tag contain the suffix `latest`. All current versions can be found [here](https://git.rz.tu-bs.de/irmb/VirtualFluids/container_registry/116). The following commands can be used to create the new tags:
+```bash
+docker image tag vf_base git.rz.tu-bs.de:4567/irmb/virtualfluids/ubuntu22_04:latest
+docker image tag vf_base git.rz.tu-bs.de:4567/irmb/virtualfluids/ubuntu22_04:1.3
+```
+
+and to push the tags to the registry:
+```bash
+docker image push --all-tags git.rz.tu-bs.de:4567/irmb/virtualfluids/ubuntu22_04
+```
+
+Afterwards one can check if the image is available [here](https://git.rz.tu-bs.de/irmb/VirtualFluids/container_registry/116).
+Then the new image can be used in the Gitlab CI jobs and the devcontainer for Visual Studio Code.
\ No newline at end of file

docs/pages/Documentation.md

@@ -24,7 +24,15 @@ If Docker cannot be used, the dependecies for VirtualFluids can also be installe
 - <!-- DOXYGEN_MAKE_REF -->[Unit Tests in VirtualFluids](Unit-Tests.md)
 - <!-- DOXYGEN_MAKE_REF -->[Regression Tests](Regression-Tests.md)
 - <!-- DOXYGEN_MAKE_REF -->[Performance Tests](Performance-Tests.md)
+
+## Maintenance
+- <!-- DOXYGEN_MAKE_REF -->[Document Code](How-To-Document-Code.md)
+- <!-- DOXYGEN_MAKE_REF -->[Review Merge Request](Review-Merge-Request.md)
+- <!-- DOXYGEN_MAKE_REF -->[How to License](How-to-License.md)
 - <!-- DOXYGEN_MAKE_REF -->[Release](Release.md)
+- <!-- DOXYGEN_MAKE_REF -->[Docker-Virtualisation](Docker-Virtualisation.md)
+- <!-- DOXYGEN_MAKE_REF -->[Gitlab CI](Gitlab-CI.md)
+
 
 ## Guidelines
 

docs/pages/Gitlab-CI.md

+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder -->
+
+# Gitlab CI
+
+VirtualFluids is using Gitlab CI to automate the build, test and deployment process. The Gitlab CI is configured in the file `.gitlab-ci.yml` in the root folder of the repository. The configuration is based on the [Gitlab CI/CD Documentation](https://docs.gitlab.com/ee/ci/).
+
+Most Gitlab CI jobs are running whith each push to the repository. Additionally, some jobs are running on a schedule. The schedule is defined [here](https://git.rz.tu-bs.de/irmb/VirtualFluids/-/pipeline_schedules).
+
+Almost all jobs are based on the Docker image from the Gitlab CI Docker Registry.
+
+## Phoenix HPC Usage
+The institute uses a "Funktionsaccount" to run simulations from the CI-Pipeline on the Phoenix HPC cluster (for example the multi-gpu test).
+The CI job uses the [HPC-Rocket](https://github.com/SvenMarcus/hpc-rocket) to communicate with the Phoenix HPC cluster. In order to access the cluster, some environments-variables, like the hostname, username and ssh-key needs to be provided. The environment-variables are stored in the [Gitlab CI/CD settings](https://git.rz.tu-bs.de/irmb/VirtualFluids/-/settings/ci_cd) of the project.
+
+## Gitlab Runner
+
+There a currently three machines, where the ci jobs are running. The machines are called `gitlab-runner01`, `gitlab-runner02` and `gitlab-runner03`. The machines are running on the Gitlab Runner software.
+The computers are located in the old VR-Lab in the cellar of the TU Braunschweig.
+The runner are registered in the Gitlab project and are using the tags `linux`, `win` and `gpu`. The tags are used in the `.gitlab-ci.yml` file to define on which runner the job should run.
+All Gitlab runner are shared to all Maintainer in this sub-project: https://git.rz.tu-bs.de/irmb/shared/runner/-/settings/ci_cd.
+With this they can use the runner in their own projects. They need to be enabled for every new project. (e.g. virtualfluids project: https://git.rz.tu-bs.de/irmb/VirtualFluids/-/settings/ci_cd).
+
+The Gitlab-Runner are registered to the GITZ Gitlab and can be found in the CI/CD - Runner part of the project settings.
+
+
+### gitlab-runner01 and gitlab-runner02 (Linux)
+- IP: 134.169.81.206/207
+- Linux Version: Ubuntu 22.04
+- Docker based
+- gitlab runner is installed and updated via ubuntu package manager.
+
+
+
+#### Update / Install NVIDIA Driver:
+Nvidia Driver needs to be reinstalled after every kernel update of the OS.
+
+0. (Optional!) Download a newer driver. Only on demand, for example a new cuda version requires a new driver. Its needs to be checked if the new driver is compatible with the GPU. With a new driver the installation script might needs to be updated - so start the installation with a new driver manually first.
+    - get newest driver link from here: https://www.nvidia.com/de-de/drivers/
+    - copy the download Link. e.g. https://us.download.nvidia.com/XFree86/Linux-x86_64/550.90.07/NVIDIA-Linux-x86_64-550.90.07.run
+    - login to runner via ssh
+    ```
+    cd nvidia-driver
+    wget https://us.download.nvidia.com/XFree86/Linux-x86_64/550.90.07/NVIDIA-Linux-x86_64-550.90.07.run
+    ```
+    - change permission
+    ```
+    sudo chmod +x <driver-file-name>
+    ```
+
+1. install driver ( e.g. 550.90.07.):
+Pass the driver file name as argument to the script (Attention: with a new driver version the installation script might needs to be updated).
+```
+sudo ./install_nvidia_driver.sh NVIDIA-Linux-x86_64-550.90.07.run
+```
+
+Done!
+
+2. check gpu access
+```
+runner@gitlab-runner02:~$ nvidia-smi
+Fri Jun 14 08:44:18 2024       
++-----------------------------------------------------------------------------------------+
+| NVIDIA-SMI 550.90.07              Driver Version: 550.90.07      CUDA Version: 12.4     |
+|-----------------------------------------+------------------------+----------------------+
+| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
+| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
+|                                         |                        |               MIG M. |
+|=========================================+========================+======================|
+|   0  NVIDIA GeForce RTX 2070 ...    Off |   00000000:01:00.0 Off |                  N/A |
+| 15%   60C    P0             N/A /  215W |       1MiB /   8192MiB |      0%      Default |
+|                                         |                        |                  N/A |
++-----------------------------------------+------------------------+----------------------+
+                                                                                         
++-----------------------------------------------------------------------------------------+
+| Processes:                                                                              |
+|  GPU   GI   CI        PID   Type   Process name                              GPU Memory |
+|        ID   ID                                                               Usage      |
+|=========================================================================================|
+|  No running processes found                                                             |
++-----------------------------------------------------------------------------------------+
+```
+
+#### Clean old docker images
+Regularly clean old dangling docker images to free up disk space.
+```
+docker system prune -a
+```
+
+### Runner3 (Windows)
+IP: 134.169.81.208
+Windows 11
+Tags: win, gpu
+Shell based
+
+Windows Gitlab Runner:
+Manual: https://docs.gitlab.com/runner/install/windows.html
+
+Updates:
+1. OS
+2. Visual Studio Installer
+3. Download and install new cmake
+4. cuda version
+
+Installed Gitlab Runner here:
+C:\GitLab-Runner
\ No newline at end of file

docs/pages/How-To-Document-Code.md

@@ -4,7 +4,7 @@
 # How To Document Code
 
 To build sustainable research software, it is mandatory to document code. 
-Even if it turns out that some developments are not continued, documentation is important to help future scientists to learn from the own experiences.  
+Even if it turns out that some developments are not continued, documentation is important to help future scientists to learn from the own experiences.
 
 The documentation of the source code takes place…
 
@@ -17,4 +17,27 @@ The documentation of the source code takes place…
    - In most of the cases comment should describe ***why*** something was implemented and not ***how***.
    - if available add formulas, references to scripts, paper, and all information you got linked to the implemented code
 
-- adding <!-- DOXYGEN_MAKE_REF -->[unit](Unit-Tests.md) and <!-- DOXYGEN_MAKE_DOXYGEN_MAKE_REFABSOLUTE -->[regression](Regression-Tests.md) tests.
+- adding <!-- DOXYGEN_MAKE_REF -->[unit](Unit-Tests.md) and <!-- DOXYGEN_MAKE_REF -->[regression](Regression-Tests.md) tests.
+
+
+## Doxygen
+The [Doxygen](https://www.doxygen.nl/) documentation is automatically generated and deployed using a Gitlab-CI job. The pages are hosted on Gitlab page here: [VirtualFluids Documentation](https://irmb.gitlab-pages.rz.tu-bs.de/VirtualFluids/index.html).
+The main configuration of the Doxygen Pages is done in the file `docs/doxygen/Doxyfile`.
+For styling the pages are based on the [doxygen-awesome-css](https://jothepro.github.io/doxygen-awesome-css/) theme. 
+
+The Documentation is build from two main parts:
+### The source code
+
+This part is sorted into groups using different special comments in the source code. For example the the file `src/lbm/collision/CollisionParameter.h` is sorted into the group `lbm` and the subgroup `collision`. This is done by the following comment in the source code:
+```
+//! \addtogroup collision
+//! \ingroup lbm
+//! \{
+
+    // ... functions and variables and everything else ...
+
+//! \}
+ ```
+
+### The markdown files in the docs/pages folder
+The markdown files are automatically translated into html files. To add the files also in the sidebar, the file `docs/doxygen/DoxygenLayout.xml` needs to be updated.
\ No newline at end of file

docs/pages/How-to-License.md

+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder -->
+
+#  How to License
+
+VirtualFluids is licensed under the [GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0.html) license. The main License `COPYING.txt` file can be found in the root folder of the repository.
+
+Additionally, the VirtualFluids project uses third-party libraries and tools that are licensed under different licenses. The licenses of these third-party libraries and tools can be found in the `LICENSES` folder in the root folder of the repository.
+
+To ensure, that every file of the project is licensed the SPDX-License-Identifier is added to every file. The SPDX-License-Identifier is a short identifier that can be found in the header of every file. Additionally, a Gitlab-CI job is using a tool called [REUSE](https://reuse.software/) to check if every file has a valid SPDX-License-Identifier.
\ No newline at end of file

docs/pages/Review-Merge-Request.md

+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder -->
+# Review Merge Request
+
+This document describes the process of reviewing a merge request in VirtualFluids. The review process is an important part of the development process. The review process ensures that the code changes are correct, documented, and tested. We follow a 4-eye principle, which means that every merge request needs to be reviewed by at least one other developer. Thereby the knowledge of the code is spread among the developers and the code quality is improved.
+
+## Review Process
+
+The reviewer is responsible for checking the code changes in the merge request. Thereby it is important to keep in mind that the review process is not only about finding bugs but also about improving the code quality. The review-process should be seen as a learning process for both the author and the reviewer. The reviewer should provide constructive feedback to the author. While we have some recommendations for the review process, the review process is not a strict process. The reviewer can adapt the process to the specific merge request.
+
+## Recommendations for the Review Process
+ 
+- The code changes are correct and do not break the existing code
+- The code changes are documented in the source code (doxygen in-code)
+- The code changes are documented in the documentation (markdown pages)
+- The code changes are tested with unit tests (existing or new tests)
+- The code changes are tested with regression tests (existing or new tests)
+- The code changes fullfill our coding guidelines (see  <!-- DOXYGEN_MAKE_REF -->[Coding Guidelines](Coding-Guidelines.md))
+    - e.g. the variable names are meaningful and the code is readable in general