ufs-community · junwang-noaa · Mar 4, 2020 · Mar 4, 2020 · Mar 4, 2020
diff --git a/doc/UsersGuide/source/CodeOverview.rst b/doc/UsersGuide/source/CodeOverview.rst
@@ -20,24 +20,24 @@ The ufs-weather-model repository supports the short- and medium-range UFS applic
     - Authoritative repository URL
   * - Umbrella repository for the UFS Weather Model
     - https://github.com/ufs-community/ufs-weather-model
-  * - Infrastructure: Flexible Modeling System 
+  * - Infrastructure: Flexible Modeling System
     - https://github.com/NOAA-GFDL/FMS
   * - Infrastructure: NOAA Environmental Modeling System
     - https://github.com/NOAA-EMC/NEMS
-  * - Infrastructure: add description
+  * - Infrastructure: Utilities
     - https://github.com/NOAA-EMC/NCEPLIBS-pyprodutil
-  * - Framework to connect the CCPP library to a host model 
+  * - Framework to connect the CCPP library to a host model
     - https://github.com/NCAR/ccpp-framework
   * - CCPP library of physical parameterizations
     - https://github.com/NCAR/ccpp-physics
   * - Umbrella repository for the physics and dynamics of the atmospheric model
     - https://github.com/NOAA-EMC/fv3atm
   * - FV3 dynamical core
     - https://github.com/NOAA-EMC/GFDL_atmos_cubed_sphere
-  * - Stochastic physics pattern generator  
+  * - Stochastic physics pattern generator
     - https://github.com/noaa-psd/stochastic_physics
 
-In the table, the left column contains a description of each repository, and the right column shows the component repositories which are pointing to (or will point to) the authoritative repositories. The ufs-weather-model currently uses git submodule to manage the sub-components. 
+In the table, the left column contains a description of each repository, and the right column shows the component repositories which are pointing to (or will point to) the authoritative repositories. The ufs-weather-model currently uses git submodule to manage the sub-components.
 
 The umbrella repository for the UFS Weather Model is named ufs-weather-model.  Under this repository reside a number of submodules that are nested in specific directories under the parent repository’s working directory.  When the ufs-weather-model repository is cloned, the *.gitmodules* file creates the following directories:
 
@@ -53,9 +53,9 @@ The umbrella repository for the UFS Weather Model is named ufs-weather-model.  U
    ├── NEMS                                    https://github.com/NCAR/NEMS
    │   └── tests/produtil/NCEPLIBS-pyprodutil  https://github.com/NOAA-EMC/NCEPLIBS-pyprodutil
    ├── stochastic_physics                      https://github.com/noaa-psd/stochastic_physics
- 
+
 ===================
-Directory Structure 
+Directory Structure
 ===================
 
 When the ufs-weather-model is cloned, the basic directory structure will be similar to the example below. Files and some directories have been removed for brevity.
@@ -81,7 +81,7 @@ When the ufs-weather-model is cloned, the basic directory structure will be simi
    │   │   ├── physics      -------- CCPP compliant physics schemes
    │   │   └── suites       -------- CCPP physics suite definition files (SDFs)
    │   ├── cpl              -------- Coupling field data structures
-   │   ├── gfsphysics 
+   │   ├── gfsphysics
    │   │   ├── CCPP_layer
    │   │   ├── GFS_layer
    │   │   └── physics     --------- unused - IPD version of physics codes
@@ -98,5 +98,6 @@ When the ufs-weather-model is cloned, the basic directory structure will be simi
    ├── stochastic_physics   -------- stochastic physics pattern generator
    ├── tests               --------- regression test scripts
 
-The physics subdirectory in the *gfsphysics* directory  is not used or supported as part of this release (all physics is available through the :term:`CCPP`).
-
+The physics subdirectory in the *gfsphysics* directory  is not used or supported
+as part of this release (all physics is available through the :term:`CCPP` using
+the repository described in :numref:`Table %s <Repo_Structure>`).
diff --git a/doc/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Introduction.rst
@@ -1,15 +1,15 @@
 .. _Introduction:
-  
+
 *************************
 Introduction
 *************************
 
 The Unified Forecast System (:term:`UFS`) :term:`Weather Model` (WM) is a prognostic model that can be
 used for short- and medium-range research and operational forecasts, as exemplified by
-its use in the operational Global Forecast System (GFS) of the National Oceanic and 
+its use in the operational Global Forecast System (GFS) of the National Oceanic and
 Atmospheric Administration (NOAA). The UFS WM v1.0 is the first public release of this
 software and represents a snapshot of a continuously evolving system undergoing open
-development. More information about the UFS can be found in its portal at https://ufscommunity.org/. 
+development. More information about the UFS can be found in its portal at https://ufscommunity.org/.
 
 Key architectural elements of the UFS WM, along with links to external detailed documentation
 for those elements, are listed below:
