Merge pull request #18 from ligiabernardet/doc_updates

Various updates to the CCPP TechDoc for v4 release

CCPPtechnical/source/Acronyms.rst

@@ -4,7 +4,7 @@
 Acronyms
 *************************
 
-.. table:: 
+.. table::
    :widths: 20 80
 
    +----------------+---------------------------------------------------+
@@ -51,8 +51,6 @@ Acronyms
    +----------------+---------------------------------------------------+
    | GFS            | Global Forecast System                            |
    +----------------+---------------------------------------------------+
-   | GMTB           | Global Model Test Bed                             |
-   +----------------+---------------------------------------------------+
    | GSD            | Global Systems Division                           |
    +----------------+---------------------------------------------------+
    | HEDMF          | Hybrid eddy-diffusivity mass-flux                 |
@@ -88,6 +86,8 @@ Acronyms
    +----------------+---------------------------------------------------+
    | NRL            | Naval Research Laboratory                         |
    +----------------+---------------------------------------------------+
+   | NSST           | Near Sea Surface Temperature ocean scheme         |
+   +----------------+---------------------------------------------------+
    | NUOPC          | National Unified Operational Prediction           |
    |                | Capability                                        |
    +----------------+---------------------------------------------------+

CCPPtechnical/source/BuildingRunningHostModels.rst

@@ -1,5 +1,5 @@
 .. _BuildingRunningHostModels:
-  
+
 ****************************************
 Building and Running Host Models
 ****************************************
@@ -41,7 +41,7 @@ Further, there are several utility libraries as part of the NCEPlibs package tha
     * sp v2.0.2 - Spectral Transformation Library
     * w3nco v2.0.6 - GRIB decoder and encoder library
 
-These libraries are prebuilt on most NOAA machines using the Intel compiler. For those needing to build the libraries themselves, GMTB recommends using the source code from GitHub at https://github.com/NCAR/NCEPlibs.git, which includes build files for various compilers and machines using OpenMP flags and which are thread-safe. Instructions for installing NCEPlibs are included on the GitHub repository webpage, but for the sake of example, execute the following for obtaining and building from source in ``/usr/local/NCEPlibs`` on a Mac:
+These libraries are prebuilt on most NOAA machines using the Intel compiler. For those needing to build the libraries themselves, DTC recommends using the source code from GitHub at https://github.com/NCAR/NCEPlibs.git, which includes build files for various compilers and machines using OpenMP flags and which are thread-safe. Instructions for installing NCEPlibs are included on the GitHub repository webpage, but for the sake of example, execute the following for obtaining and building from source in ``/usr/local/NCEPlibs`` on a Mac:
 
 .. code-block:: console
 
