============================================================================
Synopsis
============================================================================

SYNOPSIS
     build-namelist [options]
OPTIONS
     -infile "filepath"    Specify a file containing namelists to read values from.
     -namelist "namelist"  Specify namelist settings directly on the commandline by supplying 
                           a string containing FORTRAN namelist syntax, e.g.,
                              -namelist "&cism_nml dt=1800 /"
     -help [or -h]         Print usage to STDOUT.
     -silent [-s]          Turns on silent mode - only fatal messages issued.
     -verbose              Turn on verbose echoing of informational messages.
     -caseroot             CASEROOT directory variable
     -cimeroot             CIMEROOT directory variable
     -inst_string          INST_STRING variable
     -lnd_grid             LND_GRID variable
     -glc_grid             GLC_GRID variable
     -cism_phys            CISM_PHYS variable

The precedence for setting the values of namelist variables is (highest to
lowest): 
  1. namelist values set by specific command-line options, e.g., paramfile
  2. values set on the command-line using the -namelist option
  3. values read from the file specified by -infile 
  4. values from the namelist defaults file or values specifically set in
     build-namelist 


============================================================================
Summary of build-namelist
============================================================================

build-namelist 

  - exists in $SRCROOT/components/cism/bld (throughout this document, 
    $ALLCAPS denotes an xml variable while $nocaps denotes a perl variable)
  
  - is called from $CASEBUILD/cism.buildnml

    (cism.buildnml is now just a wrapper to build-namelist)

  - allows the user to edit existing namlist variables or introduce new
    variables if that is desired
    (see "user_nl_cism" and "CISM Use Cases" sections below for details)

  - depends on two files in $SRCROOT/components/cism/bld/namelist_files

      1. namelist_defaults_cism.xml
      2. namelist_definition_cism.xml

    (see "namelist_definition_cism.xml" and "namelist defaults.xml" sections
    below for details)

  - is invoked upon every build -AND- upon every call to cism.buildnml


============================================================================
user_nl_cism
============================================================================

ALL USER-SPECIFIED MODIFICATIONS TO THE CISM NAMELIST AND CISM.CONFIG FILE
SHOULD OCCUR AS ENTRIES IN $CASEROOT/user_nl_cism. Simply append each
variable entry to user_nl_cism prior to running build-namelist. Note that
there is no distinction in user_nl_cism between variables that will appear
in cism_in and those that will appear in cism.config: simply add a new
variable setting in user_nl_cism, and it will be added to the appropriate
place in cism_in or cism.config.

For example, to set the value of cism_debug to .true. and basal_tract to the
array (/1,2,3,4,5/), include the following in user_nl_cism:

  cism_debug = .true.
  basal_tract = 1 2 3 4 5

After running build-namelist, the following will appear in cism_in:

  &cism_params
    ...
    cism_debug = .true.
    ...
  /

and the following will appear in cism.config:

  [parameters]
  basal_tract = 1 2 3 4 5  
  ...


A new utility in $CASEROOT, preview-namelist, will enable you to preview the
cism_in namelist and cism.config file in $CASEROOT/CaseDocs at any time


============================================================================
namelist_definition_cism.xml
============================================================================

The file namelist_definition_cism.xml is located in the directory
$SRCROOT/components/cism/bld/namelist_files/. It contains entries for all namelist
variables that can be output by build-namelist.

As mentioned in the "CISM Use Cases" section below, a modified copy of this
file (with the same name) may be placed in the directory
$CASEROOT/SourceMods/src.cism/. Otherwise the namelist definition file
appears in build-namelist as follows:

  $nl_definition_file = \
      "$cfgdir/namelist_files/namelist_definition_cism.xml";

