From b792e827e55dda891555ebe478b2d6d7ce725100 Mon Sep 17 00:00:00 2001 From: "ligia.bernardet" Date: Sun, 8 Mar 2020 18:34:54 -0600 Subject: [PATCH] Various updates to the CCPP TechDoc. Updated list of suites, included no_nsst suites. Corrected reference to GFSv16beta (it is not operational). Changed examples to refer to supported schemes and suites. Updated acronyms and links. Removed mention to GMTB. --- CCPPtechnical/source/Acronyms.rst | 6 +- .../source/BuildingRunningHostModels.rst | 16 ++- CCPPtechnical/source/CodeManagement.rst | 15 +-- .../source/CompliantPhysicsParams.rst | 26 ++-- CCPPtechnical/source/ConstructingSuite.rst | 4 +- CCPPtechnical/source/Introduction.rst | 19 +-- CCPPtechnical/source/Overview.rst | 122 +++++++++--------- CCPPtechnical/source/ScientificDocRules.inc | 79 ++++++------ CCPPtechnical/source/index.rst | 2 +- 9 files changed, 146 insertions(+), 143 deletions(-) diff --git a/CCPPtechnical/source/Acronyms.rst b/CCPPtechnical/source/Acronyms.rst index b6b027d..a4a1896 100644 --- a/CCPPtechnical/source/Acronyms.rst +++ b/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 | +----------------+---------------------------------------------------+ diff --git a/CCPPtechnical/source/BuildingRunningHostModels.rst b/CCPPtechnical/source/BuildingRunningHostModels.rst index 349935f..edeeaea 100644 --- a/CCPPtechnical/source/BuildingRunningHostModels.rst +++ b/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) diff --git a/CCPPtechnical/source/CodeManagement.rst b/CCPPtechnical/source/CodeManagement.rst index 44c5c8d..7488eca 100644 --- a/CCPPtechnical/source/CodeManagement.rst +++ b/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. - diff --git a/CCPPtechnical/source/CompliantPhysicsParams.rst b/CCPPtechnical/source/CompliantPhysicsParams.rst index 8cdee80..acef4a6 100644 --- a/CCPPtechnical/source/CompliantPhysicsParams.rst +++ b/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 ` 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 ` .. _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 `. * 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 `. .. 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 ` contains the template for a CCPP-compliant scheme +* :ref:`Listing 2.2 ` 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 `) 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,7 +238,7 @@ 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 @@ -246,8 +246,8 @@ Input/output Variable (argument) Rules 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 ` 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 ` + 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 `). + argument in the argument list (:ref:`see list of mandatory variables `). * 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 diff --git a/CCPPtechnical/source/ConstructingSuite.rst b/CCPPtechnical/source/ConstructingSuite.rst index 99f2891..fccf247 100644 --- a/CCPPtechnical/source/ConstructingSuite.rst +++ b/CCPPtechnical/source/ConstructingSuite.rst @@ -161,10 +161,10 @@ Consider the case where a model requires that some subset of physics be called o ------------------------------- -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 diff --git a/CCPPtechnical/source/Introduction.rst b/CCPPtechnical/source/Introduction.rst index 8e9ba28..c560d0f 100644 --- a/CCPPtechnical/source/Introduction.rst +++ b/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 `_ +For the latest version of the released code, please visit the `DTC Website `_ -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. diff --git a/CCPPtechnical/source/Overview.rst b/CCPPtechnical/source/Overview.rst index abb53fb..0e5cfe8 100644 --- a/CCPPtechnical/source/Overview.rst +++ b/CCPPtechnical/source/Overview.rst @@ -5,17 +5,8 @@ CCPP Overview ************************* .. note:: The information in this document corresponds to the CCPP v4 release. - To obtain and build the latest available Technical Documentation use, the following: - commands: - - .. code-block:: console - - git clone https://github.com/NCAR/ccpp-doc - cd ccpp-doc - git checkout master - cd CCPPtechnical - make html - make latexpdf + To obtain the latest available Technical Documentation go to + https://ccpp-techdoc.readthedocs.io/en/latest/. Ideas for this project originated within the Earth System Prediction Capability (ESPC) physics interoperability group, which has representatives from the US National Center @@ -29,8 +20,8 @@ NOAA Geophysical Fluid Dynamics Laboratory (GFDL). The :term:`CCPP` expanded on meeting additional requirements put forth by `NOAA `_, and brought new functionalities to the physics-dynamics interface. Those include -the ability to choose the order of parameterizations, to subcycle individual -parameterizations by running them more frequently than other parameterizations, +the ability to choose the order of parameterizations, to subcycle individual +parameterizations by running them more frequently than other parameterizations, and to group arbitrary sets of parameterizations allowing other computations in between them (e.g., dynamics and coupling computations). @@ -71,13 +62,14 @@ which are not exposed to the user. The differences pertain to the interfaces be CCPP-Framework and the physics (physics *caps*) and the host model (host model *cap*), as well as in the procedures for calling the physics. In addition, the building option varies with choice of the host model. The only CCPP build option supported for use with the -CCPP Single-Column Model v4.0 or with the -UFS Medium-Range Weather Application v1.0 is the static build. +CCPP Single-Column Model v4.0 or with the +UFS Medium-Range Weather Application v1.0 is the static build. The dynamic build +will be phased out in a future release of the CCPP. The :term:`CCPP-Physics` contains the parameterizations and suites that are used operationally in the UFS Atmosphere, as well as parameterizations that are under development for possible transition to operations in the future. The CCPP aims to support the broad community -while benefiting from the community. In such a CCPP ecosystem +while benefiting from the community. In such a CCPP ecosystem (:numref:`Figure %s `), the CCPP can be used not only by the operational centers to produce operational forecasts, but also by the research community to conduct investigation and development. Innovations created and effectively tested by the research @@ -87,6 +79,7 @@ operational forecasts. Both the CCPP-Framework and the CCPP-Physics are developed as open source code, follow industry-standard code management practices, and are freely distributed through GitHub (https://github.com/NCAR/ccpp-physics and https://github.com/NCAR/ccpp-framework). +This documentation is housed in repository https://github.com/NCAR/ccpp-doc. .. _ccpp_ecosystem: @@ -99,74 +92,85 @@ The first public release of the CCPP took place in April 2018 and included all t parameterizations of the operational GFS v14, along with the ability to connect to the SCM. The second public release of the CCPP took place in August 2018 and additionally included the physics suite tested for the implementation of GFS v15. The third public release of -the CCPP, in June 2019, had four suites: GFS v15 and three developmental suites considered for +the CCPP, in June 2019, had four suites: GFS_v15, corresponding to the GFS v15 model implemented operationally +in June 2019, and three developmental suites considered for use in GFS v16 (GFS_v15plus with an alternate PBL scheme, csawmg with alternate convection and microphysics schemes, and GFS_v0 with alternate convection, microphysics, PBL, and land surface schemes). -In the current CCPP v4 release, an updated version of GFS v15 is available (GFSv15p2) along with three -developmental suites: the current target for the GFS v16 implementation (GFSv16beta), an updated version -of the NOAA Global Systems Division (GSD) suite (GSDv1), and the csawmg suite -(see :numref:`Table %s `). In addition to the schemes listed, more schemes are under -consideration for inclusion into the CCPP in the future. It should be noted that the public release of -the UFS Medium-Range Weather Application v1 only supports the use of the GFSv15p2 and GFSv16beta suites. +The CCPP v4 release, issued in March 2020, contains suite GFS_v15p2, which is an +updated version of the operational +GFS v15 and replaces suite GFS_v15. It also contains three developmental suites: +csawmg has minor updates, GSD_v1 is an update over the previously released GSD_v0, +and GFS_v16beta is the target suite for implementation in the upcoming operational GFSv16 +(it replaces suite GFSv15plus). Additionally, there are two new suites, +GFS_v15p2_no_nsst and GFS_v16beta_no_nsst, which are variants that treat the +sea surface temperature more simply. These variants are recommended for use when the initial conditions +do not contain all fields needed to initialize the more complex Near Sea Surface +Temperature (NSST) scheme. The `CCPP Scientific Documentation +`_ describes +the suites and their parameterizations in detail. The CCPP is governed by the groups that contribute to its development. The governance -of the CCPP-Physics is currently led by NOAA, and the GMTB works with EMC and the Next +of the CCPP-Physics is currently led by NOAA, and the DTC works with EMC and the Next Generation Global Prediction System (NGGPS) Program Office to determine which schemes and suites to be included and supported. The governance of the CCPP-Framework is jointly undertaken by NOAA and NCAR (see more information at https://github.com/NCAR/ccpp-framework/wiki -and https://dtcenter.org/gmtb/users/ccpp). Please direct all inquiries to gmtb-help@ucar.edu. +and https://dtcenter.org/gmtb/users/ccpp). Please direct all inquiries to gmtb-help@ucar.edu. .. _scheme_suite_table: .. table:: Suites supported in the CCPP - +--------------------+-----------------+--------------------------------------------------+ - | | **Operational** | **Experimental** | - +====================+=================+=================+=============+==================+ - | | **GFS_v15.2** | **GFS_v16beta** | **csawmg** | **GSD_v1** | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Microphysics | GFDL | GFDL | M-G3 | Thompson | - +--------------------+-----------------+-----------------+-------------+------------------+ - | PBL | K-EDMF | TKE EDMF | K-EDMF | saMYNN | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Deep convection | saSAS | saSAS | CSAW | GF | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Shallow convection | saSAS | saSAS | saSAS | saMYNN and saSAS | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Radiation | RRTMG | RRTMG | RRTMG | RRTMG | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Surface layer | GFS | GFS | GFS | GFS | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Gravity Wave Drag | uGWD | uGWD | uGWD | uGWD | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Land surface | Noah | Noah | Noah | RUC | - +--------------------+-----------------+-----------------+-------------+------------------+ - | Ozone | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | - +--------------------+-----------------+-----------------+-------------+------------------+ - | H\ :sub:`2`\ O | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | - +--------------------+-----------------+-----------------+-------------+------------------+ + +--------------------+-----------------+--------------------------------------------------+---------------------------------------------------+ + | | **Operational** | **Experimental** | **Variants** | + +====================+=================+=================+=============+==================+=========================+=========================+ + | | **GFS_v15p2** | **GFS_v16beta** | **csawmg** | **GSD_v1** | **GFS_v15p2_no_nsst** | **GFS_v16beta_no_nsst** | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Microphysics | GFDL | GFDL | M-G3 | Thompson | GFDL | GFDL | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | PBL | K-EDMF | TKE EDMF | K-EDMF | saMYNN | K-EDMF | TKE EDMF | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Deep convection | saSAS | saSAS | CSAW | GF | saSAS | saSAS | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Shallow convection | saSAS | saSAS | saSAS | saMYNN and saSAS | saSAS | saSAS | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Radiation | RRTMG | RRTMG | RRTMG | RRTMG | RRTMG | RRTMG | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Surface layer | GFS | GFS | GFS | GFS | GFS | GFS | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Gravity Wave Drag | uGWD | uGWD | uGWD | uGWD | uGWD | uGWD | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Land surface | Noah | Noah | Noah | RUC | Noah | Noah | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Ozone | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | H\ :sub:`2`\ O | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | NRL 2015 | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ + | Ocean | NSST | NSST | NSST | NSST | sfc_ocean | sfc_ocean | + +--------------------+-----------------+-----------------+-------------+------------------+-------------------------+-------------------------+ *The suites that are currently supported in the CCPP are listed in the second row. The types of parameterization are denoted in the first column, where H2O represents the stratospheric water -vapor parameterization. The GFS_v15.2 suite includes the GFDL microphysics, a Eddy-Diffusivity Mass +vapor parameterization. The GFS_v15p2 suite includes the GFDL microphysics, a Eddy-Diffusivity Mass Flux (K-EDMF) planetary boundary layer (PBL) scheme, scale-aware (sa) Simplified Arakawa-Schubert (SAS) convection, Rapid Radiation Transfer Model for General Circulation Models (RRTMG) radiation, the GFS surface layer, the unified gravity wave drag (uGWD), the Noah Land Surface Model (LSM), -and the 2015 Navy Research Laboratory (NRL) ozone and stratospheric water vapor schemes. -The other three suites are candidates for future operational implementations. The GFS_v16beta -suite is the same as the GFS_v15.2 suite except using the Turbulent Kinetic Energy (TKE)-based EDMF +the 2015 Navy Research Laboratory (NRL) ozone and stratospheric water vapor schemes, and the +NSST ocean scheme. The three developmental suites are candidates for future operational implementations. The GFS_v16beta +suite is the same as the GFS_v15p2 suite except using the Turbulent Kinetic Energy (TKE)-based EDMF PBL scheme. The Chikira-Sugiyama (csawmg) suite uses the Morrison-Gettelman 3 (M-G3) microphysics scheme and Chikira-Sugiyama convection scheme with Arakawa-Wu extension (CSAW). The NOAA Global Systems Division (GSD) v1 suite (GSD_v1) includes Thompson microphysics, scale-aware Mellor-Yamada-Nakanishi-Niino (saMYNN) PBL and shallow convection, Grell-Freitas (GF) deep -convection schemes, and the Rapid Update Cycle (RUC) LSM.* +convection schemes, and the Rapid Update Cycle (RUC) LSM. The two variants use the +sfc_ocean scheme instead of the NSST scheme.* -.. [#] As of this writing, the CCPP has been validated with two host models: the Global - Model Test Bed (GMTB) Single Column Model (SCM) and the atmospheric component of +.. [#] As of this writing, the CCPP has been validated with two host models: the CCPP + Single Column Model (SCM) and the atmospheric component of NOAA’s Unified Forecast System (UFS) (hereafter the UFS Atmosphere) that utilizes the Finite-Volume Cubed Sphere (FV3) dycore. The CCPP can be utilized both with the - global and standalone regional configurations of the UFS Atmosphere. Work is under - way to connect and validate the use of the CCPP-Framework with NCAR and Navy models. + global and standalone regional configurations of the UFS Atmosphere. The CCPP + has also been run experimentally with a Navy model. Work is under + way to connect and validate the use of the CCPP-Framework with NCAR models. .. include:: Introduction.rst diff --git a/CCPPtechnical/source/ScientificDocRules.inc b/CCPPtechnical/source/ScientificDocRules.inc index c766c09..a07b493 100644 --- a/CCPPtechnical/source/ScientificDocRules.inc +++ b/CCPPtechnical/source/ScientificDocRules.inc @@ -20,10 +20,10 @@ document a physics scheme using doxygen inline comments in the Fortran code and metadata information contained in the ``.meta`` files. It covers what kind of information should be in the documentation, how to mark up the inline comments so that doxygen will parse them correctly, where to put various comments within -the code, how to include information from the ``.meta`` files, +the code, how to include information from the ``.meta`` files, and how to configure and run doxygen to generate HTML -output. For an example of the HTML rendering of the CCPP Scientific Documentation, see -https://dtcenter.org/GMTB/v3.0/sci_doc. +output. For an example of the HTML rendering of the CCPP Scientific Documentation, see +https://dtcenter.org/GMTB/v4.0/sci_doc. Part of this documentation, namely metadata about subroutine arguments, has functional significance as part of the CCPP infrastructure. The metadata must be in a particular format to be parsed by Python scripts that “automatically” generate @@ -32,7 +32,7 @@ is not unique, following it will provide a level of continuity with previous documented schemes. Reviewing the documentation for CCPP parameterizations is a good way of getting -started in writing documentation for a new scheme. +started in writing documentation for a new scheme. Doxygen Comments and Commands ----------------------------- @@ -46,12 +46,11 @@ is present using the doxygen command ``“\\file”``: .. code-block:: console - !> \file gwdps.f - !! This file is the parameterization of orographic gravity wave - !! drag and mountain blocking. + ! !> \file cires_ugwp.F90 + !! This file contains the Unified Gravity Wave Physics (UGWP) scheme by Valery Yudin (University of Colorado, CIRES) A parameter definition begins with ``“!<”``, where the sign ``‘<’`` just tells -Doxygen that documentation follows. Example: + Doxygen that documentation follows. Example: .. code-block:: console @@ -89,9 +88,8 @@ using the ``“\\file”`` tag, e.g.: .. code-block:: fortran - !> \file gwdps.f - !! This file is the parameterization of orographic gravity wave - !! drag and mountain blocking. + !>\file cu_gf_driver.F90 + !! This file is scale-aware Grell-Freitas cumulus scheme driver. The brief description for each file is displayed next to the source filename on the doxygen-generated “File List” page: @@ -104,12 +102,12 @@ Doxygen Overview Page Pages in Doxygen can be used for documentation that is not directly attached to a source code entity such as file or module. They are external text files -that generate pages with a high-level scientific overview and +that generate pages with a high-level scientific overview and typically contain a longer description of a project or suite. You can refer to any source code entity from within the page. -The GMTB maintains a main page, created by the Doxygen command -``“\\mainpage”``, containing an overall description and background of the CCPP. +The DTC maintains a main page, created by the Doxygen command +``“\\mainpage”``, containing an overall description and background of the CCPP. Physics developers do not have to edit the file with the mainpage, which has a user-visible title, but not label: @@ -119,18 +117,18 @@ user-visible title, but not label: \mainpage Introduction ... */ - + All other pages listed under the main page are created using the Doxygen tag ``“\\page”`` described in the next section. In any Doxygen page, you can refer to any entity of source code by using Doxygen tag ``“\\ref”`` -or ``“@ref”``. Example in ``GFSv15_suite.txt``: - -The GFS v15 physics suite uses the parameterizations in the following order, +or ``“@ref”``. Example in ``suite_FV3_GFS_v15p2.xml.txt``: + +The GFS v15p2 physics suite uses the parameterizations in the following order, as defined in .. code-block:: console - \c FV3_GFS_v15 : + \c FV3_GFS_v15p2 : - \ref fast_sat_adj - \ref GFS_RRTMG - \ref GFS_SFCLYR @@ -138,18 +136,17 @@ as defined in - \ref GFS_NOAH - \ref GFS_SFCSICE - \ref GFS_HEDMF - - \ref GFS_GWDPS + - \ref cires_ugwp - \ref GFS_RAYLEIGH - \ref GFS_OZPHYS - \ref GFS_H2OPHYS - \ref GFS_SAMFdeep - - \ref GFS_GWDC - \ref GFS_SAMFshal - \ref GFDL_cloud - \ref GFS_CALPRECIPTYPE - \ref STOCHY_PHYS -The HTML result is `here `_. +The HTML result is `here `_. You can see that the ``“-”`` signs before ``“@ref”`` generate a list with bullets. Doxygen command ``“\\c”`` displays its argument using a typewriter font. @@ -240,7 +237,7 @@ is used to aggregate all code related to that scheme, even when it is in separat files. Since doxygen cannot know which files or subroutines belong to each physics scheme, each relevant subroutine must be tagged with the module name. This allows doxygen to understand your modularized design and generate the documentation accordingly. -`Here `_ +`Here `_ is a list of module list defined in CCPP. A module is defined using: @@ -317,18 +314,18 @@ least the following components: * A more detailed one or two paragraph description of the function of the subroutine * A comment indicating that metadata information about the subroutine arguments follows - (in this example, the subroutine is called ``SUBROUTINE_NAME``. Note that this line is + (in this example, the subroutine is called ``SUBROUTINE_NAME``. Note that this line is also functional documentation used during the CCPP *prebuild* step. .. code-block:: fortran !! \section arg_table_SUBROUTINE_NAME Argument Table - + * For subroutines that are non-empty, a second comment indicating that a table of metadata to describe the subroutine arguments will be included from a separate file in HTML format (in this case, file ``SUBROUTINE_NAME.html``). Note that empty - subroutines, as is sometimes the case for ``init`` and ``finalize`` subroutines, - do not require the inclusion of a file with metadata information. + subroutines, as is sometimes the case for ``init`` and ``finalize`` subroutines, + do not require the inclusion of a file with metadata information. Please refer to the section below for information on how to generate the HTML files with metadata information from the ``.meta`` files. @@ -348,7 +345,7 @@ least the following components: aspects of the code are automatically included in the “Detailed Algorithm” section. For subroutines that are not a CCPP entry point to a scheme, no inclusion of -metadata information is required. +metadata information is required. But it is suggested that following ``“\\ingroup”`` and ``“\\brief”``, use ``“\\param”`` to define each argument with local name, a short description and unit, i.e., @@ -357,7 +354,7 @@ But it is suggested that following ``“\\ingroup”`` and ``“\\brief”``, us !> \ingroup HEDMF !! \brief This subroutine is used for calculating the mass flux and updraft properties. !! ... - !! + !! !! \param[in] im integer, number of used points !! \param[in] ix integer, horizontal dimension !! \param[in] km integer, vertical layer dimension @@ -383,8 +380,8 @@ Bibliography Doxygen can handle in-line paper citations and link to an automatically created bibliography page. The bibliographic data for any papers that are cited need to be put in BibTeX format and saved in a .bib file. The bib file for CCPP is -included in the repository, and the doxygen configuration option -``cite_bib_files`` points to the included file. +included in the repository, and the doxygen configuration option +``cite_bib_files`` points to the included file. Citations are invoked with the following tag: @@ -436,7 +433,7 @@ things you need to pay attention to are: .. code-block:: console - INPUT = + INPUT = The following lines should be listed here: the doxygen mainpage text file, the scheme pages, and the source codes to be contained in the output. The order in @@ -488,7 +485,7 @@ determines the extension of the files. GENERATE_TREEVIEW = yes Doxygen files for layout (``ccpp_dox_layout.xml``), a HTML style (``ccpp_dox_extra_style.css``), -and bibliography (``library.bib``) are provided with the CCPP. Additionally, a +and bibliography (``library.bib``) are provided with the CCPP. Additionally, a configuration file is supplied, with the following variables modified from the default: Diagrams @@ -523,10 +520,10 @@ 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 entrypoint scheme. Before doxygen is run, the table for each scheme must be manually created in separate files in HTML format, with one file per non-empty scheme. The HTML files are included in the -Fortran files using the doygen markup below. +Fortran files using the doygen markup below. .. code-block:: fortran @@ -534,7 +531,7 @@ Fortran files using the doygen markup below. !! The tables should be created using a Python script distrbuted -with the CCPP Framework, ``ccpp/framework/scripts/metadata2html.py``. The syntax for running this +with the CCPP Framework, ``ccpp/framework/scripts/metadata2html.py``. The syntax for running this script from the directory above where the CCPP is installed is: .. code-block:: fortran @@ -574,7 +571,7 @@ In order to generate the doxygen-based documentation, one needs to follow five s ``alias doxygen /scratch4/BMC/gmtb/doxygen-1.8.10/bin/doxygen`` - Source your ``.cshrc`` file. + Source your ``.cshrc`` file. #. Document your code, including doxygen main page, scheme pages and inline comments within source code as described above. @@ -582,22 +579,22 @@ In order to generate the doxygen-based documentation, one needs to follow five s #. Run ``metadata2html.py`` to create files in HTML format containing metadata information for each CCPP entrypoint scheme. -#. Prepare a Bibliography file in BibTex format for papers referred to in the physics suites. +#. Prepare a Bibliography file in BibTex format for papers referred to in the physics suites. #. Create or edit a doxygen configuration file to control what doxygen pages, source files and bibliography file get parsed, how the source files get parsed, and to customize the output. -#. Run doxygen from directory ``ccpp/physics/physics/docs`` using the command line +#. Run doxygen from directory ``ccpp/physics/physics/docs`` using the command line to specify the doxygen configuration file as an argument: ``$doxygen $PATH_TO_CONFIG_FILE/`` Running this command may generate warnings or errors that need to be fixed - in order to produce proper output. The location and type of output + in order to produce proper output. The location and type of output (HTML, LaTeX, etc.) are specified in the configuration file. The generated HTML documentation can be viewed by pointing an HTML browser to the ``index.html`` file in the ``./docs/doc/html/`` directory. -For precise instructions on creating the scientific documentation, contact the GMTB +For precise instructions on creating the scientific documentation, contact the DTC helpdesk at gmtb-help@ucar.edu. diff --git a/CCPPtechnical/source/index.rst b/CCPPtechnical/source/index.rst index e7210b3..b8caae8 100644 --- a/CCPPtechnical/source/index.rst +++ b/CCPPtechnical/source/index.rst @@ -10,7 +10,7 @@ CCPP v4 Technical Documentation :numbered: :maxdepth: 3 - Overview + Overview CompliantPhysicsParams ConfigBuildOptions ConstructingSuite