Updates to parameters in config_defaults .rst files (#237)

* edit config intro & platform environment sections

* edit sections on cron & directory parameters, platform & parameters for running without a workflow manager

* edit NCO, file-separator, filename params, add some METplus and model config params

* ConfigWorkflow.rst revisions, added METplus to Components, grid info

* add grid config details

* changes to readme.md

* RTD readme.md edits

* create MacOS install/build instructions

* update task run and grid parameters

* fixed file params & workflow task params

* 1st draft of ConfigParameters.inc

* minor edits

* add stochastic physics var details

* update FVCOM, thread affinity params

* halo_blend, ens, crtm, custom post, subhourly updates

* update HPC-Stack submodule/docs

* Rocoto WF tasks & params

* workflow tasks/params, debug, verbose, pre-existing dir, predefined grid

* move Stochastic physics to CCP section; write component edits

* comp'l forecast, grid gen, NOMADS, user-staged files

* METplus, model config & forecast params, separator

* 2nd draft complete

* physics updates

* remove MacInstall empty file

* undo hpc-stack submodule update (save for separate PR)

* undo hpc-stack install doc update (save for separate PR)

* revisions to SPP & LSM physics

* minor edits

* update comments in LAM Grid chapter

* update LSM_SPP_EACH_STEP

* revert LSM_SPP_EACH_STEP to original definition

* combine config info into one doc instead of two

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

docs/UsersGuide/README

@@ -1,26 +1,29 @@
 Steps to build and use the Sphinx documentation tool:
 
-1) Get Sphinx and sphinxcontrib-bibtex installed on your desktop from
+1) Get Sphinx, sphinxcontrib-bibtex, and the RTD theme installed on your desktop from
     http://www.sphinx-doc.org/en/master/usage/installation.html
     https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
+    https://pypi.org/project/sphinx-rtd-theme/
+
+    For example: 
+    pip install sphinx
+    pip install sphinxcontrib-bibtex
+    pip install sphinx-rtd-theme
 
-2) Create a Sphinx documentation root directory:
-   % mkdir docs
-   % cd docs
+    One approach that has worked to resolve "Module Not Found" errors for users with MacPorts package manager: 
+    $ sudo port install py-six  # may not be necessary
+    $ sudo port install py310-sphinxcontrib-bibtex
+    $ sudo port select --set sphinx py310-sphinx
+    $ sudo port install py310-sphinx_rtd_theme
 
-3) Initialize your Sphinx project (set up an initial directory structure) using
-   % sphinx-quickstart
+    py310 can be replaced with the user's version of Python (e.g., py39) 
 
-   See http://www.sphinx-doc.org/en/master/usage/quickstart.html or
-       https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-quickstart.html
-
-    for help.  You can answer (ENTER) to most of the questions.
-
 To build html:
 
-From the directory above source and build, the sphinx project directory:
+$ cd ufs-srweather-app/docs/UsersGuide
+$ make clean && sphinx-build -b html source build
 
-make html
+The "make html" command can often be used in place of the previous command.
 
 Sphinx uses Latex to export the documentation as a PDF file.  To build pdf:
 

docs/UsersGuide/source/Components.rst

@@ -47,6 +47,17 @@ The SRW Application is distributed with the Unified Post Processor (:term:`UPP`)
 Output from UPP can be used with visualization, plotting, and verification packages or in
 further downstream post-processing (e.g., statistical post-processing techniques).
 
+.. _MetplusComponent:
+
+METplus Verification Suite
+=============================
+
+The Model Evaluation Tools (MET) are a set of verification tools developed by the Developmental Testbed Center (DTC) for use by the numerical weather prediction community to help them assess and evaluate the performance of numerical weather predictions. MET is the core component of the unified METplus verification framework. METplus spans a wide range of temporal (warn-on-forecast to climate) and spatial (storm to global) scales. The core components of the framework include MET, the associated database and display systems called METviewer and METexpress, and a suite of Python wrappers to provide low-level automation and examples, also called use-cases. METplus is intended to be extensible through additional capabilities developed by the community. 
+
+METplus is being actively developed by NCAR/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), NOAA/Environmental Modeling Center (EMC), and is open to community contributions.
+
+More details about METplus can be found on the `METplus website <https://dtcenter.org/community-code/metplus>`__.
+
 Visualization Example
 =====================
 A Python script is provided to create basic visualization of the model output. The script

