============================================================================
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 
                           command line by supplying 
                           a string containing FORTRAN namelist syntax, 
                           e.g.  -namelist "&pop_nml dt=27 /"
     -help [or -h]         Print usage to STDOUT.
     -test                 Enable checking that input datasets exist on 
                           local filesystem.
     -verbose              Turn on verbose echoing of informational 
                           messages.

The precedence for setting the values of namelist variables is (highest to
lowest): 
  1. namelist values set by specific command-line options (none right now)
  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 

By default, only fatal messages will be output to screen and build-namelist
will not check to see if input datasets exist on the local filesystem.
Further, build-namelist looks for environment variables that are set by
other CESM scripts (such as create_newcase or create_clone), so running
build-namelist from the command line will result in an error.


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

build-namelist 

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

      build-namelist -infile $CASEBUILD/popconf/cesm_namelist || exit -1

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

  - allows the user to edit existing namelist variables or introduce new
    ones if that is desired
    (see "user_nl_pop" and "POP Use Cases" sections below for details)

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

      1. namelist_defaults_pop.xml
      2. namelist_definition_pop.xml

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

  - reads the file $CASEBUILD/popconf/config_cache.xml 
    currently this file only contains ocean grid 
    information.  The grid resolution is used to determine appropriate 
    defaults for resolution-dependent namelist inputs
    (see "build-namelist details" section below for details)

  - is invoked upon every build -AND- upon every call to pop.buildnml.csh


============================================================================
user_nl_pop
============================================================================

ALL USER-SPECIFIED MODIFICATIONS TO THE POP NAMELIST SHOULD OCCUR AS
ENTRIES IN $CASEROOT/user_nl_pop. Simply append each variable entry
to user_nl_pop prior to running build-namelist. For example, to set the
value of dt_count to 14 and bckgrnd_vdc to 0.3, include the following in
user_nl_pop:

  dt_count = 14
  bckgrnd_vdc = 0.3

After running build-namelist, the following will appear in pop_in

  &time_manager_nml
    ...
    dt_count = 14
    ...
  /
  ...
  &vmix_rich_nml
    bckgrnd_vdc = 0.3
    ...
  /

It is important to note that, for the most part, build-namelist knows what
namelist each variable belongs to; except for the variables mentioned below
in the Notes subsection, you do not need to include that in user_nl_pop.
(see "POP Use Cases" at the end of this guide for more examples)


Notes:

  - As seen in the "Summary of build-namelist" section above, the only input
    to build-namelist is a file named cesm_namelist. There is a tool called
    from pop.buildnml.csh which, among other things, makes sure that all
    entries in $CASEROOT/user_nl_pop are put in cesm_namelist

  - Some variable names can show up in multiple namelists. For example:

    1. ah appears in hmix_del4t_nml, hmix_del2t_nml, and hmix_gm_nml
    2. am appears in hmix_del4u_nml and hmix_del2u_nml
    3. lauto_hmix appears in hmix_del4t_nml, hmix_del2t_nml, hmix_del4u_nml,
       and hmix_del2u_nml
    4. lvariable_hmix appears in hmix_del4t_nml, hmix_del2t_nml, 
       hmix_del4u_nml, and hmix_del2u_nml
    5. rich_mix appears in vmix_rich_nml and vmix_kpp_nml

    The CESM scripts' perl modules assume that each namelist variable has a
    unique name. To work around this condition for pop, the following
    "derived" namelist variables were introduced

      ah&hmix_del4t_nml
      ah&hmix_del2t_nml
      ah&hmix_gm_nml  
      am&hmix_del4u_nml
      am&hmix_del2u_nml  
      lauto_hmix&del4t_nml
      lauto_hmix&del2t_nml
      lauto_hmix&del4u_nml
      lauto_hmix&del2u_nml
      lvariable_hmix&del4t_nml
      lvariable_hmix&del2t_nml
      lvariable_hmix&del4u_nml
      lvariable_hmix&del2u_nml
      rich_mix&vmix_rich_nml
      rich_mix&vmix_kpp_nml

    If the user wants to change the values of ah and lvariable_hmix in the
    namelist hmix_del2t to 0.7e7 and .true., respectively, he/she needs to
    add the following lines to user_nl_pop

      ah&hmix_del2t_nml = 0.7e7
      lvariable_hmix&hmix_del2t = .true.

    After running build-namelist, the following will appear in pop_in
      
       &hmix_del2t_nml
          ah                  = 0.7e7
          ...
          lvariable_hmix      = .true.
       /

  - a new utility, $CASEROOT/preview-namelist, will enable you to preview
    the pop_in namelist in $CASEROOT/CaseDocs at any time

   
