Chapter 4. Building a Case

Table of Contents
Input data
Build-time variables
Compiler settings
User-modified source code
Building the executable
Rebuilding the executable

After configuring a case, the model executable can be built by running $CASE.$MACH.build which will:

  1. create the component namelists in $RUNDIR ($EXEROOT/run) by calling the Buildconf/ scripts $component.buildnml.csh.

  2. check for the required input data sets and download missing data automatically on local disk, and if successful proceed to the following steps.

  3. create the necessary utility libraries by calling the Buildconf/ scripts mct.buildlib, pio.buildlib and csm_share.buildlib.

  4. create the necessary component libraries by calling the Buildconf/ scripts $component.buildexe.csh.

  5. create the model executable by calling the Buildconf/ scripts ccsm.buildexe.csh.

Note: $CASEROOT/Tools/Makefile and $CASEROOT/Macros.$MACH are used to generate all necessary utility and component libraries and the model executable.

A user does not need to change the default build settings to create the executable. However, the CESM scripts provide the user with a great deal of flexibility in customizing various aspects of the build process. It is therefore useful for a user to become familiar with these in order to make optimal use of the system.

Input data

All active and data components use input datasets. A local disk needs to be populated with input data in order to run CESMwith these components. For all machines, input data is provided as part of the release via data from a subversion input data server. However, on supported machines (and some non-supported machines), data already exists in the default local-disk input data area (as specified by $DIN_LOC_ROOT_CSMDATA (see below).

Input data is handled by the build process as follows:

The following variables in env_run.xml determine where you should expect input data to reside on local disk and how this input data will be handled during the run.

DIN_LOC_ROOT_CSMDATA

The root directory of CESM input data for the selected machine. Usually a shared disk area.

DIN_LOC_ROOT

The inputdata area used for the current case. Normally, this is set to DIN_LOC_ROOT_CSMDATA but the system provides flexibility for a user to specify a distinct directory. This might be needed on certain machines if the user needs to have the input data reside in a special disk area associated with the executable directory or the batch nodes, rather than in the default local disk directory.

DIN_LOC_ROOT_CLMQIAN

CLM-specific root directory for CLM QIAN type input forcing data. This directory will only be used for I (CLM/DATM) compsets.

PRESTAGE_DATA

Allows the case input data root directory (DIN_LOC_ROOT) to differ from the machine's root input data directory (DIN_LOC_ROOT_CSMDATA).

If PRESTAGE_DATA is FALSE (the default) then DIN_LOC_ROOT will be set to DIN_LOC_ROOT_CSMDATA.

If PRESTAGE_DATA is TRUE, then DIN_LOC_ROOT will be set to EXEROOT/inputdata. In addition, data will be copied from DIN_LOC_ROOT_CSMDATA to DIN_LOC_ROOT before the model builds. The input data in EXEROOT/inputdata will then be used for the model run.

User-created input data

If you want to use new user-created dataset(s), give these dataset(s) names that are different than the names in $DIN_LOC_ROOT. The best way to access these user-specified datasets is to use the script $CCSMROOT/scripts/link_dirtree. link_dirtree creates a virtual copy of the input data directory by linking one directory tree to another. The full directory structure of the original directory is duplicated and the files are linked. Invoke the following for usage:


> cd $CCSMROOT/scripts
> link_dirtree -h

link_dirtree can be conveniently used to generate the equivalent of a local copy of $DIN_LOC_ROOT_CSMDATA which can then be populated with user-specified input datasets. For example, you can first generate a virtual copy of $DIN_LOC_ROOT_CSMDATA in /user/home/newdata with the following command:


> link_dirtree $DIN_LOC_ROOT_CSMDATA /user/home/newdata

then incorporate the new dataset(s) directly into the appropriate directory in /user/home/newdata.

Important:: If you place a new dataset for $component in /user/home/newdata, then Buildconf/$component.buildnml.csh and Buildconf/$component.input_data_list must be modified to point to this new dataset.

Using the input data server

The script $CASEROOT/check_input_data determines if the required data files for the case exist on local disk in the appropriate subdirectory of $DIN_LOC_ROOT_CSMDATA. If any of the required datasets do not exist locally, check_input_data provides the capability for downloading them to the $DIN_LOC_ROOT_CSMDATA directory hierarchy via interaction with the input data server. You can independently verify that the required data is present locally by using the following commands:


> cd $CASEROOT
> check_input_data -help
> check_input_data -inputdata $DIN_LOC_ROOT_CSMDATA -check

If input data sets are missing, you must obtain the datasets from the input data server:


> cd $CASEROOT
> check_input_data -inputdata $DIN_LOC_ROOT_CSMDATA -export

Required data files not on local disk will be downloaded through interaction with the Subversion input data server. These will be placed in the appropriate subdirectory of $DIN_LOC_ROOT_CSMDATA. For what to expect when interacting with a Subversion repository, see downloading input data.