Documentation

.github/workflows/draft-pdf.yml

@@ -0,0 +1,23 @@
+name: Draft PDF
+on: [push]
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

_config.yml

@@ -0,0 +1,6 @@
+title: VERTEX-CFD
+logo: docs/figures/vertex_cfd_heated_flow_logo.png
+description: VERTEX-CFD is a performance portable software package for computational fluid dynamics (CFD) simulations on CPU or GPU architectures.
+show_downloads: true
+google_analytics:
+theme: jekyll-theme-minimal

docs/index.md

@@ -0,0 +1,13 @@
+---
+layout: page
+title: VERTEX-CFD v1.0 User Guide
+nav_order: 2
+has_children: true
+---
+
+# VERTEX-CFD v1.0 User Guide
+VERTEX-CFD is a free, open source multi physics software for simulations of fusion applications released by Oak Ridge National Laboratory.
+---
+
+{: .custom }
+The User Guide v1.0 is currently under development and may be incomplete.

docs/installation.md

@@ -0,0 +1,113 @@
+---
+parent: VERTEX-CFD v1.0 User Guide
+nav_order: 1
+---
+
+# Installation
+VERTEX-CFD supports both CPU and GPU solvers. For full CPU and GPU capabilities, please refer to GPU installation. Otherwise, check CPU installation below.
+
+## CPU installation
+For the CPU installation, first of all, make sure you have `TRILINOS_HOME` variable defined in your environment.
+```
+TRILINOS_HOME=PATH_TO_TRILINOS/TRILINOS_VERSION
+```
+Once the `TRILINOS_HOME` is set, load the dependencies:
+```
+module load intel
+module load tbb
+module load compiler-rt/
+module load mkl
+module load python
+```
+Once the environment is ready, configuration file can be run as:
+```
+./vertexcfd-env
+```
+The content of the `vertexcfd-env` file is:
+```
+#!/bin/sh                                                                                  
+
+SOURCE=PATH_TO/vertex-cfd
+INSTALL=INSTALLATION_PATH
+Trilinos_ROOT=PATH_TO_TRILINOS/TRILINOS_VERSION
+BUILD="Release"
+BUILD_SYSTEM=Ninja
+
+rm -rf CMake*
+rm DartConfiguration.tcl
+rm CTestTestfile.cmake
+rm VertexCFDConfig.cmake
+rm -rf Testing
+
+cmake \
+    -G "$BUILD_SYSTEM" \
+    -D CMAKE_BUILD_TYPE="$BUILD" \
+    -D CMAKE_INSTALL_PREFIX="$INSTALL" \
+    -D VertexCFD_ENABLE_COVERAGE_BUILD=OFF \
+    -D CMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic -fdiagnostics-color" \
+    -D VertexCFD_ENABLE_TESTING=ON \
+    -D CLANG_FORMAT_EXECUTABLE="PATH_TO_CLANG_FORMAT" \
+    -D Trilinos_ROOT="$Trilinos_ROOT" \
+    \
+    ${SOURCE}
+```
+Please note that `BUILD_SYSTEM` environment can be both `Ninja` or `Make`. Choose the correct one based on your system. Once the configuration is completed, compilation can be initiated with following command. Please note that we used `ninja` in this example so please switch to `make` if your `BUILD_SYSTEM` is defined as `Make`.
+```
+ninja
+```
+By default, `ninja` command will use the available cores, this can be limitted as:
+```
+ninja -j4
+```
+You can replace the number 4 with the number of cores that you prefer. We do recommend to use `-j` flag as some systems tends to compile on every CPUs on the login node and fail due to the allocated/used CPUs. Once the compilation is done, VERTEX-CFD can be installed by using:
+```
+ninja install
+```
+Once installed, VERTEX-CFD is ready to run.                                                                                  
+
+## GPU installation
+For the GPU installation, CUDA needs to be loaded in the HPC environment and Trilinos needs to be built with the GPU support. Just like the CPU version, define the `TRILINOS_HOME` variable as:
+```
+TRILINOS_HOME=PATH_TO_TRILINOS/TRILINOS_VERSION_WITH_CUDA
+```
+Once the `TRILINOS_HOME` is set, load the dependencies by including cuda:
+```
+module load intel
+module load tbb
+module load compiler-rt/
+module load mkl
+module load python
+module load cuda
+```
+Once the environment is ready, configuration file can be run as:
+```
+./vertexcfd-env-gpu
+```
+The content of the `vertexcfd-env-gpu` file is:
+```
+#!/bin/sh                                                                                  
+
+SOURCE=PATH_TO/vertex-cfd
+INSTALL=INSTALLATION_PATH
+Trilinos_ROOT=PATH_TO_TRILINOS/TRILINOS_VERSION_WITH_CUDA
+BUILD="Release"
+BUILD_SYSTEM=Ninja
+
+rm -rf CMake*
+rm DartConfiguration.tcl
+rm CTestTestfile.cmake
+rm VertexCFDConfig.cmake
+rm -rf Testing
+
+cmake \
+    -G "$BUILD_SYSTEM" \
+    -D CMAKE_BUILD_TYPE="$BUILD" \
+    -D CMAKE_INSTALL_PREFIX="$INSTALL" \
+    -D VertexCFD_ENABLE_COVERAGE_BUILD=OFF \
+    -D CMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic -fdiagnostics-color" \
+    -D VertexCFD_ENABLE_TESTING=ON \
+    -D CLANG_FORMAT_EXECUTABLE="PATH_TO_CLANG_FORMAT" \
+    -D Trilinos_ROOT="$Trilinos_ROOT" \
+    \
+    ${SOURCE}
+```

