Testing GENE-X

To ensure that the GENE-X code has been installed correctly, run the unit test suite. This suite executes a series of tests to verify the correctness of the installation.

Running single unit tests

After a successful build, ./bin is created within the build directory. You can navigate there and run a test using, for example,

cd bin
srun -n8 -p interactive -t1 --mem=32G logger-utests

which allocates 8 MPI processes on the interactive partition with 1 minute runtime and 32 GB of memory. The logger-utests executable is run in this example. You are free to choose any of the utests executables.

Note

The number of MPI procs should be always 8 since most unit tests require that number of procs. The time needs to be adjusted for the maximum duration of the test. The memory allocation above was found to be sufficient. Note that some settings, for example the memory, are not necessary for running the code but are necessary to get an allocation on certain machines.

Running the unit test suite

To run the full unit test suite at once, execute, starting from the build directory,

salloc -n 8 --mem=32G --time=00:30:00 ctest --test-dir ./src/ --output-on-failure -E "utests-cpu"

potentially adjusting the total runtime to allow for running all tests.

Confix generated test scripts

If you’ve built the code using ConfiX, you’ll find two additional folders in your build directory: ./unit-testing/ and ./mms-testing/.

Unit testing

In the unit-testing/ directory, run_utests.sh script handles the correct SLURM options and unit test executions based on the machine specification and target architecture, e.g., CPU or GPU. Make sure to check the help page source run_utests.sh -h before using it. The execution mainly done via SLURM salloc with correct partition from ConfiX, with some exception in some machine using SLURM sbatch submission. source run_utests.sh runs the unit tests targeting CPU and source run_utests.sh --gpu runs ones targeting GPU. --interactive can be used to skip the SLURM command and run ctest interactively. -p can be used to only print the command. This is useful for user to copy and modify the command to their needs. -R (regex) and -E (exclude) options of ctest can be used to run specific unit test binaries. -R <binary name> can be used to execute individual unit test binary when developing specific part of GENE-X.

Note

These scripts are optional but strongly recommended for convenience and consistency.

MMS testing

You can also utilize the autogenerated MMS testing setup contained in the ./mms-testing/ directory. This setup includes a variety of test cases, each with its own parameter file, SLURM batch script, and reference file. Additionally, you can use the multitask SLURM batch scripts for GPU MMS, deep MMS, and broad MMS testing to run multiple jobs simultaneously. Dedicated shell scripts for result assertion are also provided to help you verify the accuracy of your results.

Note

For running and verifying a single MMS test manually, please consider the [first steps page]#(first-steps)

For verifying your code installation, we recommend running at least once per new machine the MMS broad test script. For that, starting from the build directory

cd ./mms-testing/grid/

open the file submit_mms_broad_cpu.sh and verify the autogenerated settings are correct. Then you can

sbatch submit_mms_broad_cpu.sh

and wait for the job to finish. With q (loaded by Confix) you can monitor your job status. Once finished, you should be able to see a file mms_broad_cpu.out (CPU run example).

You can verify the results within the file using

bash mms_assert_broad_cpu.sh

which should run without error and printout Check passed! repeatedly.