Each namelist variable is defined in an <entry> element.  The content of the
element is the documentation of how the variable is used.  Other aspects of
the variable's definition are expressed as attributes of the <entry> 
element.  Note that it is an XML requirement that the attribute values are
enclosed in quotes.  The attributes are:

  1. id
     The variable's name. Although Fortran is case insensitive, the name 
     MUST BE LOWER CASE for the perl scripts.

  2. type
     An abbreviation of the Fortran declaration for the variable. Valid
     declarations are:

       char*n
       integer
       logical
       real

     Any of these types may be followed by a comma separated list of
     integers enclosed in parenthesis to indicate an array. The current
     namelist validation code only distinguishes between string and 
     non-string types.

    All namelist values are stored in exactly the format that is required
    in a valid namelist, so if that value is a string then the quotes are
    stored as part of the value. 

  3. category
     A category assigned for organizing the documentation.

  4. group
     The name of the namelist (or group) that the variable is declared
     in. Some groups will appear in cism_in; others (by convention, those
     whose names begin with 'cism_config') will appear in cism.config.

  5. valid_values (optional)
     This attribute is mainly useful for variables that have only a small
     number of allowed values; an empty string denotes no restrictions,
     as does omitting the valid_values attribute entirely.

  6. input_pathname (optional)
     Only include this attribute to indicate that the variable contains the
     pathname of an input dataset that resides in the CESM inputdata 
     directory tree. The recognized values are "abs" to indicate that an
     absolute pathname is required or "rel:var_name" to indicate that the
     pathname is relative and that the namelist variable "var_name" contains
     the absolute root directory.

The following is an example entry for the dt_option variable:

   <entry id="dt_option" 
   type="char*80" 
   category="time"
   group="time_manager_nml" 
   valid_values="steps_per_year,steps_per_day,seconds,hours,">
   time-step units
   </entry>

Any text that appears after the first > (after valid_values) and before the
</entry> string is used for documentation purposes only. In the example 
above, "time-step units" is ignored by build-namelist.


============================================================================
namelist_defaults_cism.xml
============================================================================

The file namelist_defaults_cism.xml is located in the directory
$SRCROOT/components/cism/bld/namelist_files/. It provides default values for
variables contained in the input namelist definition file. 

The build-namelist script is passed the glc_grid, lnd_grid and cism_phys
attributes as command-line arguments. These attributes, along with optional
user-specified attributes, are used in build-namelist to find the best match
when looking for default values of variables.

In build-namelist the namelist defaults file appears as follows

  $nl_defaults_file = "$cfgdir/namelist_files/namelist_defaults_cism.xml";

The default namelist value for a given namelist variable is the one that
matches the most attributes; if multiple values match the same number of
attributes then the first value encountered will be chosen. For example,
consider the namelist variable ewn. Its entry in the defaults file is

   <ewn glc_grid="gland10" >151</ewn>
   <ewn glc_grid="gland20" >76</ewn>
   <ewn glc_grid="gland5"  >301</ewn>
   <ewn glc_grid="gland5UM">301</ewn>

The default value of ewn therefore depends on the value of glc_grid.

Not all namelist items have defaults specified in
namelist_defaults_cism.xml. Those that don't have a default value there have
their default value set in build-namelist. This applies, for example, to
namelist items whose default value is derived from other variables (e.g.,
'runid' is taken from the case name, and so does not have a default in
namelist_defaults_cism.xml).


============================================================================
build-namelist details
============================================================================

--- Overview of four main perl objects ---

build-namelist has four perl objects that it uses

  1. $cfg
     A configuration object obtained from the CISM config_cache.xml
     file. This specifies the glc and land grid resolutions.

       my $cfg = Build::Config->new('config_cache.xml');

  2. $definition
     A namelist definition object which provides a method for verifying that
     the output namelist variables are in the definition file and are output
     in the correct namelist groups.

       my $definition = Build::NamelistDefinition->new($nl_definition_file);

  3. $defaults
     A namelist defaults object which provides default values for variables
     contained in the namelist_definition_cism.xml file.

       my $defaults = Build::NamelistDefaults->new($nl_defaults_file, $cfg);

     Note that both $nl_defaults_file and $cfg are passed - this is why the
     glc_grid, lnd_grid and cism_phys attributes do not need to be passed to
     add_defaults() (see "Examples" subsection below)

  4. $nl
     An empty namelist object which contains the model namelist values
     (where the values are determined by the order of precedence outlined
     in the "Synopsis" section above)

       my $nl = Build::Namelist->new();

