Kernels and Tests

XGC’s major components can be run independently from the full code to aid in testing and development. They can be run independently in two modes: Test and Kernel.

  • Test mode: Runs a small, predefined example and compares against expected results. Uses GoogleTest (GTest) to verify results. Used to confirm correctness.

  • Kernel mode: Runs the same code, but the user specifies the scale (e.g. number of particles) via a command-line input. Results are not verified. Used to test performance.

There is also a unit test suite, unitTest-cpu (currently CPU only) which tests individual functions throughout the code; as such, there is no corresponding kernel.


Follow the XGC compilation instructions. If not all XGC dependencies are available, use the CMake configuration flag:


This will configure the kernel and test targets without needing to worry about PETSc, ADIOS2, etc.

All kernels/tests require the following dependencies be found:

  • Kokkos

  • Cabana

Tests will only configure if GTest is found.

Currently, even kernels that do not use Cabana require it. In the future, each individual kernel’s required dependencies will correspond to its actual dependencies.

Configured make targets have the form {component}{Test,Kernel}-{cpu,gpu}, for example: collisionsTest-gpu. Commonly used components:

  • collisions

  • push

  • electron_scatter

Every kernel has a corresponding test.

If you want to compile the entire kernel/test suite and not compile all the XGC versions (to save time), configure with the -DBUILD_FULL_XGC=Off flag mentioned above, then make everything:

mkdir build; cd build
cmake -DBUILD_FULL_XGC=Off ..
make -j


All component tests/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)

Tests take no input, e.g.:


Kernels currently take a command-line input to specify scale. e.g.:

./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

Currently, all 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