Include documentation for using templates in the experiment configuration file

docs/UsersGuide/source/CodeReposAndDirs.rst

@@ -42,15 +42,15 @@ repositories associated with this umbrella repo (see :numref:`Table %s <top_leve
    +---------------------------------+---------------------------------------------------------+
 
 The UFS Weather Model contains a number of sub-repositories used by the model as 
-documented `here <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/CodeOverview.html>`_.
+documented `here <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/CodeOverview.html>`__.
 
 Note that the prerequisite libraries (including NCEP Libraries and external libraries) are not
 included in the UFS SRW Application repository. The source code for these components resides in
 the repositories `NCEPLIBS <https://github.com/NOAA-EMC/NCEPLIBS>`_ and `NCEPLIBS-external
 <https://github.com/NOAA-EMC/NCEPLIBS-external>`_. 
 
 These external components are already built on the preconfigured platforms listed `here 
-<https://github.com/ufs-community/ufs-srweather-app/wiki/Supported-Platforms-and-Compilers>`_.
+<https://github.com/ufs-community/ufs-srweather-app/wiki/Supported-Platforms-and-Compilers>`__.
 However, they must be cloned and built on other platforms according to the instructions provided
 in the wiki pages of those repositories: https://github.com/NOAA-EMC/NCEPLIBS/wiki and
 https://github.com/NOAA-EMC/NCEPLIBS-external/wiki.

docs/UsersGuide/source/ConfigNewPlatform.rst

@@ -4,7 +4,7 @@
 Configuring a New Platform
 ==========================
 
-The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, as specified `here <https://github.com/ufs-community/ufs-srweather-app/wiki/Supported-Platforms-and-Compilers>`_. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s <SW-OS-Requirements>`.
+The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, as specified `here <https://github.com/ufs-community/ufs-srweather-app/wiki/Supported-Platforms-and-Compilers>`__. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s <SW-OS-Requirements>`.
 
 The first step to installing on a new machine is to install :term:`NCEPLIBS` (https://github.com/NOAA-EMC/NCEPLIBS), the NCEP libraries package, which is a set of libraries created and maintained by NCEP and EMC that are used in many parts of the UFS. NCEPLIBS comes with a large number of prerequisites (see :numref:`Section %s <SW-OS-Requirements>` for more info), but the only required software prior to starting the installation process are as follows:
 
@@ -170,7 +170,7 @@ If you are using your machine’s built-in MPI compilers, it is recommended you
 
    export CMAKE_Platform=macosx.gnu
 
-This is the variable used by the weather model to set a few additional flags based on your machine. The available options can be found `here <https://github.com/ufs-community/ufs-weather-model/tree/release/public-v2/modulefiles>`_. 
+This is the variable used by the weather model to set a few additional flags based on your machine. The available options can be found `here <https://github.com/ufs-community/ufs-weather-model/tree/release/public-v2/modulefiles>`__. 
 
 Now all the prerequisites have been installed and variables set, so you should be ready to build the model!
 
@@ -211,8 +211,7 @@ Once the data has been staged, setting up your experiment on a platform without
 ``MACHINE="MACOS" or MACHINE="LINUX"``
   These are the two ``MACHINE`` settings for generic, non-Rocoto-based platforms; you should choose the one most appropriate for your machine. ``MACOS`` has its own setting due to some differences in how command-line utilities function on Darwin-based operating systems.
 
-``LAYOUT_X=2``
-``LAYOUT_Y=2``
+``LAYOUT_X=2, LAYOUT_Y=2``
   These are the settings that control the MPI decomposition when running the weather model. There are default values, but for your machine it is recommended that you specify your own layout to achieve the correct number of MPI processes for your application.  In total, your machine should be able to handle ``LAYOUT_X×LAYOUT_Y+WRTCMP_write_tasks_per_group`` tasks. ``WRTCMP_write_tasks_per_group`` is the number of MPI tasks that will be set aside for writing model output, and it is a setting dependent on the domain you have selected. You can find and edit the value of this variable in the file ``regional_workflow/ush/set_predef_grid_params.sh``.
 
 ``RUN_CMD_UTILS="mpirun -np 4"``

docs/UsersGuide/source/InputOutputFiles.rst

@@ -31,7 +31,7 @@ from a location on disk to your experiment directory by the workflow generation
 pre-processing utilities use many different datasets to create grids, and to generate model
 input datasets from the external model files.  A detailed description of the input files
 for the pre-processing utilities can be found `here 
-<https://noaa-emcufs-utils.readthedocs.io/en/ufs-v2.0.0/>`_.
+<https://noaa-emcufs-utils.readthedocs.io/en/ufs-v2.0.0/>`__.
 
 UFS Weather Model
 -----------------
@@ -41,14 +41,14 @@ must be staged by the user unless you are running on a pre-configured platform,
 you can link to the existing copy on that machine. See :numref:`Section %s <StaticFixFiles>`
 for more information. The static, grid, and date specific files are linked in the experiment
 directory by the workflow scripts. An extensive description of the input files for the weather
-model can be found in the `UFS Weather Model User's Guide <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/>`_.
+model can be found in the `UFS Weather Model User's Guide <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/>`__.
 The namelists and configuration files for the SRW Application are created from templates by the
 workflow, as described in :numref:`Section %s <WorkflowTemplates>`.
 
 Unified Post Processor (UPP)
 ----------------------------
 Documentation for the UPP input files can be found in the `UPP User's Guide
-<https://upp.readthedocs.io/en/upp-v9.0.0/InputsOutputs.html>`_.
+<https://upp.readthedocs.io/en/upp-v9.0.0/InputsOutputs.html>`__.
 
 .. _WorkflowTemplates:
 
@@ -110,7 +110,7 @@ and are shown in :numref:`Table %s <TemplateFiles>`.
 
 Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``,
 ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide
-<https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#input-files>`_,
+<https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#input-files>`__,
 while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide
 <https://noaa-emcufs-utils.readthedocs.io/en/ufs-v2.0.0/>`_.
 
@@ -162,7 +162,7 @@ experiment run directory ``EXPTDIR/YYYYMMDDHH/INPUT`` and consist of the followi
 * ``sfc_data.nc -> sfc_data.tile7.halo0.nc``
 
 These output files are used as inputs for the UFS weather model, and are described in the `Users Guide 
-<https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#grid-description-and-initial-condition-files>`_.
+<https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#grid-description-and-initial-condition-files>`__.
 
 UFS Weather Model
 -----------------
@@ -182,11 +182,11 @@ the file names are specified in the input file ``model_configure`` and are set t
 * ``phyfHHH.nc``
 
 Additional details may be found in the UFS Weather Model `Users Guide
-<https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#output-files>`_.
+<https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#output-files>`__.
 
 Unified Post Processor (UPP)
 ----------------------------
-Documentation for the UPP output files can be found `here <https://upp.readthedocs.io/en/upp-v9.0.0/InputsOutputs.html>`_.
+Documentation for the UPP output files can be found `here <https://upp.readthedocs.io/en/upp-v9.0.0/InputsOutputs.html>`__.
 
 For the SRW Application, the weather model netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH/postprd``
 directory and have the naming convention (file->linked to):
@@ -205,7 +205,7 @@ located in ``ufs-srweather-app/src/EMC_post/parm``.
 .. note::
    This process requires advanced knowledge of which fields can be output for the UFS Weather Model.
 
-Use the directions in the `UPP User's Guide <https://upp.readthedocs.io/en/upp-v9.0.0/InputsOutputs.html#control-file>`_
+Use the directions in the `UPP User's Guide <https://upp.readthedocs.io/en/upp-v9.0.0/InputsOutputs.html#control-file>`__
 for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that
 the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default).
 
@@ -240,7 +240,7 @@ where the static files are located. If you are on a pre-configured or configurab
 need to stage the fixed files manually because they have been prestaged and the paths
 are set in ``regional_workflow/ush/setup.sh``. If the user's platform is not defined
 in that file, the static files can be pulled individually or as a full tar file from the `FTP data repository
-<https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/fix/>`_ or from `Amazon Web Services (AWS) cloud storage
+<https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/fix/>`__ or from `Amazon Web Services (AWS) cloud storage
 <https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/fix/fix_files.tar.gz>`_
 and staged on your machine. The paths to the staged files must then be set in ``config.sh``
 as follows:
@@ -268,7 +268,7 @@ not have access to the NOAA HPSS and you need to pull and stage the data manuall
 set ``USE_USER_STAGED_EXTRN_FILES`` to ``TRUE`` and then set the paths to the where the IC/LBC files are located. 
 
 A small sample of IC/LBCs is available at the `FTP data repository
-<https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/gst_model_data.tar.gz>`_ or from `AWS cloud storage
+<https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/gst_model_data.tar.gz>`__ or from `AWS cloud storage
 <https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/ic/gst_model_data.tar.gz>`_.
 
 Initial and Lateral Boundary Condition Organization

docs/UsersGuide/source/Introduction.rst

@@ -53,20 +53,20 @@ Forecast Model
 The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere
 (:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:`BlackEtAl2020`.
 The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s
-Guide for the UFS :term:`Weather Model` is `here <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/>`_. 
+Guide for the UFS :term:`Weather Model` is `here <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/>`__. 
 
 Supported model resolutions in this release include a 3-, 13-, and 25-km predefined Contiguous
 U.S. (CONUS) domain, all with 64 vertical levels. Preliminary tools for users to define their
 own domain are also available in the release with full, formal support of these tools to be
 provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM,
 which features relatively uniform grid cells across the entirety of the domain. Additional
 information about the FV3 dynamical core can be found `here 
-<https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html>`_ and on the `NOAA Geophysical
+<https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html>`__ and on the `NOAA Geophysical
 Fluid Dynamics Laboratory website <https://www.gfdl.noaa.gov/fv3/>`_.
 
 Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP)
 Land Surface Model options, are supported through the Common Community Physics Package
-(:term:`CCPP`; described `here <https://dtcenter.org/community-code/common-community-physics-package-ccpp>`_).
+(:term:`CCPP`; described `here <https://dtcenter.org/community-code/common-community-physics-package-ccpp>`__).
 Atmospheric physics are a set of numerical methods describing small-scale processes such
 as clouds, turbulence, radiation, and their interactions. There are two physics options
 supported for the release. The first is an experimental physics suite being tested for use

docs/UsersGuide/source/SRWAppOverview.rst

@@ -191,7 +191,7 @@ Case-specific Configuration
 .. _DefaultConfigSection:
 
 Default configuration: ``config_defaults.sh``
---------------------------------------------
+---------------------------------------------
 When generating a new experiment (described in detail in :numref:`Section %s <GeneratingWflowExpt>`),
 the ``config_defaults.sh`` file is read first and assigns default values to the experiment
 parameters. Important configuration variables in the ``config_defaults.sh`` file are shown in 
@@ -408,7 +408,7 @@ Generating a Regional Workflow Experiment
 =========================================
 
 Steps to a Generate a New Experiment
-----------------------------------
+------------------------------------
 Generating an experiment requires running
 
 .. code-block:: console
@@ -454,7 +454,7 @@ when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own so
 ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files
 ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls.
 There is usually no need for users to modify these files. To relaunch the workflow from scratch,
-delete these two *.db files and then call the launch script repeatedly for each task. 
+delete these two \*.db files and then call the launch script repeatedly for each task. 
 
 .. _WorkflowTasksFig:
 

docs/UsersGuide/source/TemplateVars.rst

@@ -0,0 +1,50 @@
+.. _TemplateVars:
+
+==============================================================
+Using Template Variables in the Experiment Configuration Files
+==============================================================
+The SRW App's experiment configuration system supports the use of template variables
+in ``config_defaults.sh`` and ``config.sh``.  A template variable --- or, more briefly,
+a "template" --- is an experiment configuration variable that contains in its definition
+references to values of other variables.  If the template is defined properly as
+described below (in particular, with single quotes), then these references will **not**
+be expanded (i.e. set to the values of the referenced variables) at the time the
+experiment's variable definitions file (``var_defns.sh``) is generated or sourced.
+Instead, they will be expanded and evaluated **at run time**, i.e. whenever bash's
+``eval`` built-in command is used on the template.  The script or function that will
+evaluate the template must first source ``var_defns.sh`` (to define the template and
+possibly also variables referenced by it), then ensure that any variables referenced
+by the template that are not already defined in ``var_defns.sh`` get defined locally,
+and only then call ``eval`` to evaluate the template.
+
+As an example, consider a template named ``MY_CMD`` that is defined in ``config_defaults.sh``
+(or redefined by the user in ``config.sh``) as follows:
+
+   .. code-block:: none
+
+     MY_CMD='cd ${some_dir}'
+
+Here, ``some_dir`` may be an experiment variable defined in ``var_defns.sh`` or a
+local variable defined in a script or function that will evaluate the template.  Note
+that it is important to use single quotes on the right-hand side of the definition above;
+otherwise, bash will try to evaluate ``${some_dir}`` when constructing ``var_defns.sh``,
+which may result in an error and/or unexpected behavior (e.g. if ``${some_dir}`` is not
+yet defined).  The experiment generation system will define ``MY_CMD`` in ``var_defns.sh``
+in exactly the same way as in ``config_defaults.sh`` and/or ``config.sh``, e.g.
+``MY_CMD='cd ${some_dir}'``.  Then the following code snippet in a script or function
+will evaluate the contents of ``MY_CMD`` using a locally-set value of ``some_dir``:
+
+   .. code-block:: none
+
+     ...
+     . var_defns.sh       # Source the experiment's variable definitions file (assuming
+                          # it is in the current directory).  This defines the MY_CMD
+                          # template variable (in addition to other variables).
+     ...
+     some_dir="20200715"  # Set the local variable some_dir.
+     ...
+     eval ${MY_CMD}       # Use eval to evaluate the contents of MY_CMD.  The value of
+                          # some_dir specified in this file a few lines above is substituted
+                          # for ${some_dir} in MY_CMD before MY_CMD is evaluated.
+     ...
+

docs/UsersGuide/source/WE2Etests.rst

@@ -1,4 +1,4 @@
-.. _WE2E_tests:
+.. _WE2Etests:
 
 ================================
 Workflow End-to-End (WE2E) Tests

docs/UsersGuide/source/index.rst

@@ -15,6 +15,7 @@ UFS Short-Range Weather App Users Guide
    CodeReposAndDirs
    SRWAppOverview
    ConfigWorkflow
+   TemplateVars
    LAMGrids
    InputOutputFiles
    ConfigNewPlatform