============================================================================
namelist_definition_pop.xml
============================================================================

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

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

  $nl_definition_file = \
      "$cfgdir/namelist_files/namelist_definition_pop.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 parentheses 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.

  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 nprocs_clinic variable:

   <entry 
      id="nprocs_clinic" 
      type="integer" 
      category="decomp" 
      group="domain_nml" >
      Number of processors in the baroclinic distribution.

      Default: Set by CESM scripts
   </entry>

Any text that appears after the first > (after valid_values) and before the
</entry> string is used for documentation purposes only.


============================================================================
namelist_defaults_pop.xml
============================================================================

The file namelist_defaults_pop.xml is located in the directory
$SRCROOT/components/pop/bld/namelist_files/. It provides default values for
variables contained in the input namelist definition file. As mentioned in
the "Summary of build-namelist" section above, build-namelist reads the
ocn_grid attribute from config_cache.xml in $CASEBUILD/popconf. This
attribute, along with optional user-specified attributes, is used in
build-namelist to find the best match when looking for default values of
variables.

In build-namelist the file appears as follows:

  $nl_defaults_file = "$cfgdir/namelist_files/namelist_defaults_pop.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 ns_boundary_type. Its entry in the defaults
file is

    <ns_boundary_type>closed</ns_boundary_type>
    <ns_boundary_type ocn_grid="tx1v1"  >tripole</ns_boundary_type>
    <ns_boundary_type ocn_grid="tx0.1v2">tripole</ns_boundary_type>

The default value of ns_boundary_type will is "tripole" if the ocn_grid is
either tx1v1 or tx0.1v2 (because one attribute will be matched), otherwise
it will be set to 'closed' (because no attributes will match and 'closed'
is the first value listed).