--- Required $CIMEROOT/utils/perl5lib perl files  ---

The root directory for the perl5 required utilities is

  my $perl5lib_dir = ${CIMEROOT}/utils/perl5lib";

This directory contains all the required perl files:

  1. The Build::Config module provides utilities to access the configuration
     information in the config_cache.xml file

       $perl5lib_dir/Build/Config.pm

  2. The Build::NamelistDefinition module provides utilities to validate
     that the output namelists are consistent with the namelist definition
     file

       $perl5lib_dir/Build/NamelistDefinition.pm

  3. The Build::NamelistDefaults module provides a utility to obtain default
     values of namelist variables based on finding a best fit with the
     attributes specified in the defaults file.

       $perl5lib_dir/Build/NamelistDefaults.pm

  4. The Build::Namelist module provides utilities to parse input namelists,
     to query and modify namelists, and to write output namelists.

       $perl5lib_dir/Build/Namelist.pm

--- Creation of $nl ---

Additions to the namelist object, $nl, are made via calls to the
build-namelist method add_default(), which adds a value for the specified
variable to the specified namelist object.  This method checks the
definition file and adds the variable to the correct namelist group. The
value can be provided by using the optional argument key 'val' in the
calling list, otherwise a default value is obtained from the namelist
defaults object. If no default value is found this method throws an
exception unless the 'nofail' option is set to 1 (true).

Additional optional keyword=>value pairs may be specified.  If the keyword
'val' is not present, then any other keyword=>value pairs that are specified
will be used to match attributes in the defaults file.

The variables already in the object have the higher precedence, so if the
specified variable is already defined in the object it does not get
overwritten.

In some cases, a namelist variable only appears in the namelist if its value
is given by the user in user_nl_cism. For these variables, the default value
is given in the code rather than in namelist_defaults_cism.xml. This is
achieved by NOT putting an add_default call for this variable in
build-namelist.

--- Examples ---

  1. Use the default value for namelist variable cism_debug

     build-namelist:

       add_default($nl, 'cism_debug');

     namelist_defaults_cism.xml:

       <cism_debug>.false.</cism_debug>

     namelist_definitions_cism.xml:

       <entry id="cism_debug" 
       type="logical" 
       category="cism" 
       group="cism_params" 
       valid_values="">
       Default: false
       </entry>

     result in cism_in:

     &cism_params
       ...
       cism_debug = .true.
       ...
     /


  2. Set the value for the namelist variable ewn, which depends on the value
     of "glc_grid" in the config_cache.xml file. Note that the value of
     "glc_grid" does not need to be explicitly passed.

     build-namelist:

       add_default($nl, 'ewn');

     namelist_defaults_cism.xml:

       <ewn glc_grid="gland10" >151</ewn>
       <ewn glc_grid="gland20" >76</ewn>
       <ewn glc_grid="gland5"  >301</ewn>
       <ewn glc_grid="gland5UM">301</ewn>

     namelist_definitions_cism.xml:

       <entry 
       id="ewn" 
       type="integer" 
       category="cism_config"
       group="cism_config_grid" >
       </entry>

     result in cism.config if glc_grid="gland5":

     [grid]
     ...
     ewn = 301
     ...

     result in cism.config if glc_grid="gland10":

     [grid]
     ...
     ewn = 151
     ...


  3. Set the value for the namelist variable runid to $CASE

     build-namelist:

       add_default($nl, 'runid', 'val'=>"$CASE");

     namelist_defaults_cism.xml:

       The contents of namelist defaults does not matter, since a value is
       specified in build-namelist.

     namelist_definitions_cism.xml:

       <entry id="runid" 
       type="char*128" 
       category="time"
       group="time_manager_nml" 
       valid_values="">
       Simulation identifier (ie case name)
       </entry>

     result in cism_in if $CASE="mycase":

       &time_manager_nml
         ...
         runid = 'mycase'
         ...
       /


  4a. Add a default for variable $var if an appropriate value is found,
      otherwise do not include $var in the namelist

      build-namelist:

        add_default($nl, $var, 'nofail'=>1)

  4b. Set the value for the namelist variable $var, but do not prepend it
      with a directory prefix.

      build-namelist:

        add_default($nl, $var, 'noprepend'=>1)

  5. Only include the namelist variable 'calving_fraction' in cism.config if a
     value is given by the user in user_nl_cism; otherwise, use default value
     given in the code

     (No references to calving_fraction in build-namelist)

