[release/public v2]: Final documentation edits (#312)

* adjust Mac/Linux organization * mark's edits pt1 * mac/linux reorg * minor edits * QS & BR updates * QS node allocation reorg * minor edits * update UFS_UTILS sci doc link & SRW App citation date * remove I/O comments * update CCPP options * update NC-QS & config_defaults.sh table in B/R * update config.sh info * edit VX section * generate forecast section * expt run section * Natalie's updates to intro & minor other details * minor prereq fix * update to automated Rocoto section * update for mac/linux sections * mac/linux typo fix * mac/linux typo fix * macos/linux edits * macos/linux edits * remove space * remove duplicate command Co-authored-by: gspetro <gillian.s.petro@gmail.com> Co-authored-by: Will Mayfield <59745143+willmayfield@users.noreply.github.com> Co-authored-by: Natalie Perlin <68030316+natalie-perlin@users.noreply.github.com> Co-authored-by: gsketefian <31046882+gsketefian@users.noreply.github.com> Co-authored-by: Natalie Perlin <nperlin@redlineperf.com>
ufs-community · Jun 22, 2022 · f717265 · f717265
1 parent b6843a7
commit f717265
Show file tree

Hide file tree

Showing 8 changed files with 203 additions and 199 deletions.
diff --git a/README.md b/README.md
@@ -11,4 +11,4 @@ The UFS SRW App User's Guide associated with the development branch is at: https
 For instructions on how to clone the repository, build the code, and run the workflow, see:
 https://github.com/ufs-community/ufs-srweather-app/wiki/Getting-Started
 
-UFS Development Team. (2022, June 17). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.0.0). Zenodo. https://doi.org/10.5281/zenodo.6505854
+UFS Development Team. (2022, June 22). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.0.0). Zenodo. https://doi.org/10.5281/zenodo.6505854
diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst
diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst
@@ -19,10 +19,7 @@ These components are documented within this User's Guide and supported through a
 Pre-processor Utilities and Initial Conditions
 ==============================================
 
-The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User's Guide <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__.
-
-..
-   COMMENT: Update link!
+The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__ and in the `UFS_UTILS Scientific Documentation <https://ufs-community.github.io/UFS_UTILS/ver-1.7.0/index.html>`__.
 
 The SRW Application can be initialized from a range of operational initial condition files. It is possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. 
 

diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst
@@ -48,6 +48,8 @@ Platform Environment
 ``WFLOW_MOD_FN``: (Default: "")
    Name of alternative workflow module file to use if running on an unsupported platform. Is set automatically for supported machines.
 
+.. _sched:
+
 ``SCHED``: (Default: "")
    The job scheduler to use (e.g., Slurm) on the specified ``MACHINE``. Leaving this an empty string allows the experiment generation script to set it automatically depending on the machine the workflow is running on. Valid values: ``"slurm"`` | ``"pbspro"`` | ``"lsf"`` | ``"lsfcray"`` | ``"none"``
 
@@ -397,7 +399,7 @@ CCPP Parameter
    | ``"FV3_GFS_v16"`` 
    | ``"FV3_RRFS_v1beta"`` 
    | ``"FV3_HRRR"``
-   | ``"FV3_WoFS"``
+   | ``"FV3_WoFS_v0"``
 
    **Other valid values include:**
 

diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst
@@ -27,10 +27,7 @@ The data format for these files can be :term:`GRIB2` or :term:`NEMSIO`. More inf
 
 Pre-processing (UFS_UTILS)
 ---------------------------
-When a user generates the regional workflow, as described in :numref:`Section %s <GenerateWorkflow>`, the workflow generation script links the input data for the pre-processing utilities to the experiment directory. The 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 in the `UFS_UTILS Documentation <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__.
-
-..
-   COMMENT: Update link! (UFS_UTILS)
+When a user generates the regional workflow, as described in :numref:`Section %s <GenerateWorkflow>`, the workflow generation script links the input data for the pre-processing utilities to the experiment directory. The 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 in the UFS_UTILS `Technical Documentation <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__ and `Scientific Documentation <https://ufs-community.github.io/UFS_UTILS/ver-1.7.0/index.html>`__.
 
 UFS Weather Model
 -----------------
