Introduction

This document describes how to create a functional or acceptance testcase for LIS 7. The testcase should contain everything needed to reproduce the testcase output. The testcase for the NAM 242 forcing reader will be used in this guide as an example. When creating your testcase, replace nam242forcingtest with the name of your case where applicable.

The rest of this document will guide the reader through the creation of the following files:

1

README

Provides a high-level description of the testcase itself as well as instructions for running the testcase.

2

ldt.config

The configuration file used to run LDT to produce the input domain and parameter file for LIS (e.g., lis_input.d01.nc).

3

input.ctl

A GrADS descriptor file used to display the input parameter file (e.g., lis_input.d01.nc).

4

lis.config

The configuration file used to run LIS.

5

MODEL_OUTPUT_LIST.TBL

A configuration file used by LIS to set the output for the test-case.

6

output.ctl

A GrADS descriptor file used to display the output from the LIS run.

7

testcase.ctl

A GrADS descriptor file used to display the target output contained in the output tar file (e.g., nam242forcingtest_output_v72.tar.gz).

8

nam242forcingtest_ldt_v72.tar.gz

The LDT tar file contains all the files needed to run LDT to produce the input domain and parameter file for LIS (e.g., lis_input.d01.nc).

9

nam242forcingtest_input_v72.tar.gz

The input tar file contains all the files needed to run LIS.

10

nam242forcingtest_output_v72.tar.gz

The output tar file contains target output for the testcase (i.e., what LIS should produce when the testcase is run).
Files 1 though 7 are stored with the LISF source code repository on GitHub (see lis/testcases/metforcing/nam242 for example). Files 8, 9, and 10 are stored on our data portal server.

Creating a Testcase

A testcase is created in four steps:

  1. Create the README file

  2. Create the LDT tar file (e.g., nam242forcingtest_ldt_v72.tar.gz).

  3. Create the INPUT tar file (e.g., nam242forcingtest_input_v72.tar.gz).

  4. Create the OUTPUT tar file (e.g., nam242forcingtest_output_v72.tar.gz).

These testcases may be run on systems other than discover so it must be self-contained. For example, the config files should not refer to /discover/nobackup/…​ (or to a symbolic link to data elsewhere on discover). Please use files and results generated in previous steps (see, for example, Step 4.3), to ensure that your testcase is both complete and self-contained.

Please do NOT commit the LDT, input, and output tar.gz files into the LISF repository. These files are too large to store in a GitHub repository and will be stored on our data portal instead.

Before continuing with Step 1, create a clean working directory in which to build the testcase. In the steps that follow, you will create new files and sub-directories within this parent directory.

Step 1: Create the README file

Create a file named README and add a high-level description of the testcase, instructions for running the testcase, and any additional notes (i.e., citations, links, data format information). This file will be saved in the LISF source code repository in the appropriate testcases sub-directory. See the NAM 242 testcase README for an example.

Step 2: Create the LDT tar file

In this step you will organize all the files needed by LDT to reproduce the lis_input.d01.nc domain and parameter file.

  1. Create a clean working directory for this step and change directories into it.

  2. Create the ldt.config file as appropriate for your testcase. If you have already created your ldt.config file, create a copy here.

    A copy of this ldt.config file will be saved in the LISF source code repository in the appropriate testcases sub-directory.

  3. Create a directory named input and place all input files listed in the ldt.config file into it. For example:

    % ls input
input/LS_PARAMETERS/UMD/25KM/landcover_UMD.1gd4r
input/LS_PARAMETERS/UMD/25KM/landmask_UMD.1gd4r
input/LS_PARAMETERS/UMD/25KM/elev_GTOPO30.1gd4r
input/LS_PARAMETERS/metforcing_parms/NAM/terrain.242.grb
    To reduce the filesize of the tar file created in this step, the input directory should contain only the files necessary for the LDT run. Do not include files associated with options that are disabled in the ldt.config file. For large forcing datasets, only include the subset of files necessary for the temporal domain of the testcase.

  4. Verify that the filepaths listed in your ldt.config file match the file locations in the new input directory. Update the filepaths if necessary.

  5. Run LDT to produce the input domain and parameter file for LIS (e.g., lis_input.d01.nc). Verify that the output is as expected.

  6. Create an input.ctl GrADS descriptor file for viewing the input parameter file. A copy of this file will be saved in the LISF source code repository in the appropriate testcases sub-directory.

  7. Copy the input domain and parameter file to lis_input_testcase.d01.nc and rename the log file created by the LDT run to ldtlog_testcase.0000.

  8. Create the LDT tar file, then gzip it (replacing nam242forcingtest with the name of your testcase):

    % tar cf nam242forcingtest_ldt_v72.tar ldtlog_testcase.0000 \
                                       lis_input_testcase.d01.nc \
                                       input