============================================================================
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 POP config_cache.xml file,
     which is created by pop.cpl7.template and can be found in the 
     directory $CASEROOT/Builddconf/popconf/. Currently this only specifies
     the grid resolution.

       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 namelist_definition_pop.xml 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_pop.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
     ocn_grid attribute does not need to be passed to add_defaults()
     (see the "Creation of $nl" and "Examples" subsections 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_defaults(), 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.

--- Examples ---

  1. Use the default value for namelist variable ew_boundary_type.

     build-namelist:

       add_default($nl, 'ew_boundary_type');

     namelist_defaults_pop.xml:

       <ew_boundary_type>cyclic</ew_boundary_type>

     namelist_definitions_pop.xml:

       <entry
       id="ew_boundary_type"
       type="char*256"
       category="decomp"
       group="domain_nml"
       valid_values="cyclic,closed" >
       Type of boundary in the logical east-west direction for global domain.

       Valid Values: 'cyclic', 'closed'
       Default: 'cyclic'
       </entry>

     result in pop_in:

     &domain_nml
       ...
       ew_boundary_type = 'cyclic'
       ...
     /

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

     build-namelist:

       add_default($nl, 'ns_boundary_type');

     namelist_defaults_pop.xml:

       <ns_boundary_type>closed</ns_boundary_type>
       <ns_boundary_type ocn_grid="tx1v1"  >tripole</ns_boundary_type>
       <ns_boundary_type ocn_grid="tx0.1v2">tripole</ns_boundary_type>

     namelist_definitions_pop.xml:

       <entry
       id="ns_boundary_type"
       type="char*256"
       category="decomp"
       group="domain_nml"
       valid_values="cyclic,closed,tripole" >
       Type of boundary in the logical north-south direction for global domain.

       Valid Values: 'cyclic', 'closed', 'tripole'
       Default: 'closed'
       </entry>

     result in pop_in if ocn_grid="gx1v6":

     &domain_nml
       ...
       ns_boundary_type = 'closed'
       ...
     /

     result in pop_in if ocn_grid="tx1v1":

     &domain_nml
       ...
       ns_boundary_type = 'tripole'
       ...
     /

  3. Set the value for the namelist variable clinic_distribution_type to
     the value of the environment variable $POP_DECOMPTYPE (environment
     variables are not used in namelist_defaults_pop.xml).

     build-namelist:

       add_default($nl, 'clinic_distribution_type', \
                   'val'=>"$POP_DECOMPTYPE");

     namelist_defaults_pop.xml:

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

     namelist_definitions_pop.xml:

       <entry 
       id="clinic_distribution_type" 
       type="char*256" 
       category="decomp" 
       group="domain_nml" 
       valid_values="cartesian,balanced,spacecurve,blockone" >
       Method to use to distribute blocks in baroclinic distribution.

       Valid Values: 'cartesian', 'balanced', 'spacecurve', 'blockone'
       Default: 'cartesian'
       </entry>

     result in pop_in if $POP_DECOMPTYPE="cartesian":

       &domain_nml
         clinic_distribution_type='cartesian'
         ...
       /

     result in pop_in if $POP_DECOMPTYPE="spacecurve":

       &domain_nml
         clinic_distribution_type='spacecurve'
         ...
       /

  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. These two options are used together in instances where a dataset is
      only available for a subset of grids. For example, bottom_cell_file is
      specified for the tx0.1v2 grid; for all other grids, we want to set
      bottom_cell_file='unknown_bottom_cell'.

      build-namelist:

        add_default($nl, 'bottom_cell_file', 'nofail'=>1)
        if ($nl->get_value('bottom_cell_file')) {
          # DO NOTHING
        } else {
          add_default($nl, 'bottom_cell_file', \
                      'val'=>'unknown_bottom_cell','noprepend'=>1);
        }

      namelist_defaults_pop.xml (all one line in file):

        <bottom_cell_file ocn_grid="tx0.1v2">
          components/pop/tx0.1v2/grid/dzbc_pbc_s2.0_200709.ieeer8
        </bottom_cell_file>

      namelist_definitions_pop.xml:
 
        <entry
        id="bottom_cell_file"
        type="char*256"
        category="grid"
        group="grid_nml"
        input_pathname="abs" >
        Input file for thickness of partial bottom cells.

        Default: 'unknown_bottom_cell'
        </entry>

      Note: this is done rather than just adding 'unknown_bottom_cell' to
            namelist_defaults_pop.xml because the latter would result in
            the string '$DIN_LOC_ROOT/unknown_bottom_cell' being entered
            into the namelist (due to the input_pathname="abs" field in the
            definition above).


============================================================================
POP 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_pop. As shown in the "user_nl_pop" section above,
   one example is to set dt_count to 14 and bckgrnd_vdc to 0.3. The file 
   $CASEROOT/user_nl_pop would then look as follows

     ...
     dt_count = 14
     bckgrnd_vdc = 0.3

   Note that all pop namelist variables can be changed in this manner,
   unless the same variable appears in multiple namelists. Those variables
   are listed in the "user_nl_pop" section above.

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

Q: I have modified $CASEROOT/user_nl_pop, but I want to see the namelist
   to make sure everything looks okay before building. How do I do this?

A: The utility $CASEROOT/preview-namelist will generate copies of all the
   namelists (including pop_in) in $CASEROOT/CaseDocs. You can run this
   utility at any time.

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

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

A: We do not recommend changing the default values directly in the code, so
   the official answer is that you should keep a copy of user_nl_pop with
   your preferred defaults and use that for each case. However, if you are
   adamant about changing the defaults in your own sandbox, it is possible.
   To do so, you can modify the namelist_defaults_pop.xml file in
   $SRCROOT/components/pop/bld/namelist_files to change the default values. For
   example:

   1. If you want to change local_mixing_fraction from 0.33 to 0.375, you
      would change

        <local_mixing_fraction>0.33</local_mixing_fraction>

      to

        <local_mixing_fraction>0.375</local_mixing_fraction>

      This would result in the following new default setting in pop_in:

        &tidal_nml
          local_mixing_fraction = 0.375
          ...
        /

   2. If you want to change bckgrnd_vdc_dpth for 1000.0e02 to 2000.0e02 for
      runs using the gx1v6 grid, without affecting the value for any other
      grid, you would change
   
        <bckgrnd_vdc_dpth ocn_grid="gx1v6">1000.0e02</bckgrnd_vdc_dpth>

      to

        <bckgrnd_vdc_dpth ocn_grid="gx1v6">2000.0e02</bckgrnd_vdc_dpth>
   
      This would result in the following new default setting in pop_in:

        &vmix_kpp_nml
          ...
          bckgrnd_vdc_dpth = 2000.0e02
          ...
        /

      for any _g16 resolutions while not changing the value for other grids.
      Again, keep in mind that this is a dangerous practice, especially if
      you share your sandbox with others and they expect the usual default
      values to be set.

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

Q: How do I change the default values of streams associated with an existing
   passive tracer?

A: Stream variables can be changed by simply editing the contents of
   user_nl_pop.

   For example - for gx3v7 and gx1v6, the default values of tavg_freq and
   tavg_freq_opt are

      tavg_freq = 1 1 1
      tavg_freq_opt = 'nmonth' 'nday' 'once'

   To switch from monthly values to daily values for the first stream, add
   the following to $CASEROOT/user_nl_pop

      tavg_freq_opt = 'nday' 'nday' 'once'

   Note that these default values are set by ocn.base.tavg.csh in 
   $SRCROOT/components/pop/input_templates; to change the default values, edit 
   this file.

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

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

A: Place a modified copy of namelist_definition_pop.xml (that includes your
   new variables) in the $CASEROOT/SourceMods/src.pop 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_pop file.

   For example, to add a variable gatekeeper_id to &domain_nml and set it
   equal to 'mlevy', you would take the following steps:

     1. Copy $SRCROOT/components/pop/bld/namelist_definition_pop.xml to
        $CASEROOT/SourceMods/src.pop

     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 domain_nml"
        block):

          <entry 
          id="gatekeeper_id"
          type="char*256"
          category="pop"
          group="domain_nml" >
          Default: ''
          </entry>

     3. Add the following to $CASEROOT/user_nl_pop

          gatekeeper_id = 'mlevy'

     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 pop namelist variable to the pop code base?

