2. CCPP-Compliant Physics Parameterizations

The rules for a scheme to be considered CCPP-compliant are summarized in this section. It should be noted that making a scheme CCPP-compliant is a necessary but not guaranteed step for the acceptance of the scheme in the pool of supported CCPP-Physics. Acceptance is dependent on scientific innovation, demonstrated value, and compliance with the rules described below. The criteria for acceptance of a scheme into the CCPP is under development.

It is recommended that parameterizations be comprised of the smallest units that will be used. 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.

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 points. In order to minimize the layers of code in the CCPP, the implementation of a driver is discouraged, that is, it is preferable that the CCPP be composed of atomic parameterizations. One example is the implementation of the MG microphysics, in which a simple entrypoint leads to two versions of the scheme, MG2 and MG3. A cleaner implementation would be to retire MG2 in favor of MG3, to put MG2 and MG3 as separate schemes, or to create a single scheme that can behave as MG2 nd MG3 depending on namelist options.

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_hrrr.F90 in the ccpp-physics/physics directory.
  • To deal with optional arguments. A driver can check whether optional arguments have been 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.

Schemes in the CCPP are classified into two categories: primary schemes and interstitial schemes. Primary schemes are the major parameterizations, such as PBL, microphysics, convection, radiation, surface layer parameterizations, etc. Interstitial schemes are modularized pieces of code that perform data preparation, diagnostics, or other “glue” functions and allow primary schemes to work together as a suite. They can be categorized as “scheme-specific” or “suite-level”. Scheme-specific interstitial schemes augment a specific primary scheme (to provide additional functionality). Suite-level interstitial schemes provide additional functionality on top of a class of primary schemes, connect two or more schemes together, or provide code for conversions, initializing sums, or applying tendencies, for example. The rules and guidelines provided in the following sections apply both to primary and interstitial schemes.

2.1. General Rules

A CCPP-compliant scheme is in the form of Fortran modules. Listing 2.1 contains the template for a CCPP-compliant scheme (ccpp/framework/doc/DevelopersGuide/scheme_template.F90), which includes four essential components: argument metadata tables, the _init, _run, and _finalize subroutines.

    module scheme_template

      contains

      subroutine scheme_template_init ()
      end subroutine scheme_template_init

      subroutine scheme_template_finalize()
      end subroutine scheme_template_finalize

!> \section arg_table_scheme_template_run Argument Table
!! | local_name | standard_name      | long_name                                | units | rank | type      | kind  | intent | optional |
!! |------------|--------------------|------------------------------------------|-------|------|-----------|-------|--------|----------|
!! | errmsg     | ccpp_error_message | error message for error handling in CCPP | none  |    0 | character | len=* | out    | F        |
!! | errflg     | ccpp_error_flag    | error flag for error handling in CCPP    | flag  |    0 | integer   |       | out    | F        |
!!
      subroutine scheme_template_run (errmsg, errflg)

         implicit none

         !--- arguments
         ! add your arguments here
         character(len=*), intent(out)   :: errmsg
         integer,          intent(out)   :: errflg

         !--- local variables
         ! add your local variables here

         continue

         !--- initialize CCPP error handling variables
         errmsg = ''
         errflg = 0

         !--- initialize intent(out) variables
         ! initialize all intent(out) variables here

         !--- actual code
         ! add your code here

         ! in case of errors, set errflg to a value != 0,
         ! assign a meaningful message to errmsg and return

         return

      end subroutine scheme_template_run

    end module scheme_template

Listing 2.1: Fortran template for a CCPP-compliant scheme showing an argument table and the _init, _run, and _finalize subroutines.

More details are found below:

  • Each scheme must be in its own module and must include three (_init, _run, and _finalize) subroutines (entry points). The module name and the subroutine names must be consistent with the scheme name. The _init and _finalize subroutines are run automatically when the CCPP-Physics are initialized and finalized, respectively. These two subroutines may be called more than once, depending on the host model’s parallelization strategy, and as such must be idempotent (the answer must be the same when the subroutine is called multiple times). The _run subroutine contains the code to execute the scheme.
  • Each non-empty CCPP entrypoint subroutine requires a commented argument table (Listing 2.1). Empty subroutines do not require an argument table (e.g., scheme_template_init in Listing 2.1), since no variables need to be passed.
  • The argument table contains the metadata of the variables required by the scheme. The table must precede the entry point subroutine (_init, _run, and _finalize) and must start with !> \section arg_table_subroutine_name Argument Table and end with a line containing only !!
  • The current metadata attributes of a variable include local_name, standard_name, long_name, units, rank, type, kind, intent, and optional (see more in section Doxygen Modules of this chapter).
  • If the width of an argument table exceeds 250 characters, the table should be wrapped in C preprocessor directives:
