In order to build and run CLM2.1 in offline mode, a sample script, jobscript.csh, and a corresponding Makefile are provided in the bld/offline directory. In addition, two perl scripts mkDepends (used to generate dependencies in a form suitable for inclusion into a Makefile), and mkSrcfiles (used to make a list of files containing source code) are also included.
Jobscript.csh creates a model executable at T42 model resolution with RTM river routing activated, determines the necessary input datasets, constructs the input model namelist and runs the model for one day. Users must edit this script appropriately in order to build and run the executable for their particular requirements and in their particular environment. This script is provided only as an example to aid the novice user in getting CLM2.1 up and running as quickly as possible.
The script can be run with minimal user modification, assuming the user resets several environment variables at the top of the script. In particular, the user must set CSMDATA to point to the full disk pathname of the root directory containing the untarred input dataset subdirectories. The user must also set ROOTDIR to point to the full disk pathname of the root directory containing the untarred source code. Finally, the user must set MODEL_EXEDIR to point to the directory where the user wants the executable to be built and run.
The script can be divided into five functional sections: 1) specification of script environment variables; 2) creation of the model input namelist; 3) creation of two header files (misc.h and preproc.h) and a directory search path file (Filepath) needed to build the model executable; 4) creation of the model executable; and 5) execution of the model. Jobscript.csh is set up so that the user will normally only have to modify sections 1) and 2) in order to obtain a model executable and associated namelist. Each of these functional sections is discussed in what follows.
Table 4 lists the user modifiable script environment variables. Some of these variables are used by the Makefile to build the model executable. Although the script provides tentative settings for all these variables, the provided values will generally have to be modified by the user.
| Script Variable | Description |
| ROOTDIR | Full pathname for the root source code directory. |
| CSMDATA | Full pathname of root input datasets directory. |
| MODEL_EXEDIR | Full pathname for the directory where the model executable will reside. |
| Object files will be built in the directory $MODEL_EXEDIR/obj. | |
| NTHREADS | Number of OpenMP multitasking threads. If set to 1, environment variable SMP is set to FALSE and OpenMP threading is not invoked in the Makefile. NTHREADS should not exceed the number of physical CPUs (ie, processors) on a shared memory machine and should not exceed the number of CPUs in a node on a distributed memory machine |
| NTASKS | Number of MPI tasks. If set to 1, the environment variable SPMD is set to FALSE and distributed memory implementation is not invoked in the Makefile. If NTASKS is greater than 1, distributed memory is enabled. |
| LSMLON | Number of model grid longitudes. |
| LSMLAT | Number of model grid latitudes. |
| LIB_NETCDF | Full pathname of directory containing the netCDF library. |
| The setting depends on user's target machine. | |
| INC_NETCDF | Full pathname of directory containing netCDF include files. |
| The setting depends on user's target machine. | |
| LIB_MPI | Full pathname of directory containing the MPI library. |
| The setting depends on user's target machine. | |
| Only needed if ntasks larger than 1. | |
| INC_MPI | Full pathname for directory containing the MPI include files. |
| The setting depends on user's target machine. | |
| Only needed if ntasks is larger than 1. | |
| DEBUG | Turns debugging flags on in Makefile (valid values are TRUE or FALSE) |
To obtain a model executable, the environment variables LIB_NETCDF and INC_NETCDF, which provide pathnames to netCDF library and include files must be specified. Furthermore, if the model is to be run under MPI (i.e. NTASKS is greater than 1), then directories containing the MPI library and MPI include files must also be specified as environment variables in the script. (This is not the case on the IBM and the COMPAQ, where the MPI library and include files are obtained directly from the compiler command).
Before building and running the model, the user must specify model namelist variables via the namelist, clmexp. A default namelist is generated by jobscript.csh. This namelist results in the generation of a one day model run using the provided datasets. Namelist input is written to the file lnd.stdin and can be divided into several categories: run definitions, datasets, history and restart file settings and land model physics settings. A full discussion of model namelist variables is given in section 4.
The user will generally not need to modify the section of jobscript.csh that creates the header and directory search path files. The script creates three files in the directory $MODEL_EXEDIR/obj: the header files misc.h and preproc.h and the directory search path file, Filepath. To modify these files, the user should edit the file contents from within the script rather than attempt to edit the files directly, since the script will overwrite the files upon execution. The use of these files by gnumake is discussed in section 3.1.4. Each of these files is summarized below.
The file, misc.h, contains resolution- and model-independent C-language pre-processor (cpp) tokens
| misc.h cpp token | Description |
| SPMD | If defined, enables distributed memory, SPMD (single program multiple data), implementation. Automatically defined if environment variable NTASKS > 1. See section 3.1.1. |
| PERGRO | If defined, enables modifications that test reasonable perturbation error growth. Only applicable in cam mode (see CAM User's Guide). |
The file preproc.h contains resolution-dependent and model-dependent C-language cpp tokens
| preproc.h cpp token | Synopsis |
| OFFLINE | If defined, offline mode is invoked |
| COUP_CSM | If defined, ccsm mode is invoked |
| COUP_CAM | If defined, cam mode is invoked |
| LSMLON | Number of model longitudes |
| LSMLAT | Number of model latitudes |
| RTM | If defined, RTM river routing is invoked |
C-preprocessor directives of the form #include, #if defined, etc., are used in the model source code to enhance code portability and allow for the implementation of distinct blocks of functionality (such as incorporation of different modes) within a single file. Header files, such as misc.h and preproc.h, are included with #include statements within the source code. When gnumake is invoked, the C preprocessor includes or excludes blocks of code depending on which cpp tokens have been defined. C-preprocessor directives are also used to perform textual substitution for resolution-specific parameters in the code. The format of these tokens follows standard cpp protocol in that they are all uppercase versions of the Fortran variables, which they define. Thus, a code statement like
Filepath contains a list of directories used by Makefile to resolve the location of source files and to determine dependencies. The search begins in the current directory and proceeds to each directory appearing in Filepath, in the order in which they are specified. All files appearing in these directories will be used unless duplicate files are found. For the case of duplicate files, the first file found will be used by gnumake to create the object file. If user-modified code is introduced, Filepath should contain, as the first entry, the directory containing the user code.
Users can add new search directories by editing jobscript.csh under ``build Filepath''. The default Filepath directory hierarchy for CLM2.1 is as follows:
| Source Directories | Functionality |
| $MODEL_SRCDIR/main | control routines (history, restart, etc) |
| $MODEL_SRCDIR/biogeophys | biogeophysics routines |
| $MODEL_SRCDIR/ecosysdyn | ecosystem dynamics routines |
| $MODEL_SRCDIR/riverroute | river routing routines |
| $MODEL_SRCDIR/camclm_share | code shared between CAM and CLM2 |
| $MODEL_SRCDIR/csm_share | code shared by all CCSM geophysical model components |
| $MODEL_SRCDIR/utils/timing | timing routines |
| $MODEL_SRCDIR/mksrfdata | generation of surface dataset routines |
The user will generally not need to modify the section of jobscript.csh that builds the model executable. Jobscript.csh invokes gnumake to generate the model executable. The file, Makefile, located in the bld/offline directory, contains commands used by gnumake on each of the supported target architectures. Successful invocation of gnumake results in an executable, "clm", along with a log file, "compile_log.clm", documenting the build procedure. Any problems encountered during the build procedure will be documented in this log file. A parallel gnumake is achieved in the script by invoking gnumake with the -j option, which specifies the number of job commands to run in parallel.
The user will generally not need to modify the section of jobscript.csh that runs the model executable. Jobscript.csh will execute the commands required to run the model under the supported target architectures. The model runtime environment is determined by the script environment variables NTASKS and NTHREADS. If NTHREADS is greater than 1, OpenMp multitasking will be used for the number of threads specified. If NTASKS is greater than 1, the model will be run under MPI for the number of tasks specified. If both are greater than 1 (this should only be used for the IBM(SP) or the COMPAQ), then hybrid mode OpenMP/MPI will be used (see section 3.1.1).
Most MPI implementations provide a startup script which accepts the MPI executable as a command line argument. Additional command line arguments allow the user to specify details such as the various machine architectures or number of processes to use for the run. Once MPI has created the specified number of processes, model execution will begin. The collection of active tasks will then compute locally and exchange messages with each other to integrate the model.
Upon successful completion of the model run, several files will be generated in MODEL_EXEDIR. These include history, restart, and initialization files (see section 4.3) as well as log files documenting the model execution. These log files will have names of clm.log.YYMMDD-HHMMSS, where YY is the last two digits of the current model year, MM is the month, DD is the day of the month, HH is the hour, MM is the minutes, and SS is the seconds of the start of the model run. Timing files, (e.g. ``timing.0''), containing model performance statistics are also generated in the executable directory.