docs/theory.md

@@ -0,0 +1,18 @@
+---
+parent: VERTEX-CFD v1.0 User Guide
+title: Theory
+nav_order: 2
+usemathjax: true
+---
+
+# Theory
+
+---
+
+## The physics
+
+## The discretized equations
+
+## Boundary conditions
+
+## Initial conditions

docs/usage.md

@@ -0,0 +1,105 @@
+---
+parent: VERTEX-CFD v1.0 User Guide
+title: Usage
+nav_order: 3
+usemathjax: true
+---
+
+# Usage
+
+Once installed, VERTEX-CFD relies on two files. The first one is the 'vertexcfd' executable and the second one is the input file for the simulation. After the installation, the executable is located in `INSTALL_PATH/bin/vertexcfd`. The input file is case spesific and there are example case files in `vertex-cfd/examples/inputs`. In this document, the input file located in `vertex-cfd/examples/inputs/incompressible/incompressible_2d_channel.xml` will be used as an example case. 
+
+## Running a simulation
+In order to run a simulation in serial, vertexcfd can be called directly as:
+
+```
+INSTALL_PATH/bin/vertexcfd --i=PATH_TO_INPUT_FILE/incompressible_2d_channel.xml
+```
+To run in parallel, `mpirun` is required. An example script for the SLURM scheduler is below:
+```
+#!/bin/bash
+#SBATCH -N 1
+#SBATCH --ntasks-per-node=32
+#SBATCH --time=1:00:00
+#SBATCH -o output.log
+#SBATCH -e error.log
+
+source PATH_TO_ENVIRONMENT_SCRIPT
+
+export OMP_PROC_BIND=true
+export OMP_PLACES=threads
+
+mpirun INSTALL_PATH/bin/vertexcfd --i=PATH_TO_INPUT_FILE/incompressible_2d_channel.xml
+```
+Once the simulation starts, the example output should look like:
+```
+============================================================================
+Time Integration Begin
+Thu Mar 31 21:46:09 2022
+
+  Stepper = Backward Euler
+  Simulation Time Range  [0, 0.2]
+----------------------------------------------------------------------------
+
+Time Step = 1; Order = 1
+CFL = 1.000e+00; dt = 6.186e-03; Time = 0.00000e+00
+ | Nonlinear | F 2-Norm | # Linear | R 2-Norm |
+           0   6.65e-02
+           1   2.03e-02          1   6.45e-16
+           2   4.66e-04          1   4.25e-16
+           3   5.40e-07          1   5.36e-16
+           4   3.19e-13          1   6.58e-16
+Time step time to completion (s): 5.97e+00
+
+Time Step = 2; Order = 1
+CFL = 1.000e+00; dt = 5.644e-03; Time = 6.18583e-03
+ | Nonlinear | F 2-Norm | # Linear | R 2-Norm |
+           0   5.73e-02
+           1   5.72e-03          1   4.68e-16
+           2   5.40e-05          1   4.01e-16
+           3   3.47e-09          1   7.18e-16
+Time step time to completion (s): 8.96e+00
+
+Time Step = 3; Order = 1
+CFL = 1.000e+00; dt = 5.385e-03; Time = 1.18299e-02
+ | Nonlinear | F 2-Norm | # Linear | R 2-Norm |
+           0   5.37e-02
+           1   4.14e-03          1   4.17e-16
+           2   3.35e-05          1   3.47e-16
+           3   2.01e-09          1   5.54e-16
+Time step time to completion (s): 7.03e-01
+... ...
+... ...
+... ...
+... ...
+Time Step = 40; Order = 1
+CFL = 1.000e+00; dt = 4.853e-03; Time = 1.93731e-01
+ | Nonlinear | F 2-Norm | # Linear | R 2-Norm |
+           0   3.57e-02
+           1   1.15e-03          1   3.89e-16
+           2   1.68e-06          1   3.90e-16
+           3   1.66e-12          1   3.20e-16
+Time step time to completion (s): 1.73e+00
+    41 *  (dt = 4.852e-03, new = 1.417e-03)  Adjusting dt to hit final time.
+
+Time Step = 41; Order = 1
+CFL = 1.000e+00; dt = 1.417e-03; Time = 1.98583e-01
+ | Nonlinear | F 2-Norm | # Linear | R 2-Norm |
+           0   3.56e-02
+           1   3.11e-04          1   2.95e-16
+           2   3.67e-08          1   2.73e-16
+           3   4.40e-16          1   2.86e-16
+Time step time to completion (s): 6.91e+00
+
+----------------------------------------------------------------------------
+Total runtime = 1.45e+02 sec
+              = 2.42e+00 min
+              = 0.04 hr
+Thu Mar 31 21:51:51 2022
+Time integration complete.
+============================================================================
+```
+Once the simulation is completed. The results should be ready for visualization. For the visualization, we suggest ParaView. However, any visualization software that supports Exodus format should work. The example solution file screenshot visualized in Paraview is shown below:
+
+![paraview-ss](https://github.com/user-attachments/assets/75483e4a-cfec-4a51-891f-3b7c72262ba7)
+

index.md

@@ -0,0 +1,41 @@
+---
+layout: default
+title: Home
+nav_order: 1
+permalink: /
+---
+
+An open-source CFD code for multi-physics modeling and simulation with a focus on fusion applications.
+{: .fs-6 .fw-300 }
+
+[User Guide](docs/index.html){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+
+[View it on GitHub][AdditiveFOAM repo]{: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+## Contributing
+We encourage you to contribute to VERTEX-CFD! Please check the guidelines on how to do so.
+
+#### Contributors
+- [Marco Delchini](https://www.ornl.gov/staff-profile/marc-olivier-delchini)
+- [Kellis Kincaid](https://www.ornl.gov/staff-profile/kellis-c-kincaid)
+- [Furkan Oz](https://www.ornl.gov/staff-profile/furkan-oz)
+- [Kalyan Gottiparthi](https://www.ornl.gov/staff-profile/kalyan-c-gottiparthi)
+- [Jason Degraw](https://www.ornl.gov/staff-profile/jason-w-degraw)
+- [Filipe Leite Brandao](https://www.ornl.gov/staff-profile/filipe-leite-brandao)
+
+## Citing
+If you use VERTEX-CFD in your work, please cite the Zenodo DOI [![DOI](DOI_NUMBER)](DOI_NUMBER) of the version you used as a software citation:
+```bibtex
+@software{vertex-cfd,
+  author       = {AUTHORS},
+  title        = {VERTEX-CFD: Release 1.0},
+  month        = jun,
+  year         = 2024,
+  publisher    = {Zenodo},
+  version      = {1.0.0},
+  doi          = {DOI_NUMBER},
+  url          = {DOI_URL}
+}
+```