PIConGPU units tests

- add units tets for PIConGPU
  - build first test case to check particle shapes
- call unit tests in the CI

.gitlab-ci.yml

@@ -126,6 +126,20 @@ pmacc-compile-reduced-matrix:
         job: pmacc-generate-reduced-matrix
     strategy: depend
 
+picongpu-unittest-generate-reduced-matrix:
+  variables:
+    PIC_INPUTS: "unit"
+    TEST_TUPLE_NUM_ELEM: 1
+  extends: ".base_generate-reduced-matrix"
+
+picongpu-unittest-compile-reduced-matrix:
+  stage: test
+  trigger:
+    include:
+      - artifact: compile.yml
+        job: picongpu-unittest-generate-reduced-matrix
+    strategy: depend
+
 pypicongpu-generate-full-matrix:
   stage: generate
   image: ubuntu:22.04

share/ci/backendFlags.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+###################################################
+# translate PIConGPU backend names into CMake Flags
+###################################################
+
+get_backend_flags()
+{
+    backend_cfg=(${1//:/ })
+    num_options="${#backend_cfg[@]}"
+    if [ $num_options -gt 2 ] ; then
+        echo "-b|--backend must be contain 'backend:arch' or 'backend'" >&2
+        exit 1
+    fi
+    if [ "${backend_cfg[0]}" == "cuda" ] ; then
+        result+=" -Dalpaka_ACC_GPU_CUDA_ENABLE=ON -Dalpaka_ACC_GPU_CUDA_ONLY_MODE=ON"
+        if [ $num_options -eq 2 ] ; then
+            result+=" -DCMAKE_CUDA_ARCHITECTURES=\"${backend_cfg[1]}\""
+        else
+            result+=" -DCMAKE_CUDA_ARCHITECTURES=52"
+        fi
+    elif [ "${backend_cfg[0]}" == "omp2b" ] ; then
+        result+=" -Dalpaka_ACC_CPU_B_OMP2_T_SEQ_ENABLE=ON"
+        if [ $num_options -eq 2 ] ; then
+            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
+        fi
+    elif [ "${backend_cfg[0]}" == "serial" ] ; then
+        result+=" -Dalpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE=ON"
+        if [ $num_options -eq 2 ] ; then
+            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
+        fi
+    elif [ "${backend_cfg[0]}" == "tbb" ] ; then
+        result+=" -Dalpaka_ACC_CPU_B_TBB_T_SEQ_ENABLE=ON"
+        if [ $num_options -eq 2 ] ; then
+            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
+        fi
+    elif [ "${backend_cfg[0]}" == "threads" ] ; then
+        result+=" -Dalpaka_ACC_CPU_B_SEQ_T_THREADS_ENABLE=ON"
+        if [ $num_options -eq 2 ] ; then
+            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
+        fi
+    elif [ "${backend_cfg[0]}" == "hip" ] ; then
+        result+=" -Dalpaka_ACC_GPU_HIP_ENABLE=ON -Dalpaka_ACC_GPU_HIP_ONLY_MODE=ON"
+        if [ $num_options -eq 2 ] ; then
+            result+=" -DGPU_TARGETS=\"${backend_cfg[1]}\""
+        else
+            # If no architecture is given build for Radeon VII or MI50/60.
+            result+=" -DGPU_TARGETS=gfx906"
+        fi
+    else
+        echo "unsupported backend given '$1'" >&2
+        exit 1
+    fi
+
+    echo "$result"
+    exit 0
+}

share/ci/generate_reduced_matrix.sh

@@ -33,6 +33,9 @@ folders=()
 if [ "$PIC_INPUTS" == "pmacc" ] ; then
   # create test cases for PMacc
   echo "pmacc" | tr " " "\n" | n_wise_generator.py $@ --limit_boost_version
+elif [ "$PIC_INPUTS" == "unit" ] ; then
+   # create test cases for PMacc
+   echo "unit" | tr " " "\n" | n_wise_generator.py $@ --limit_boost_version
 else
   # create test cases for PIConGPU
   for CASE in ${PIC_INPUTS}; do

share/ci/n_wise_generator.py

@@ -296,7 +296,8 @@ def is_valid_combination(row):
             v_cuda_hip_str = "" if v_cuda_hip == 0 else str(v_cuda_hip)
             os_name = pairs[2][0]
             os_version = get_version(pairs[2])
-            image_prefix = "_run" if folder == "pmacc" else "_compile"
+            image_prefix = "_run" if folder == "pmacc" or folder == "unit"\
+                else "_compile"
             job_name = compiler + "_" + backend + v_cuda_hip_str + \
                 "_boost" + boost_version + "_" + folder.replace("/", ".")
             print(job_name + ":")

share/ci/run_picongpu_unit_tests.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+
+set -e
+set -o pipefail
+
+export code_DIR=$CI_PROJECT_DIR
+source $code_DIR/share/ci/backendFlags.sh
+
+# the default build type is Release
+# if neccesary, you can rerun the pipeline with another build type-> https://docs.gitlab.com/ee/ci/pipelines.html#manually-executing-pipelines
+# to change the build type, you must set the environment variable PIC_BUILD_TYPE
+if [[ ! -v PIC_BUILD_TYPE ]] ; then
+    PIC_BUILD_TYPE=Release ;
+fi
+
+if [[ "$CI_RUNNER_TAGS" =~ .*cpuonly.* ]] ; then
+    # In cases where the compile-only job is executed on a GPU runner but with different kinds of accelerators
+    # we need to reset the variables to avoid compiling for the wrong architecture and accelerator.
+    unset CI_GPUS
+    unset CI_GPU_ARCH
+fi
+
+if [ -n "$CI_GPUS" ] ; then
+    # select randomly a device if multiple exists
+    # CI_GPUS is provided by the gitlab CI runner
+    SELECTED_DEVICE_ID=$((RANDOM%CI_GPUS))
+    export HIP_VISIBLE_DEVICES=$SELECTED_DEVICE_ID
+    export CUDA_VISIBLE_DEVICES=$SELECTED_DEVICE_ID
+    echo "selected device '$SELECTED_DEVICE_ID' of '$CI_GPUS'"
+else
+    echo "No GPU device selected because environment variable CI_GPUS is not set."
+fi
+
+if [[ "$PIC_BACKEND" =~ hip.* ]] || [[ "$PIC_BACKEND" =~ cuda.* ]] ; then
+    if [ -n "$CI_GPU_ARCH" ] ; then
+        export PIC_BACKEND="${PIC_BACKEND}:${CI_GPU_ARCH}"
+    fi
+fi
+
+###################################################
+# cmake config builder
+###################################################
+
+PIC_CONST_ARGS=""
+PIC_CONST_ARGS="${PIC_CONST_ARGS} -DCMAKE_BUILD_TYPE=${PIC_BUILD_TYPE}"
+CMAKE_ARGS="${PIC_CONST_ARGS} ${PIC_CMAKE_ARGS} -DCMAKE_CXX_COMPILER=${CXX_VERSION} -DBOOST_ROOT=/opt/boost/${BOOST_VERSION}"
+CMAKE_ARGS="$CMAKE_ARGS -DUSE_MPI_AS_ROOT_USER=ON"
+
+# check and activate if clang should be used as CUDA device compiler
+if [ -n "$CI_CLANG_AS_CUDA_COMPILER" ] ; then
+  export PATH="$(agc-manager -b cuda)/bin:$PATH"
+  CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_COMPILER=${CXX_VERSION}"
+fi
+
+alpaka_backend=$(get_backend_flags ${PIC_BACKEND})
+CMAKE_ARGS="$CMAKE_ARGS $alpaka_backend"
+
+###################################################
+# build and run unit tests
+###################################################
+
+# adjust number of parallel builds to avoid out of memory errors
+# PIC_BUILD_REQUIRED_MEM_BYTES is a configured variable in the CI web interface
+PIC_PARALLEL_BUILDS=$(($CI_RAM_BYTES_TOTAL/$PIC_BUILD_REQUIRED_MEM_BYTES))
+
+# limit to number of available cores
+if [ $PIC_PARALLEL_BUILDS -gt $CI_CPUS ] ; then
+    PIC_PARALLEL_BUILDS=$CI_CPUS
+fi
+
+# CI_MAX_PARALLELISM is a configured variable in the CI web interface
+if [ $PIC_PARALLEL_BUILDS -gt $CI_MAX_PARALLELISM ] ; then
+    PIC_PARALLEL_BUILDS=$CI_MAX_PARALLELISM
+fi
+
+## run unit tests
+export unitTest_folder=$HOME/buildPICUnitTest
+mkdir -p $unitTest_folder
+cd $unitTest_folder
+
+echo -e "\033[0;32m///////////////////////////////////////////////////"
+echo "PIC_BUILD_REQUIRED_MEM_BYTES-> ${PIC_BUILD_REQUIRED_MEM_BYTES}"
+echo "CI_RAM_BYTES_TOTAL          -> ${CI_RAM_BYTES_TOTAL}"
+echo "CI_CPUS                     -> ${CI_CPUS}"
+echo "CI_MAX_PARALLELISM          -> ${CI_MAX_PARALLELISM}"
+echo "number of processor threads -> $(nproc)"
+echo "number of parallel builds   -> $PIC_PARALLEL_BUILDS"
+echo "cmake version               -> $(cmake --version | head -n 1)"
+echo "build directory             -> $(pwd)"
+echo "CMAKE_ARGS                  -> ${CMAKE_ARGS}"
+echo "accelerator                 -> ${PIC_BACKEND}"
+echo "input set                   -> ${PIC_TEST_CASE_FOLDER}"
+echo -e "/////////////////////////////////////////////////// \033[0m \n\n"
+
+cmake $CMAKE_ARGS $code_DIR/share/picongpu/unit
+make -j $PIC_PARALLEL_BUILDS
+# execute on one device
+ctest -V

share/ci/run_pmacc_tests.sh

@@ -3,6 +3,8 @@
 set -e
 set -o pipefail
 
+source $CI_PROJECT_DIR/share/ci/backendFlags.sh
+
 # the default build type is Release
 # if neccesary, you can rerun the pipeline with another build type-> https://docs.gitlab.com/ee/ci/pipelines.html#manually-executing-pipelines
 # to change the build type, you must set the environment variable PMACC_BUILD_TYPE
@@ -28,62 +30,6 @@ if [ -n "$CI_CLANG_AS_CUDA_COMPILER" ] ; then
     CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_COMPILER=${CXX_VERSION}"
 fi
 
-###################################################
-# translate PIConGPU backend names into CMake Flags
-###################################################
-
-get_backend_flags()
-{
-    backend_cfg=(${1//:/ })
-    num_options="${#backend_cfg[@]}"
-    if [ $num_options -gt 2 ] ; then
-        echo "-b|--backend must be contain 'backend:arch' or 'backend'" >&2
-        exit 1
-    fi
-    if [ "${backend_cfg[0]}" == "cuda" ] ; then
-        result+=" -Dalpaka_ACC_GPU_CUDA_ENABLE=ON -Dalpaka_ACC_GPU_CUDA_ONLY_MODE=ON"
-        if [ $num_options -eq 2 ] ; then
-            result+=" -DCMAKE_CUDA_ARCHITECTURES=\"${backend_cfg[1]}\""
-        else
-            result+=" -DCMAKE_CUDA_ARCHITECTURES=52"
-        fi
-    elif [ "${backend_cfg[0]}" == "omp2b" ] ; then
-        result+=" -Dalpaka_ACC_CPU_B_OMP2_T_SEQ_ENABLE=ON"
-        if [ $num_options -eq 2 ] ; then
-            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
-        fi
-    elif [ "${backend_cfg[0]}" == "serial" ] ; then
-        result+=" -Dalpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE=ON"
-        if [ $num_options -eq 2 ] ; then
-            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
-        fi
-    elif [ "${backend_cfg[0]}" == "tbb" ] ; then
-        result+=" -Dalpaka_ACC_CPU_B_TBB_T_SEQ_ENABLE=ON"
-        if [ $num_options -eq 2 ] ; then
-            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
-        fi
-    elif [ "${backend_cfg[0]}" == "threads" ] ; then
-        result+=" -Dalpaka_ACC_CPU_B_SEQ_T_THREADS_ENABLE=ON"
-        if [ $num_options -eq 2 ] ; then
-            result+=" -DPMACC_CPU_ARCH=\"${backend_cfg[1]}\""
-        fi
-    elif [ "${backend_cfg[0]}" == "hip" ] ; then
-        result+=" -Dalpaka_ACC_GPU_HIP_ENABLE=ON -Dalpaka_ACC_GPU_HIP_ONLY_MODE=ON"
-        if [ $num_options -eq 2 ] ; then
-            result+=" -DGPU_TARGETS=\"${backend_cfg[1]}\""
-        else
-            # If no architecture is given build for Radeon VII or MI50/60.
-            result+=" -DGPU_TARGETS=gfx906"
-        fi
-    else
-        echo "unsupported backend given '$1'" >&2
-        exit 1
-    fi
-
-    echo "$result"
-    exit 0
-}
-
 ###################################################
 # build an run tests
 ###################################################

share/ci/run_tests.sh

@@ -5,6 +5,8 @@ set -o pipefail
 
 if [ "$1" == "pmacc" ] ; then
   $CI_PROJECT_DIR/share/ci/run_pmacc_tests.sh
+elif [ "$1" == "unit" ] ; then
+    $CI_PROJECT_DIR/share/ci/run_picongpu_unit_tests.sh
 else
   $CI_PROJECT_DIR/share/ci/run_picongpu_tests.sh
 fi

share/picongpu/unit/CMakeLists.txt

@@ -0,0 +1,93 @@
+# Copyright 2023 Rene Widera
+#
+# This file is part of PIConGPU.
+#
+# PIConGPU is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# PIConGPU is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with PIConGPU.
+# If not, see <http://www.gnu.org/licenses/>.
+#
+
+cmake_minimum_required(VERSION 3.22.0)
+project("UnitTest")
+
+###############################################################################
+# Language Flags
+###############################################################################
+
+# enforce C++17
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_CXX_STANDARD 17)
+
+
+################################################################################
+# CMake policies
+#
+# Search in <PackageName>_ROOT:
+#   https://cmake.org/cmake/help/v3.12/policy/CMP0074.html
+################################################################################
+if(POLICY CMP0074)
+    cmake_policy(SET CMP0074 NEW)
+endif()
+
+################################################################################
+# PMacc
+################################################################################
+find_package(PMacc REQUIRED CONFIG PATHS "${CMAKE_CURRENT_SOURCE_DIR}/../../../include/pmacc")
+
+###############################################################################
+# Catch2
+###############################################################################
+
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../../../thirdParty/catch2 ${CMAKE_BINARY_DIR}/catch2)
+
+################################################################################
+# MPI
+################################################################################
+
+# MPI is provided by pmacc but to execute the binaries via root additional flags must be given to the execution command
+option(USE_MPI_AS_ROOT_USER "add --allow-run-as-root mpiexec used by ctest" OFF)
+
+if(USE_MPI_AS_ROOT_USER)
+    set(MPI_RUNTIME_FLAGS "--allow-run-as-root")
+endif()
+
+# PIConGPU
+
+include_directories(BEFORE "${CMAKE_CURRENT_SOURCE_DIR}/../../../include")
+
+###############################################################################
+# Targets
+###############################################################################
+
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/test)
+
+# CTest
+enable_testing()
+
+# Test cases
+# Each *UT.cpp file is an independent executable with one or more test cases
+file(GLOB_RECURSE TESTS *.cpp)
+foreach(dim 2 3)
+    foreach(testCaseFilepath ${TESTS})
+        get_filename_component(testCaseFilename ${testCaseFilepath} NAME)
+        string(REPLACE "UT.cpp" "" testCase ${testCaseFilename})
+        set(testExe "${PROJECT_NAME}-${testCase}-${dim}D")
+        cupla_add_executable(${testExe} ${testCaseFilepath})
+        target_compile_definitions(${testExe} PRIVATE TEST_DIM=${dim})
+        target_link_libraries(${testExe} PUBLIC Catch2 Catch2WithMain)
+        target_link_libraries(${testExe} PRIVATE pmacc::pmacc)
+        add_test(NAME "${testCase}-${dim}D" COMMAND mpiexec ${MPI_RUNTIME_FLAGS} -n 1 ./${testExe})
+    endforeach()
+    string(REPLACE "-DTEST_DIM=${dim}" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
+endforeach()

share/picongpu/unit/README.rst

@@ -0,0 +1,12 @@
+PIConGPU unit test
+==================
+
+Test components in an as best as possible isolated environment.
+
+Example how to compile and execute the tests.compile
+
+.. code-block:: bash
+    # compile for NVIDIA GPUs
+    cmake <path_to_picongpu_source>/share/picongpu/unit/ -Dalpaka_ACC_GPU_CUDA_ENABLE=ON
+    make -j
+    ctest