2.2 The build-namelist utility

The build-namelist utility builds namelists which specify run-time details for CAM and CLM. These are written to a single file (by default, the file namelist in the directory from which build-namelist is invoked).

The only required input for build-namelist is a configuration cache file produced by a previous invocation of configure (./config_cache.xml by default). build-namelist looks at this file to determine the features of the CAM executable, such as the dynamical core and horizontal resolution, that affect the default specifications for namelist variables. The default values themselves are specified in the files DefaultCAMEXPNamelist.xml and DefaultCLMEXPNamelist.xml in the CAM configuration script directory.

The user can specify namelist values that are not set by default, or can override the values that are set by default, in a number of ways. The method with highest precedence is to use the specific command-line options indicated in Table 2.3. The next highest precedence is given to any values set on the command-line using the -namelist option. Finally, at the lowest precedence, the default values are used. There is also an interactive prompting option (-i) which allows the user to view the namelist produced by the default and command-line settings, and make final changes.

2.2.1 Options to build-namelist

To get a list of all available options, type build-namelist -help. Available options are also provided here in Table 2.3.

All options may be specified with either one or two leading dashes, e.g., -help or -help. When multiple options are listed separated by a vertical bar (|), either version may be used.

Table 2.3: Command line arguments to build-namelist

Option Name	Description	Default
-cam_cfg dir	dir is the directory that contains the CAM configuration scripts, which includes perl modules as well as various defaults files that are required by build-namelist. It is possible (but not recommended) to move build-namelist to another directory, but then the configuration script directory must be explicitly specified so that build-namelist can find its support files. Normally this directory will be determined by looking at the pathname that is used to invoke build-namelist (assuming that build-namelist has not been moved from the configuration script directory). If build-namelist is not in the configuration script directory, then that directory can be specified either by this option, by setting the environment variable CAM_CFGDIR to the configuration script directory, or by setting the environment variable CAM_ROOT to the root directory of the CAM distribution assuming that the configuration directory is $CAM_ROOT/models/atm/cam/bld.	directory part of the absolute pathname used to invoke build-namelist
-case name	name is the case identifier for the CAM run (up to 32 characters). This value is used to set the caseid variable in the CAM namelist.	camrun
-config file	file is a configuration cache file produced by the configure script. build-namelist obtains the configuration of the CAM executable from this file.	config_cache.xml
-csmdata dir	dir is the root directory for the default initial and boundary datasets supplied with the CAM distribution. This directory can also be specified by setting the CSMDATA environment variable. It is assumed that the root directory will contain the subdirectories atm/cam2 for CAM datasets and lnd/clm2 for CLM datasets.	/fs/cgd/csm/ inputdata. This value is set in the files DefaultCAMEXPNamelist.xml and DefaultCLMEXPNamelist.xml in the CAM configuration script directory.
-h | -help	Print usage to STDOUT.
-i | -interactive	Turns on interactive prompting to modify a namelist.
-infile file	file is a namelist file to read values from. All values read from this file will appear in the output namelist unless they are overridden by other values having higher precedence.	none
-namelist namelist	namelist is a string that contains namelist settings using valid namelist syntax, e.g., -namelist "&camexp nelapse=-10, empty_htapes=.true. /" Namelist values set on the command-line take precedence over values read from a file specified with the -infile option.	none
-o file	file is the filename of the output namelist.	namelist
-runtype name	name specifies the type of simulation. Valid values are initial, restart, or branch.	initial
-s | -silent	Turns off all output to STDOUT. Fatal error messages will still be issued to STDERR.
-test	Enable checking that initial and boundary datasets exist on local filesystem.	no checking
-v num	num specifies the verbosity level of the output to STDOUT. The default (1) echos only the name of the file produced by build-namelist. Level 2 adds echoing of the results from the -test option, and level 3 adds echoing of the default values read from the files in the CAM configuration script directory.	1

2.2.2 Environment variables used by build-namelist

The environment variables recognized by build-namelist are presented in Table 2.4.

Table 2.4: Environment variables used by build-namelist

Variable Name	Description
CSMDATA	The root directory for the default initial and boundary datasets supplied with the CAM distribution. It is assumed that the root directory will contain the subdirectories atm/cam2 for CAM datasets and lnd/clm2 for CLM datasets.
CAM_ROOT	The root directory of the CAM distribution. The directory containing the configuration scripts is $CAM_ROOT/models/atm/cam/bld.
CAM_CFGDIR	The directory that contains the CAM configuration scripts. This is provided only for the special case that the configuration scripts are taken from a directory outside of the CAM distribution.