Running unit tests using utest - BrianCurtis-NOAA/ufs-weather-model GitHub Wiki

What is Unit Test

  • A suite of tests
  • Each test addresses a single aspect of the requirement a new implementation should satisfy:
    • Thread (THR) reproducibility: varying the number of threads produces the same results
    • MPI process (MPI) reproducibility: varying the number of MPI tasks produces the same results
    • Domain decomposition (DCP) reproducibility: varying the tile layout of FV3 produces the same results
    • Restart (RST) reproducibility: restarting produces the same results
    • 64/32 (BIT): changing to double/single precision can be compiled and simulation can be run to completion
    • Debug (DBG): can be compiled and simulation can be run to completion in debug mode

Why Unit Test

  • Purpose of running unit tests is to satisfy the operational implementation requirement
  • Currently, regression tests conduct unit tests only for 'control' test
  • Bugs that break the unit tests and are found later during the model implementation stage could be very difficult to debug
  • Identify problems earlier in the development process
  • Developers ensure their implementations pass unit tests before requesting a Pull Reqeust

Procedure to Run Unit Test

  • Developers finish code changes and do their own tests
  • Pick a test case under ufs-weather-model/tests/tests that is relevant to his/her code changes
  • Modify or add a test case if no test exists that can test the developer's code changes
  • $ cd ufs-weather-model/tests
  • $ ./utest -n <test-name>
  • Check and commit the unit test report/logfile to the developer's branch
  • Make a pull request

Examples (using fv3_ccpp_control as <test-name>)

  • To run all tests: $ ./utest -n fv3_ccpp_control
  • To run THR test only: $ ./utest -n fv3_ccpp_control -c thr
  • To run MPI and DCP tests only: $ ./utest -n fv3_ccpp_control -c mpi,dcp
  • To run DBG and RST tests only: $ ./utest -n fv3_ccpp_control -c dbg,rst

Command Line Interface

  • $ ./utest -h: displays usage of shell script
  • $ ./utest -n <test-name>: runs all unit tests for test-name
  • $ ./utest -n <test-name> -c <test-case>: runs a specific unit test case (thr, mpi, dcp, rst, bit, dbg)
  • Other option flags are:
    • -k: keep run directory
    • -e: use ecFlow
    • -b: test bit reproducibility
    • -d: test debug reproducibility
    • -x: skip compilation
    • -z: skip running (i.e., only compiles)

Input Files

  • utest.bld
    • Specify required build options in this format: <test-name> | <build_opt>
    • <build_opt> can be WW3=Y, CCPP=Y, etc.
  • <test-name>, <INPUT_NML>, <FV3_RUN>: all similar to those in regression tests

Output Files

  • UnitTests_<machine>.<compiler>.log: unit test logfile (commit)
  • Compile_ut_<machine>.<compiler>.log: compile logfile (do not commit)
  • ufs-weather-model/log_ut_<machine>.<compiler> directory (do not commit)

File Locations Summary

  • utest: ufs-weather-model/tests
  • utest.bld: ufs-weather-model/tests
  • <test-name>: ufs-weather-model/tests/tests
  • UnitTests_<machine>.<compiler>.log: ufs-weather-model/tests
  • Compile_ut_<machine>.<compiler>.log: ufs-weather-model/tests
  • log_ut_<machine>.<compiler> directory: ufs-weather-model/tests
  • Run directory
    • On Hera: /scratch1/NCEPDEV/stmp2/$USER/FV3_UT/ut_*
    • On Orion: /work/noaa/stmp/$USER/stmp/$USER/FV3_UT/ut_*
    • On Dell P3: /gpfs/dell2/ptmp/$USER/FV3_UT/ut_*

Details on Unit Test Configuration

  • THR: Number of threads = 2, Tasks per node /= 2
  • MPI: JNPES /= 2, WRITE_GROUP = 2, WRTTASK_PER_GROUP = 12
  • DCP: Swap INPES and JNPES
  • RST: use restart files at middle of the run (SHOUR+FHMAX/2) and compare results at end of the run (SHOUR+FHMAX)
  • BIT: able to compile and run to completion with different precision
  • DBG: able to compile and run to completion in debug mode
⚠️ **GitHub.com Fallback** ⚠️