#if 0
!> \section arg_table_scheme_template_run Argument Table
!> ...
!!
#endif
  • For better readability, the columns in the argument table are aligned.
  • All external information required by the scheme must be passed in via the argument list. Statements such as ‘use EXTERNAL_MODULE’ should not be used for passing in data and all physical constants should go through the argument list.
  • Note that standard names, variable names, module names, scheme names and subroutine names are all case sensitive.
  • Interstitial modules (scheme_pre and scheme_post) can be included if any part of the physics scheme must be executed before (_pre) or after (_post) the module scheme defined above. These situations are described in more detail in Section 5.1.

2.2. Input/output Variable (argument) Rules

  • Variables available for CCPP physics schemes are identified by their unique standard_name. While an effort is made to comply with existing standard_name definitions of the Climate and Forecast (CF) conventions (http://cfconventions.org), additional names 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 name of the host model. Running the CCPP prebuild script (described in Chapter 8) 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.
  • A standard_name cannot be assigned to more than one local variable (local_name). The local_name of a variable can be chosen freely and does not have to match the local_name in the host model.
  • All variable information (units, rank, index ordering) must match the specifications on the host model side, but sub-slices can be used/added in the host model. For example, when using the UFS Atmosphere as the host model, tendencies are split in GFS_typedefs.F90 so they can be used in the necessary physics scheme:
!! | IPD_Data(nb)%Intdiag%dt3dt(:,:,1) | cumulative_change_in_temperature_due_to_longwave_radiation
!! | IPD_Data(nb)%Intdiag%dt3dt(:,:,2) | cumulative_change_in_temperature_due_to_shortwave_radiation_and_orographic_gravity_wave_drag
!! | IPD_Data(nb)%Intdiag%dt3dt(:,:,3) | cumulative_change_in_temperature_due_to_PBL

  • The two mandatory variables that any scheme-related subroutine must accept as intent(out) arguments are errmsg and errflg (see also coding rules in Section 2.3).

  • At present, only two types of variable definitions are supported by the CCPP-framework:

    • Standard Intrinsic Fortran variables are preferred (character, integer, logical, real). For character variables, the length should be specified as * in order to allow the host model to specify the corresponding variable with a length of its own choice. All others can have a kind attribute of a kind type defined by the host model.
    • Derived data types (DDTs). While the use of DDTs is discouraged, some use cases may justify their application (e.g. DDTs for chemistry that contain tracer arrays or information on whether tracers are advected). It should be understood that use of DDTs within schemes forces their use in host models and potentially limits a scheme’s portability. Where possible, 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 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 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).

2.3. Coding Rules

  • Code must comply to modern Fortran standards (Fortran 90/95/2003).
  • Labeled end statements should be used for modules, subroutines and functions, for example, module scheme_template → end module scheme_template.
  • Implicit variable declarations are not allowed. The implicit none statement is mandatory and is preferable at the module-level so that it applies to all the subroutines in the module.
  • All intent(out) variables must be set inside the subroutine, including the mandatory variables errflg and errmsg.
  • Decomposition-dependent host model data inside the module cannot be permanent, i.e. variables that contain domain-dependent data cannot be kept using the save attribute.
  • goto statements are not alowed.
  • common blocks are not allowed.
  • Errors are handled by the host model using the two mandatory arguments errmsg and errflg. In the event of an error, a meaningful error message should be assigned to errmsg and set errflg to a value other than 0, for example:
write (errmsg, ‘(*(a))’) ‘Logic error in scheme xyz: …’
errflg = 1
return
  • Schemes are not allowed to abort/stop the program.
  • Schemes are not allowed to perform I/O operations except for reading lookup tables or other information needed to initialize the scheme, including stdout and stderr. Diagnostic messages are tolerated, but should be minimal.
  • Line lengths of up to 120 characters are suggested for better readability (exception: CCPP metadata argument tables).

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).