@@ -19,21 +19,21 @@ for those elements, are listed below:
 - The Flexible Modeling System (:term:`FMS`), a software infrastructure used for functions such as
   parallelization (https://www.gfdl.noaa.gov/fms/).
 
-- The Common-Community Physics Package (:term:`CCPP`) library of 
-  physical parameterizations (:term:`Parameterization or physics scheme`) and the 
+- The Common-Community Physics Package (:term:`CCPP`) library of
+  physical parameterizations (:term:`Parameterization or physics scheme`) and the
   framework to use it with the model
   (https://dtcenter.org/community-code/common-community-physics-package-ccpp).
 
 - The stochastic physics capability, including the Stochastic Kinetic Backscatter Scheme (SKEBS),
   the Stochastically Perturbed Parameterization Tendencies (SPPT) scheme, the perturbed boundary
-  layer humidity (SHUM) scheme, and the cellular automata method 
+  layer humidity (SHUM) scheme, and the cellular automata method
   (https://stochastic-physics.readthedocs.io/en/ufs_public_release/).
 
 - The NOAA Environmental Modeling System (:term:`NEMS`) model driver used to create the main program
   (https://noaa-emc.github.io/NEMS_doc/index.html).
 
-- The libraries needed to build the system, such as: 
-    - National Centers for Environmental Prediction (NCEP) Libraries 
+- The libraries needed to build the system, such as:
+    - National Centers for Environmental Prediction (NCEP) Libraries
     - Earth System Modeling Framework (ESMF; https://www.earthsystemcog.org/projects/esmf/)
     - System libraries
 
@@ -47,50 +47,63 @@ For the UFS WM v1.0 release, the following aspects are supported:
 
 - Sixty-four vertical levels at predetermined locations.
 
-- Two physics suites (:term:`suite`), corresponding to GFS v15.2 (operational at the time of the release) and
-  GFS v16beta (October 2019 version, in preparation for operational implementation in 2021).
-
+- Four physics suites (:term:`suite`), corresponding to GFS v15.2 (operational at the time of the release) and
+  GFS v16beta (October 2019 version, in preparation for operational implementation in 2021). Variants
+  with and without prediction of Sea Surface Temperature (SST) are included.
+
 - Ability to run with or without SKEBS, SPPT, and SHUM.
- 
-- Ability to initialize from GFS files in Gridded Binary v2 (GRIB2) format for past dates, 
+
+- Ability to initialize from GFS files in Gridded Binary v2 (GRIB2) format for past dates,
   starting January 1, 2018, when the preprocessing utility chgres is employed. Dates before
   that may work, but are not guaranteed.
- 
+
 - Output files in Network Common Data Form (NetCDF) format.
 
-The GFS v15.2 physics suite uses the following physical parameterization: the Simplified Arakawa Schubert shallow and deep convective schemes, the Geophysical Fluid Dynamics Laboratory (GFDL) microphysics scheme, the Noah Land Surface Model (LSM), the Rapid Radiative Transfer Model for Global Circulation Models (RRTMG) radiation scheme, the hybrid eddy-diffusivity mass-flux (EDMF) planetary boundary layer (PBL) scheme based on the Smagorinsky K theory, and an orographic gravity wave drag (GWD) parameterization. In the GFS v16beta suite, a moist TKE-based EDMF scheme replaces the K-based one and a non-stationary GWD parameterization is added. It should be noted that the public release code reflects the state of development as of the fall of 2019, and therefore the parameterizations contains innovations beyond what is currently in operations. In other words, the GFDL microphysics distributed for use in GFS v15.2 and GFS v16beta is the same scheme and contains development beyond what was transitioned to operations for GFS v15 in June 2019. It should also be noted that further changes are expected to the GFS v16 suite before it is implemented in operations in 2021.
+The GFS_v15p2 physics suite uses the following physical parameterizations: the
+Simplified Arakawa Schubert shallow and deep convective schemes, the Geophysical
+Fluid Dynamics Laboratory (GFDL) microphysics scheme, the Noah Land Surface Model (LSM),
+the Rapid Radiative Transfer Model for Global Circulation Models (RRTMG) radiation scheme,
+the hybrid eddy-diffusivity mass-flux (EDMF) planetary boundary layer (PBL) scheme based on the Smagorinsky K theory,
+an orographic gravity wave drag (GWD) parameterization, and the Near SST (NSST) ocean scheme to predict SST.
+In the GFS_v16beta suite, a moist TKE-based EDMF scheme replaces the K-based one and a non-stationary GWD parameterization is added.
+The GFS_v15p2_no_nsst and the GFS_v16beta_no_nsst suites use a simple ocean scheme instead of the NSST scheme.
+This simple ocean scheme keeps the SST constant throughout the forecast and is recommended for use when the initial
+conditions do not contain all fields needed to initialize the NSST scheme.
+It should be noted that the public release code reflects the state of development as of the fall of 2019,
+and therefore the parameterizations contains innovations beyond what is currently in operations.
+In other words, the GFDL microphysics distributed for use in GFS v15.2 and GFS v16beta
+is the same scheme and contains development beyond what was transitioned to operations for GFS v15 in June 2019.
+It should also be noted that further changes are expected to the GFS v16 suite before it is implemented in operations in 2021.
 
 The UFS WM v1 code is portable and can be used with Linux and Mac operating systems with Intel and GNU compilers. It has been tested in a variety of platforms widely used by atmospheric scientists, such as the NOAA research Hera system, the National Center for Atmospheric Research (NCAR) Cheyenne system, the National Science Foundation Stampede system, and Mac laptops.
 
 .. note::
 
    At this time, the following aspects are unsupported:  standalone regional domains, configurations in which a mediator is used to couple the atmospheric model to models of other earth domains (such as ocean, ice, and waves), horizontal resolutions other than the supported ones, different number or placement of vertical levels, physics suites other than GFS v15.2 and GFS v16beta the *cellular automata* stochastic scheme, initialization from sources other than GFS, the use of different file formats for input and output, and the use of the model in different computational platforms. It is expected that the UFS WM supported capabilities will be expanded in future releases.
 
-It should be noted that the UFS WM is a component of the UFS Medium-Range Weather Application, which also contains pre- and post-processing components, a comprehensive build system, and workflows for configuration and execution of the application. At this time, the UFS WM is only supported to the general community for use as part of the UFS Medium-Range Weather Application. However, those wishing to contribute development to the UFS WM should become familiar with the procedures for running the model as a standalone component and for executing the regression tests to make sure no inadvertent changes to the results have been introduced during the development process.
+It should be noted that the UFS WM is a component of the UFS Medium-Range Weather Application, which also contains pre- and post-processing components, a comprehensive build system, and workflows for configuration and execution of the application. At this time, the UFS WM is only supported to the general community for use as part of the UFS Medium-Range Weather Application. However, those wishing to contribute development to the UFS WM should become familiar with the procedures for running the model as a standalone component and for executing the regression tests described in this guide to make sure no inadvertent changes to the results have been introduced during the development process.
 
-Support for the UFS WM is provided through the UFS Forum by the Developmental Testbed Center (DTC) and other groups involved in UFS development, such as NOAA’s Environmental Modeling Center (EMC), NOAA research laboratories (GFDL, NSSL, ESRL, and AOML), and NCAR. UFS users and developers are encouraged not only to post questions, but also to help address questions posted by other members of the community. 
+Support for the UFS WM is provided through the UFS Forum by the Developmental Testbed Center (DTC) and other groups involved in UFS development, such as NOAA’s Environmental Modeling Center (EMC), NOAA research laboratories (GFDL, NSSL, ESRL, and AOML), and NCAR. UFS users and developers are encouraged not only to post questions, but also to help address questions posted by other members of the community.
 
 This WM User’s Guide is organized as follows:
 
 - :numref:`Chapter %s <CodeOverview>` (Code Overview) provides a description of the various
-  code repositories from which source code is pulled and an overview of the directory structure. 
+  code repositories from which source code is pulled and an overview of the directory structure.
 
-- :numref:`Chapter %s <BuildingAndRunning>` (Building and Running the WM)
+- :numref:`Chapter %s <BuildingAndRunning>` (Building and Running the WM) explains how to use the WM without an application.
 
 - :numref:`Chapter %s <InputsOutputs>` (Inputs and Outputs) lists the model inputs and outputs
   and has a description of the key files.
 
 - :numref:`Chapter %s <SDFandNamelistExamplePractices>` (SDF and namelist samples and best practices)
   contains a description of the :term:`Suite Definition File (SDF)` and namelists needed to configure the model
-  for running with the GFS v15.2 and GFS v16beta physics suites. 
+  for running with the GFS v15.2 and GFS v16beta physics suites.
 
 The next chapter:
 
-- :numref:`Chapter %s <ContributingDevelopment>` (Contributing development)
+- :numref:`Chapter %s <ContributingDevelopment>` (Contributing development) goes beyond the capabilities supported in the public release to cover code management for conducting development and proposing contributions back to the authoritative code repositories. It should be noted that the regression tests described here are mandatory for committing code back to the ufs-weather-model authoritative code repository. These regressions tests differ from those distributed with the workflows for UFS applications, which are intended for application users and developers to assess the quality of their installations and the impact of their code changes.
 
-goes beyond the capabilities supported in the public release to cover code management for conducting
-development and proposing contributions back to the authoritative code repositories. It should be noted that the regression tests described here are mandatory for committing code back to the ufs-weather-model authoritative code repository. These regressions tests differ from those distributed with the workflows for UFS applications, which are intended for application users and developers to assess the quality of their installations and the impact of their code changes. Finally,
-:numref:`Chapters %s <Acronyms>` and :numref:`%s <Glossary>` contain a list of acronyms and a glossary, respectively.
+Finally, :numref:`Chapters %s <Acronyms>` and :numref:`%s <Glossary>` contain a list of acronyms and a glossary, respectively.
 
 .. This is how you cite a reference :cite:`Bernardet2018`.