@@ -100,10 +97,7 @@ and are shown in :numref:`Table %s <TemplateFiles>`.
    | README.xml_templating.md    | Instructions for Rocoto XML templating with Jinja.           |
    +-----------------------------+--------------------------------------------------------------+
 
-Additional information related to ``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/release-public-v3/InputsOutputs.html#model-configuration-files>`__, while information on ``regional_grid.nml`` can be found in the `UFS_UTILS User's Guide <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__.
-
-..
-   COMMENT: Update links! (for UFS_UTILS)
+Additional information related to ``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/release-public-v3/InputsOutputs.html#model-configuration-files>`__, while information on ``regional_grid.nml`` options can be found in the `UFS_UTILS Technical Documentation <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/ufs_utils.html#regional-esg-grid>`__.
 
 Migratory Route of the Input Files in the Workflow
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst
@@ -8,11 +8,11 @@ The Unified Forecast System (:term:`UFS`) is a community-based, coupled, compreh
 
 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 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.
+This documentation provides a :ref:`Quick Start Guide <NCQuickstart>` designed for use on `Level 1 systems <https://github.com/ufs-community/ufs-srweather-app/wiki/Supported-Platforms-and-Compilers>`__ or as an overview of the workflow. It also provides a :ref:`Container-Based Quick Start Guide <QuickstartC>` for running the SRW Application in a container and a :ref:`detailed guide <BuildRunSRW>` for running the SRW App on any supported platform. Additionally, this User's Guide provides an overview of the :ref:`release components <Components>` and details on how to customize or modify different portions of the workflow.
 
 The SRW App v2.0.0 citation is as follows and should be used when presenting results based on research conducted with the App:
 
-UFS Development Team. (2022, June 17). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.0.0). Zenodo. https://doi.org/10.5281/zenodo.6505854
+UFS Development Team. (2022, June 22). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.0.0). Zenodo. https://doi.org/10.5281/zenodo.6505854
 
 
 How to Use This Document
@@ -30,7 +30,7 @@ Variables presented as ``AaBbCc123`` in this User's Guide typically refer to var
 File paths or code that include angle brackets (e.g., ``build_<platform>_<compiler>``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). 
 
 .. hint:: 
-   * To get started running the SRW App, see the :ref:`Quick Start Guide <QuickstartC>` for beginners or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application <BuildRunSRW>`. 
+   * To get started running the SRW App, users can view :numref:`Chapter %s <NCQuickstart>` for a quick overview of the workflow steps. For more detailed explanations, users can refer to the :ref:`Container-Based Quick Start Guide <QuickstartC>` or the in-depth chapter on :ref:`Building and Running the Short-Range Weather Application <BuildRunSRW>`. 
    * For background information on the SRW App code repositories and directory structure, see :numref:`Section %s <SRWStructure>` below. 
    * For an outline of SRW App components, see section :numref:`Section %s <ComponentsOverview>` below or refer to :numref:`Chapter %s <Components>` for a more in-depth treatment.
 
@@ -73,11 +73,8 @@ The UFS SRW Application has been designed so that any sufficiently up-to-date ma
    * 53 GB input data for a standard collection of global database, or "fix" data (topography, climatology, observational database) for a short 12-hour test forecast on CONUS 25km domain. See data download instructions in :numref:`Section %s <DownloadingStagingInput>`.
    * 8 GB for :term:`HPC-Stack` full installation
    * 3 GB for ``ufs-srweather-app`` installation
-   * 1 GB boundary conditions for a short 12-h test forecast on CONUS 25km domain. See data download instructions in :numref:`Section %s <DownloadingStagingInput>`
-   * 17 GB for a 12-h test forecast on CONUS 25km domain, with model output saved hourly, see :numref:`Section %s <GridSpecificConfig>`
-
-
-* 4GB memory (CONUS 25km domain)
+   * 1 GB for boundary conditions for a short 12-h test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s <DownloadingStagingInput>`
+   * 17 GB for a 12-h test forecast on the CONUS 25km domain, with model output saved hourly, see :numref:`Section %s <GridSpecificConfig>`
 
 * Fortran compiler released since 2018
 
@@ -113,7 +110,7 @@ The following software is also required to run the SRW Application, but the :ter
 For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew <https://brew.sh/>`__ package manager for MacOS. See :numref:`Chapter %s <MacInstall>` and :numref:`Chapter %s <MacMorePackages>` for further guidance on installing these prerequisites on MacOS.
 
 * bash v4.x
