diff --git a/docs/doxygen/DoxygenLayout.xml b/docs/doxygen/DoxygenLayout.xml index ed18fe28ce4eba2b962d31058ef2f50cf119a69e..27ce7ce6ac34703c7823c62dd1a1bbdeb76f47a1 100644 --- a/docs/doxygen/DoxygenLayout.xml +++ b/docs/doxygen/DoxygenLayout.xml @@ -6,18 +6,18 @@ <!-- Navigation index tabs for HTML output --> <navindex> <tab type="mainpage" visible="yes" title=""/> - <tab type="usergroup" title="Documentation" url="@ref documentation"> - <tab type="user" url="@ref getting-start-with-docker" visible="yes" title="Getting Start with Docker" intro=""/> - <tab type="user" url="@ref getting-start-not-using-docker" visible="yes" title="Getting Start 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 release" visible="yes" title="Release" intro=""/> - <tab type="user" url="@ref coding-guidelines" visible="yes" title="Coding Guideline" intro=""/> - <tab type="user" url="@ref direction-scheme" visible="yes" title="Direction Scheme" intro=""/> - <tab type="user" url="@ref kernel-scheme" visible="yes" title="Kernel Scheme" intro=""/> + <tab type="usergroup" title="Documentation" url="@ref Documentation"> + <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 Release" visible="yes" title="Release" intro=""/> + <tab type="user" url="@ref Coding-Guidelines" visible="yes" title="Coding Guidelines" intro=""/> + <tab type="user" url="@ref Direction-Scheme" visible="yes" title="Direction Scheme" intro=""/> + <tab type="user" url="@ref Kernel-Scheme" visible="yes" title="Kernel Scheme" intro=""/> </tab> <!-- <tab type="pages" visible="yes" title="" intro=""/> --> <tab type="topics" visible="yes" title="Modules" intro=""/> diff --git a/docs/pages/Build-And-Run.md b/docs/pages/Build-and-Run.md similarity index 94% rename from docs/pages/Build-And-Run.md rename to docs/pages/Build-and-Run.md index 1bf70f6c914d9771f3c3654de877a276e1b1686a..e4c623acda14a0fe6257d2bdc7f2523185e70759 100644 --- a/docs/pages/Build-And-Run.md +++ b/docs/pages/Build-and-Run.md @@ -6,7 +6,8 @@ This guide describes how to start using and developing VirtualFluids in the terminal. Alternativly you can use Visual Studio to build an run it. ## Build -The necessary packages needs to be installed. Either we are working in a <!-- DOXYGEN_MAKE_REF -->[Docker container](getting-start-with-docker.md) or have installed the packages <!-- DOXYGEN_MAKE_REF -->[manually](getting-start-manually). + +The necessary packages needs to be installed. Either we are working in a <!-- DOXYGEN_MAKE_REF -->[Docker container](Getting-Started-with-Docker.md) or have installed the packages <!-- DOXYGEN_MAKE_REF -->[manually](Getting-Started-Not-Using-Docker.md). We can check if the necessary packages are installed by running the following commands in the terminal: ``` git --version @@ -48,6 +49,7 @@ Additionaly, the following options can be passed to cmake: - -DVF_ENABLE_PYTHON_BINDINGS=ON: enable python bindings (included in all_make and all_msvc) ## Run the examples + VirtualFluids project comes with a list of examples. The source code of the examples are located in the folder `./apps/`. Most of the apps requires a configuration file, which lays next to source code example. For instance a simulation on the GPU containing a flow around a sphere can be started with the following command: diff --git a/docs/pages/debugging-with-vscode.md b/docs/pages/Debugging-with-Vscode.md similarity index 100% rename from docs/pages/debugging-with-vscode.md rename to docs/pages/Debugging-with-Vscode.md diff --git a/docs/pages/Direction-Scheme.md b/docs/pages/Direction-Scheme.md index fe8686c100f5917e10d6a19076e163bb93ee27ae..77429656d941bc9fc09e1b8bd8fd38ae8d4d6146 100644 --- a/docs/pages/Direction-Scheme.md +++ b/docs/pages/Direction-Scheme.md @@ -35,6 +35,7 @@ ## GPU PointerChasing + | Direction | Index | P_MMM | P_P00 | P_0P0 | P_00P | |--------------------|-------|-------|-------|-------|-------| | 000 | 0 | 0 | 0 | 0 | 0 | diff --git a/docs/pages/Documentation.md b/docs/pages/Documentation.md index c04c34f667c2f526b46cc7a7c27cfa49a3267694..9f427e2296bed289ce42d893aaacb733a9ae0d0b 100644 --- a/docs/pages/Documentation.md +++ b/docs/pages/Documentation.md @@ -2,27 +2,31 @@ <!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder --> # Documentation + Welcome to the VirtualFluids Documentation! ## Getting Started + We recommend using VirtualFludis with Docker -- <!-- DOXYGEN_MAKE_REF -->[Getting Started with Docker](getting-start-with-docker.md) +- <!-- DOXYGEN_MAKE_REF -->[Getting Started with Docker](Getting-Started-with-Docker.md) If Docker cannot be used, the dependecies for VirtualFluids can also be installed manually directly on your machine: -- <!-- DOXYGEN_MAKE_REF -->[Installing the Dependencies manually](getting-start-not-using-docker.md) +- <!-- DOXYGEN_MAKE_REF -->[Installing the Dependencies manually](Getting-Started-Not-Using-Docker.md) After the installation VirtualFluids can be compiled and executed: -- <!-- DOXYGEN_MAKE_REF -->[Compiling and Running the examples](build-and-run.md) +- <!-- DOXYGEN_MAKE_REF -->[Compiling and Running the examples](Build-and-Run.md) ## Development -- <!-- DOXYGEN_MAKE_REF -->[Contributing](../../contributing.md) -- <!-- DOXYGEN_MAKE_REF -->[Document Code](how-to-document-code.md) -- <!-- DOXYGEN_MAKE_REF -->[Debugging in VS Code](debugging-with-vscode.md) -- <!-- DOXYGEN_MAKE_REF -->[Unit Tests in VirtualFluids](unit-tests.md) -- <!-- DOXYGEN_MAKE_REF -->[Regression Tests](regression-tests.md) -- <!-- DOXYGEN_MAKE_REF -->[Release](release.md) + +- <!-- DOXYGEN_MAKE_REF -->[Contributing](../../Contributing.md) +- <!-- DOXYGEN_MAKE_REF -->[Document Code](How-To-Document-Code.md) +- <!-- DOXYGEN_MAKE_REF -->[Debugging in VS Code](Debugging-with-Vscode.md) +- <!-- DOXYGEN_MAKE_REF -->[Unit Tests in VirtualFluids](Unit-Tests.md) +- <!-- DOXYGEN_MAKE_REF -->[Regression Tests](Regression-Tests.md) +- <!-- DOXYGEN_MAKE_REF -->[Release](Release.md) ## Guidelines -- <!-- DOXYGEN_MAKE_REF -->[Coding Guidelines](coding-guidelines.md) -- <!-- DOXYGEN_MAKE_REF -->[Direction Scheme](direction-scheme.md) -- <!-- DOXYGEN_MAKE_REF -->[Kernel Scheme](kernel-scheme.md) + +- <!-- DOXYGEN_MAKE_REF -->[Coding Guidelines](Coding-Guidelines.md) +- <!-- DOXYGEN_MAKE_REF -->[Direction Scheme](Direction-Scheme.md) +- <!-- DOXYGEN_MAKE_REF -->[Kernel Scheme](Kernel-Scheme.md) diff --git a/docs/pages/getting-start-not-using-docker.md b/docs/pages/Getting-Started-Not-Using-Docker.md similarity index 98% rename from docs/pages/getting-start-not-using-docker.md rename to docs/pages/Getting-Started-Not-Using-Docker.md index b84427f69af0896116ac296d5b5962c99291143d..4d82d6d46a8c3c768c1577778d51e6a0603df060 100644 --- a/docs/pages/getting-start-not-using-docker.md +++ b/docs/pages/Getting-Started-Not-Using-Docker.md @@ -1,7 +1,7 @@ <!-- SPDX-License-Identifier: GPL-3.0-or-later --> <!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder --> -# Getting Start not using Docker +# Getting Started Not Using Docker VirtualFluids is supported on Linux and Windows. We recommend using VirtualFludis with Docker. If, for whatever reason, Docker cannot be used, VirtualFluids can also be installed manually. The following packages are necessary for this: diff --git a/docs/pages/getting-start-with-docker.md b/docs/pages/Getting-Started-with-Docker.md similarity index 99% rename from docs/pages/getting-start-with-docker.md rename to docs/pages/Getting-Started-with-Docker.md index 28e5c911a7a5493a2215e9d6647c025395d91a21..200b24297b368f6ba9292199777273c48b29dbb4 100644 --- a/docs/pages/getting-start-with-docker.md +++ b/docs/pages/Getting-Started-with-Docker.md @@ -1,7 +1,7 @@ <!-- SPDX-License-Identifier: GPL-3.0-or-later --> <!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder --> -# Getting Start with Docker +# Getting Started with Docker This page describes how to start using and developing VirtualFluids. diff --git a/docs/pages/how-to-document-code.md b/docs/pages/How-To-Document-Code.md similarity index 86% rename from docs/pages/how-to-document-code.md rename to docs/pages/How-To-Document-Code.md index 528352cbea3dc07cd9869eae1775dd074fb4aac9..9fce94a3fee69a988ba7ad1222526b1198bf7d27 100644 --- a/docs/pages/how-to-document-code.md +++ b/docs/pages/How-To-Document-Code.md @@ -1,7 +1,7 @@ <!-- SPDX-License-Identifier: GPL-3.0-or-later --> <!-- SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder --> -# How to document code +# 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. @@ -17,4 +17,4 @@ 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_DOXYGEN_MAKE_REFABSOLUTE -->[regression](Regression-Tests.md) tests. diff --git a/docs/pages/Kernel-Scheme.md b/docs/pages/Kernel-Scheme.md index 9535fc51a0abe73037b507726073d22fbef6d03a..72e5db5f71e8a6c45835fd90e1a2b6131746d32c 100644 --- a/docs/pages/Kernel-Scheme.md +++ b/docs/pages/Kernel-Scheme.md @@ -11,7 +11,7 @@ five-part naming structure: - fourth field: model - fifth field (optional): Other -## first field - one letter: +## First field - one letter: - C Central Moments/ Cascade - K Cumulant @@ -19,13 +19,13 @@ five-part naming structure: - F Factorized - M MRT -## third field: +## Third field: - Incompressible - Compressible - Selective -## fourth field: +## Fourth field: - NavierStokes - AdvectionDiffusion diff --git a/docs/pages/regression-tests.md b/docs/pages/Regression-Tests.md similarity index 100% rename from docs/pages/regression-tests.md rename to docs/pages/Regression-Tests.md diff --git a/docs/pages/Release.md b/docs/pages/Release.md index 8b91c19e02550884eb3d0ac3695086d344c33938..a6d11a197c1fe7df01858f7f5ea77c5011034b3f 100644 --- a/docs/pages/Release.md +++ b/docs/pages/Release.md @@ -4,6 +4,7 @@ # Release ## Release Policy + MAJOR.MINOR.PATCH - Patch: Bugfixes, no new features - Minor: New features @@ -13,9 +14,11 @@ MAJOR.MINOR.PATCH Release of VirtulFluids can be done by the core developers of VirtualFluids. A Release requires the following steps: ## 0. Check Issues and Merge Requests + - [ ] Check if there are open issues or merge requests which are assigned to the current Release ## 1. Version Number and Authors + - [ ] Update the version number in the authors.cff - [ ] Update the version number in the CMakeLists.txt - [ ] Update the version number in the pyproject.toml @@ -26,15 +29,18 @@ Release of VirtulFluids can be done by the core developers of VirtualFluids. A R - people which are not involved in the current Release are listed in AUTHORS.md ## 2. Update the Changelog + - [ ] Update the Changelog.md ## 3. Prepare Release + 1. [ ] Merge the develop branch into main 2. [ ] Create a tag for the current Release with the version number 3. Tag and Main Branch are automatically mirrored to https://github.com/irmb/virtualfluids 4. When Zenodo sees the new tag on github, it automatically creates a new version on Zenodo ## Repositories + - Main Repository: https://git.rz.tu-bs.de/irmb/virtualfluids - Mirror: https://github.com/irmb/virtualfluids - Zenodo: https://zenodo.org/records/10283049 (DOI: https://doi.org/doi/10.5281/zenodo.10283048) diff --git a/docs/pages/unit-tests.md b/docs/pages/Unit-Tests.md similarity index 99% rename from docs/pages/unit-tests.md rename to docs/pages/Unit-Tests.md index 2f19b80bb5cfe0a61cb01a742aa03597fc1b1aaf..f194fce3c5107b876887f518bd81d5bc7404db10 100644 --- a/docs/pages/unit-tests.md +++ b/docs/pages/Unit-Tests.md @@ -6,12 +6,14 @@ This page describes how to add unit tests to VirtualFluids. VirtualFluids uses the C++ testing and mocking framework [GoogleTest](http://google.github.io/googletest/). ## 0. Test Structure in VirtualFluids + VirtualFluids is build upon multiple libraries `<library>` (e.g. [basics](https://git.rz.tu-bs.de/irmb/virtualfluids/-/tree/main/src/basics)). Every library can have a corresponding test executable. The test executable is called `<library>Test` and is created automatically by the CMake build system if the following two conditions are met: 1. The CMakeLists.txt of the libraries contains: `vf_add_tests()` (e.g. the basics library: [CMakeLists.txt](https://git.rz.tu-bs.de/irmb/virtualfluids/-/blob/main/src/basics/CMakeLists.txt)) 2. The library contains a file following the naming convention: `<fileName>Test.cpp` (e.g: [StringUtilTest.cpp](https://git.rz.tu-bs.de/irmb/virtualfluids/-/blob/main/src/basics/StringUtilities/StringUtilTest.cpp)) ## 1. Building and Running Tests + The tests can be built by running the following commands: ``` cmake .. -DBUILD_VF_UNIT_TESTS=ON @@ -79,11 +81,13 @@ The next step ist to **act** on the target behavior. The act step should cover t The third and final step is to **assert** the expected outcome. The result or response of the act step is checked. The assertion(s) determine(s) whether the test passes or fails. ### Assertions with googletest + For the assert step googleTest provides two options: [EXPECT and ASSERT](http://google.github.io/googletest/reference/assertions.html). Upon failure, `EXPECT_` macros generate nonfatal failures and allow the current function to continue running, while `ASSERT_` macros generate fatal failures and abort the current function. The above example uses the ``EXPECT_THAT`` macro. With ``EXPECT_THAT()`` you can use Google Test's [predefined matchers](http://google.github.io/googletest/reference/matchers.html) from the testing namespace (for example ``testing::IsTrue()`` or ``testing::IsEmpty()`` or your own custom matchers. The example above uses the custom matcher ``RealEQ()`` for testing the equality of two real numbers (float or double). ## 3. Common Problems + When you test a class which depends on CUDA you may get a build error like this: ``` fatal error: cuda_runtime.h: No such file or directory @@ -102,4 +106,5 @@ For VirtualFluidsGPU you can find the CMakeList here: ``VirtualFluids/src/gpu/Vi <!-- Gleiches Problm wie in Punkt 2. Running the Tests --> ## 4. Further Information + You can find further information on how to write tests in [GoogleTest User’s Guide](http://google.github.io/googletest/). \ No newline at end of file