The script test-model.pl in the bld/offline/tests directory runs a suite of basic tests for the CLM2.0 model running in offline mode on a 3x3 model grid. In order to use test-model.pl, the user needs to have at least Perl version 5.004 on their system. This test suite is designed for model testing when the user is modifying model code or simply porting the code to another machine. The test suite provides a check that the basic functionality of the model still works despite the changes the user has introduced.
In this section the usage of test-model.pl for basic acceptance testing is described. The command-line arguments to ``test-model.pl'' are summarized as well environment variables that are useful to use the script.
The script, test-model.pl, is designed to be run interactively. Although, this script can be run at other labs, testing has only be done on NCAR machines. Consequently, the following discussion will be confined to NCAR platforms. The user should feel free to try the scripts at other labs.
Before running the CLM2.0 test suite, the user needs to set the
environment variable, MODEL_DATADIR, specifying the full disk
pathname containing the untarred subdirectories NCEPDATA, inidata, pftdata, rawdata, rtmdata and srfdata. At NCAR, CCSM input datasets are stored on a NFS mounted
directory, "/fs/cgd/csm/inputdata/lnd/clm2". Consequently, this is the
default value for $MODEL_DATADIR in the testing scripts.
If the user has untarred the source code such that the test-model.pl
script is in the directory ``/home/user/clm2/bld/offline/tests'',
then the user may invoke the script as follows:
cd /home/user/clm2/bld/offline/tests
test-model.pl
The script, test-model.pl, is designed such that the common settings the user might want to control are easily set by command line arguments. The "-h" option to test-model.pl lists all of the possible command-line options.
| -h | Help (this message) |
| -t | List the tests that are performed |
| -clean | Clean the old directories out |
| -nofail | Continue even if errors are found |
| -r | Continue a previous run of the script at the point it left off at |
| -s n | Skip to given test n (or range of numbers) |
| (example -s 4 start with test no. 4) | |
| (or -s 2-4 do tests 2 through 4) | |
| -c dir | Compare to another version of the CLM2 model in this directory |
| (example -c /home/user/clm2/src) | |
| -l lab | Set the lab you are running at |
The "-t" option to "test-model.pl" lists all of the possible tests
where there associated numbers. Below is a brief summary of each
test.
An important feature of test-model.pl is the ability to compare
modified CLM2.0 code to a previous program library. This is useful in
order to ensure that the implemented modifications do not change
answers if that is what is expected. Using the command line option
"-c dir" the user can compare to a previous program library by giving
the full path to the root of the library to compare to. For example,
if a test library can be found in "/home/user/clm2mod/src'' and the
unmodified library is located in ``/home/user/clm2/src'' then ``-c''
can be used as follows:
cd /home/user/testmod/bld/offline/tests
test-model.pl -c /home/user/clm2/src
When the "-c" option is used, only test 6 is compared to test 5 (see the list of tests above). If this comparison isidentical, the modified model is identified as being bit-for-bit with the control library. This is reported at the end of test-model.pl (and in the log file) as follows:
Many times differences with respect to a control library are intended to be bit-for-bit. As explained above simply by using the "-c" option to test-model.pl can easily identify if two model libraries give identical answers. However, it is more difficult to verify if changes are within machine roundoff. Currently, if non bit-for-bit differences occur, differences between the history files produced by both the control as well as modified libraries must be examined to determine if these differences indicate only roundoff level changes.