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), and a namelist file for control of dry deposition which is shared by CAM and CLM (in the file drv_flds_in).
The task of constructing a correct namelist has become extremely complex due to the large number of configurations supported by CAM. Editing namelists by hand is an extremely fragile process due to the number of variables that need to be set, and to the many interdependencies among them. We do not recommend editing namelists by hand. All customizations of the CAM namelist are possible by making use of the build-namelist command line options.
Some of the important features of build-namelist are:
All valid namelist variables are known to build-namelist. So an invalid
variable specified by the user (supplied either by the
-namelist options) will cause
build-namelist to fail with an error message telling which namelist
variable is invalid. This is a big improvement over a runtime failure
caused by an invalid variable which typically gives no hint as to which
variable caused the problem.
In addition to knowing all valid variable names and their
types, build-namelist also knows which namelist group each variable belongs to.
This means that the user only needs to specify variable names to build-namelist
and not the group names. The
-namelist options still require valid namelist syntax
as input, but the group name is ignored. So all variables can be put
in a single group with an arbitrary name, for example, "&xxx ... /".
Since build-namelist knows all namelist variables specified by the user it is able to do consistency checking. In general however, build-namelist assumes that the user is the expert and will not override a user specification unless there is a major inconsistency, for example if variables have been set to use parameterizations which can not be run at the same time.
All configurations have namelist variables that must be specified, and build-namelist has a mechanism to provide default values for these variables. When an appropriate default value cannot be found then build-namelist will fail with an informative message.
When running a configuration for the first time there are often many input
datasets that may not be in the local input data directory. In order to
facilitate getting the required datasets build-namelist has an
-test, that can be used to produce a complete list
of required datasets and report status of whether or not they are present
in the local directory. This list can then be used to obtain the needed
datasets from the CESM SVN input data repository.
One 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 other required input for build-namelist is the root directory for the input
datasets. This is required since nearly all input files must be specified
using absolute filepaths, but the defaults are stored as filepaths which
are relative to the root directory. It is expected that the actual
location of the root directory is something that will be resolved at
runtime. The way this is done is to either specify it using
-csmdata argument, or to set the environment variable
The methods for setting the values of namelist variables, listed from highest to lowest precedence, are:
using specific command-line options,
setting values in a file specified by
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
--help. The few
options that can be expressed as single letter switches may not be clumped,
-h -s -v may NOT be expressed
-hsv. When multiple options are listed separated by a
vertical bar either version may be used.
Case identifier up to 80 characters. This value is used to set the
case_name variable in the driver namelist. Default:
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
Read the specified configuration cache file to determine the configuration of the CAM executable. Default: config_cache.xml.
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.
Root directory of CESM input data.
Can also be set by using the
CSMDATA environment variable.
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 | -h
Print usage to STDOUT.
Ignore the date attribute of the initial condition files when determining the default.
Ignore just the year part of the date attribute of the initial condition files when determining the default.
Specify a file containing namelists to read values from.
Writes out a list of pathnames for required input datasets to the specified file.
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 /"
Specify the number of MPI tasks to be used by the run. This is only used to set a default decomposition for the FV dycore, i.e., the npr_yz variable.
Type of simulation. Default:
-silent | -s
Turns on silent mode - only fatal messages issued.
Enable 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.
Specify a use case.
-verbose | -v
Turn on verbose echoing of informational messages.
Echo the source code repository tag name used to check out this CAM distribution.