@@ -153,14 +153,16 @@ Running a case requires three pieces of information: the case to run (consisting
     ./run_gmtb_scm.py -c CASE_NAME [-s SUITE_NAME] [-n PHYSICS_NAMELIST_PATH] [-g]
 
 
-When invoking the run script, the only required argument is the name of the case to run. The case name used must match one of the case configuration files located in ``../etc/case_config`` (*without the .nml extension!*). If specifying a suite other than the default, the suite name used must match the value of the suite name in one of the SDFs located in ``../../ccpp/suites`` (Note: not the filename of the SDF). As part of the third CCPP release, the following suite names are valid:
+When invoking the run script, the only required argument is the name of the case to run. The case name used must match one of the case configuration files located in ``../etc/case_config`` (*without the .nml extension!*). If specifying a suite other than the default, the suite name used must match the value of the suite name in one of the SDFs located in ``../../ccpp/suites`` (Note: not the filename of the SDF). As part of the CCPP v4 release, the following suite names are valid:
 
-    * SCM_GFS_v15
-    * SCM_GFS_v15plus
+    * SCM_GFS_v15p2
+    * SCM_GFS_v15p2_no_nsst
+    * SCM_GFS_v16beta
+    * SCM_GFS_v16beta_no_nsst
     * SCM_csawmg
-    * SCM_GSD_v0
+    * SCM_GSD_v1
 
-Note that using the Thompson microphysics scheme (as in ``SCM_GSD_v0``) requires the existence of lookup tables during its initialization phase. As of the release, computation of the lookup tables has been prohibitively slow with this model, so it is highly suggested that they be downloaded and staged to use this scheme (and the ``SCM_GSD_v0`` suite). Pre-computed tables have been created and are available for download at the following URLs:
+Note that using the Thompson microphysics scheme (as in ``SCM_GSD_v1``) requires the existence of lookup tables during its initialization phase. As of the release, computation of the lookup tables has been prohibitively slow with this model, so it is highly suggested that they be downloaded and staged to use this scheme (and the ``SCM_GSD_v1`` suite). Pre-computed tables have been created and are available for download at the following URLs:
     * https://dtcenter.org/GMTB/freezeH2O.dat (243 M)
     * https://dtcenter.org/GMTB/qr_acr_qg.dat (49 M)
     * https://dtcenter.org/GMTB/qr_acr_qs.dat (32 M)

CCPPtechnical/source/CodeManagement.rst

@@ -20,12 +20,12 @@ https://github.com/NCAR/ccpp-framework
 
 https://github.com/NCAR/ccpp-physics
 
-Users have read-only access to these repositories and as such cannot accidentally destroy any important (shared) branches of these authoritative repositories. Both CCPP repositories are public (no GitHub account required) and may be used directly to read or create forks. Write permission is generally restricted, however. 
+Users have read-only access to these repositories and as such cannot accidentally destroy any important (shared) branches of these authoritative repositories. Both CCPP repositories are public (no GitHub account required) and may be used directly to read or create forks. Write permission is generally restricted, however.
 
 The following branches are recommended for CCPP developers:
 
 +----------------------------------------+-------------+
-| Repository (GMTB development version)  | Branch name |
+| Repository                             | Branch name |
 +========================================+=============+
 | https://github.com/NCAR/ccpp-physics   | master      |
 +----------------------------------------+-------------+
@@ -95,7 +95,7 @@ The GitHub forking workflow relies on forks (personal copies) of the shared repo
 Note that personal forks are not required until a user wishes to make code contributions. The procedure for how to check out the code laid out below can be followed without having created any forks beforehand.
 
 -----------------------------------
-Checking out the Code 
+Checking out the Code
 -----------------------------------
 Instructions are provided here for the ccpp-physics repository. Similar steps are required for the ccpp-frameworkx repository. The process for checking out the CCPP is described in the following, assuming access via https rather than ssh. We strongly recommend setting up passwordless access to GitHub (see https://help.github.com/categories/authenticating-to-github).
 
@@ -120,11 +120,11 @@ However, if you are making code changes, you must create a local branch.
 .. code-block:: console
 
    git checkout -b my_local_development_branch
- 
+
 Once you are ready to contribute the code to the upstream repository, you need to create a PR (see next section). In order to do so, you first need to create your own fork of this repository (see previous section) and configure your fork as an additional remote destination, which we typically label as origin. For example:
 
 .. code-block:: console
- 
+
    git remote add origin https://github.com/YOUR_GITHUB_USER/ccpp-physics
    git remote update
 
@@ -141,7 +141,7 @@ For each repository/submodule, you can check the configured remote destinations
    git remote -v show
    git remote update
    git branch -a
- 
+
 As opposed to branches without modifications described in step 3, changes to the upstream repository can be brought into the local branch by pulling them down. For example (where a local branch is checked out):
 
 .. code-block:: console
@@ -156,7 +156,7 @@ As opposed to branches without modifications described in step 3, changes to the
 Committing Changes to your Fork
 ==================================
 Once you have your fork set up to begin code modifications, you should check that the cloned repositories upstream and origin are set correctly:
-		
+
 .. code-block:: console
 
    git remote -v
@@ -243,4 +243,3 @@ Several people (aka CODEOWNERS) are automatically added to the list of reviewers
 Once the PR has been approved, the change is merged to master by one of the code owners. If there are pending conflicts, this means that the code is not up to date with the trunk. To resolve those, pull the target branch from upstream as described above, solve the conflicts and push the changes to the branch on your fork (this also updates the PR).
 
 Note. GitHub offers a draft pull request feature that allows users to push their code to GitHub and create a draft PR. Draft PRs cannot be merged and do not automatically initiate notifications to the CODEOWNERS, but allow users to prepare the PR and flag it as “ready for review” once they feel comfortable with it.
-

CCPPtechnical/source/CompliantPhysicsParams.rst

@@ -14,7 +14,7 @@ It is recommended that parameterizations be comprised of the smallest units that
 For example, if a given set of deep and shallow convection schemes will always be called together
 and in a pre-established order, it is acceptable to group them within a single scheme. However, if one
 envisions that the deep and shallow convection schemes may someday operate independently, it is
-recommended to code two separate schemes to allow more flexibility.  
+recommended to code two separate schemes to allow more flexibility.
 
 Some schemes in the CCPP have been implemented using a driver as an entry point. In this context,
 a driver is defined as a wrapper that sits on top of the actual scheme and provides the CCPP entry
@@ -37,7 +37,7 @@ The implementation of a driver is reasonable under the following circumstances:
   provided by the host model to either write out a message and return an error code or call a
   subroutine with or without optional arguments. For example, see ``mp_thompson_hrrr.F90``,
   ``radsw_main.f``, or ``radlw_main.f`` in the ``ccpp-physics/physics`` directory.
- 
+
 * To perform unit conversions or array transformations, such as flipping the vertical direction
   and rearranging the index order, for example, ``cu_gf_driver.F90`` in the ``ccpp-physics/physics``
   directory.
@@ -60,7 +60,7 @@ General Rules
 A CCPP-compliant scheme is in the form of Fortran modules. :ref:`Listing 2.1 <scheme_template>` contains
 the template for a CCPP-compliant scheme (``ccpp/framework/doc/DevelopersGuide/scheme_template.F90``),
 which includes three essential components: the *_init*, *_run*, and *_finalize* subroutines. Each ``.f`` or ``.F90``
-file that contains an entry point(s) for CCPP scheme(s) must be accompanied by a .meta file in the same directory 
+file that contains an entry point(s) for CCPP scheme(s) must be accompanied by a .meta file in the same directory
 as described in :numref:`Section %s <MetadataRules>`
 
 .. _scheme_template:
@@ -84,8 +84,8 @@ More details are found below:
   metadata about the arguments to the scheme(s). For more information, see :numref:`Section %s <MetadataRules>`.
 
 * Non-empty schemes must be preceded by the three lines below. These are markup comments used by Doxygen,
-  the software employed to create the scientific documentation, to insert an external file containing metadata 
-  information (in this case, ``schemename_run.html``) in the documentation. See more on this topic in 
+  the software employed to create the scientific documentation, to insert an external file containing metadata
+  information (in this case, ``schemename_run.html``) in the documentation. See more on this topic in
   :numref:`Section %s <SciDoc>`.
 
 .. code-block:: fortran
@@ -165,7 +165,7 @@ Metadata Rules
    dimensions = (horizontal_dimension,vertical_dimension)
    dimensions = (horizontal_dimension,vertical_dimension_of_ozone_forcing_data,number_of_coefficients_in_ozone_forcing_data)
 
-* :ref:`Listing 2.2 <meta_template>` contains the template for a CCPP-compliant scheme 
+* :ref:`Listing 2.2 <meta_template>` contains the template for a CCPP-compliant scheme
   (``ccpp/framework/doc/DevelopersGuide/scheme_template.meta``),
 
 .. _meta_template:
@@ -184,7 +184,7 @@ Input/output Variable (argument) Rules
   are used in the CCPP (see below for further information).
 
 * A list of available standard names and an example of naming conventions can be found in
-  ``ccpp/framework/doc/DevelopersGuide/CCPP_VARIABLES_${HOST}.pdf``, where ``${HOST}`` is the 
+  ``ccpp/framework/doc/DevelopersGuide/CCPP_VARIABLES_${HOST}.pdf``, where ``${HOST}`` is the
   name of the host model.  Running the CCPP *prebuild* script (described in :numref:`Chapter %s <CCPPPreBuild>`)
   will generate a LaTeX source file that can be compiled to produce
   a PDF file with all variables defined by the host model and requested by the physics schemes.
@@ -238,16 +238,16 @@ Input/output Variable (argument) Rules
      DDTs should be broken into components that could be usable for another scheme of the same type.
 
 * It is preferable to have separate variables for physically-distinct quantities. For example,
-  an array containing various cloud properties should be split into its individual 
+  an array containing various cloud properties should be split into its individual
   physically-distinct components to facilitate generality. An exception to this rule is if
   there is a need to perform the same operation on an array of otherwise physically-distinct
   variables. For example, tracers that undergo vertical diffusion can be combined into one array
   where necessary. This tactic should be avoided wherever possible, and is not acceptable merely
   as a convenience.
 
 * If a scheme is to make use of CCPP’s subcycling capability, the loop counter can be obtained
-  from CCPP as an ``intent(in)`` variable (see :ref:`Listing 6.2 <MandatoryVariables>` for a mandatory
-  list of variables that are provided by the CCPP-Framework and/or the host model for this and other purposes). 
+  from CCPP as an ``intent(in)`` variable (see a :ref:`mandatory list of variables <MandatoryVariables>`
+  that are provided by the CCPP-Framework and/or the host model for this and other purposes).
 
 .. _CodingRules:
 
@@ -293,7 +293,7 @@ Coding Rules
 Additional coding rules are listed under the *Coding Standards* section of the NOAA NGGPS
 Overarching System team document on Code, Data, and Documentation Management for NOAA Environmental
 Modeling System (NEMS) Modeling Applications and Suites (available at
-https://docs.google.com/document/u/1/d/1bjnyJpJ7T3XeW3zCnhRLTL5a3m4_3XIAUeThUPWD9Tg/edit#heading=h.97v79689onyd). 
+https://docs.google.com/document/u/1/d/1bjnyJpJ7T3XeW3zCnhRLTL5a3m4_3XIAUeThUPWD9Tg/edit#heading=h.97v79689onyd).
 
 Parallel Programming Rules
 ==========================
@@ -317,7 +317,7 @@ in a physics scheme:
    * The implementation of reading and writing of data must be scalable to perform
      efficiently from a few to millions of tasks.
    * The MPI communicator must be provided by the host model as an ``intent(in)``
-     argument in the argument list (:ref:`Listing 6.2 <MandatoryVariables>`).
+     argument in the argument list (:ref:`see list of mandatory variables <MandatoryVariables>`).
    * The use of MPI_COMM_WORLD is not allowed.
 
 * Calls to MPI and OpenMP functions, and the import of the MPI and OpenMP libraries,
@@ -344,7 +344,7 @@ in a physics scheme:
      me = 0
    #endif
 
-* For Fortran coarrays, consult with the GMTB helpdesk (gmtb-help@ucar.edu).
+* For Fortran coarrays, consult with the DTC helpdesk (gmtb-help@ucar.edu).
 
 .. include:: ScientificDocRules.inc
 

CCPPtechnical/source/ConstructingSuite.rst

@@ -161,10 +161,10 @@ Consider the case where a model requires that some subset of physics be called o
    </suite>
 
 -------------------------------
-Operational GFS v16beta Suite
+GFS v16beta Suite
 -------------------------------
 
-Here is the :term:`SDF` for the physics suite equivalent to the operational GFS v16beta in the :term:`UFS` Atmosphere, which employs various groups and subcycling:
+Here is the :term:`SDF` for the physics suite equivalent to the GFS v16beta in the :term:`UFS` Atmosphere, which employs various groups and subcycling:
 
 .. code-block:: xml
 

CCPPtechnical/source/Introduction.rst

@@ -1,21 +1,22 @@
-.. include:: prolog.inc 
+.. include:: prolog.inc
 
 How to Use this Document
 ========================
 
-This document contains documentation for the Common Community Physics Package (CCPP). It decsribes the:
+This document contains documentation for the Common Community Physics Package (CCPP). It describes the
 
-* physics schemes and interstitials
-* suite definition files
+* Physics schemes and interstitials
+* Suite definition files
 * CCPP-compliant parameterizations
-* adding a new scheme/suite
-* host-side coding
-* fundamentals of obtaining, pre-building, building and running the CCPP with the ufs-weather-model
+* Process to add a new scheme or suite
+* Host-side coding
 * CCPP code management and governance
 
-For the latest version of the released code, please visit the `GMTB Website <http://www.dtcenter.org/gmtb/users/ccpp>`_
+For the latest version of the released code, please visit the `DTC Website <http://www.dtcenter.org/gmtb/users/ccpp>`_
 
-Please send questions and comments to the help desk: gmtb-help@ucar.edu
+Please send questions and comments to the help desk: gmtb-help@ucar.edu.
+When using the CCPP with NOAA's Unified Forecast System, questions can also be posted
+in the UFS Forum at https://forums.ufscommunity.org/.
 
 This table describes the type changes and symbols used in this guide.