============================================================================
Handling multiple instances
============================================================================

When NINST_GLC > 1, there are multiple instances of CISM (i.e., an
ensemble). Each instance has its own namelist, and its own cism.config file.

In this case, there is no user_nl_cism. Instead, there is one such file for
each instance: user_nl_cism_0001, user_nl_cism_0002, etc. User modifications
in user_nl_cism_0001 will be put in cism_in_0001 or cism.config_0001, and
similarly for user_nl_cism_0002, etc. If there are modifications to cism_in
or cism.config that you want to make for all instances, you must put these
modifications in ALL of the user_nl_cism files (user_nl_cism_0001,
user_nl_cism_0002, etc.).

Note that one of the namelist items in cism_in is 'paramfile', which gives
the name of the cism.config file. For simplicity, this namelist item is
specified by a command-line option from the script calling build-namelist,
and cannot be overridden by users. In the single instance case, cism_in
specifies a paramfile of 'cism.config'. In the multi-instance case,
cism_in_0001 specifies a paramfile of 'cism.config_0001', cism_in_0002
specifies a paramfile of 'cism.config_0002', etc.


============================================================================
CISM Use Cases
============================================================================

Q: How do I add my own case-specific namelist variable changes?

A: For each namelist variable, just add a line of the form

     namelist_var = namelist_val
   
   to $CASEROOT/user_nl_cism. As shown in the "user_nl_cism" section above,
   one example is to set cism_debug to .true. and basal_tract to the array
   (/1,2,3,4,5/). The file $CASEROOT/user_nl_cism would then look as follows

     ...
     cism_debug = .true.
     basal_tract = 1 2 3 4 5

   All cism namelist variables, as well as entries in cism.config, can be
   changed in this manner.

----------------------------------------------------------------------------

Q: Rather than making the same changes to user_nl_cism over and over, can
   I change the default values used by build-namelist?

A: Yes, you can modify the namelist_defaults_cism.xml file in
   $SRCROOT/components/cism/bld/namelist_files to change the default values. For
   example:

   1. If you want to change geothermal from -5.e-2 to -6.e-2, you
      would change

        <geothermal>-5.e-2</geothermal>

      to

        <geothermal>-6.e-2</geothermal>

      This would result in the following new default setting in cism.config:

        [parameters]
        ...
        geothermal = -6.e-2
        ...

   2. If you want to change ntem from 1. to 2. for runs using the gland5
      grid, without affecting the value for any other grid, you would change
   
        <ntem glc_grid="gland5"  >1.</ntem>

      to

        <ntem glc_grid="gland5"  >2.</ntem>
   
      This would result in the following new default setting in cism.config:

        [time]
        ...
        ntem = 2.
        ...

      for any runs with GLC_GRID=gland5, while not changing the value for
      other grids.

----------------------------------------------------------------------------

Q: How do I add new cism namelist variables for just my case?

