============================================================================ 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 "&pop2_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 $CODEROOT/ocn/pop2/bld (throughout this document, $ALLCAPS denotes an environment variable while $nocaps denotes a perl variable) - is called as follows from $CASEBUILD/pop2.buildnml.csh build-namelist -infile $CASEBUILD/pop2conf/cesm_namelist || exit -1 (pop2.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_pop2" and "POP2 Use Cases" sections below for details) - depends on two files in $CODEROOT/ocn/pop2/bld/namelist_files 1. namelist_defaults_pop2.xml 2. namelist_definition_pop2.xml (see "namelist_definition_pop2.xml" and "namelist defaults.xml" sections below for details) - reads the file $CASEBUILD/pop2conf/config_cache.xml (created by pop2.cpl7.template); 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 pop2.buildnml.csh ============================================================================ user_nl_pop2 ============================================================================ ALL USER-SPECIFIED MODIFICATIONS TO THE POP2 NAMELIST SHOULD OCCUR AS ENTRIES IN $CASEROOT/user_nl_pop2. Simply append each variable entry to user_nl_pop2 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_pop2: dt_count = 14 bckgrnd_vdc = 0.3 After running build-namelist, the following will appear in pop2_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_pop2. (see "POP2 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 pop2.buildnml.csh which, among other things, makes sure that all entries in $CASEROOT/user_nl_pop2 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 pop2, 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_pop2 ah&hmix_del2t_nml = 0.7e7 lvariable_hmix&hmix_del2t = .true. After running build-namelist, the following will appear in pop2_in &hmix_del2t_nml ah = 0.7e7 ... lvariable_hmix = .true. / - a new utility, $CASEROOT/preview-namelist, will enable you to preview the pop2_in namelist in $CASEROOT/CaseDocs at any time ============================================================================ namelist_definition_pop2.xml ============================================================================ The file namelist_definition_pop2.xml is located in the directory $CODEROOT/ocn/pop2/bld/namelist_files/. It contains entries for all namelist variables that can be output by build-namelist. As mentioned in the "POP2 Use Cases" section below, a modified copy of this file (with the same name) may be placed in the directory $CASEROOT/SourceMods/src.pop2/. Otherwise the file appears in build-namelist as follows: $nl_definition_file = \ "$cfgdir/namelist_files/namelist_definition_pop2.xml"; Each namelist variable is defined in an 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 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: Number of processors in the baroclinic distribution. Default: Set by CESM scripts Any text that appears after the first > (after valid_values) and before the string is used for documentation purposes only. ============================================================================ namelist_defaults_pop2.xml ============================================================================ The file namelist_defaults_pop2.xml is located in the directory $CODEROOT/onc/pop2/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/pop2conf. 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_pop2.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 closed tripole tripole 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 POP2 config_cache.xml file, which is created by pop2.cpl7.template and can be found in the directory $CASEROOT/Builddconf/pop2conf/. 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_pop2.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_pop2.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 $SCRIPTSROOT/ccsm_utils/Tools/perl5lib/ perl files --- The root directory for the perl5 required utilities is my $perl5lib_dir = "${SCRIPTSROOT}/ccsm_utils/Tools/perl5lib"; This directory contains all the required perl files: 1. The XML::Lite module is required to parse the XML files. $perl5lib_dir/XML/Lite.pm 2. The Build::Config module provides utilities to access the configuration information in the config_cache.xml file $perl5lib_dir/Build/Config.pm 3. The Build::NamelistDefinition module provides utilities to validate that the output namelists are consistent with the namelist definition file $perl5lib_dir/Build/NamelistDefinition.pm 4. 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 5. 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_pop2.xml: cyclic namelist_definitions_pop2.xml: Type of boundary in the logical east-west direction for global domain. Valid Values: 'cyclic', 'closed' Default: 'cyclic' result in pop2_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_pop2.xml: closed tripole tripole namelist_definitions_pop2.xml: Type of boundary in the logical north-south direction for global domain. Valid Values: 'cyclic', 'closed', 'tripole' Default: 'closed' result in pop2_in if ocn_grid="gx1v6": &domain_nml ... ns_boundary_type = 'closed' ... / result in pop2_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_pop2.xml). build-namelist: add_default($nl, 'clinic_distribution_type', \ 'val'=>"$POP_DECOMPTYPE"); namelist_defaults_pop2.xml: The contents of namelist defaults does not matter, since a value is specified in build-namelist. namelist_definitions_pop2.xml: Method to use to distribute blocks in baroclinic distribution. Valid Values: 'cartesian', 'balanced', 'spacecurve', 'blockone' Default: 'cartesian' result in pop2_in if $POP_DECOMPTYPE="cartesian": &domain_nml clinic_distribution_type='cartesian' ... / result in pop2_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_pop2.xml (all one line in file): ocn/pop/tx0.1v2/grid/dzbc_pbc_s2.0_200709.ieeer8 namelist_definitions_pop2.xml: Input file for thickness of partial bottom cells. Default: 'unknown_bottom_cell' Note: this is done rather than just adding 'unknown_bottom_cell' to namelist_defaults_pop2.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). ============================================================================ POP2 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_pop2. As shown in the "user_nl_pop2" section above, one example is to set dt_count to 14 and bckgrnd_vdc to 0.3. The file $CASEROOT/user_nl_pop2 would then look as follows ... dt_count = 14 bckgrnd_vdc = 0.3 Note that all pop2 namelist variables can be changed in this manner, unless the same variable appears in multiple namelists. Those variables are listed in the "user_nl_pop2" section above. ---------------------------------------------------------------------------- Q: I have modified $CASEROOT/user_nl_pop2, 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 pop2_in) in $CASEROOT/CaseDocs. You can run this utility at any time. ---------------------------------------------------------------------------- Q: Rather than making the same changes to user_nl_pop2 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_pop2 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_pop2.xml file in $CODEROOT/ocn/pop2/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 0.33 to 0.375 This would result in the following new default setting in pop2_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 1000.0e02 to 2000.0e02 This would result in the following new default setting in pop2_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_pop2. 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_pop2 tavg_freq_opt = 'nday' 'nday' 'once' Note that these default values are set by ocn.base.tavg.csh in $CODEROOT/ocn/pop2/input_templates; to change the default values, edit this file. ---------------------------------------------------------------------------- Q: How do I add new pop2 namelist variables for just my case? A: Place a modified copy of namelist_definition_pop2.xml (that includes your new variables) in the $CASEROOT/SourceMods/src.pop2 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_pop2 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 $CODEROOT/ocn/pop2/bld/namelist_definition_pop2.xml to $CASEROOT/SourceMods/src.pop2 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): Default: '' 3. Add the following to $CASEROOT/user_nl_pop2 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 pop2 namelist variable to the pop2 code base? A: Again, we do not recommend editing files in $CODEROOT and instead ask that you follow the instructions above to use SourceMods/src.pop2/. However, if you must change the code in your sandbox, you would add new namelist variables by editting namelist_definition_pop2.xml directly in $CODEROOT/ocn/pop2/bld/namelist_files/. You may also want to update namelist_defaults_pop2.xml and build-namelist so your new value can be set automatically. Continuing the example above, we would add mlevy to namelist_defaults_pop2.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_pop2.xml (for this example, assume problem is of type logical) 2. Add this dependency to the namelist_defaults_pop2.xml file mlevy someone_else 3. Add the following lines to build_namelist_pop2 (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.pop2/ - this version will then be used by CESM. ---------------------------------------------------------------------------- Q: What happens with files that used to be placed in the directory $CASEROOT/SourceMods/src.pop2/? 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.pop2/ 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 pop2.buildexe.csh rather than calling ocn.${module}.setup.csh.