Merge pull request #13 from climbfuji/doc_unit_conversions

Automated unit conversion documentation and update of README.md

CCPPtechnical/source/AddingNewSchemes.rst

@@ -10,6 +10,8 @@ This chapter contains a brief description on how to add a new scheme to the *CCP
 
     * If the variables are already available, they can be invoked in the scheme’s metadata file and one can skip the rest of this subsection. If the variable required is not available, consider if it can be calculated from the existing variables in the CCPP. If so, an interstitial scheme (such as ``scheme_pre``; see more in :numref:`Chapter %s <CompliantPhysParams>`) can be created to calculate the variable. However, the variable must be defined but not initialized in the host model as the memory for this variable must be allocated on the host model side.  Instructions for how to add variables to the host model side is described in :numref:`Chapter %s <Host-side Coding>`.
 
+     .. note:: The CCPP framework is capable of performing automatic unit conversions between variables provided by the host model and variables required by the new scheme. See :numref:`Section %s <AutomaticUnitConversions>` for details.
+
     * If new namelist variables need to be added, the ``GFS_control_type`` DDT should be used. In this case, it is also important to modify the namelist file ``input.nml`` to include the new variable.
 
     * It is important to note that not all data types are persistent in memory. Most variables in the interstitial data type are reset (to zero or other initial values) at the beginning of a physics group and do not persist from one set to another or from one group to another. The diagnostic data type is periodically reset because it is used to accumulate variables for given time intervals.  However, there is a small subset of interstitial variables that are set at creation time and are not reset; these are typically dimensions used in other interstitial variables. 

CCPPtechnical/source/AutoGenPhysCaps.rst

@@ -30,7 +30,9 @@ are described in the ``.meta`` files associated with the host model and the sche
 The CCPP *prebuild* step for the dynamic build performs the following tasks:
 
 * Checks requested vs provided variables by ``standard_name``.
-* Checks units, rank, type.
+* Checks units, rank, type for consistency. Perform unit conversions if a mismatch
+  of units is detected and the required conversion has been implemented (see
+  :numref:`Section %s <AutomaticUnitConversions>` for details).
 * Creates Fortran code that adds pointers to the host model variables and stores them in the 
   ccpp-data structure (``ccpp_fields_*.inc``). A hash table that is part of cdata is populated with 
   key = standard_name of a variable and value = location of that variable in memory (i.e. a c-pointer).