A: Place a modified copy of namelist_definition_cism.xml (that includes your
   new variables) in the $CASEROOT/SourceMods/src.cism directory. You do
   not need to modify build-namelist or the defaults file, just set the
   appropriate values for the new variables in $CASEROOT/user_nl_cism file.

   For example, to add a variable the_answer to the cism.config parameters
   and set it equal to 42, you would take the following steps:

     1. Copy $CODEROOT/glc/cism/bld/namelist_definition_cism.xml to
        $CASEROOT/SourceMods/src.cism

     2. Add the following (it can be added anywhere as long as it isn't in a
        comment, but for consistency put it in the "group: cism.config:
        parameters" block):

          <entry 
          id="the_answer"
          type="integer"
          category="cism_config"
          group="cism_config_parameters" >
          The answer to the question of life, the universe and everything
          </entry>

     3. Add the following to $CASEROOT/user_nl_cism

          the_answer=42

     Note that you will also need to include a SourceMod to read in this
     new variable, otherwise you will get a runtime error!

----------------------------------------------------------------------------

Q: How do I add a new cism namelist variable to the cism code base?

A: Follow the instructions above, but rather than editing a copy in
   SourceMods/src.cism, edit namelist_definition_cism.xml directly in
   $CODEROOT/glc/cism/bld/namelist_files. You may also want to update
   namelist_defaults_cism.xml and build-namelist so your new value can be
   set automatically. Continuing the example above, we would add

     <the_answer>42</the_answer>

   to namelist_defaults_cism.xml and

     add_default($nl, 'the_answer');

   to build-namelist. Again, note that this will build a namelist with the
   new variable, but you will need to update the source code to read it!

----------------------------------------------------------------------------

Q: How do I introduce a new namelist variable that has dependencies on other
   namelist variables?

A: You can pass values through the add_default() function. As above, suppose
   we want to introduce a new variable 'the_answer'. Let's also introduce a
   new variable named 'is_binary'. To have gatekeeper_id depend on
   is_binary, we do the following.

     1. Add is_binary and the_answer to namelist_definitions_cism.xml (for
        this example, assume is_binary is of type logical)

     2. Add this dependency to the namelist_defaults_cism.xml file

          <the_answer is_binary=".false.">42</the_answer>
          <the_answer is_binary=".true.">101010</the_answer>

     3. Add the following lines to build-namelist (note that is_binary must
        be set before the_answer)

          add_default($nl, 'is_binary', 'val'=>".false.");
          my $is_binary = $nl->get_value('is_binary');
          add_default($nl, 'the_answer', 'is_binary'=>"$is_binary");


   Note that strings can not have spaces in the XML; to remove spaces
   from a Perl variable use the following prior to sending it through
   add_default as a dependency
 
     $varname =~ s/ //g;
    
----------------------------------------------------------------------------

Q: How do I add an optional section in the cism.config file? There are some
   CISM settings that depend on the mere presence / absence of a certain
   section.

A: An existing example of this is the [GTHF] section. If this section is
   present in the config file, then certain code is enabled, controlled by
   the variables in this section. The following changes were needed to
   create this optional section; this is also what you'll have to do to
   create a new optional section:

   1. Added a do_gthf variable in
      namelist_files/namelist_definition_cism.xml, with
      group="cism_config_control":

        <entry id="do_gthf"
        type="logical"
        category="cism_config_gthf"
        group="cism_config_control" >
        Determines whether the GTHF (geothermal heat flux) section is output to the cism.config file.
        Default: false
        </entry>

      Also added a corresponding default value in
      namelist_files/namelist_defaults_cism.xml:

        <do_gthf>.false.</do_gthf>

   2. Added a new section in namelist_files/namelist_definition_cism.xml
      that lists all of the possible variables that might appear in that
      section. See the section with the heading "group: cism.config: GTHF
      (geothermal heat flux)".

      Note that the variables in this section do NOT appear in
      namelist_defaults_cism.xml. Thus, if a user sets do_gthf to
      .true. without specifying the values of any of these variables, they
      will take their values from the hard-coded defaults in the cism code.

   3. Added some code in build-namelist that controls whether to print the
      [GTHF] section in the cism.config file:

        # Some code in cism keys off of whether the [GTHF] section is present
        # (even if it's empty), thus we only want to add this section if it's
        # really desired by the user
        add_default($nl, 'do_gthf');
        if ($nl->get_value('do_gthf') eq '.true.') {
            print $fh "\n[GTHF]\n";
            $nl->write_cism_config($fh, "cism_config_gthf");
        }
        else {
            confirm_empty("cism_config_gthf", "items in gthf section can only be set if do_gthf is set to .true.");
        }


      Note that, if defaults were desired (specified in
      namelist_defaults_cism.xml), add_default lines could be added in the
      'if' block of the above conditional, before the call to
      write_cism_config.

   