2.4. Parallel Programming Rules

Most often shared memory (OpenMP: Open Multi-Processing) and MPI (Message Passing Interface) communication are done outside the physics in which case the physics looping and arrays already take into account the sizes of the threaded tasks through their input indices and array dimensions. The following rules should be observed when including OpenMP or MPI communication in a physics scheme:

  • Shared-memory (OpenMP) parallelization inside a scheme is allowed with the restriction that the number of OpenMP threads to use is obtained from the host model as an intent(in) argument in the argument list (Listing 6.2).

  • MPI communication is allowed in the _init and _finalize phase for the purpose of computing, reading or writing scheme-specific data that is independent of the host model’s data decomposition. An example is the initial read of a lookup table of aerosol properties by one or more MPI processes, and its subsequent broadcast to all processes. Several restrictions apply:

    • 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 (Listing 6.2).
    • The use of MPI_COMM_WORLD is not allowed.

  • Calls to MPI and OpenMP functions, and the import of the MPI and OpenMP libraries, must be guarded by C preprocessor directives as illustrated in the following listing. OpenMP pragmas can be inserted without C preprocessor guards, since they are ignored by the compiler if the OpenMP compiler flag is omitted.

#ifdef MPI
  use mpi
#endif
#ifdef OPENMP
  use omp_lib
#endif
...
#ifdef MPI
  call MPI_BARRIER(mpicomm, ierr)
#endif

#ifdef OPENMP
  me = OMP_GET_THREAD_NUM()
#else
  me = 0
#endif

2.5. Scientific Documentation Rules

Technically, scientific documentation is not needed for a parameterization to work with the CCPP. However, scientific and technical documentation is important for code maintenance and for fostering understanding among stakeholders. As such, it is required of physics schemes in order to be included in the CCPP. This section describes the process used for documenting parameterizations in the CCPP. Doxygen was chosen as a tool for generating human-readable output due to its built-in functionality with Fortran, its high level of configurability, and its ability to parse inline comments within the source code. Keeping documentation with the source itself increases the likelihood that the documentation will be updated along with the underlying code. Additionally, inline documentation is amenable to version control.