A: Again, we do not recommend editing files in $SRCROOT and instead ask
   that you follow the instructions above to use SourceMods/src.pop/.
   However, if you must change the code in your sandbox, you would add new
   namelist variables by editting namelist_definition_pop.xml directly in
   $SRCROOT/components/pop/bld/namelist_files/. You may also want to update
   namelist_defaults_pop.xml and build-namelist so your new value can be
   set automatically. Continuing the example above, we would add

     <gatekeeper_id>mlevy</gatekeeper_id>

   to namelist_defaults_pop.xml and

     add_default($nl, 'gatekeeper_id');

   to build-namelist. As above, 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 'gatekeeper_id'. Let's also introduce
   a new variable named 'problem'. To have gatekeeper_id depend on problem,
   we add do the following.

     1. Add problem and gatekeeper_id to namelist_definitions_pop.xml (for
        this example, assume problem is of type logical)

     2. Add this dependency to the namelist_defaults_pop.xml file

          <gatekeeper_id problem=".false.">mlevy</gatekeeper_id>
          <gatekeeper_id problem=".true.">someone_else</gatekeeper_id>

     3. Add the following lines to build_namelist_pop (note that problem
        must be set before gatekeeper_id)

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

        Note that strings cannot 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 change the contents of ${ocn_grid}_tavg_contents for my
   experiment?

A: Simply place your modified version of the ${ocn_grid}_tavg_contents file
   in $CASEROOT/SourceMods/src.pop/ - this version will then be used by
   CESM.

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

Q: What happens with files that used to be placed in the directory
   $CASEROOT/SourceMods/src.pop/?

A: There is no change to this functionality. For example, you can still
   place a modified copy of ${ocn_grid}_transport_contents in the directory
   $CASEROOT/SourceMods/src.pop/ and it will used by CESM (the namelist
   variable diag_transport_file will be point to a copy of the modified
   file).

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

Q: Are they any other notable changes in the build system?

A: Yes, the number of tracers (NT) is now a variable passed in when POP is
   compiled, rather than being stored a file. Additionally, NT is set in
   pop.buildexe.csh rather than calling ocn.${module}.setup.csh.