docs/UsersGuide/source/Glossary.rst

@@ -9,6 +9,13 @@ Glossary
    CCPP
       The `Common Community Physics Package <https://dtcenter.org/community-code/common-community-physics-package-ccpp>`_ is a forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model.
 
+   chgres_cube
+       The preprocessing software used to create initial and boundary condition files to 
+       “coldstart” the forecast model.
+
+   CRTM
+      `Community Radiative Transfer Model <https://www.jcsda.org/jcsda-project-community-radiative-transfer-model>`__. CRTM is a fast and accurate radiative transfer model developed at the `Joint Center for Satellite Data Assimilation <https://www.jcsda.org/>`__ (JCSDA) in the United States. It is a sensor-based radiative transfer model and supports more than 100 sensors, including sensors on most meteorological satellites and some from other remote sensing satellites. 
+
    Component
       A software element that has a clear function and interface. In Earth system models, components are often single portions of the Earth system (e.g. atmosphere, ocean, or land surface) that are assembled to form a whole.
 
@@ -21,28 +28,45 @@ Glossary
    CONUS
       Continental United States
 
-   chgres_cube
-       The preprocessing software used to create initial and boundary condition files to 
-       “coldstart” the forecast model.
+   cycle
+      An hour of the day on which a forecast is started. 
+
+   cycle-dependent 
+      Describes a workflow task that needs to be run at the start of each :term:`cycle` of an experiment.
+
+   cycle-independent
+      Describes a workflow task that only needs to be run once per experiment, regardless of the number of cycles in the experiment.
+
+   dycore
+      See :term:`dynamical core`.
 
    dynamical core
       Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion.
 
    EPIC
       EPIC stands for the `Earth Prediction Innovation Center <https://epic.noaa.gov/>`__. EPIC seeks to accelerate scientific research and modeling contributions through continuous and sustained community engagement to produce the most accurate and reliable operational modeling system in the world. 
 
+   ESMF
+      `Earth System Modeling Framework <https://earthsystemmodeling.org/docs/release/ESMF_8_1_1/ESMF_usrdoc.pdf>`__. The ESMF defines itself as “a suite of software tools for developing high-performance, multi-component Earth science modeling applications.” 
+
    FV3
       The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical 
       Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both 
       hydrostatic and non-hydrostatic atmospheric simulations.  It is the dycore used in the 
       UFS Weather Model.
 
+   FVCOM
+      `Finite Volume Community Ocean Model <http://fvcom.smast.umassd.edu/>`__. FVCOM is used in modeling work for the `Great Lakes Coastal Forecasting System (next-gen FVCOM) <https://www.glerl.noaa.gov/res/glcfs/>`__ conducted by the `Great Lakes Environmental Research Laboratory <https://www.glerl.noaa.gov/>`__. 
+
    GFS
       `Global Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast>`_. The GFS is a National Centers for Environmental Prediction (NCEP) weather forecast model that generates data for dozens of atmospheric and land-soil variables, including temperatures, winds, precipitation, soil moisture, and atmospheric ozone concentration. The system couples four separate models (atmosphere, ocean model, land/soil model, and sea ice) that work together to accurately depict weather conditions.
 
    GRIB2 
       The second version of the World Meterological Organization's (WMO) standard for distributing gridded data.  
 
+   halo
+      A strip of cells on the edge of the regional grid. The :ref:`wide halo <WideHalo>` surrounds the regional grid and is used to feed the lateral boundary conditions into the grid. The :ref:`HALO_BLEND <HaloBlend>` parameter refers to a strip of cells on the *inside* the boundary of the native grid. This halo smooths out mismatches between the external and internal solutions. 
+
    HPC-Stack
       The `HPC-Stack <https://github.com/NOAA-EMC/hpc-stack>`__ is a repository that provides a unified, shell script-based build system for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) <https://ufscommunity.org/>`__ and the `Joint Effort for Data assimilation Integration (JEDI) <https://jointcenterforsatellitedataassimilation-jedi-docs.readthedocs-hosted.com/en/latest/>`__ framework.
 
@@ -52,18 +76,24 @@ Glossary
    IC/LBC
       Initial conditions/lateral boundary conditions
 
