Scientific Documentation

Prepare the Code

In this part of the training you will see how to add documentation to the new scheme, rtfim. The documentation uses Doxygen markup, so it can later be converted for display as an html or PDF document.  The doxygen markup have been added to the template. At the end of this section, students are expected to

• finish the metadata table 
• insert the calculation of RFTIM 
• add the citation in library.bib file.

Subroutines rftim_init() and rftim_finalize() are just empty placeholders, we do not need to document them. Since rftim_run() is the entry point of the RFTIM scheme, Doxygen documentation should include:

1. In the first line of the Fortran file, add a brief one-sentence overview of the file purpose following “\file”, e.g.,

!>\file rftim.F90
!! This file contains the modified Red Flag Threat Index calculation.

The Doxygen code block begins with “!>”, and subsequent lines begin with “!!”.

2. Define a parent module using “\defgroup”, e.g., this module implements a particular scheme functionality. Also add a  one-line description of the scheme with reference using “\cite” if applicable.  Add the following lines after “end subroutine rftim_finalize”

!>\defgroup rftim_cal The Modified Red Flag Threat Index calculation
!!\brief This module calculates RFTIM using the 2-m relative humidity in percent
!! and 6m wind speed in miles per hour Lindley et al. (2011) \cite lindley_et_al_2011.

Doxygen can handle in-line paper citations and link to an automatically created bibliography page. A ccpp/physics/physics/docs/library.bib file in BibTex format is provided in the repository. Insert  the following item in the file (order is not important):

          @article {lindley_et_al_2011,
                Author  = {T.T. Lindley and J.D. Vitale and W.S. Burgett and M.-J. Beierle},
                Title      = {Proximity meteorological observations for wind-driven grassland wildfire starts on the southern High Plains},
                Journal = {Electronic J. Severe Storms Meteor.},
                Year     = {2011},
                Volume= {6},
                Number  = {1},
                Pages   = {1-27}}

3. In rftim_run(), which is the entry point to the scheme, further documentation will include:

     An argument table with:

• Local variable name “local_name”
• CF-standard compliant “standard_name”: this is used as a key to communicate variables between the CCPP and the host model
• Short description “long_name”
• Units (format follows “unit exponent”, i.e., m2 s-2 for m2/s2)
• Rank (0 for scalar, 1 for 1-D array, 2 for 2-D array, etc)

 

Part of the argument table is intentionally left blank. Student are expected to fill in the remaining metadata.

     The scheme general algorithm:

• Start with “\section sectionID XYZ General Algorithm”
• List in-line calculation steps by using “-#” markers

 

4. For those child subroutines that are not an entry point to the scheme, we can associate a subroutine or function with its parent module by using “\ingroup” to enable the auto-generation of a  calling hierarchy within the scheme.

!>\ingroup rftim_cal
!!This function calculates the climatological relative humidity to integer.
!!...(detailed description could go here)...
!!\param lon  real, longitude in radiance
!!\param rh   real, relative humidity in percentage
!!\param rfti_rh  integer, the climatological relative humidity
    elemental function rfti_rh_clima(lat,lon,rh) result(rfti_rh)

 

Following a brief description of this function or subroutine, use “\param” to define each parameter with local name, provide a short description and list the unit (optional but highly recommended).

 

Run Doxygen

 

• Get set up to use Doxygen v1.8.10 by adding  the following line into .cshrc file under your home directory:

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

• Source your .cshrc file.
• Edit file ccpplatex_dox and add the new files to the INPUT variable: 

                        ../calpreciptype.f90   \
### EMC_CCPP_TRAINING rftim
                        ../rftim.F90       \
                        .. module_rftim_clima.F90    \

Here RFTIM scheme is inserted after calpreciptype.f90

Under ccpp/physics/physics/docs,  run Doxygen by typing:

bash:

doxygen ccpplatex_dox 2>&1 | tee ccppdoc.log

tcsh:

doxygen ccpplatex_dox | & tee ccppdoc.log

• The generated html  will be located under ccpp-physics/physics/doc/html/.
• In order to visualize the output, later you can transfer the html/ directory to your local machine. It can be viewed by pointing a browser to the index.html file.