@@ -213,7 +215,9 @@ and therefore requires one or more SDFs (see left side of :numref:`Figure %s <cc
 The CCPP *prebuild* step for the static build performs the tasks below.
 
 * Check requested vs provided variables by ``standard_name``.
-* Check units, rank, type.
+* Check units, rank, type. Perform unit conversions if a mismatch
+  of units is detected and the required conversion has been implemented (see
+  :numref:`Section %s <AutomaticUnitConversions>` for details).
 * Filter unused schemes and variables.
 * Create Fortran code for the static Application Programming Interface (API) that replaces the dynamic API (CCPP-Framework). The hash table used by the dynamic build to store variables in memory is left empty. 
 * Create *caps* for groups and suite(s).
@@ -436,5 +440,60 @@ file* ``ccpp_FV3_GFS_v15_cap.F90`` *showing calls to the group caps*
 ``FV3_GFS_v15_fast_physics_init_cap``, ``FV3_GFS_v15_time_vary_init_cap`` *, etc. 
 for the static build where a group name is not specified.*
 
+.. _AutomaticUnitConversions:
 
+Automatic unit conversions
+==========================
 
+The CCPP framework is capable of performing automatic unit conversions if a mismatch of
+units between the host model and a physics scheme is detected, provided that the required
+unit conversion has been implemented.
+
+If a mismatch of units is detected and an automatic unit conversion can be performed,
+the CCPP prebuild script will document this with a log message as in the following example:
+
+.. code-block:: console
+
+   INFO: Comparing metadata for requested and provided variables ...
+   INFO: Automatic unit conversion from m to um for effective_radius_of_stratiform_cloud_ice_particle_in_um after returning from MODULE_mp_thompson SCHEME_mp_thompson SUBROUTINE_mp_thompson_run
+   INFO: Automatic unit conversion from m to um for effective_radius_of_stratiform_cloud_liquid_water_particle_in_um after returning from MODULE_mp_thompson SCHEME_mp_thompson SUBROUTINE_mp_thompson_run
+   INFO: Automatic unit conversion from m to um for effective_radius_of_stratiform_cloud_snow_particle_in_um after returning from MODULE_mp_thompson SCHEME_mp_thompson SUBROUTINE_mp_thompson_run
+   INFO: Generating schemes makefile/cmakefile snippet ...
+
+The CCPP framework is performing only the minimum unit conversions necessary, depending on the
+intent information of the variable in the parameterization's metadata table. In the above example,
+the cloud effective radii are ``intent(out)`` variables, which means that no unit conversion is required
+before entering the subroutine ``mp_thompson_run``. Below are examples for auto-generated code performing
+automatic unit conversions from ``m`` to ``um`` or back, depending on the intent of the variable. The conversions
+are performed in the individual physics scheme caps for the dynamic build, or the group caps for the static build.
+
+.. code-block:: fortran
+
+   ! var1 is intent(in)
+           call mp_thompson_run(...,recloud=1.0E-6_kind_phys*re_cloud,...,errmsg=cdata%errmsg,errflg=cdata%errflg)
+           ierr=cdata%errflg
+
+   ! var1 is intent(inout)
+           allocate(tmpvar1, source=re_cloud)
+           tmpvar1 = 1.0E-6_kind_phys*re_cloud
+           call mp_thompson_run(...,re_cloud=tmpvar1,...,errmsg=cdata%errmsg,errflg=cdata%errflg)
+           ierr=cdata%errflg
+           re_cloud = 1.0E+6_kind_phys*tmpvar1
+           deallocate(tmpvar1)
+
+   ! var1 is intent(out)
+           allocate(tmpvar1, source=re_cloud)
+           call mp_thompson_run(...,re_cloud=tmpvar1,...,errmsg=cdata%errmsg,errflg=cdata%errflg)
+           ierr=cdata%errflg
+           re_cloud = 1.0E+6_kind_phys*tmpvar1
+           deallocate(tmpvar1)
+
+If a required unit conversion has not been implemented the CCPP prebuild script will generate an error message as follows:
+
+.. code-block:: console
+
+   INFO: Comparing metadata for requested and provided variables ...
+   ERROR: Error, automatic unit conversion from m to pc for effective_radius_of_stratiform_cloud_ice_particle_in_um in MODULE_mp_thompson SCHEME_mp_thompson SUBROUTINE_mp_thompson_run not implemented
+
+All automatic unit conversions are implemented in ``ccpp/framework/scripts/conversion_tools/unit_conversion.py``,
+new unit conversions can be added to this file by following the existing examples.

CCPPtechnical/source/CCPPPreBuild.rst

@@ -23,7 +23,9 @@ on the host model side and from the individual physics schemes (``.meta`` files;
  * Compiles a list of variables provided by the host model.
 
  * Matches these variables by their ``standard_name``, checks for missing variables and mismatches of their 
-   attributes (e.g., units, rank, type, kind) and processes information on optional variables.
+   attributes (e.g., units, rank, type, kind) and processes information on optional variables. Performs
+   automatic unit conversions if a mismatch of units is detected between a scheme and the host model
+   (see :numref:`Section %s <AutomaticUnitConversions>` for details).
 
  * For the static build only, filters out unused variables for a given suite.
 

README.md

@@ -7,6 +7,23 @@ Common Community Physics Package (CCPP).  A viewable version of the latest docum
 The documentation is generated with Sphinx, using the reStructuredText (*.rst*) files in the 
 *CCPPtechnical/source* directory.  Output can be generated in HTML or PDF formats.
 
+## Prerequisites
+
+In order to create the technical documentation as described below, Sphinx and its 
+extension sphinxcontrib-bibtex need to be installed on the system. If PDF output
+is required, TeX/LaTeX must also be installed.
+
+Sphinx can be installed in various ways (see
+[https://www.sphinx-doc.org/en/master/usage/installation.html]([https://www.sphinx-doc.org/en/master/usage/installation.html])),
+for example using Anaconda:
+```
+conda install sphinx
+conda install -c conda-forge sphinxcontrib-bibtex
+```
+
+Comprehensive TeX/LaTeX distributions are provided for Windows, macOS and Linux.
+For more information see [https://www.latex-project.org/get/](https://www.latex-project.org/get/).
+
 ## Creating the technical documentation
 
 To generate the technical documentation:
@@ -27,3 +44,4 @@ cd ccpp-doc/CCPPtechnical
 make latexpdf
 ```
 This will generate a PDF file *./build/latex/CCPPtechnical.pdf*.
+