The build-namelist utility builds namelists (and on occasion other types of input files) which specify run-time details for CAM and the components it's running with in standalone mode. When executed from the CESM scripts it only produces a namelist file for the CAM component (in the file atm_in). 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 file $CAM_ROOT/models/atm/cam/bld/namelist_files/namelist_defaults_cam.xml, and in the use case files located in the directory $CAM_ROOT/models/atm/cam/bld/namelist_files/use_cases/.
The methods for setting the values of namelist variables, listed from highest to lowest precedence, are:
using specific command-line options,
i.e., -case and -runtype,
using the -namelist option,
setting values in a file specified by -infile,
specifying a -use_case option,
setting values in the namelist defaults file.
The first four of these methods for specifying namelist variables are the ones available to the user without requiring code modification. Any namelist variable recognized by CAM can be modified using method 2 or 3. The final two methods represent defaults that are hard coded as part of the code base.
To get a list of all available options, type build-namelist --help. Available options are also listed just below.
The following options may all be specified with either one or two leading
dashes, e.g., -help or --help. The few
options that can be expressed as single letter switches may not be clumped,
e.g., -h -s -v may NOT be expressed
as -hsv. When multiple options are listed separated by a
vertical bar either version may be used.
-case <name>
Case identifier up to 80 characters. This value is used to set the
case_name variable in the driver namelist. Default: camrun
-cice_nl <namelist>
Specify namelist settings for CICE directly on the commandline by supplying
a string containing FORTRAN namelist syntax, e.g.,
-cice_nl "&ice histfreq=1 /".
This namelist will be passed to the invocation of the CICE build-namelist
via its -namelist argument.
-config <filepath>Read the specified configuration cache file to determine the configuration of the CAM executable. Default: config_cache.xml.
-config_cice <filepath>Filepath of the CICE config_cache file. This filepath is passed to the invocation of the CICE build-namelist. Only specify this to override the default filepath which was set when the CICE configure was invoked by the CAM configure.
-csmdata <dir>
Root directory of CCSM input data.
Can also be set by using the CSMDATA environment variable.
-dir <dir>Directory where output namelist files for each component will be written, i.e., atm_in, drv_in, ice_in, lnd_in and ocn_in. Default: current working directory.
-help | -hPrint usage to STDOUT.
-ignore_ic_dateIgnore the date attribute of the initial condition files when determining the default.
-ignore_ic_yearIgnore just the year part of the date attribute of the initial condition files when determining the default.
-infile <filepath>Specify a file containing namelists to read values from.
-inputdata <filepath>Writes out a list of pathnames for required input datasets to the specified file.
-namelist <namelist>Specify namelist settings directly on the commandline by supplying a string containing FORTRAN namelist syntax, e.g., -namelist "&atm stop_option='ndays' stop_n=10 /"
-runtype
[startup|continue|branch]
Type of simulation. Default: startup.
-silent | -sTurns on silent mode - only fatal messages issued.
-testEnable checking that input datasets exist on local filesystem. This is also a convenient way to generate a list of the required input datasets for a model run.
-use_case <name>Specify a use case.
-verbose | -vTurn on verbose echoing of informational messages.
-versionEcho the source code repository tag name used to check out this CAM distribution.