From 079629b8283b4bf9139e4f568b37bafc88455a6b Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Mon, 23 Oct 2023 13:48:50 -0500 Subject: [PATCH] Add section in developer's guide about possible reasons for failing tests (#2738) --- docs/source/devguide/tests.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/source/devguide/tests.rst b/docs/source/devguide/tests.rst index 582bb033d9e..9a102d2dc29 100644 --- a/docs/source/devguide/tests.rst +++ b/docs/source/devguide/tests.rst @@ -59,6 +59,31 @@ If you want to view testing output on failure run:: ctest --output-on-failure +Possible Reasons for Test Failures +---------------------------------- + +You may find that when you run the test suite, not everything passes. First, +make sure you have satisfied all the prerequisites above. After you have done +that, consider the following: + +- When building OpenMC, make sure you run CMake with + ``-DCMAKE_BUILD_TYPE=Debug``. Building with a release build will result in + some test failures due to differences in which compiler optimizations are + used. +- Because tallies involve the sum of many floating point numbers, the + non-associativity of floating point numbers can result in different answers + especially when the number of threads is high (different order of operations). + Thus, if you are running on a CPU with many cores, you may need to limit the + number of OpenMP threads used. It is recommended to set the + :envvar:`OMP_NUM_THREADS` environment variable to 2. +- Recent versions of NumPy use instruction dispatch that may generate different + results depending the particular ISA that you are running on. To avoid issues, + you may need to disable AVX512 instructions. This can be done by setting the + :envvar:`NPY_DISABLE_CPU_FEATURES` environment variable to "AVX512F + AVX512_SKX". When NumPy/SciPy are built against OpenBLAS, you may also need to + limit the number of threads that OpenBLAS uses internally; this can be done by + setting the :envvar:`OPENBLAS_NUM_THREADS` environment variable to 1. + Generating XML Inputs ---------------------