============================================================================ 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 -scriptsroot SCRIPTSROOT directory variable -inst_string INST_STRING variable -lnd_grid LND_GRID variable -glc_grid GLC_GRID 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 $CODEROOT/glc/cism/bld (throughout this document, $ALLCAPS denotes an environment or xml variable while $nocaps denotes a perl variable) - is called from $CASEBUILD/cism.buildnml.csh (cism.buildnml.csh 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 $CODEROOT/glc/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.csh ============================================================================ 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 $CODEROOT/glc/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 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 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: time-step units Any text that appears after the first > (after valid_values) and before the 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 $CODEROOT/glc/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 and lnd_grid 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 151 76 301 301 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 and lnd_grid 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 $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_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: .false. namelist_definitions_cism.xml: Default: false 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: 151 76 301 301 namelist_definitions_cism.xml: 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: Simulation identifier (ie case name) 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 'asthenosphere' 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 asthenosphere 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 $CODEROOT/glc/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 -5.e-2 to -6.e-2 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 1. to 2. 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): The answer to the question of life, the universe and everything 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 42 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 42 101010 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": Determines whether the GTHF (geothermal heat flux) section is output to the cism.config file. Default: false Also added a corresponding default value in namelist_files/namelist_defaults_cism.xml: .false. 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.