Address Issue 67: Updates for latest release (#69)

 - Adds section on "time-split" vs "process-split" schemes
 - Adds some tips for allocating memory in a way that allows "stateless" schemes (though we don't use that term)
 - Make some format and wording consistency changes
 - Some format and wording fixes
 - Clarify some rules as actual rules and not just suggestions

CCPPtechnical/source/Acronyms.rst

@@ -1,5 +1,3 @@
-.. _Acronyms:
-
 *************************
 Acronyms
 *************************
@@ -120,7 +118,7 @@ Acronyms
    +----------------+---------------------------------------------------+
    | SAS            | Simplified Arakawa-Schubert                       |
    +----------------+---------------------------------------------------+
-   | SCM            | Single Column Model                               |
+   | SCM            | Single-Column Model                               |
    +----------------+---------------------------------------------------+
    | SDF            | Suite Definition File                             |
    +----------------+---------------------------------------------------+

CCPPtechnical/source/AddingNewSchemes.rst

@@ -29,7 +29,7 @@ There are, broadly speaking, two approaches for connecting an existing physics s
 
    *Diagram of the methods described in this section.*
 
-Method 1 is the preferred method of adapting a scheme to CCPP. This involves making modifications to the original scheme so that it is CCPP-compliant (see :numref:`Chapter %s <CompliantPhysParams>`), containing subroutines that correspond to CCPP entry points (i.e. ``schemename_init``, ``schemename_run``, etc.) as necessary. It should be accompanied by appropriate metadata files (see :numref:`Section %s <MetadataRules>`), and it must be updated to remove any disallowed features as listed in :numref:`Section %s <CodingRules>`.
+Method 1 is the preferred method of adapting a scheme to CCPP. This involves making modifications to the original scheme so that it is CCPP-compliant (see :numref:`Chapter %s <CompliantPhysParams>`), containing subroutines that correspond to CCPP entry points (i.e. ``{schemename}_init``, ``{schemename}_run``, etc.) as necessary. It should be accompanied by appropriate metadata files (see :numref:`Section %s <MetadataRules>`), and it must be updated to remove any disallowed features as listed in :numref:`Section %s <CodingRules>`.
 
 While method 1 is preferred, there are cases where method 1 may not be possible: for example, in schemes that are shared with other, non-CCPP hosts, and so require specialized, model-specific drivers, and might be beholden to different coding standards required by another model. In cases such as this, method 2 may be employed.
 
@@ -65,9 +65,9 @@ If information from the previous timestep is needed, it is important to identify
 
 Consider allocating the new variable only when needed (i.e. when the new scheme is used and/or when a certain control flag is set). If this is a viable option, following the existing examples in ``CCPP_typedefs.F90`` and ``GFS_typedefs.meta`` for allocating the variable and setting the ``active`` attribute in the metadata correctly.
 
-------------------------------
-Adding a new scheme to CCPP
-------------------------------
+----------------------------------
+Incorporating a scheme into CCPP
+----------------------------------
 The new scheme and any interstitials will need to be added to the CCPP prebuild configuration file. Add the new scheme to the Python dictionary in ``ccpp-scm/ccpp/config/ccpp_prebuild_config.py`` using the same path as the existing schemes:
 
 .. code-block:: 
@@ -87,7 +87,16 @@ To add this new scheme to a suite definition file (:term:`SDF`) for running with
 
 No further modifications of the build system are required, since the :term:`CCPP Framework` will auto-generate the necessary makefiles that allow the host model to compile the scheme.
 
+------------------------------------
+Time-split vs. process-split schemes
+------------------------------------
+
+One decision that will need to be made when incorporating a new scheme into CCPP is whether the scheme will be intended to be run as a time-split scheme or a process-split scheme:
+
+* A *process-split* scheme is one that is intended to use the host model's atmospheric state as an input, independent of state modifications made by other schemes that may or may not be called before this scheme. In this case, the resulting atmospheric state after a :term:`group` of schemes is executed can be simply calculated by applying the tendencies from each individual scheme to the initial atmospheric state prior to the calling of the physics group.
+* A *time-split* scheme is one that may work with a modified atmospheric state resulting from the previous application of one or more other time-split schemes. In this case, special care must be taken when applying tendencies to the atmospheric state, to ensure that both this and subsequent schemes are making the correct assumptions about the intput and output atmospheric state. Additionally, the order schemes appear within a group for a given SDF must be considered carefully.
 
+Currently the CCPP Physics contains a mix of process-split and time-split schemes, with the different strategies being handled by host-specific interstitial schemes. Future releases of CCPP will include a more robust system for handling these differences in the methods updating the atmospheric state.
 
 ==================================
 Testing and debugging a new scheme

CCPPtechnical/source/CompliantPhysicsParams.rst

@@ -29,13 +29,13 @@ The implementation of a driver is reasonable under the following circumstances:
 
 * To preserve schemes that are also distributed outside of the CCPP. For example, the Thompson
   microphysics scheme is distributed both with the Weather Research and Forecasting (WRF) model
-  and with the CCPP. Having a driver with CCPP directives allows the Thompson scheme to remain
-  intact so that it can be synchronized between the WRF model and the CCPP distributions. See
-  more in ``mp_thompson.F90`` in the ``ccpp-physics/physics`` directory.
+  and with CCPP. Having a driver with CCPP directives allows the Thompson scheme to remain
+  intact so that it can be synchronized between the WRF model and the CCPP distributions. You 
+  can view this driver module in ``ccpp-physics/physics/mp_thompson.F90``.
 
-* To perform unit conversions or array transformations, such as flipping the vertical direction
-  and rearranging the index order, for example, ``cu_gf_driver.F90`` or ``gfdl_cloud_microphys.F90``
-  in the ``ccpp-physics/physics`` directory.
+* To perform array transformations, such as flipping the vertical direction
+  or rearranging the index order: for example, in the subroutine ``gfdl_cloud_microphys_run``
+  in ``ccpp-physics/physics/gfdl_cloud_microphys.F90``.
 
 Schemes in the CCPP are classified into two categories: :term:`primary schemes <primary scheme>` and :term:`interstitial schemes <interstitial scheme>`.
 A *primary* scheme is one that updates the state variables and tracers or that
@@ -101,7 +101,7 @@ initialized or not.
 
 :ref:`Listing 2.1 <scheme_template>` contains a template for a CCPP-compliant scheme, which 
 includes the *_run* subroutine for an example *scheme_template* scheme. Each ``.F`` or ``.F90``
-file that contains an entry point(s) for CCPP scheme(s) must be accompanied by a .meta file in the 
+file that contains one or more entry point for a CCPP scheme must be accompanied by a .meta file in the 
 same directory as described in :numref:`Section %s <MetadataRules>`
 
 .. _scheme_template:
@@ -491,9 +491,9 @@ Input/Output Variable (argument) Rules
 Coding Rules
 ============
 
-* Code must comply to modern Fortran standards (Fortran 90 or newer), where possible.
+* Code must comply to modern Fortran standards (Fortran 90 or newer).
 
-* Uppercase file endings (`.F`, `.F90`) are preferred to enable preprocessing by default.
+* Use uppercase file suffixes (`.F`, `.F90`) to enable preprocessing by default.
 
 * Labeled ``end`` statements should be used for modules, subroutines, functions, and type definitions;
   for example, ``module scheme_template → end module scheme_template``.
@@ -690,7 +690,16 @@ The following rules should be observed when including OpenMP or MPI communicatio
      me = 0
    #endif
 
-* For Fortran coarrays, consult with the CCPP Forum (https://dtcenter.org/forum/ccpp-user-support).
+* If the error flag is set within a parallelized section of code, ensure that error flag is broadcast to all tasks/processes.
+
+Memory allocation
+^^^^^^^^^^^^^^^^^
+
+* <b>Schemes should not use dynamic memory allocation on the heap.</b>
+
+* Schemes should not contain data that may clash when multiple non-interacting instances of the scheme are being used in one executable. This is because some host models may run multiple CCPP instances from the same executable.
+
+* No variables should be allocated at the module level. Variables should either be allocated by the host model (for input and output variables) or within individual subroutines (for internal scheme variables).
 
 .. include:: ScientificDocRules.inc
 

CCPPtechnical/source/ConstructingSuite.rst

@@ -22,8 +22,6 @@ Groups
 
 The concept of grouping physics in the SDF (reflected in the ``<group name="XYZ">`` elements) enables *groups* of parameterizations to be called with other computation (such as related to the dycore, I/O, etc.) in between. One can edit the groups to suit the needs of the host application. For example, if a subset of physics schemes needs to be more tightly connected with the dynamics and called more frequently, one could create a group consisting of that subset and place a ``ccpp_physics_run`` call in the appropriate place in the host application. The remainder of the parameterization groups could be called using ``ccpp_physics_run`` calls in a different part of the host application code.
 
-..  _Subcycling:
-
 -----------------
 Subcycling
 -----------------
@@ -147,7 +145,7 @@ Consider the case where a model requires that some subset of physics be called o
 GFS v16beta Suite
 -------------------------------
 
-Here is the SDF for the physics suite equivalent to the GFS v16beta in the Single Column Model (:term:`SCM`), which employs various groups and subcycling:
+Here is the SDF for the physics suite equivalent to the GFS v16beta in the Single-Column Model (:term:`SCM`), which employs various groups and subcycling:
 
 .. code-block:: xml
 

CCPPtechnical/source/Glossary.rst

@@ -95,7 +95,7 @@ Glossary
       A collection of physics :term:`schemes <scheme>` that do not share memory (e.g. fast and slow physics)
 
    SCM
-      The :term:`CCPP` Single Column Model (SCM) is a simple 1D :term:`host model` designed to be used with the CCPP
+      The :term:`CCPP` Single-Column Model (SCM) is a simple 1D :term:`host model` designed to be used with the CCPP
       Physics and Framework as a lightweight alternative to full 3D dynamical models for testing
       and development of physics :term:`schemes <scheme>` and :term:`suites <suite>`. See the `SCM User Guide <https://dtcenter.org/sites/default/files/paragraph/scm-ccpp-guide-v6-0-0.pdf>`_
       for more information.

CCPPtechnical/source/Introduction.rst

@@ -35,7 +35,7 @@ The following table describes the type changes and symbols used in this guide.
          * The names of CCPP-specific terms, subroutines, etc.
          * Captions for figures, tables, etc.
      - 
-         * Each scheme must include at least one of the following subroutines: *_timestep_init*, *_init*, *_run*, *_finalize*, and *_timestep_finalize*.
+         * Each scheme must include at least one of the following subroutines: ``{schemename}_timestep_init``, ``{schemename}_init``, ``{schemename}_run``, ``{schemename}_finalize``, and ``{schemename}_timestep_finalize``.
          * *Listing 2.1: Fortran template for a CCPP-compliant scheme showing the* _run *subroutine.*
    * - **AaBbCc123**
      - Words or phrases requiring particular emphasis

CCPPtechnical/source/Overview.rst

@@ -55,7 +55,7 @@ The architecture of the CCPP and its connection to a host model is shown in
 Two elements of the CCPP are highlighted: a library of physical parameterizations
 (:term:`CCPP Physics`) that conforms to selected standards and an infrastructure (:term:`CCPP Framework`)
 that enables connecting the physics to a host model. The third element (not shown)
-is the CCPP Single Column Model (:term:`SCM`), a simple host model that can be used with the CCPP
+is the CCPP Single-Column Model (:term:`SCM`), a simple host model that can be used with the CCPP
 Physics and Framework.
 
 .. _ccpp_arch_host:
@@ -211,7 +211,7 @@ please visit the `DTC Website <https://dtcenter.org/community-code/common-commun
 Please post questions and comments to the GitHub discussions board for the relevant code repository:
  - CCPP Physics https://github.com/NCAR/ccpp-physics/discussions
  - CCPP Framework https://github.com/NCAR/ccpp-framework/discussions
- - Single Column Model https://github.com/NCAR/ccpp-scm/discussions
+ - Single-Column Model https://github.com/NCAR/ccpp-scm/discussions
  - UFS Weather Model https://github.com/ufs-community/ufs-weather-model/discussions
 
 .. include:: Introduction.rst

CCPPtechnical/source/ParamSpecificOutput.rst

@@ -442,7 +442,7 @@ Physics-side changes
 In order to output auxiliary arrays, developers need to change at least the following
 two files within the physics (see also example in :numref:`Section %s <CodeModExample>`):
 
-* A CCPP entrypoint scheme (Fortran source code)
+* A CCPP entry point scheme (Fortran source code)
    * Add array(s) and its/their dimension(s) to the list of subroutine arguments
    * Declare array(s) with appropriate intent and dimension(s).  Note that array(s) do not
      need to be allocated by the developer.  This is done automatically in ``GFS_typedefs.F90``.

CCPPtechnical/source/ScientificDocRules.inc

@@ -463,7 +463,7 @@ Including metadata information
 -----------------------------------------------
 
 As described above, a table of metadata information should be included in the documentation
-for every CCPP entrypoint scheme. Before doxygen is run, the table for each scheme must be manually
+for every CCPP entry point scheme. Before doxygen is run, the table for each scheme must be manually
 created in separate files in HTML format, with one file per scheme. The HTML files are included in the
 Fortran files using the doygen markup below.
 
@@ -490,11 +490,11 @@ For the example of the  :term:`SCM`, where both scripts need to be called from t
    ./ccpp/framework/scripts/metadata2html.py -m ccpp/physics/physics/file.meta -o ccpp/physics/physics/docs
 
 where ``-m`` is used to specify a file with metadata information and ``-o`` is used to specify
-the directory for output. Note that a single input file (``.meta``) may have more than one CCPP entrypoint
+the directory for output. Note that a single input file (``.meta``) may have more than one CCPP entry point
 scheme, and therefore can be used to generate more than one HTML file.
 
 Note that the ``.meta`` files are supplied in the CCPP Physics repository, and that there is a ``.meta`` file for
-each Fortran file that contains one or more CCPP entrypoint scheme. The ``.meta`` files are located in the same
+each Fortran file that contains one or more CCPP entry point scheme. The ``.meta`` files are located in the same
 directory as the scheme Fortran files (``ccpp-physics/physics``).
 
 To generate the complete Scientific Documentation, the script ``./ccpp/framework/scripts/metadata2html.py``
@@ -527,7 +527,7 @@ In order to generate the doxygen-based documentation, you will need to follow fi
    comments within the source code as described above.
 
 #. Run ``metadata2html.py`` to create files in HTML format containing metadata
-   information for each CCPP entrypoint scheme.
+   information for each CCPP entry point scheme.
 
 #. Prepare a Bibliography file in BibTex format for papers or other references cited in the physics suites.