-* `gcc@11` compiler package
+* GNU compiler suite v.11 or higher with gfortran
 * cmake
 * make
 * coreutils
@@ -125,9 +122,6 @@ Optional but recommended prerequisites for all systems:
 * Rocoto Workflow Management System (1.3.1)
 * Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` for graphics
 
-..
-   COMMENT: Lmod is listed as required
-
 .. _ComponentsOverview: 
 
 SRW App Components Overview 
@@ -136,10 +130,7 @@ SRW App Components Overview
 Pre-processor Utilities and Initial Conditions
 ------------------------------------------------
 
-The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. One pre-processing utility converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, these files are used as input to the atmospheric model (FV3-LAM). Additional information about the pre-processor utilities can be found in :numref:`Chapter %s <Utils>` and in the `UFS_UTILS User’s Guide <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__.
-
-..
-   COMMENT: Update link!
+The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. One pre-processing utility converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, these files are used as input to the atmospheric model (FV3-LAM). Additional information about the pre-processor utilities can be found in :numref:`Chapter %s <Utils>`, in the `UFS_UTILS Technical Documentation <https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/>`__, and in the `UFS_UTILS Scientific Documentation <https://ufs-community.github.io/UFS_UTILS/ver-1.7.0/index.html>`__.
 
 Forecast Model
 -----------------
@@ -307,7 +298,7 @@ A number of sub-directories are created under the ``regional_workflow`` director
 
 Experiment Directory Structure
 --------------------------------
-When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Section %s <GenerateWorkflow>`), a user-defined experimental directory (``EXPTDIR``) is created based on information specified in the ``config.sh`` file. :numref:`Table %s <ExptDirStructure>` shows the contents of the experiment directory before running the experiment workflow.
+When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Section %s <GenerateWorkflow>`), a user-defined experimental directory (``$EXPTDIR``) is created based on information specified in the ``config.sh`` file. :numref:`Table %s <ExptDirStructure>` shows the contents of the experiment directory before running the experiment workflow.
 
 .. _ExptDirStructure:
 
@@ -435,8 +426,11 @@ A list of available documentation is shown in :numref:`Table %s <list_of_documen
    | UFS SRW Application        | https://ufs-srweather-app.readthedocs.io/en/release-public-v2/                  |
    | User's Guide               |                                                                                 |
    +----------------------------+---------------------------------------------------------------------------------+
-   | UFS_UTILS User's           | https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/                    |
-   | Guide                      |                                                                                 |
+   | UFS_UTILS Technical        | https://noaa-emcufs-utils.readthedocs.io/en/ufs_utils_1_7_0/                    |
+   | Documentation              |                                                                                 |
+   +----------------------------+---------------------------------------------------------------------------------+
+   | UFS_UTILS Scientific       | https://ufs-community.github.io/UFS_UTILS/ver-1.7.0/index.html                  |
+   | Documentation              |                                                                                 |
    +----------------------------+---------------------------------------------------------------------------------+
    | UFS Weather Model          | https://ufs-weather-model.readthedocs.io/en/release-public-v3/                  |
    | User's Guide               |                                                                                 |

diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst
@@ -77,13 +77,21 @@ For a detailed explanation of how to build and run the SRW App on any supported
       
       Users will need to adjust the experiment parameters in the ``config.sh`` file to suit the needs of their experiment (e.g., date, time, grid, physics suite, etc.). More detailed guidance is available in :numref:`Section %s <UserSpecificConfig>`. Parameters and valid values are listed in :numref:`Chapter %s <ConfigWorkflow>`. 
 
-   #. Load the python environment for the regional workflow. Users on Level 3-4 systems will need to use one of the existing ``wflow_<platform>`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. 
+   #. Load the python environment for the regional workflow. Users on Level 2-4 systems will need to use one of the existing ``wflow_<platform>`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. 
 
       .. code-block:: console
 
          module use <path/to/modulefiles>
          module load wflow_<platform>
-         conda activate regional_workflow
+
+      After loading the workflow, users should follow the instructions printed to the console. For example, if the output says: 
+
+      .. code-block:: console
+
+         Please do the following to activate conda:
+            > conda activate regional_workflow
+      
+      then the user should run ``conda activate regional_workflow`` to activate the ``regional_workflow`` environment. 
 
    #. Generate the experiment workflow.