The purpose of this section is to provide an understanding of how to properly document a physics scheme using doxygen inline comments. It covers what kind of information should be in the documentation, how to mark up the inline comments so that doxygen will parse it correctly, where to put various comments within the code, and how to configure and run doxygen to generate HTML (or other format) output. Part of this documentation, namely subroutine argument tables, have functional significance as part of the CCPP infrastructure. These tables must be in a particular format to be parsed by Python scripts that “automatically” generate a software cap for a given physics scheme. Although the procedure outlined herein 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. The CCPP Scientific Documentation can be converted to html format (see https://dtcenter.org/GMTB/v3.0/sci_doc/).

2.5.1. Doxygen Comments and Commands

All doxygen commands start with a backslash (“\”) or an at-sign (“@”). The doxygen inline comment blocks begin with “!>”, and subsequent lines begin with “!!”, which means that regular Fortran comments using “!” are not parsed by doxygen.

In the first line of each Fortran file, a brief one-sentence overview of the file purpose is present using the doxygen command “\\file”:

!> \file gwdps.f
!! This file is the  parameterization of orographic gravity wave
!! drag and mountain blocking.

A parameter definition begins with “!<”, where the sign ‘<’ just tells Doxygen that documentation follows. Example:

integer, parameter, public :: NF_VGAS = 10   !< number of gas species
integer, parameter         :: IMXCO2  = 24   !< input CO2 data longitude points
integer, parameter         :: JMXCO2  = 12   !< input CO2 data latitude points
integer, parameter         :: MINYEAR = 1957 !< earlist year 2D CO2 data available

2.5.2. Doxygen Documentation Style

To document a physics suite, a broad array of information should be included in order to serve both software engineering and scientific purposes. The documentation style could be divided into four categories:

  • Doxygen Files
  • Doxygen Pages (overview page and scheme pages)
  • Doxygen Modules
  • Bibliography

2.5.2.1. Doxygen files

Doxygen provides the “\\file” tag as a way to provide documentation on the Fortran source code file level. That is, in the generated documentation, one may navigate by source code filenames (if desired) rather than through a “functional” navigation. The most important documentation organization is through the “module” concept mentioned below, because the division of a scheme into multiple source files is often functionally irrelevant. Nevertheless, using a “\\file” tag provides an alternate path to navigate the documentation and it should be included in every source file. Therefore, it is prudent to include a small documentation block to describe what code is in each file using the “\\file” tag, e.g.:

!> \file gwdps.f
!! This file is the  parameterization of orographic gravity wave
!! drag and mountain blocking.

The brief description for each file is displayed next to the source filename on the doxygen-generated “File List” page:

_images/DoxygenFileList.png

2.5.2.2. 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 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. Physics developers do not have to edit the file with the mainpage, which has a 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, as defined in

\c FV3_GFS_v15 :
 - \ref fast_sat_adj
 - \ref GFS_RRTMG
 - \ref GFS_SFCLYR
 - \ref GFS_NSST
 - \ref GFS_NOAH
 - \ref GFS_SFCSICE
 - \ref GFS_HEDMF
 - \ref GFS_GWDPS
 - \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. You can see that the “-” signs before “@ref” generate a list with bullets. Doxygen command “\\c” displays its argument using a typewriter font.

2.5.2.3. Physics Scheme Pages

Each major scheme in CCPP should have its own scheme page containing an overview of the parameterization. These pages are not tied to the Fortran code directly; instead, they are created with a separate text file that starts with the command “\\page”. Scheme pages are stored in the ccpp-physics/physics/docs/pdftxt directory. Each page has a label (e.g., “GFS_SAMFdeep” in the following example) and a user-visible title (“GFS Scale-Aware Simplified Arakawa-Schubert (sa-SAS) Deep Convection Scheme” in the following example). It is noted that labels must be unique across the entire doxygen project so that the “\\ref” command can be used to create an unambiguous link to the structuring element. It therefore makes sense to choose label names that refer to their context.

/**
\page GFS_SAMFdeep GFS Scale-Aware Simplified Arakawa-Schubert (sa-SAS) Deep Convection Scheme
\section des_deep Description
 The scale-aware mass-flux (SAMF) deep convection scheme is an
 updated version of the previous Simplified Arakawa-Schubert (SAS) scheme
 with scale and aerosol awareness and parameterizes the effect of deep
 convection on the environment (represented by the model state variables)
 in the following way …

\section intra_deep  Intraphysics Communication
\ref arg_table_samfdeepcnv_run

\section gen_al_deep General Algorithm
\ref general_samfdeep

*/

The physics scheme page will often describe the following:

  1. Description section (“\\section”), which usually includes:

    • Scientific origin and scheme history (“\\cite”)

    • Key features and differentiating points

    • A picture is worth a thousand words (“\\image”)

      To insert images into doxygen documentation, you’ll need to have your images ready in a graphical format, such as Portable Network Graphic (png), depending on which type of doxygen output you are planning to generate. For example, for LaTeX output, the images must be provided in Encapsulated PostScript (.eps), while for HTML output the images can be provided in the png format. Images are stored in ccpp-physics/physics/docs/img directory. Example of including an image for HTML output:

\image  html  gfdl_cloud_mp_diagram.png "Figure 1: GFDL MP at a glance (Courtesy of S.J. Lin at GFDL)" width=10cm

  1. Intraphysics Communication Section (“\\section”)

    The argument table for CCPP entry point subroutine {scheme}_run will be in this section. It is created by inserting a reference link (“\\ref”) to the table in the Fortran code for the scheme.

  2. General Algorithm Section (“\\section”)

    The general description of the algorithn will be in this section. It is created by inserting a reference link (“\\ref”) in the Fortran code for the scheme.

The symbols “/\*\*” and “*/” need to be the first and last entries of the page. See an example of GFS Scale-Aware Simplified Arakawa-Schubert (sa-SAS) Deep Convection Scheme page in the previous page.

Note that separate pages can also be created to document something that is not a scheme. For example, a page could be created to describe a suite, or how a set of schemes work together. Doxygen automatically generates an index of all pages that is visible at the top-level of the documentation, thus allowing the user to quickly find, and navigate between, the available pages.

2.5.2.4. Doxygen Modules

The CCPP documentation is based on doxygen modules (note this is not the same as Fortran modules). Each doxygen module pertains to a particular parameterization and is used to aggregate all code related to that scheme, even when it is in separate 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 is a list of module list defined in CCPP.

A module is defined using:

!>\defgroup group_name group_title

Where group_name is the identifier and the group_title is what the group is referred to in the output. In the example below, we’re defining a parent module “GFS radsw Main”:

!> \defgroup module_radsw_main GFS radsw Main
!! This module includes NCEP's modifications of the RRTMG-SW radiation
!! code from AER.
!! ...
!!\author   Eli J. Mlawer, emlawer@aer.com
!!\author   Jennifer S. Delamere, jdelamer@aer.com
!!\author   Michael J. Iacono, miacono@aer.com
!!\author   Shepard A. Clough
!!\version NCEP SW v5.1  Nov 2012 -RRTMG-SW v3.8
!!

One or more contact persons should be listed with author. If you make significant modifications or additions to a file, consider adding an author and a version line for yourself. The above example generates the Author, Version sections on the page. All email addresses are converted to mailto hypertext links automatically:

Author

Eli J. Mlawer, emlawer@aer.com

Jennifer S. Delamere, jdelamer@aer.com

Michael J. Iacono, miacono@aer.com

Shepard A. Clough

Version
NCEP SW v5.1 Nov 2012 -RRTMG-SW v3.8

In order to include other pieces of code in the same module, the following tag must be used at the beginning of a comment block:

\ingroup group_name

For example:

!>\ingroup module_radsw_main
!> The subroutine computes the optical depth in band 16:  2600-3250
!! cm-1 (low - h2o,ch4; high - ch4)
!-----------------------------------
      subroutine taumol16
!...................................

In the same comment block where a group is defined for a physics scheme, there should be some additional documentation. First, using the “\\brief” command, a brief one or two sentence description of the scheme should be included. After a blank doxygen comment line, begin the scheme origin and history using “\\version”, “\\author” and “\\date”.

Each subroutine that is a CCPP entry point to a parameterization, should be further documented with a documentation block immediately preceding its definition in the source. The documentation block should include at least the following components:

  • A brief one- or two-sentence description with the "\\brief" tag

  • A more detailed one or two paragraph description of the function of the subroutine

  • An argument table that includes entries for each subroutine argument

    • The argument table content should be immediately preceded by the following line:
!!\section arg_table_SUBROUTINE_NAME

This line is also functional documentation used during the CCPP prebuild step. The first line of the table should contain the following “header” names

  1. local_name: contains the local subroutine variable name
  2. standard_name: CF-compliant standard name
  3. long_name: a short description
  4. units: format follows “unit exponent”, i.e. m2 s-2 for m:sup:2/s:sup:2
  5. rank: 0 for scalar, 1 for 1-D array, 2 for 2-D array, etc.
  6. type: integer, real, logical, character, DDT, etc.
  7. kind: the specified floating point precision kind (at present, to be extended to different integer kinds in the future)
  8. intent: in, out, inout
  9. optional: T/F

The argument table should be immediately followed by a blank doxygen line “!!”, which is needed to denote the end of an argument table. Here is an example :

!! \section arg_table_scheme_X__run Argument Table
!! | local_name | standard_name                            | long_name                                   | units   | rank | type    |    kind   | intent | optional |
!! |------------|------------------------------------------|---------------------------------------------|---------|------|---------|-----------|--------|----------|
!! | im         | horizontal_loop_extent                   | horizontal loop extent                      | count   |    0 | integer |           | in     | F        |
!! | levs       | vertical_dimension                       | vertical layer dimension                    | count   |    0 | integer |           | in     | F        |

The order of arguments in the table does not have to match the order of actual arguments in the subroutine.

  • A section called “General Algorithm” with a bullet or numbered list of the tasks completed in the subroutine algorithm
  • At the end of initial subroutine documentation block, a “Detailed algorithm” section is started and the entirety of the code is encompassed with the “!> @{” and “!> @}” delimiters. This way, any comments explaining detailed 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 argument table 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.,

!>  \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
!!  \param[in] ntrac   integer, number of tracers
!!  \param[in] delt    real, physics time step
!!  ...
!!  \section general_mfpbl mfpbl General Algorithm
!!  -# Determine an updraft parcel's entrainment rate, buoyancy, and vertical velocity.
!!  -# Recalculate the PBL height ...
!!  -# Calculate the mass flux profile and updraft properties.
!!  \section detailed_mfpbl mfpbl Detailed Algorithm
!>  @{
       subroutine mfpbl(im,ix,km,ntrac,delt,cnvflg,                       &
       &   zl,zm,thvx,q1,t1,u1,v1,hpbl,kpbl,                              &
       &   sflx,ustar,wstar,xmf,tcko,qcko,ucko,vcko)
         …
       end subroutine mfpbl
!>  @}

2.5.2.5. 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.

Citations are invoked with the following tag:

\cite bibtex_key_to_paper

2.5.2.6. Equations

See link for information about including equations. For the best rendering, the following option should be set in the Doxygen configuration file:

USE_MATHJAX            = YES
MATHJAX_RELPATH        =  https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2

There are many great online resources to use the LaTeX math typesetting used in doxygen.

2.5.3. Doxygen Configuration

2.5.3.1. Configuration File

The CCPP contains a doxygen configuration file ./ccpp/physics/physics/docs/ccpplatex_dox, such that you don’t need to create an additional one.

If starting from scratch, you can generate a default configuration file using the command:

doxygen -g <config_file>

Then you can edit the default configuration file to serve your needs. The default file includes plenty of comments to explain all the options. Some of the important things you need to pay attention to are:

  • The name of your project:
PROJECT_NAME = ‘your project name’
  • The input files (relative to the directory where you run doxygen):
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 which schemes are listed determines the order in the html result.

  • The directory where to put the documentation (if you leave it empty, then the documentation will be created in the directory where you run doxygen):
OUTPUT_DIRECTORY = doc
  • The type of documentation you want to generate (HTML, LaTeX and/or something else):
GENERATE_HTML = YES

If HTML is chosen, the following tells doxygen where to put the html documentation relative OUTPUT_DIRECTORY:

HTML_OUTPUT = html

and

HTML_FILE_EXTENSION = .html

tells what the extension of the html files should be.

  • Other important settings for a Fortran code project are:
OPTIMIZE_FOR_FORTRAN        =    YES
EXTENSION_MAPPING           = .f=FortranFree        \
                              .F90=FortranFree      \
                              .f90=FortranFree
LAYOUT_FILE                 = ccpp_dox_layout.xml
CITE_BIB_FILES              = library.bib
FILE_PATTERN                = *.f     \
                              *.F90   \
                              *.f90   \
                              *.txt
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 configuration file is supplied, with the following variables modified from the default:

2.5.3.2. Diagrams

On its own, Doxygen is capable of creating simple text-based class diagrams. With the help of the additional software GraphViz, Doxygen can generate additional graphics-based diagrams, optionally in Unified Modeling Language (UML) style. To enable GraphViz support, the configure file parameter “HAVE_DOT” must be set to “YES”.

You can use doxygen to create call graphs of all the physics schemes in CCPP. In order to create the call graphs you will need to set the following options in your doxygen config file:

HAVE_DOT             = YES
EXTRACT_ALL          = YES
EXTRACT_PRIVATE      = YES
EXTRACT_STATIC       = YES
CALL_GRAPH           = YES

Note that will need the DOT (graph description language) utility to be installed when starting doxygen. Doxygen will call it to generate the graphs. On most distributions the DOT utility can be found in the GraphViz package. Here is the call graph for subroutine mpdrv in GFDL cloud microphysics generated by doxygen:

_images/DoxygenCallGraph.png

2.5.4. Using Doxygen

In order to generate doxygen-based documentation, one needs to follow four steps:

  1. Have the doxygen executable installed on your computer. For example, for the NOAA machine Theia, add the following line into .cshrc file in your home directory:

    alias doxygen/scratch4/BMC/gmtb/doxygen-1.8.10/bin/doxygen

    Source your .cshrc file.

  2. Document your code, including doxygen main page, scheme pages and inline comments within source code as described above.

  3. Prepare a Bibliography file in BibTex format for papers referred to in the physics suites.

  4. 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.

  5. Run the doxygen command from the command line with the doxygen configuration file given as an argument:

$doxygen $PATH_TO_CONFIG_FILE/<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 (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 helpdesk at gmtb-help@ucar.edu.