[develop]: Add Tutorial Chapter for the SRW App (#556)

This PR adds a Tutorial chapter to the SRW App (and several plotting/png files, which makes this PR look much bigger than it is!). The Tutorial chapter outlines 5 severe weather cases. A complete tutorial is available for the first case. The hope is to fill out the others with each new SRW App release. To supplement the tutorial, a document on SSH access and data transfer was added to help users download plots from an HPC/cloud system to their local device. Additionally, a few Glossary updates were needed for the tutorial, as well as minor corrections to the plotting/TemplateVars explanations.

2023-02-02 NOTE:
This commit has been re-written to remove binary image files from the repository.

---------

Co-authored-by: gspetro <[email protected]>

docs/UsersGuide/source/ConfigWorkflow.rst

@@ -410,7 +410,7 @@ A standard set of environment variables has been established for *nco* mode to s
    Only *community* mode is fully supported for this release. *nco* mode is used by those at the Environmental Modeling Center (EMC) and Global Systems Laboratory (GSL) who are working on pre-implementation operational testing. Other users should run the SRW App in *community* mode. 
 
 ``envir, NET, model_ver, RUN``:
-   Standard environment variables defined in the NCEP Central Operations WCOSS Implementation Standards document. These variables are used in forming the path to various directories containing input, output, and workflow files. The variables are defined in the `WCOSS Implementation Standards <https://www.nco.ncep.noaa.gov/idsb/implementation_standards/ImplementationStandards.v11.0.0.pdf?>`__ document (pp. 4-5) as follows:
+   Standard environment variables defined in the NCEP Central Operations WCOSS Implementation Standards document. These variables are used in forming the path to various directories containing input, output, and workflow files. The variables are defined in the `WCOSS Implementation Standards <https://www.nco.ncep.noaa.gov/idsb/implementation_standards/ImplementationStandards.v11.0.0.pdf?>`__ document (pp. 4-5) as follows: 
 
    ``envir``: (Default: "para")
       Set to "test" during the initial testing phase, "para" when running in parallel (on a schedule), and "prod" in production. 
@@ -427,6 +427,8 @@ A standard set of environment variables has been established for *nco* mode to s
 ``OPSROOT``: (Default: "")
   The operations root directory in *nco* mode.
 
+.. _workflow-switches:
+
 WORKFLOW SWITCHES Configuration Parameters
 =============================================
 
@@ -689,6 +691,8 @@ Non-default parameters for the ``make_sfc_climo`` task are set in the ``task_mak
 ``SFC_CLIMO_DIR``: (Default: "")
    The directory containing pre-generated surface climatology files to use when ``MAKE_SFC_CLIMO_TN`` is set to false.
 
+.. _task_get_extrn_ics:
+
 GET_EXTRN_ICS Configuration Parameters
 =========================================
 
@@ -770,6 +774,7 @@ Set parameters associated with NOMADS online data.
 ``NOMADS_file_type``: (Default: "nemsio")
    Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"``
 
+.. _task_get_extrn_lbcs:
 
 GET_EXTRN_LBCS Configuration Parameters
 ==========================================
@@ -1768,17 +1773,20 @@ Additional Parameters
 Typically, the following parameters must be set explicitly by the user in the configuration file (``config.yaml``) when executing the plotting tasks. 
 
 ``COMOUT_REF``: (Default: "")
-   The directory where the GRIB2 files from post-processing are located. In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will correspond to the location in the experiment directory where the post-processed output can be found (e.g., ``$EXPTDIR/$DATE_FIRST_CYCL/postprd``). In *nco* mode, this directory should be set to the location of the COMOUT directory and end with ``$PDY/$cyc``.
+   The directory where the GRIB2 files from post-processing are located. In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will correspond to the location in the experiment directory where the post-processed output can be found (e.g., ``$EXPTDIR/$DATE_FIRST_CYCL/postprd``). In *nco* mode, this directory should be set to the location of the ``COMOUT`` directory and end with ``$PDY/$cyc``. For more detail on *nco* standards and directory naming conventions, see `WCOSS Implementation Standards <https://www.nco.ncep.noaa.gov/idsb/implementation_standards/ImplementationStandards.v11.0.0.pdf?>`__ (particularly pp. 4-5). 
 
 ``PLOT_FCST_START``: (Default: 0)
    The starting forecast hour for the plotting task. For example, if a forecast starts at 18h/18z, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. If a forecast starts at 18h/18z, but the user only wants plots from the 6th forecast hour on, "starting forecast hour" should be 6.
 
 ``PLOT_FCST_INC``: (Default: 3)
-   Forecast hour increment for the plotting task. This may be the same as ``INCR_CYCL_FREQ``, or it may be a multiple of ``INCR_CYCL_FREQ``. For example, if ``INCR_CYCL_FREQ`` is set to 3, there will be forecast output every three hours for the duration of the forecast. If the user wants plots of all of this output, they should set ``PLOT_FCST_INC: 3``. If the user only wants plots for some of the output (e.g., every 6 hours), they should set ``PLOT_FCST_INC: 6``. However, there must be forecast output available at the designated increments to produce the plots. In this example, setting ``PLOT_FCST_INC: 7`` would produce an error because there is only forecast output available for hours 3, 6, 9, ..., etc. 
+   Forecast hour increment for the plotting task. For example, if the user wants plots for each forecast hour, they should set ``PLOT_FCST_INC: 1``. If the user only wants plots for some of the output (e.g., every 6 hours), they should set ``PLOT_FCST_INC: 6``. 
 
 ``PLOT_FCST_END``: (Default: "")
    The last forecast hour for the plotting task. For example, if a forecast run for 24 hours, and the user wants plots for each available hour of forecast output, they should set ``PLOT_FCST_END: 24``. If the user only wants plots from the first 12 hours of the forecast, the "last forecast hour" should be 12.
 
+``PLOT_DOMAINS``: (Default: ["conus"])
+   Domains to plot. Currently supported options are ["conus"], ["regional"], or both (i.e., ["conus", "regional"]).
+
 Global Configuration Parameters
 ===================================
 

docs/UsersGuide/source/Glossary.rst

@@ -67,6 +67,9 @@ Glossary
    cycle-independent
       Describes a workflow task that only needs to be run once per experiment, regardless of the number of cycles in the experiment.
 
+   data assimilation
+      One of the major sources of error in weather and climate forecasts is uncertainty related to the initial conditions that are used to generate future predictions. Even the most precise instruments have a small range of unavoidable measurement error, which means that tiny measurement errors (e.g., related to atmospheric conditions and instrument location) can compound over time. These small differences result in very similar forecasts in the short term (i.e., minutes, hours), but they cause widely divergent forecasts in the long term. Data assimilation systems seek to mitigate this problem by combining the most timely observational data with other sources of data, such as historical data, to provide an analysis of possible atmospheric states and the probabilities of each. Errors in weather and climate forecasts can also arise because models are imperfect representations of reality. Data assimilation systems can use techniques including stochastic physics, which applies randomized perturbations to the physical tendencies or the physical parameters of a model, to compensate for model uncertainty. 
+
    dycore
    dynamical core
       Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion.
@@ -188,6 +191,9 @@ Glossary
    NWP
       Numerical Weather Prediction (NWP) takes current observations of weather and processes them with computer models to forecast the future state of the weather. 
 
+   NWS
+      The `National Weather Service <https://www.weather.gov/>`__ (NWS) is an agency of the United States government that is tasked with providing weather forecasts, warnings of hazardous weather, and other weather-related products to organizations and the public for the purposes of protection, safety, and general information. It is a part of the National Oceanic and Atmospheric Administration (NOAA) branch of the Department of Commerce.
+
    Orography
       The branch of physical geography dealing with mountains.
 
@@ -229,6 +235,9 @@ Glossary
    Umbrella repository
       A repository that houses external code, or "externals," from additional repositories.
 
+   Updraft helicity
+      Helicity measures the rotation in a storm's updraft (rising) air. Significant rotation increases the probability that the storm will become a supercell thunderstorm or a tornado. See http://ww2010.atmos.uiuc.edu/(Gh)/guides/mtr/svr/modl/fcst/params/hel.rxml for more details on updraft helicity. 
+
    UPP
       The `Unified Post Processor <https://dtcenter.org/community-code/unified-post-processor-upp>`__ is software developed at :term:`NCEP` and used operationally to 
       post-process raw output from a variety of :term:`NCEP`'s :term:`NWP` models, including the :term:`FV3`.

docs/UsersGuide/source/InputOutputFiles.rst

@@ -306,7 +306,7 @@ where:
 
 For example, a forecast using FV3GFS GRIB2 data that starts at 18h00 UTC would have a {cycle} value of 18, which is the 000th forecast hour. The LBCS file for 21h00 UTC would be named ``gfs.t18z.pgrb2.0p25.f003``. 
 
-In some cases, it may be necessary to specify values for ``EXTRN_MDL_FILES_*CS``variables. This is often the case with HRRR and RAP data. An example ``config.yaml`` excerpt using HRRR and RAP data appears below: 
+In some cases, it may be necessary to specify values for ``EXTRN_MDL_FILES_*CS`` variables. This is often the case with HRRR and RAP data. An example ``config.yaml`` excerpt using HRRR and RAP data appears below: 
 
 .. code-block:: console
 

docs/UsersGuide/source/RunSRW.rst

@@ -537,8 +537,8 @@ To configure an experiment and python environment for a general Linux or Mac sys
 
 .. _PlotOutput:
 
-Plot the Output
------------------
+Plotting Configuration (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 An optional Python plotting task (PLOT_ALLVARS) can be activated in the workflow to generate plots for the :term:`FV3`-:term:`LAM` post-processed :term:`GRIB2`
 output over the :term:`CONUS`. It generates graphics plots for a number of variables, including:
@@ -561,12 +561,12 @@ the same cycle starting date/time and forecast hours. Other parameters may diffe
 .. _Cartopy:
 
 Cartopy Shapefiles
-^^^^^^^^^^^^^^^^^^^^^
+`````````````````````
 
 The Python plotting tasks require a path to the directory where the Cartopy Natural Earth shapefiles are located. The medium scale (1:50m) cultural and physical shapefiles are used to create coastlines and other geopolitical borders on the map. On `Level 1 <https://github.com/ufs-community/ufs-srweather-app/wiki/Supported-Platforms-and-Compilers>`__ systems, this path is already set in the system's machine file using the variable ``FIXshp``. Users on other systems will need to download the shapefiles and update the path of ``$FIXshp`` in the machine file they are using (e.g., ``$SRW/ush/machine/macos.yaml`` for a generic MacOS system, where ``$SRW`` is the path to the ``ufs-srweather-app`` directory). The subset of shapefiles required for the plotting task can be obtained from the `SRW Data Bucket <https://noaa-ufs-srw-pds.s3.amazonaws.com/NaturalEarth/NaturalEarth.tgz>`__. The full set of medium-scale (1:50m) Cartopy shapefiles can be downloaded `here <https://www.naturalearthdata.com/downloads/>`__. 
 
 Task Configuration
-^^^^^^^^^^^^^^^^^^^^^
+`````````````````````
 
 Users will need to add or modify certain variables in ``config.yaml`` to run the plotting task(s). At a minimum, users must set ``RUN_TASK_PLOT_ALLVARS`` to true in the ``workflow_switches:`` section:
 
@@ -593,16 +593,16 @@ When plotting output from a single experiment, no further adjustments are necess
 corresponds to the cycle date and hour in YYYYMMDDHH format (e.g., ``2019061518``).
 
 Plotting the Difference Between Two Experiments
-```````````````````````````````````````````````````
+""""""""""""""""""""""""""""""""""""""""""""""""""
 
-When plotting the difference between two experiments, users must set the baseline experiment directory using the ``COMOUT_REF`` template variable. For example, in *community* mode, users can set:
+When plotting the difference between two experiments (``expt1`` and ``expt2``), users must set the ``COMOUT_REF`` template variable in ``expt2``'s ``config.yaml`` file to point at forecast output from the ``expt1`` directory. For example, in *community* mode, users can set ``COMOUT_REF`` as follows in the ``expt2`` configuration file:
 
 .. code-block:: console
 
    task_plot_allvars:
-      COMOUT_REF: '${EXPT_BASEDIR}/${EXPT_SUBDIR}/${PDY}${cyc}/postprd'
+      COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd'
 
-In *community* mode, using default directory names and settings, ``$COMOUT_REF`` will resemble ``/path/to/expt_dirs/test_community/2019061518/postprd``. Additional details on the plotting variables are provided in :numref:`Section %s <PlotVars>`. 
+This will ensure that ``expt2`` can produce a difference plot comparing ``expt1`` and ``expt2``. In *community* mode, using default directory names and settings, ``$COMOUT_REF`` will resemble ``/path/to/expt_dirs/test_community/2019061518/postprd``. Additional details on the plotting variables are provided in :numref:`Section %s <PlotVars>`. 
 
 The output files (in ``.png`` format) will be located in the ``postprd`` directory for the experiment.
 

docs/UsersGuide/source/TemplateVars.rst

@@ -1,8 +1,8 @@
 .. _TemplateVars:
 
-===============================================================
-Using Template Variables in the Experiment Configuration Files
-===============================================================
+======================
+Template Variables
+======================
 
 The SRW App's experiment configuration system supports the use of template variables
 in ``config_defaults.yaml`` and ``config.yaml``. A template variable --- or "template" --- is an experiment configuration variable that contains references to values of other variables. 
@@ -54,17 +54,22 @@ To generate difference plots, users must use the template variable ``COMOUT_REF`
 to indicate where the :term:`GRIB2` files from post-processing are located. 
 
 In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will 
-take the form ``/path/to/exptdir/$PDY$cyc/postprd``, where ``$PDY`` refers to the 
-cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. 
+take the form ``/path/to/expt_dirs/expt_name/$PDY$cyc/postprd``, where ``$PDY`` refers 
+to the cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. 
 (These variables are set in previous tasks based on the value of ``DATE_FIRST_CYCL``.)
-Concretely, users can set ``COMOUT_REF`` as follows:
+Given two experiments, ``expt1`` and ``expt2``, users can generate difference plots by 
+setting ``COMOUT_REF`` in the ``expt2`` configuration file (``config.yaml``) as follows:
 
 .. code-block:: console
 
-   COMOUT_REF: '${EXPT_BASEDIR}/${EXPT_SUBDIR}/${PDY}${cyc}/postprd'
+   COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd'
 
-In *nco* mode, this directory should be set to the location of the ``COMOUT`` directory 
-(``${COMOUT}`` in the example below) and end with ``${PDY}/${cyc}``. For example:
+The ``expt2`` workflow already knows where to find its own post-processed output, so 
+``COMOUT_REF`` should point to post-processed output for the other experiment (``expt1``). 
+
+In *nco* mode, this directory should be set to the location of the first experiment's 
+``COMOUT`` directory (``${COMOUT}`` in the example below) and end with ``${PDY}/${cyc}``. 
+For example:
 
 .. code-block:: console