#-------------------------------------------------------------------------------sub validate_options {    my ($source, $opts) = @_;    my ($opt, $old, @expect);        # runtype    $opt = 'runtype';    @expect = ('initial', 'restart', 'branch');    if (defined $opts->{$opt}) {	$old = $opts->{$opt};	$opts->{$opt} = valid_option($old, @expect)	    or die "invalid value of $opt ($old) specified in $source\n".                   "expected one of: @expect\n";    }}__END__#-------------------------------------------------------------------------------# The following pod is used to produce the documentation for this script# which appears in the CAM User's Guide#-------------------------------------------------------------------------------=head4 2.1.2.2 The build-namelist scriptB<build-namelist> produces namelists for both CAM and CLM.  These arewritten to a single file (F<namelist> by default) in the directory fromwhich B<build-namelist> is invoked.  The only required input forB<build-namelist> is a configuration cache file produced by a previousinvocation of B<configure>.  The cache file provides information about theconfiguration of the CAM executable that B<build-namelist> needs to providethe correct default values for things like initial and boundary datasets.The default values are specified in the files F<DefaultCAMEXPNamelist.xml>and F<DefaultCLMEXPNamelist.xml> in the CAM configuration script directory.The user can specify namelist values that are not set by default, or canoverride the values that are set by default, in two ways.  A file thatcontains a namelist may be specified using the B<-infile> option, andnamelist values may be specified directly on the command-line using theB<-namelist> option.  The command-line specification takes precedence overvalues read from a file, and both take precedence over the default values.In addition a few namelist variables may be set with specific command-lineoptions and these settings take precedence over the values set usingB<-namelist> or B<-infile>.  There is also an interactive prompting option(B<-i>) which allows the user to view the namelist produced by the defaultand command-line settings, and make final changes.=head4 OptionsThe following options may all be specified with either one or two leadingdashes, e.g., B<-help> or B<--help>.  When multiple options are listedseparated by a vertical bar (B<|>), either version may be used.=over 4=item -cam_cfg F<dir>F<dir> is the directory that contains the CAM configuration scripts, whichincludes perl modules as well as various defaults files that are requiredby B<build-namelist>.  It is possible (but not recommended) to moveB<build-namelist> to another directory, but then the configuration scriptdirectory must be explicitly specified so that B<build-namelist> can findits support files.  Normally this directory will be determined by lookingat the pathname that is used to invoke B<build-namelist> (assuming thatB<build-namelist> has not been moved from the configuration scriptdirectory).  If B<build-namelist> is not in the configuration scriptdirectory, then that directory can be specified either by this option, bysetting the environment variable B<CAM_CFGDIR> to the configuration scriptdirectory, or by setting the environment variable B<CAM_ROOT> to the rootdirectory of the CAM distribution assuming that the configuration directoryis B<$CAM_ROOT/models/atm/cam/bld>.Default: directory part of the absolute pathname used to invokeB<build-namelist>=item -case F<name>F<name> is the case identifier for the CAM run (up to 32 characters).  Thisvalue is used to set the F<caseid> variable in the CAM namelist.Default: camrun=item -config F<file>F<file> is a configuration cache file produced by the B<configure> script.B<build-namelist> obtains the configuration of the CAM executable from thisfile.Default: F<config_cache.xml>=item -csmdata F<dir>F<dir> is the root directory for the default initial and boundary datasetssupplied with the CAM distribution.  This directory can also be specifiedby setting the CSMDATA environment variable.  It is assumed that the rootdirectory will contain the subdirectories F<atm/cam2> for CAM datasets andF<lnd/clm2> for CLM datasets.Default: F</fs/cgd/csm/inputdata>.  This value is set in the filesF<DefaultCAMEXPNamelist.xml> and F<DefaultCLMEXPNamelist.xml> in the CAMconfiguration script directory.=item -h | -helpPrint usage to STDOUT.=item -i | -interactiveTurns on interactive prompting to modify a namelist.=item -infile F<file>F<file> is a namelist file to read values from.  All values read from thisfile will appear in the output namelist unless they are overridden by othervalues having higher precedence.Default: none=item -namelist F<namelist>F<namelist> is a string that contains namelist settings using validnamelist syntax, e.g.,   -namelist "&camexp nelapse=-10, trace_gas=.true. /"Namelist values set on the command-line take precedence over values read from a file specified with the B<-infile> option.Default: none=item -o F<file>F<file> is the filename of the output namelist.Default: F<namelist>=item -runtype F<name>F<name> specifies the type of simulation.  Valid values are B<initial>,B<restart>, or B<branch>.Default: B<initial>=item -s | -silentTurns off all output to STDOUT.  Fatal error messages will still be issuedto STDERR.=item -testEnable checking that initial and boundary datasets exist on local filesystem.Default: no checking=item -v F<num>F<num> specifies the verbosity level of the output to STDOUT.  The default(1) echos only the name of the file produced by B<build-namelist>.  Level 2adds echoing of the results from the B<-test> option, and level 3 addsechoing of the default values read from the files in the CAM configurationscript directory.Default: 1=back=head4 Environment variablesThe environment variables recognized by B<build-namelist> are the following:=over 4=item CSMDATAThe root directory for the default initial and boundary datasets suppliedwith the CAM distribution.  It is assumed that the root directory willcontain the subdirectories F<atm/cam2> for CAM datasets and F<lnd/clm2> forCLM datasets.=item CAM_ROOTThe root directory of the CAM distribution.  The directory containing theconfiguration scripts is $CAM_ROOT/models/atm/cam/bld.=item CAM_CFGDIRThe directory that contains the CAM configuration scripts.  This isprovided only for the special case that the configuration scripts are takenfrom a directory outside of the CAM distribution.=back=head4 Using build-namelist from the command-lineThis section provides a few simple examples of using B<build-namelist> fromthe command-line and building a namelist using interactive prompt mode.=head4 Example 1: build a default namelistAssume the shell variable C<camcfg> is set to the CAM configurationdirectory and that B<configure> has been invoked to build a default CAMexecutable (Eulerian dynamics at T42).  The first time a namelist for aparticular CAM configuration is produced, we recommend using the B<-test>option which checks whether the initial and boundary datasets exist on alocal filesystem.  If they do not then a warning is issued to inform theuser which datasets must be copied to the directory from which CAM will berun.The invocation of B<build-namelist>,  % $camcfg/build-namelist -test  Write out namelist to: namelist produces the following default namelist:  &camexp   absems_data = '/fs/cgd/csm/inputdata/atm/cam2/rad/abs_ems_factors_fastvx.052001.nc'   bndtvo      = '/fs/cgd/csm/inputdata/atm/cam2/ozone/noaao3.1990.21999.nc'   bndtvs      = '/fs/cgd/csm/inputdata/atm/cam2/sst/sst_HadOIBl_bc_64x128_clim_c020411.nc'   caseid      = 'camrun'   iyear_ad    = 1950   ncdata      = '/fs/cgd/csm/inputdata/atm/cam2/inic/gaus/cami_0000-09-01_64x128_T42_L26_c020430.nc'   nelapse     = -1   nsrest      = 0  /	         &clmexp         finidat     = '/fs/cgd/csm/inputdata/lnd/clm2/inidata/cam/clmi_0000-09-01_64x128_T42_c020402.nc'   fpftcon     = '/fs/cgd/csm/inputdata/lnd/clm2/pftdata/pft-physiology'   fsurdat     = '/fs/cgd/csm/inputdata/lnd/clm2/srfdata/cam/clms_64x128_T42_c011120.nc'  /B<build-namelist> used the configuration cache file (F<config_cache.xml>)that was procuded by B<configure> to determine the dynamics package, landmodel, and resolution of the CAM executable.  This information was used tochoose the default initial and boundary datasets.  The default run type isan initial run (C<nsrest=0>), the run length is 1 day beyond the date ofthe initial conditions (C<nelapse=-1>), and the valid year for thecalculated orbital parameters is 1950 (C<iyear_ad=1950>).The absence of warnings from B<build-namelist> indicates that all the initial and boundary datasets were found on the local filesystem.=cut