Testing And Verification

Instructions

• Unit tests only test the /zero layer. Regression tests test the /app layer.
• Unit tests are focused on particular /zero modules and bear the same name as the module they test. For example, core/unit/ctest_array.c tests the core/zero/array.c module.
• Unit tests should be modular, test only what is necessary, and be simple.
• Only test code that you understand completely.
• For code changes, run relevant unit tests and focused regression tests when simulation behavior is affected. Choose tests based on the changed component.
• Do not run the entire regression suite unless you are asked to; it can take a long time. Use the task's scope and available resources to choose the suitable testing scope.
• For documentation or agent configuration changes, validate the changed files and references; solver tests and memory checks are unnecessary.
• Report what was checked and any checks that could not run. If required context is missing or unreadable, report the exact path rather than silently skipping it.

Running unit tests

Operate relative to the repository root (git rev-parse --show-toplevel).

In order to run all Gkeyll unit tests:

1. Compile all unit tests; see compilation.
2. Run all unit tests with

make -j"$NPROC" unit-run

In order to run all unit tests for a specific solver, e.g. gyrokinetic:

1. Compile all unit tests for that solver; see compilation.
2. Run all unit tests for that solver, e.g. for gyrokinetic use

make -j"$NPROC" gyrokinetic-unit-run

One can also compile and run a single unit test of interest. Simply:

1. Compile the unit; see compilation.
2. Run the executable from the repository root: For example, in order to run core/unit/ctest_array.c do

make -j"$NPROC" ./build/core/unit/ctest_array
./build/core/unit/ctest_array

If the Gkeyll was build on a CPU-only machine or without GPU support, unit tests will simply ignore GPU tests (via pre-processor if-statements). When running on a machine with a supported GPU, and if Gkeyll is configured to build GPU code, running these tests will automatically run the corresponding GPU tests. If a GPU is not available but Gkeyll was built to use GPUs, the GPU tests may simply fail or exit (e.g. due to GPU memory allocation errors).

Parallel unit tests

There are a few parallel unit tests that use MPI, whose names begin with mctest. These tests are compiled the same way as serial tests, but must be run with the appropriate MPI execution command.

For example if Gkeyll was built and configured with the MPI in gkylsoft/openmpi/, then a parallel unit test (for example mctest_mpi_comm.c) may be run with

<mpi_install_prefix>/bin/mpirun -np 4 build/core/unit/mctest_mpi_comm

Running regression tests

C regression tests

Regression tests written in C and located in creg/ directories need to be compiled first, see compilation.

Once compiled the regression test may be run serially with, for gyrokinetic/creg/rt_gk_sheath_2x2v_p1.c for example:

./build/gyrokinetic/creg/rt_gk_sheath_2x2v_p1

See

./build/gyrokinetic/creg/rt_gk_sheath_2x2v_p1 -h

for command line arguments that may be available (not all are actually supported). For example, the following command

./build/gyrokinetic/creg/rt_gk_sheath_2x2v_p1 -s1

limits the regression to a one-step smoke test.

CUDA builds place the executable in cuda-build/ instead of build/, and regression tests use -g to indicate GPU execution.