Release v1.0 branch, merge to master (NCAR#53)

Merge updates to the release branch back to master (primarily documentation updates, a few build updates)

doc/UsersGuide/SCM/acknow.tex → doc/DevelopersGuide/acknow.tex

@@ -8,11 +8,11 @@
 \textcolor{darkgray}{\LARGE Acknowledgement}
 \vspace*{1cm}\par
 
-If significant help was provided via the HWRF helpdesk for work resulting in a publication, please acknowledge the Developmental Testbed Center Hurricane Team.\\
+If significant help was provided via the GMTB helpdesk for work resulting in a publication, please acknowledge the Developmental Testbed Center GMTB Team.\\
 \vspace*{1cm}\par
 For referencing this document please use:\\ 
 \vspace*{1cm}\par
-Biswas, M. K., L. Carson, K. Newman, L. Bernardet, C. Holt, 2016: Community HWRF Users' Guide V3.8a, NOAA Technical Memorandum OAR GSD-47, 149 pp., http://doi.org/10.7289/V5/TM-OAR-GSD-47.
+Heinzeller, D., L. Bernardet, L. Carson, and G. Firl, 2018. Common Community Physics Package (CCPP) v1.0 Developers' Guide. 15pp. Available at https://dtcenter.org/gmtb/users/ccpp/docs/CCPP-DevGuide-v1.pdf
 
 \end{flushleft}
 \end{titlepage}

doc/DevelopersGuide/chap_appendix.tex

@@ -0,0 +1,2 @@
+\chapter{Appendix}\label{appendix}
+

doc/DevelopersGuide/chap_intro.tex

@@ -0,0 +1,12 @@
+\chapter{Introduction}\label{chap_introduction}
+\setlength{\parskip}{12pt}
+
+The Common Community Physics Package (CCPP) is designed to facilitate the implementation of physics innovations in state-of-the-art atmospheric models, the use of various models to develop physics, and the acceleration of transition of physics innovations to operational NOAA models. The CCPP consists of two separate software packages, the pool of CCPP-compliant physics schemes (\execout{ccpp-physics}) and the framework (driver) that connects the physics schemes with a host model (\execout{ccpp-framework}).
+
+The connection between the host model and the physics schemes through the CCPP framework is realized with caps on both sides as illustrated in Fig.~\ref{fig_ccpp_design_with_ccpp_prebuild} in Chapter~\ref{chap_hostmodel}. While the caps to the individual physics schemes are auto-generated, the cap that connects the framework (Physics Driver) to the host model must be created manually. For more information about the CCPP design and implementation, please see the CCPP Design Overview at {\url{https://dtcenter.org/gmtb/users/ccpp/docs/}}.
+
+This document serves two purposes, namely to describe the technical work of writing a CCPP-compliant physics scheme and adding it to the pool of CCPP physics schemes (Chapter~\ref{chap_schemes}), and to explain in detail the process of connecting an atmospheric model (host model) with the CCPP (Chapter~\ref{chap_hostmodel}). For further information and an example for integrating CCPP with a host model, the reader is referred to the GMTB Single Column Model (SCM) User and Technical Guide v1.0 available at {\url{https://dtcenter.org/gmtb/users/ccpp/docs}}.
+
+At the time of writing, the CCPP is supported for use with the GMTB Single Column Model (SCM). Support for use of CCPP with the experimental version of NCEP's Global Forecast System (GFS) that employs the Finite-Volume Cubed-Sphere dynamical core (FV3GFS) is expected in future releases. 
+
+The GMTB welcomes contributions to CCPP, whether those are bug fixes, improvements to existing parameterizations, or new parameterizations. There are two aspects of adding innovations to the CCPP: technical and programmatic. This Developer's Guide explains how to make parameterizations technically compliant with the CCPP. Acceptance in the master branch of the CCPP repositories, and elevation of a parameterization to supported status, depends on a set of scientific and technical criteria that are under development as part of the incipient CCPP Governance. Contributions can be made in form of git pull requests to the development repositories but before initiating a major development for the CCPP please contact GMTB at \url{gmtb-help@ucar.edu} to create an integration and transition plan. For further information, see the Developer's Corner for CCPP at \url{https://dtcenter.org/gmtb/users/ccpp/developers/index.php}. Note that while the pool of CCPP physics and the CCPP framework are managed by the Global Model Test Bed (GMTB) and governed jointly with partners, the code governance for the host models lies with their respective organizations. Therefore, inclusion of CCPP within those models should be brought up to their governing bodies.

doc/DevelopersGuide/chap_schemes.tex

@@ -0,0 +1,117 @@
+\chapter{CCPP-compliant physics schemes}
+\label{chap_schemes}
+\setlength{\parskip}{12pt}
+
+\section{Writing a CCPP-compliant physics scheme}
+\label{sec_writescheme}
+The rules for writing a CCPP-compliant scheme are summarized in the following. Listing~\ref{lst_scheme_template} contains a Fortran template for a CCPP-compliant scheme, which can also be found in \execout{ccpp-framework/doc/DevelopersGuide/scheme\_template.F90}.
+
+General rules:
+\begin{itemize}
+\item Scheme must be in its own module (module name $=$ scheme name) and must have three entry points (subroutines) starting with the name of the module: module \execout{scheme\_template} $\rightarrow$ subroutines \execout{scheme\_template\_\{init,finalize,run\}}. Note: at present, the \execout{\_init} and \execout{\_finalize} routines can not be used, and are simply placeholders (c.\,f. listing~\ref{lst_scheme_template})
+\item Empty schemes (e.\,g. \execout{scheme\_template\_init} in listing~\ref{lst_scheme_template}) need no argument table.
+\item Schemes in use require an argument table as below, the order of arguments in the table must be the same as in the argument list of the subroutine.
+\item An argument table must precede the subroutine, and must start with
+\begin{lstlisting}[language=Fortran]
+!> \section arg_table_subroutine_name Argument Table
+\end{lstlisting}
+and end with a line containing only
+\begin{lstlisting}[language=Fortran]
+!!
+\end{lstlisting}
+\item All external information required by the scheme must be passed in via the argument list, i.e. no external modules (except if defined in the Fortran standards 95--2003).
+\item If the width of an argument table exceeds 250 characters, wrap the argument table in CPP preprocessor directives:
+\begin{lstlisting}[language=Fortran]
+#if 0
+!> \section arg_table_scheme_template_run Argument Table
+...
+!!
+#endif
+\end{lstlisting}
+\item Module names, scheme names and subroutine names are case sensitive.
+\item For better readability, it is suggested to align the columns in the metadata table.
+\end{itemize}
+
+Input/output variable (argument) rules:
+\begin{itemize}
+\item Variables available for CCPP physics schemes are identified by their unique \execout{standard\_name}. While an effort is made to comply with existing \execout{standard\_name} definitions of the CF conventions (\url{http://cfconventions.org}), additional names are introduced by CCPP (see below for further information).
+\item A \execout{standard\_name} cannot be assigned to more than one local variable (\execout{local\_name}).
+\item All information (units, rank) must match the specifications on the host model side.
+\end{itemize}
+
+Coding rules:
+\begin{itemize}
+\item Code must comply to modern Fortran standards (Fortran 90/95/2003)
+\item Use labeled \execout{end} statements for modules, subroutines and functions, example:\\
+\execout{module scheme\_template} $\rightarrow$ \execout{end module scheme\_template}.
+\item Use \execout{implicit none}.
+\item All \execout{intent(out)} variables must be initialized properly inside the subroutine.
+\item No permanent state inside the module, i.\,e. no variables carrying the \execout{save} attribute.
+\item No \execout{goto} statements.
+\item Errors are handled by the host model using the two mandatory arguments \execout{errmsg} and \execout{errflg}. In the event of an error, assign a meaningful error message to \execout{errmsg} and set \execout{errflg} to a value other than 0.
+\item Schemes are not allowed to abort/stop the program.
+\item Schemes are not allowed to perform I/O operations (except for reading lookup tables or other information needed to initialize the scheme)
+\item Line lengths of 120 characters are suggested for better readibility (exception: CCPP metadata argument tables).
+\end{itemize}
+Parallel programming rules:
+\begin{itemize}
+\item If OpenMP is used, the number of allowed threads must be provided by the
+  host model as an \execout{intent(in)} argument in the argument list.
+\item If MPI is used, it is restricted to global communications: {barrier}, {broadcast}, {gather}, {scatter}, {reduce}; the MPI communicator must be provided by the host model as an \execout{intent(in)} argument in the argument list.
+\item If Fortran coarrays are used, consult with the GMTB helpdesk at (\url{gmtb-help@ucar.edu}).
+\end{itemize}
+Scientific Documentation rules:
+\begin{itemize}
+\item Scientific documentation is not technically needed for a parameterization to work with the CCPP. However, inclusion of inline scientific documentation is highly recommended and necessary before a parameterization is submitted for inclusion in the CCPP. 
+\item Scientific documentation for CCPP parameterizations should be inline within the Fortran code using markups according to the Doxygen software. Reviewing the documentation for CCPP v1.0 parameterizations is a good way of getting started in writing documentation for a new scheme.
+\item The CCPP Scientific Documentation can be converted to html format (see \url{https://dtcenter.org/gmtb/users/ccpp/docs/sci_doc/}.
+\item For precise instructions on creating the scientific documentation, contact the GMTB helpdesk at \url{gmtb-help@ucar.edu}.
+\end{itemize}
+\begin{sidewaysfigure}
+\lstinputlisting[language=Fortran,
+                 %basicstyle=\scriptsize\fontfamily{qcr}\fontshape{n}\fontseries{l}\selectfont
+                 basicstyle=\scriptsize\ttfamily,
+                 label=lst_scheme_template,
+                 caption=Fortran template for a CCPP-compliant scheme,
+                 firstline=78]{./scheme_template.F90}
+\end{sidewaysfigure}
+
+\section{Adding a new scheme to the CCPP pool}
+\label{sec_addscheme}
+This section describes briefly how to add a new scheme to the CCPP pool and use it with a host model that already supports the CCPP.
+\begin{enumerate}
+\item Identify the required variables for your target host model: for a list of variables available for host model \execsub{XYZ} (currently \execout{SCM} and \execout{FV3}), see \execout{ccpp-framework/doc/DevelopersGuide/CCPP\_VARIABLES\_XYZ.pdf}. Contact the GMTB helpdesk at \url{gmtb-help@ucar.edu} if you need additional variables that you believe should be provided by the host model or as part of a pre-/post-scheme (interstitial scheme) instead of being calculated from existing variables inside your scheme.
+\item Identify if your new scheme requires additional interstitial code that must be run before/after the scheme and that cannot be part of the scheme itself, for example because of dependencies on other schemes and/or the order the scheme is run in the suite definition file. As of now, interstitial schemes should be created in cooperation with the GMTB helpdesk.
+\item Follow the guidelines outlined in the previous section to make your scheme CCPP-compliant. Make sure to use an uppercase suffix \execout{.F90} to enable CPP preprocessing.
+\item Locate the CCPP prebuild configuration files for the target host model, for example:
+\begin{lstlisting}[language=Python]
+ccpp-framework/scripts/ccpp_prebuild_config_FV3.py # for GFDL FV3
+ccpp-framework/scripts/ccpp_prebuild_config_SCM.py # FOR GMTB SCM
+\end{lstlisting}
+\item Add the new scheme to the list of schemes using the same path as the existing schemes:
+\begin{samepage}
+\begin{lstlisting}[language=Python]
+SCHEME_FILES = [
+    ...
+    '../some_relative_path/existing_scheme.F90',
+    '../some_relative_path/new_scheme.F90',
+    ...
+    ]
+\end{lstlisting}
+\end{samepage}
+\item If the new scheme uses optional arguments, add information on which ones to use further down in the configuration file. See existing entries and documentation in the configuration file for the possible options:
+\begin{lstlisting}[language=Python]
+OPTIONAL_ARGUMENTS = {
+    'SCHEME_NAME' : {
+        'SCHEME_NAME_run' : [
+            # list of all optional arguments in use for this model, by standard_name
+            ],
+            # instead of list [...], can also say 'all' or 'none'
+        },
+    }
+\end{lstlisting}
+\item Place new scheme in the same location as existing schemes in the CCPP directory structure, e.\,g. \execout{../some\_relative\_path/new\_scheme.F90}.
+\item Edit the runtime suite definition file (see, for example, GMTB Single Column Model Technical Guide v1.0, chapter 6.1.3, \url{https://dtcenter.org/gmtb/users/ccpp/docs}) and add the new scheme at the place it should be run.
+\item Done!
+\end{enumerate}
+\textbf{Note:} Making a scheme CCPP-compliant is a necessary step for acceptance of the scheme in the pool of supported CCPP physics schemes, but does not guarantee it. Acceptance is subject to approval by a Governance committee and depends on scientific innovation, demonstrated added value, and compliance with the above rules. The criteria for acceptance of innovations into the CCPP is under development. For further information, please contact the GMTB helpdesk at \url{gmtb-help@ucar.edu}.

doc/DevelopersGuide/host_cap_template.F90

@@ -0,0 +1,67 @@
+module example_ccpp_host_cap
+
+  use ccpp_types,         only: ccpp_t
+  use ccpp,               only: ccpp_init, ccpp_finalize
+  use ccpp_fcall,         only: ccpp_run
+  use ccpp_fields,        only: ccpp_field_add
+  use iso_c_binding,      only: c_loc
+
+! Include auto-generated list of modules for ccpp
+#include "ccpp_modules.inc"
+
+  implicit none
+
+!  CCPP data structure
+  type(ccpp_t), save, target :: cdata
+
+  public :: physics_init, physics_run, physics_finalize
+
+contains
+
+  subroutine physics_init(ccpp_suite_name)
+    character(len=*), intent(in) :: ccpp_suite_name
+    integer :: ierr
+    ierr = 0
+
+    call ccpp_init(ccpp_suite_name, cdata, ierr)
+    if (ierr/=0) then
+      write(*,'(a)') "An error occurred in ccpp_init"
+      stop
+    end if
+
+! Include auto-generated list of calls to ccpp_field_add
+#include "ccpp_fields.inc"
+
+  end subroutine physics_init
+
+  subroutine physics_run(step)
+    ! the step (currently called IPD step) to run as
+    ! defined in the runtime suite definition file
+    integer, intent(in) :: step
+    integer :: ierr
+    ierr = 0
+
+    call ccpp_run(cdata%suite%ipds(step), cdata, ierr)
+    ! future versions: call ccpp_run(cdata, step=step, ierr=ierr)
+    if (ierr/=0) then
+      ! errmsg is known because of #include ccpp_modules.inc
+      write(*,'(a,i0,a)') "An error occurred in physics step ", step, &
+                          "; error message: '" // trim(errmsg) // "'"
+      stop
+    end if
+
+  end subroutine physics_run
+
+  subroutine physics_finalize()
+    integer :: ierr
+    ierr = 0
+
+    call ccpp_finalize(cdata, ierr)
+    if (ierr/=0) then
+      write(*,'(a)') "An error occurred in ccpp_finalize"
+      stop
+    end if
+
+  end subroutine physics_finalize
+
+end module example_ccpp_host_cap

doc/DevelopersGuide/main.tex

@@ -0,0 +1,39 @@
+\documentclass[12pt,letterpaper,oneside]{scrbook}
+
+\usepackage{import}
+\import{../common/}{gmtb.sty}
+
+\makeindex
+
+\hypersetup{
+        pdfauthor={Dom Heinzeller / Ligia Bernardet / Laurie Carson / Grant Firl},
+        pdftitle={Common Community Physics Package (CCPP)},
+}
+
+\begin{document}
+
+\frontmatter
+\import{./}{title.tex}
+
+\clearpage
+\thispagestyle{empty}
+\import{./}{acknow.tex}
+
+\tableofcontents
+
+\import{./}{preface.tex}
+
+\mainmatter
+
+\import{./}{chap_intro.tex}
+\import{./}{chap_schemes.tex}
+\import{./}{chap_hostmodel.tex}
+
+\appendix
+
+\renewcommand{\thechapter}{\Alph{chapter}}
+%\import{./}{chap_appendix.tex}
+
+\backmatter
+
+\end{document}