+   ICs
+      Initial conditions
+
    LAM
       Limited Area Model, formerly known as the "Stand-Alone Regional Model," or SAR. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. 
 
-   LBC
-      Lateral boundary conditions.
+   LBCs
+      Lateral boundary conditions
 
    MPI
       MPI stands for Message Passing Interface. An MPI is a standardized communication system used in parallel programming. It establishes portable and efficient syntax for the exchange of messages and data between multiple processors that are used by a single computer program. An MPI is required for high-performance computing (HPC).
 
    NAM
       `North American Mesoscale Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/north-american-mesoscale>`_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes.
 
+   namelist
+      A namelist defines a group of variables or arrays. Namelists are an I/O feature for format-free input and output of variables by key-value assignments in FORTRAN compilers. Fortran variables can be read from and written to plain-text files in a standardised format, usually with a ``.nml`` file ending.
+
    NCEP
       National Centers for Environmental Prediction, an arm of the National Weather Service,
       consisting of nine centers. More information can be found at https://www.ncep.noaa.gov.
@@ -87,18 +117,27 @@ Glossary
    NEMSIO
       A binary format for atmospheric model output from :term:`NCEP`'s Global Forecast System (GFS).
 
+   NUOPC
+      The `National Unified Operational Prediction Capability <https://earthsystemmodeling.org/nuopc/>`__ Layer "defines conventions and a set of generic components for building coupled models using the Earth System Modeling Framework (:term:`ESMF`)." 
+
    NWP
       Numerical Weather Prediction (NWP) takes current observations of weather and processes them with computer models to forecast the future state of the weather. 
 
    Orography
       The branch of physical geography dealing with mountains.
 
+   Parameterization
+      Simplified functions that approximate the effects of small-scale processes (e.g., microphysics, gravity wave drag) that cannot be explicitly resolved by a model grid’s representation of the earth.
+
    RAP
       `Rapid Refresh <https://rapidrefresh.noaa.gov/>`__. The continental-scale NOAA hourly-updated assimilation/modeling system operational at NCEP. RAP covers North America and is comprised primarily of a numerical forecast model and an analysis/assimilation system to initialize that model. RAP is complemented by the higher-resolution 3km High-Resolution Rapid Refresh (HRRR) model.
 
    Repository
       A central location in which files (e.g., data, code, documentation) are stored and managed. 
 
+   SDF
+      Suite Definition File. An external file containing information about the construction of a physics suite. It describes the schemes that are called, in which order they are called, whether they are subcycled, and whether they are assembled into groups to be called together.
+
    UFS
       The Unified Forecast System is a community-based, coupled comprehensive Earth modeling 
       system consisting of several applications (apps). These apps span regional to global 

docs/UsersGuide/source/Introduction.rst

@@ -6,7 +6,7 @@ Introduction
 
 The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. NOAA’s operational model suite for numerical weather prediction (:term:`NWP`) is quickly transitioning to the UFS from a number of different modeling systems. The UFS enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal <https://ufscommunity.org/>`__.
 
-The UFS includes `multiple applications <https://ufscommunity.org/science/aboutapps/>`__ that support different forecast durations and spatial domains. This documentation describes the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum <https://forums.ufscommunity.org/>`_. New and improved capabilities for this release include the addition of a verification package (METplus) for both deterministic and ensemble simulations and support for four Stochastically Perturbed Perturbation (SPP) schemes. Future work will expand the capabilities of the application to include data assimilation (DA) and a forecast restart/cycling capability. 
+The UFS includes `multiple applications <https://ufscommunity.org/science/aboutapps/>`__ that support different forecast durations and spatial domains. This documentation describes the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes to several days. The SRW Application v2.0.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum <https://forums.ufscommunity.org/>`_. New and improved capabilities for this release include the addition of a verification package (METplus) for both deterministic and ensemble simulations and support for four Stochastically Perturbed Perturbation (SPP) schemes. Future work will expand the capabilities of the application to include data assimilation (DA) and a forecast restart/cycling capability. 
 
 This documentation provides a :ref:`Quick Start Guide <QuickstartC>` for running the SRW Application in a container and a :ref:`detailed guide <BuildRunSRW>` for running the SRW App on supported platforms. It also provides an overview of the :ref:`release components <Components>` and details on how to customize or modify different portions of the workflow.