Kernels and Tests

XGC’s major components can be run independently from the full code to aid in testing and development. The kernels can be run in test mode for verification. There is also a unit test suite, UnitTests-cpu (currently CPU only) which tests individual functions throughout the code; as such, there is no corresponding kernel.


The kernels are built by default if you are building XGC (see cmake_build_instructions.rst). However, this can be inconvenient since the kernels require only a subset of the XGC dependencies. If you only want the kernels and tests, use the following instructions instead.

All kernels/tests require Kokkos and Cabana. The Collisions kernel requires LAPACK. Tests will only configure if GTest is found. For instructions on installing these dependencies, see 3rd Party Software Installations.

Once Kokkos, Cabana, and optionally GTest are installed, you can configure and build with:

mkdir build; cd build
cmake \
     -DKokkos_ROOT=<path to Kokkos> \
     -DCabana_ROOT=<path to Cabana> \
     -DLAPACK_ROOT=<path to LAPACK> \
     -DGTEST_ROOT=<path to GTest> \
make -j

The executables have the form {component}Kernel-{cpu,gpu}, for example: collisionsKernel-gpu. Commonly used components:

  • collisions

  • electron_push

  • electron_scatter


All component kernels require input files. If security settings permit it, running


in the build directory will download the directory containing these files from the Kitware website, then run all CPU tests. However, this automatic download fails in many systems. In that case, you must download the data manually, taking the most recent* tarball from here. The tarball contains a directory called SmallExample.

Run the executables from the directory that contains SmallExample. (i.e. the executables expect to find files of the form ./SmallExample/example.txt)

To test the kernels, use “–test”, e.g.:

./electron_pushKernel-cpu --test

This mode will run a small, predefined example and compares against expected results. For collisions, it is the same calculation as -n_nodes 3. For the other kernels, it is the same calculation as -n_ptl 37. GoogleTest (GTest) is used to confirm correctness of results.

Outside of test mode, results are not verified. The kernel scale must be user-specified via a command-line input, e.g.:

./electron_pushKernel-cpu -n_ptl 50000

will run with 50000 particles. “-n_ptl” is the input for all kernels except the collision kernel, since the collision kernel does not involve particles. In that kernel, scaling is done by adding mesh nodes. The syntax is:

./collisionsKernel-cpu -n_nodes 3000

If further customization of the collision kernel inputs is desired, one can supply a file in Fortran namelist format, specifiying its location with “-file”.

Currently, all kernels and tests are single-process (i.e. no MPI).

* More robustly, use the tarball with the sha512 found in your repo’s version of utils/regression_tests/SmallExample.tar.gz.sha512