% gzip nam242forcingtest_ldt_v72.tar

    It should now be safe to delete the input directory created in this step.

Your working directory for this step should now contain the following files:

  • ldt.config

  • input.ctl

  • nam242forcingtest_ldt_v72.tar.gz

Change into the parent directory and proceed to Step 3.

Step 3: Create the input tar file

In this step you will organize the input data used in the LIS run.

  1. Create a clean working directory for this step and change directories into it.

  2. Copy the input domain and parameter file (e.g., lis_input.d01.nc) from Step 2.

  3. Create an input directory and copy all required input files listed into it, including any parameter files that are not processed by LDT. Note that you must create an input/forcing_variables.txt file that specifies which forcing variables are needed by LIS for this testcase.

    % ls input
input/forcing_variables.txt
input/MET_FORCING/NAM242/20120901/00/fh.0000_tl.press_gr.awp242
input/MET_FORCING/NAM242/20120901/00/fh.0003_tl.press_gr.awp242
input/MET_FORCING/NAM242/20120901/00/fh.0006_tl.press_gr.awp242
input/MET_FORCING/NAM242/20120901/00/fh.0009_tl.press_gr.awp242
                             .
                             .
                             .
input/MET_FORCING/NAM242/20120903/18/fh.0003_tl.press_gr.awp242
input/MET_FORCING/NAM242/20120903/18/fh.0006_tl.press_gr.awp242
input/MET_FORCING/NAM242/20120903/18/fh.0009_tl.press_gr.awp242
input/MET_FORCING/NAM242/20120903/18/fh.0012_tl.press_gr.awp242
    To reduce the filesize of the tar file created in this step, the input directory should contain only the files necessary for the LIS run. For large forcing datasets, only include the subset of files necessary for the temporal domain of the testcase.

  4. Create the input tar file, then gzip it (replacing nam242forcingtest with the name of your testcase):

    % tar cf nam242forcingtest_input_v72.tar lis_input.d01.nc \
                                         input
% gzip nam242forcingtest_input_v72.tar

    Don’t delete the input directory just yet, as you may have to make adjustments in the next step.

Your working directory for this step should now contain the following files:

  • input/

  • nam242forcingtest_input_v72.tar.gz

Change into the parent directory and proceed to Step 4.

Step 4: Create the output tar file

In this step you will organize the target output files that the output of test runs can be checked against.

  1. Create a clean working directory for this step and change directories into it.

  2. Create the lis.config file and MODEL_OUTPUT_LIST.TBL file as appropriate for your testcase (or copy them here if they already exist). Copies of these two files will be saved in the LISF source code repository in the appropriate testcases sub-directory.

  3. Copy and unpack the nam242forcingtest_input_v72.tar.gz file created in Step 3.

    % gzip -dc nam242forcingtest_input_v72.tar.gz | tar xf -

  4. Run LIS and verify that the output is as expected. If the run halts due to missing data, revisit Step 3.

  5. Create an output.ctl GrADS descriptor file for viewing the output data. A copy of this file will be saved in the LISF source code repository in the appropriate testcases sub-directory.

  6. Rename the OUTPUT directory to TARGET_OUTPUT and move all lislog.00* files into it. TARGET_OUTPUT should now contain all files generated by the LIS run. For example:

    % ls TARGET_OUTPUT
lislog.0000  SURFACEMODEL  SURFACEMODEL.d01.stats

  7. Create a testcase.ctl GrADS descriptor file for viewing the target output data in the TARGET_OUTPUT directory. A copy of this file will be saved in the LISF source code repository in the appropriate testcases sub-directory.

  8. Create the output tar file, then gzip it (replacing nam242forcingtest with the name of your testcase):

    % tar cf nam242forcingtest_output_v72.tar TARGET_OUTPUT
% gzip nam242forcingtest_output_v72.tar

Your working directory for this step should now contain the following files:

  • TARGET_OUTPUT/

  • output.ctl

  • testcase.ctl

  • nam242forcingtest_output_v72.tar.gz

Change directories into the parent directory containing the README file.

Finishing Up

You can now move all the files listed in the table at the top of this document out of their respective sub-directories and into this directory. Change permissions on the files in this directory to enable read access (e.g., chmod 755 *). If the testcase files are associated with a Pull Request, include the filepath to this directory in a comment. Otherwise, contact Brendan McAndrew and Jim Geiger about adding the testcase to the internal test suite.