diff --git a/CMakeLists.txt b/CMakeLists.txt index 45b02dbc..aa9252ef 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -8,7 +8,7 @@ endif (NOT PROJECT) cmake_minimum_required(VERSION 3.0) project(ccpp - VERSION 3.0.0 + VERSION 4.0.0 LANGUAGES C CXX Fortran) # Use rpaths on MacOSX diff --git a/doc/DevelopersGuide/CCPP_VARIABLES_FV3.pdf b/doc/DevelopersGuide/CCPP_VARIABLES_FV3.pdf index dd6283b8..b5362516 100644 Binary files a/doc/DevelopersGuide/CCPP_VARIABLES_FV3.pdf and b/doc/DevelopersGuide/CCPP_VARIABLES_FV3.pdf differ diff --git a/doc/DevelopersGuide/CCPP_VARIABLES_SCM.pdf b/doc/DevelopersGuide/CCPP_VARIABLES_SCM.pdf index 543f1c9a..29ffd5d8 100644 Binary files a/doc/DevelopersGuide/CCPP_VARIABLES_SCM.pdf and b/doc/DevelopersGuide/CCPP_VARIABLES_SCM.pdf differ diff --git a/doc/DevelopersGuide/Makefile b/doc/DevelopersGuide/Makefile deleted file mode 100644 index 501e745a..00000000 --- a/doc/DevelopersGuide/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -# -# Makefile for the CCPP (SCM) Users Guide -# - -.PHONY: main.pdf all clean - -all: main.pdf - -main.pdf: main.tex - latexmk -f -pdf -pdflatex="pdflatex" -use-make main.tex - open main.pdf - -clean: - latexmk -CA - diff --git a/doc/DevelopersGuide/README.md b/doc/DevelopersGuide/README.md new file mode 100644 index 00000000..25e51919 --- /dev/null +++ b/doc/DevelopersGuide/README.md @@ -0,0 +1,12 @@ +# CCPP Framework Developers Guide + +The PDF files in this directory are generated in the following manner: + +When the ``ccpp_prebuild.py`` script is run for a host model, such as a single +column model (SCM) or the UFS Weather Model, a file named ``CCPP_VARIABLES_SCM.tex`` or +``CCPP_VARIABLES_FV3.tex`` is created in this directory. + +To create the PDF files, the latex to pdf converter is necessary: + +``pdflatex CCPP_VARIABLES_SCM.tex`` +``pdflatex CCPP_VARIABLES_FV3.tex`` diff --git a/doc/DevelopersGuide/acknow.tex b/doc/DevelopersGuide/acknow.tex deleted file mode 100644 index a5437152..00000000 --- a/doc/DevelopersGuide/acknow.tex +++ /dev/null @@ -1,23 +0,0 @@ -\begin{titlepage} -%\BgThispage -%\newgeometry{left=1cm,right=4cm} -\vspace*{0.5cm} -\noindent - -\begin{flushleft} -\textcolor{darkgray}{\LARGE Acknowledgement} -\vspace*{1cm}\par - -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 -Heinzeller, D., L. Bernardet, L. Carson, and G. Firl, 2018. Common Community Physics Package (CCPP) v2.0 Developers' Guide. 19pp. Available at https://dtcenter.org/gmtb/users/ccpp/docs/CCPP-DevGuide-v2.pdf - -\end{flushleft} -\end{titlepage} -\pagebreak{} - - - - diff --git a/doc/DevelopersGuide/chap_appendix.tex b/doc/DevelopersGuide/chap_appendix.tex deleted file mode 100644 index 861284b6..00000000 --- a/doc/DevelopersGuide/chap_appendix.tex +++ /dev/null @@ -1,2 +0,0 @@ -\chapter{Appendix}\label{appendix} - diff --git a/doc/DevelopersGuide/chap_hostmodel.tex b/doc/DevelopersGuide/chap_hostmodel.tex deleted file mode 100644 index 8d3150b0..00000000 --- a/doc/DevelopersGuide/chap_hostmodel.tex +++ /dev/null @@ -1,328 +0,0 @@ -\chapter{Integrating CCPP with a host model} -\label{chap_hostmodel} -\setlength{\parskip}{12pt} -%\label{section: addhostmodel} -This chapter describes the process of connecting a host model with the pool of CCPP physics schemes through the CCPP framework. This work can be split into several distinct steps outlined in the following sections. - -\section{Checking variable requirements on host model side} -\begin{sidewaysfigure} -\begin{lstlisting}[language=Fortran, - basicstyle=\scriptsize\ttfamily, - label=lst_mandatory_variables_by_ccpp, - caption=Mandatory variables that are provided by the CCPP framework (and must not be defined by the host model)] - -!! | local_name | standard_name | long_name | units | rank | type | kind | intent | optional | -!! |------------|--------------------|--------------------------------------|-------|------|-----------|---------|--------|----------| -!! | errflg | ccpp_error_flag | error flag for error handling | flag | 0 | integer | | none | F | -!! | errmsg | ccpp_error_message | error message for error handling | none | 0 | character | len=512 | none | F | -!! | loop_cnt | ccpp_loop_counter | loop counter for subcycling loops | index | 0 | integer | | none | F | -!! -\end{lstlisting}\vskip2ex -\begin{lstlisting}[language=Fortran, - basicstyle=\scriptsize\ttfamily, - label=lst_mandatory_variables_by_hostmodel, - caption=Mandatory variables that must be provided by the host model (local name is not fixed)] - -!! | local_name | standard_name | long_name | units | rank | type | kind | intent | optional | -!! |------------|--------------------|--------------------------------------|-------|------|-----------|---------|--------|----------| -!! | mpirank | mpi_rank | current MPI rank | index | 0 | integer | | none | F | -!! | mpiroot | mpi_root | master MPI rank | index | 0 | integer | | none | F | -!! | mpicomm | mpi_comm | MPI communicator | index | 0 | integer | | none | F | -!! | mpisize | mpi_size | number of MPI tasks in communicator | count | 0 | integer | | none | F | -!! | nthreads | omp_threads | number of threads for use by physics | count | 0 | integer | | none | F | -\end{lstlisting} -\end{sidewaysfigure} -The first step consists of making sure that the necessary variables for running the CCPP physics schemes are provided by the host model. A list of all variables required for the current pool of physics can be found in \execout{ccpp\{-,/\}framework/doc/DevelopersGuide/CCPP\_VARIABLES\_XYZ.pdf (\execout{XYZ}: SCM, FV3)}. While most of the variable requirements come from the CCPP physics schemes, a small number of variables are required for correct operation of the CCPP and for compliance with its standards. These variables are described in Listings~\ref{lst_mandatory_variables_by_ccpp} and~\ref{lst_mandatory_variables_by_hostmodel}. In case a required variable (that is not mandatory for CCPP) is not provided by the host model, there are several options: -\begin{itemize} -\item If a particular variable is only required by schemes in the pool that will not get used, these schemes can be commented out in the ccpp prebuild config (see Sect.~\ref{sec_addscheme}). -\item If a variable can be calculated from existing variables in the model, an interstitial scheme (usually called \execsub{scheme\_name\_pre}) can be created that calculates the missing variable. However, the memory for this variable must be allocated on the host model side (i.\,e. the variable must be defined but not initialized in the host model). Another interstitial scheme (usually called \execsub{scheme\_name\_post}) might be required to update variables used by the host model with the results from the new scheme. At present, adding interstitial schemes should be done in cooperation with the GMTB Help Desk (\url{gmtb-help@ucar.edu}). -\item In some cases, the declaration and calculation of the missing variable can be placed entirely inside the host model. Please consult with the GMTB Help Desk. -\end{itemize} - -At present, only two types of variable definitions are supported by the CCPP framework: -\begin{itemize} -\item Standard Fortran variables (\execout{character}, \execout{integer}, \execout{logical}, \execout{real}) defined in a module or in the main program. For \execout{character} variables, a fixed length is required. All others can have a \execout{kind} attribute of a kind type defined by the host model. -\item Derived data types (DDTs) defined in a module or the main program. While the use of derived data types as arguments to physics schemes in general is discouraged (see Sect.~\ref{sec_writescheme}), it is perfectly acceptable for the host model to define the variables requested by physics schemes as components of DDTs and pass these components to CCPP by using the correct \execout{local\_name} (see Listing~\ref{lst_metadata_table_hostmodel} for an example). -\end{itemize} -With the CCPP, it is possible to not only refer to components of derived types, but also to slices of arrays in the metadata table as long as these are contiguous in memory (see Listing~\ref{lst_metadata_table_hostmodel} in the following section for an example). - -\section{Adding metadata variable tables for the host model} -To establish the link between host model variables and physics scheme variables, the host model must provide metadata tables similar to those presented in Sect.~\ref{sec_writescheme}. The host model can have multiple metadata tables or just one. For each variable required by the pool of CCPP physics schemes, one and only one entry must exist on the host model side. The connection between a variable in the host model and in the physics scheme is made through its \execout{standard\_name}. - -The following requirements must be met when defining variables in the host model metadata tables (see also listing~\ref{lst_metadata_table_hostmodel} for examples of host model metadata tables). -\begin{itemize} -\item The \execout{standard\_name} must match that of the target variable in the physics scheme. -\item The type, kind, shape and size of the variable (as defined in the host model Fortran code) must match that of the target variable. -\item The attributes \execout{units}, \execout{rank}, \execout{type} and \execout{kind} in the host model metadata table must match those in the physics scheme table. -\item The attributes \execout{optional} and \execout{intent} must be set to \execout{F} and \execout{none}, respectively. -\item The \execout{local\_name} of the variable must be set to the name the host model cap (see Sect.~\ref{sec_hostmodel_cap}) uses to refer to the variable. -\item The name of the metadata table must match the name of the module or program in which the variable is defined, or the name of the derived data type if the variable is a component of this type. -\item Metadata tables describing module variables must be placed inside the module. -\item Metadata tables describing components of derived data types must be placed immediately before the type definition. -\end{itemize} -\begin{sidewaysfigure} -\begin{lstlisting}[language=Fortran, - %basicstyle=\scriptsize\fontfamily{qcr}\fontshape{n}\fontseries{l}\selectfont - basicstyle=\scriptsize\ttfamily, - label=lst_metadata_table_hostmodel, - caption=Example metadata table for a host model] - module example_vardefs - - implicit none - -!> \section arg_table_example_vardefs -!! | local_name | standard_name | long_name | units | rank | type | kind | intent | optional | -!! |------------|---------------|-----------|-------|------|-----------|--------|--------|----------| -!! | ex_int | example_int | ex. int | none | 0 | integer | | none | F | -!! | ex_real1 | example_real1 | ex. real | m | 2 | real | kind=8 | none | F | -!! | errmsg | error_message | err. msg. | none | 0 | character | len=64 | none | F | -!! | errflg | error_flag | err. flg. | flag | 0 | logical | | none | F | -!! - - integer, parameter :: r15 = selected_real_kind(15) - integer :: ex_int - real(kind=8), dimension(:,:) :: ex_real1 - character(len=64) :: errmsg - logical :: errflg - -! Derived data types - -!> \section arg_table_example_ddt -!! | local_name | standard_name | long_name | units | rank | type | kind | intent | optional | -!! |------------|---------------|-----------|-------|------|-----------|--------|--------|----------| -!! | ext%l | example_flag | ex. flag | flag | 0 | logical | | none | F | -!! | ext%r | example_real3 | ex. real | kg | 2 | real | r15 | none | F | -!! | ext%r(:,1) | example_slice | ex. slice | kg | 1 | real | r15 | none | F | -!! - type example_ddt - logical :: l - real, dimension(:,:) :: r - end type example_ddt - - type(example_ddt) :: ext - - end module example_vardefs -\end{lstlisting} -\end{sidewaysfigure} - -\section{Writing a host model cap for the CCPP} -\label{sec_hostmodel_cap} -The purpose of the host model cap is to abstract away the communication between the host model and the CCPP physics schemes. While CCPP calls can be placed directly inside the host model code, it is recommended to separate the cap in its own module for clarity and simplicity. The host model cap is responsible for: -\begin{description} -\item[\textbf{Allocating memory for variables needed by physics.}] This is only required if the variables are not allocated by the host model, for example for interstitial variables used exclusively for communication between the physics schemes. -\item[\textbf{Allocating the \execout{cdata} structure.}] The \execout{cdata} structure handles the data exchange between the host model and the physics schemes and must be defined in the host model cap or another suitable location in the host model. The \execout{cdata} variable must be persistent in memory. Note that \execout{cdata} is not restricted to being a scalar but can be a multi-dimensional array, depending on the needs of the host model. For example, a model that uses a 1-dimensional array of blocks for better cache-reuse may require \execout{cdata} to be a 1-dimensional array of the same size. Another example of a multi-dimensional array of \execout{cdata} is in the GMTB SCM, which uses a 1-dimensional \execout{cdata} array for $N$ independent columns. -\item[\textbf{Calling the suite initialization subroutine.}] The suite initialization subroutine takes two arguments, the name of the runtime suite definition file (of type \execout{character}) and the name of the \execout{cdata} variable that must be allocated at this point. \emph{Note.} The suite initialization routine \execout{ccpp\_init} parses the suite definition file and initializes the state of the suite and its schemes. This process must be repeated for every element of a multi-dimensional \execout{cdata}. For performance reasons, it is possible to avoid repeated reads of the suite definition file and to have a single state of the suite shared between the elements of \execout{cdata}. This is a developmental feature and has implications on the physics initialization. Host model developers interested in this feature should contact the GMTB Help Desk (\url{gmtb-help@ucar.edu}). -\item[\textbf{Populating the \execout{cdata} structure.}] Each variable required by the physics schemes must be added to the \execout{cdata} structure -- or to each element of a multi-dimensional \execout{cdata} -- on the host model side. This is an automated task and accomplished by inserting a preprocessor directive -\begin{lstlisting}[language=Fortran] -#include ccpp_modules.inc -\end{lstlisting} -at the top of the cap (before \execout{implicit none}) to load the required modules (e.\,g. module \execout{example\_vardefs} in listing~\ref{lst_metadata_table_hostmodel}), and a second preprocessor directive -\begin{lstlisting}[language=Fortran] -#include ccpp_fields.inc -\end{lstlisting} -after the \execout{cdata} variable and the variables required by the physics schemes are allocated. - -\emph{Note.} The CCPP framework supports splitting physics schemes into different sets that are used in different parts of the host model. An example therefore is the separation between slow and fast physics processes for the GFDL microphysics implemented in FV3GFS: while the slow physics are called as part of the usual model physics, the fast physics are integrated in the dynamical core. The separation of physics into different sets is part of the CCPP prebuild configuration (see Sect.~\ref{sec_ccpp_prebuild_config}), which allows to create multiple include files (e.g. \execout{ccpp\_fields\_slow\_physics.inc} and \execout{ccpp\_fields\_fast\_physics.inc} that can be used by different \execout{cdata} structures in different parts of the model). Please contact the GMTB Help Desk (\url{gmtb-help@ucar.edu}) if you would like to use this feature. -\item[\textbf{Providing interfaces to call CCPP for the host model.}] The cap must provide functions or subroutines that can be called at the appropriate places in the host model time integration loop and that internally call \execout{ccpp\_init}, \execout{ccpp\_physics\_init}, \execout{ccpp\_physics\_run}, \execout{ccpp\_physics\_finalize} and \execout{ccpp\_finalize}, and handle any errors returned. -\end{description} -Listing~\ref{lst_host_cap_template} contains a simple template of a host model cap for CCPP, which can also be found in \execout{ccpp/framework/doc/DevelopersGuide/host\_cap\_template.F90}. -\begin{figure} -\lstinputlisting[language=Fortran, - %basicstyle=\scriptsize\fontfamily{qcr}\fontshape{n}\fontseries{l}\selectfont - basicstyle=\scriptsize\ttfamily, - label=lst_host_cap_template, - caption=Fortran template for a CCPP host model cap]{./host_cap_template.F90} -\end{figure}\clearpage -\section{Configuring and running the CCPP prebuild script} -\label{sec_ccpp_prebuild_config} -\begin{figure} -\centerline{\includegraphics[width=0.85\textwidth]{./images/ccpp_design_with_ccpp_prebuild.pdf}} -\caption{Role of the CCPP prebuild script and the \execout{cdata} structure in the software architecture of an atmospheric modeling system.}\label{fig_ccpp_design_with_ccpp_prebuild} -\end{figure} -The CCPP prebuild script \execout{ccpp/framework/scripts/ccpp\_prebuild.py} is the central piece of code that connects the host model with the CCPP physics schemes (see Figure~\ref{fig_ccpp_design_with_ccpp_prebuild}). This script must be run before compiling the CCPP physics library and the host model cap. The CCPP prebuild script automates several tasks based on the information collected from the metadata tables on the host model side and from the individual physics schemes: -\begin{itemize} -\item Compiles a list of variables required to run all schemes in the CCPP physics pool. -\item Compiles a list of variables provided by the host model. -\item Matches these variables by their \execout{standard\_name}, checks for missing variables and mismatches of their attributes (e.\,g., units, rank, type, kind) and processes information on optional variables (see also Sect.~\ref{sec_writescheme}). -\item Creates Fortran code (\execout{ccpp\_modules.inc}, \execout{ccpp\_fields.inc}) that stores pointers to the host model variables in the \execout{cdata} structure. -\item Auto-generates the caps for the physics schemes. -\item Populates makefiles with schemes and caps. -\end{itemize} - -In order to connect the CCPP with a host model \execsub{XYZ}, a Python-based configuration file for this model must be created in the host model's repository. The easiest way is to copy an the existing configuration file for the TEST model in sub-directory \execout{schemes/check} of the \execout{ccpp-framework} repository. -The configuration in \execout{ccpp\_prebuild\_config.py} depends largely on (a) the directory structure of the host model itself, (b) where the \execout{ccpp/framework} and the \execout{ccpp/physics} directories are located relative to the directory structure of the host model, and (c) from which directory the \execout{ccpp\_prebuild.py} script is executed before/during the build process (this is referred to as \execout{basedir} in \execout{ccpp\_prebuild\_config\_XYZ.py}). - -Listing~\ref{lst_ccpp_prebuild_config} contains an example for the SCM CCPP prebuild config. Here, it is assumed that both \execout{ccpp/framework} and \execout{ccpp/physics} are located in the top-level directory of the host model, and that \execout{ccpp\_prebuild.py} is executed from the same top-level directory. -\begin{lstlisting}[language=python, - basicstyle=\scriptsize\ttfamily, - label=lst_ccpp_prebuild_config, - float=p, - caption=CCPP prebuild config for SCM (shortened)] -# Host model identifier -HOST_MODEL_IDENTIFIER = "TEST" - -# Add all files with metadata tables on the host model side, -# relative to basedir = top-level directory of host model -VARIABLE_DEFINITION_FILES = [ - 'scm/src/gmtb_scm_type_defs.f90', - 'scm/src/gmtb_scm_physical_constants.f90' - ] - -# Add all physics scheme dependencies relative to basedir - note that the CCPP -# rules stipulate that dependencies are not shared between the schemes! -SCHEME_FILES_DEPENDENCIES = [] # can be empty - -# Add all physics scheme files relative to basedir -SCHEME_FILES = { - # Relative path : [ list of sets in which scheme may be called ] - 'ccpp/physics/physics/GFS_DCNV_generic.f90' : ['physics'], - 'ccpp/physics/physics/sfc_sice.f' : ['physics'], - } - -# Auto-generated makefile/cmakefile snippets that contains all schemes -SCHEMES_MAKEFILE = 'ccpp/physics/CCPP_SCHEMES.mk' -SCHEMES_CMAKEFILE = 'ccpp/physics/CCPP_SCHEMES.cmake' - -# CCPP host cap in which to insert the ccpp_field_add statements; -# determines the directory to place ccpp_{modules,fields}.inc -TARGET_FILES = [ - 'scm/src/gmtb_scm.f90', - ] - -# Auto-generated makefile/cmakefile snippets that contains all caps -CAPS_MAKEFILE = 'ccpp/physics/CCPP_CAPS.mk' -CAPS_CMAKEFILE = 'ccpp/physics/CCPP_CAPS.cmake' - -# Directory where to put all auto-generated physics caps -CAPS_DIR = 'ccpp/physics/physics' - -# Optional arguments - only required for schemes that use optional arguments. -# ccpp_prebuild.py will throw an exception if it encounters a scheme subroutine -# with optional arguments if no entry is made here. Possible values are: -OPTIONAL_ARGUMENTS = { - #'subroutine_name_1' : 'all', - #'subroutine_name_2' : 'none', - #'subroutine_name_3' : [ 'var1', 'var2'], - } - -# HTML document containing the model-defined CCPP variables -HTML_VARTABLE_FILE = 'ccpp/physics/CCPP_VARIABLES.html' - -# LaTeX document containing the provided vs requested CCPP variables -LATEX_VARTABLE_FILE = 'ccpp/framework/doc/DevelopersGuide/CCPP_VARIABLES.tex' - -######## Template code to generate include files ######## - -# Name of the CCPP data structure in the host model cap; -# in the case of SCM, this is a vector with loop index i -CCPP_DATA_STRUCTURE = 'cdata(i)' - -# Modules to load for auto-generated ccpp_field_add code -# in the host model cap (e.g. error handling) -MODULE_USE_TEMPLATE_HOST_CAP = \ -''' -use ccpp_errors, only: ccpp_error -''' - -# Modules to load for auto-generated ccpp_field_get code -# in the physics scheme cap (e.g. derived data types) -MODULE_USE_TEMPLATE_SCHEME_CAP = \ -''' - use machine, only: kind_phys - use GFS_typedefs, only: GFS_statein_type, ... -''' - -# EOF -\end{lstlisting} -\clearpage - -Once the configuration in \execout{ccpp\_prebuild\_config.py} is complete, run -\begin{lstlisting}[language=bash] -./ccpp/framework/scripts/ccpp_prebuild.py --config=full_path_of_config_file [--debug] -\end{lstlisting} -from the top-level directory. Without the debugging flag, the output should look like -\begin{lstlisting}[language=bash,basicstyle=\scriptsize\ttfamily] -INFO: Logging level set to INFO -INFO: Parsing metadata tables for variables provided by host model ... -INFO: Parsed variable definition tables in module gmtb_scm_type_defs -INFO: Parsed variable definition tables in module gmtb_scm_physical_constants -INFO: Parsed variable definition tables in module ccpp_types -INFO: Metadata table for model SCM written to ccpp/physics/CCPP_VARIABLES_SCM.html -INFO: Parsing metadata tables in physics scheme files ... -INFO: Parsed tables in scheme rrtmg_lw -... -INFO: Checking optional arguments in physics schemes ... -INFO: Metadata table for model SCM written to ccpp/framework/doc/DevelopersGuide/CCPP_VARIABLES_SCM.tex -INFO: Comparing metadata for requested and provided variables ... -INFO: Generating module use statements for set physics ... -INFO: Generated module use statements for 4 module(s) -INFO: Generating ccpp_field_add statements for set physics ... -INFO: Generated ccpp_field_add statements for 606 variable(s) -INFO: Generating include files for host model cap scm/src/gmtb_scm.f90 ... -INFO: Generated module-use include file scm/src/ccpp_modules.inc -INFO: Generated fields-add include file scm/src/ccpp_fields.inc -INFO: Generating schemes makefile/cmakefile snippet ... -INFO: Added 81 schemes to ccpp/physics/CCPP_SCHEMES.mk and ccpp/physics/CCPP_SCHEMES.cmake -INFO: Generating caps makefile/cmakefile snippet ... -INFO: Added 64 auto-generated caps to ccpp/physics/CCPP_CAPS.mk and ccpp/physics/CCPP_CAPS.cmake -INFO: CCPP prebuild step completed successfully. -\end{lstlisting} - -\section{Building the CCPP framework and physics library} -\label{sec_ccpp_build} -\subsection{Preface} -It is highly recommended to build the CCPP physics library and software framework as part of the host model. Both \execout{ccpp-framework} and \execout{ccpp-physics} use a cmake build system, which can be integrated in the host model's cmake build system, as it is the case for the SCM. For the example of FV3GFS, which employs a traditional make build system, the cmake build for the CCPP framework and physics are triggered by the host model's \execout{compile.sh} script. - -\emph{Note.} It is possible to build the CCPP framework standalone, for example for testing purposes. It is generally not possible to build the CCPP physics library without running the CCPP prebuild script, since the build system relies on the auto-generated cmake code snippets that define the physics schemes and caps to compile. Further, any thirdparty libraries required by the physics schemes must be compiled and installed separately and the appropriate compiler and linker flags must be set manually. For example, the CCPP physics used by GMTB's SCM require several of NCEP's libraries (bacio, sp, w3nco); FV3GFS in addition requires the ESMF libraries and, depending on the operating system, also the Intel Math Kernel Library MKL (currently MacOSX only). -\subsection{Standalone ccpp-framework build}\label{sec_ccpp_framework_standalone_build} -The instructions laid out below demonstrate how to build the CCPP framework independently of the host model. It is assumed that the Github repository is checked out into a local directory \execout{ccpp-framework}. -\begin{description} -\item[\textbf{Set environment variables.}] In general, CCPP requires the \execout{CC} and \execout{FC} variables to point to the correct compilers. If threading (OpenMP) will be used inside the CCPP physics or the host model calling the CCPP physics, OpenMP-capable compilers must be used. -\item[\textbf{Build the CCPP framework.}] Use the following steps to build the CCPP framework. -\begin{lstlisting}[language=bash] -cd ccpp-framework -mkdir build && cd build -cmake -DCMAKE_INSTALL_PREFIX=$PWD .. -# add -DOPENMP=ON before .. for OpenMP build -# add -DCMAKE_BUILD_TYPE=Debug before .. for 'Debug' build -make -# add VERBOSE=1 for verbose output -make install -# add VERBOSE=1 after install for verbose output -\end{lstlisting} -\item[\textbf{Update environment variables.}] The previous install step creates directories \execout{include} and \execout{lib} inside the build directory. These directories and the newly built library \execout{libccpp.so} need to be added to the environment variables \execout{FFLAGS} and \execout{LDFLAGS}, respectively (example for bash, assuming the current directory is still the above build directory): -\begin{lstlisting}[language=bash] -export FFLAGS="-I$PWD/include/ccpp $FFLAGS" -export LDFLAGS="-L$PWD/lib -lccpp $LDFLAGS" -\end{lstlisting} -\item[\textbf{Testing the CCPP framework.}] Several unit tests are provided by the CCPP framework. These cover basic functionality and will be expanded to increase the test coverage in future releases. The unit tests are run from the build directory using -\begin{lstlisting}[language=bash] -export LD_LIBRARY_PATH=$PWD/schemes/check/src/check-build:$LD_LIBRARY_PATH -make test -\end{lstlisting} -\end{description} -\subsection{Integration with host model build system} -To allow for a flexible configuration of the CCPP framework and physics with multiple models, the \execout{CMakeLists.txt} configuration files for both packages use a cmake variable \execout{PROJECT}. This variable can be set as part of the cmake call (\execout{cmake -DPROJECT=XYZ}) or by a \execout{CMakeLists.txt} that integrates \execout{ccpp-framework} and \execout{ccpp-physics}. If not specified, \execout{PROJECT} is set to 'Unknown'. - -The basic steps to build the CCPP framework and physics for a specific host model are outlined in the following. -\begin{description} -\item[\textbf{Recommended directory structure.}] As mentioned in Section~\ref{sec_ccpp_prebuild_config}, we recommend placing the two repositories \execout{ccpp-framework} and \execout{ccpp-physics} into directories \execout{ccpp/framework} and \execout{ccpp/physics} relative to the top-level directory of the host model, and to adapt the CCPP prebuild config such that it can be run from the top-level directory. -\item[\textbf{Set environment variables.}] In addition to the compiler variables \execout{CC} and \execout{FC}, the CCPP physics require further enviroment variables for thirdparty libraries used by the physics schemes. The setup scripts for SCM (in \execout{scm/etc}) or FV3GFS (in \execout{conf} or \execout{modulefiles}) provide useful examples for the correct environment settings. -\item[\textbf{Build the CCPP framework.}] See previous section on how to build the CCPP framework. The cmake variable \execout{PROJECT} can be set to customize the build using \execout{ccpp/framework/CMakeLists.txt}. This includes preprocessor flags such as \execout{-DMPI}. -\item[\textbf{Update environment variables.}] See previous section on how to update the compiler and linker flags. -\item[\textbf{Build CCPP physics library.}] Before building \execout{ccpp-physics}, its top-level cmake configuration \execout{ccpp/physics/CMakeLists.txt} must be customized for the host model. This includes compiler flags, preprocessor flags etc. The user is referred to the existing configurations. The CCPP physics library is built starting from the build directory \execout{ccpp/framework/build}: -\begin{lstlisting}[language=bash] -cd ../.. # back to top-level directory -cd ccpp/physics -mkdir build && cd build -cmake .. -# add -DOPENMP=ON before .. for OpenMP build -# note that OpenMP build requires finding -# detect_openmp.cmake from ccpp/framework/cmake -make -# add VERBOSE=1 after install for verbose output -\end{lstlisting} -\end{description} -Following these steps, the include files and the library \execout{libccpp.so} that the host model needs to be compiled and linked against are located in \execout{ccpp/framework/build/include} and \execout{ccpp/framework/build/lib}. Note that there is no need to link the host model to the CCPP physics library in \execout{ccpp/physics/build}, as long as it is in the search path of the dynamic loader of the OS (for example by adding the directory \execout{ccpp/physics/build} to the \execout{LD\_LIBRARY\_PATH} environment variable). This is because the CCPP physics library is loaded dynamically by the CCPP framework using the library name specified in the runtime suite definition file (see the GMTB Single Column Model Technical Guide v2.1, Chapter 6.1.3, (\url{https://dtcenter.org/gmtb/users/ccpp/docs/}) for further information). Setting the environment variables \execout{FFLAGS} and \execout{LDFLAGS} as described for the CCPP framework standalone build in Sect.~\ref{sec_ccpp_framework_standalone_build} should be sufficient to compile the host model with its newly created host model cap (Sect.~\ref{sec_hostmodel_cap}) and connect to the CCPP library and framework. - -For a complete integration of the CCPP infrastructure and physics library build systems in the host model build system, users are referred to the existing implementations in GMTB SCM and FV3GFS. \ No newline at end of file diff --git a/doc/DevelopersGuide/chap_intro.tex b/doc/DevelopersGuide/chap_intro.tex deleted file mode 100644 index 6b313991..00000000 --- a/doc/DevelopersGuide/chap_intro.tex +++ /dev/null @@ -1,12 +0,0 @@ -\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. The CCPP framework generates a large fraction of code that can be included in the host model cap to facilitate this process. For more information about the CCPP design and implementation, 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 v2.1 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 available as an internal release for the developers. A public release of FV3GFS with CCPP is planned for early 2019. - -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. 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 (e.g., NCAR), 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. \ No newline at end of file diff --git a/doc/DevelopersGuide/chap_schemes.tex b/doc/DevelopersGuide/chap_schemes.tex deleted file mode 100644 index 22a9b76b..00000000 --- a/doc/DevelopersGuide/chap_schemes.tex +++ /dev/null @@ -1,158 +0,0 @@ -\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\}}. The \execout{\_init} and \execout{\_finalize} routines are run automatically when the CCPP physics are initialized. These routines may be called more than once, depending on the host model's parallelization strategy, and as such must be idempotent (that is, multiple calls must not change the answer). -\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}). The \execout{local\_name} of a variable can be chosen freely and does not have to match the \execout{local\_name} in the host model. -\item All information (units, rank) must match the specifications on the host model side. -\item The two mandatory variables that every scheme must accept as \execout{intent(out)} arguments are \execout{errmsg} and \execout{errflg} (see also coding rules). -\item At present, only two types of variable definitions are supported by the CCPP framework: -\begin{itemize} -\item Standard Fortran variables (\execout{character}, \execout{integer}, \execout{logical}, \execout{real}). For \execout{character} variables, the length should be specified as $\ast$. All others can have a \execout{kind} attribute of a kind type defined by the host model. -\item Derived data types (DDTs). While the use of DDTs is discouraged in general, some use cases may justify their application (e.g. DDTs for chemistry that contain tracer arrays, information on whether tracers are advected, \dots). -\end{itemize} -\item If a scheme is to make use of CCPP's subcycling capability in the runtime suite definition file (SDF; see also GMTB Single Column Model Technical Guide v2.1, chapter 6.1.3, \url{https://dtcenter.org/gmtb/users/ccpp/docs}), the loop counter can be obtained from CCPP as an \execout{intent(in)} variable (see Listings~\ref{lst_mandatory_variables_by_ccpp} and~\ref{lst_mandatory_variables_by_hostmodel} for a mandatory list of variables that are provided by the CCPP framework and/or the host model for this and other purposes). -\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 of decomposition-dependent host model data inside the module. -\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 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 through the subroutine's argument table (Listings~\ref{lst_mandatory_variables_by_ccpp} and~\ref{lst_mandatory_variables_by_hostmodel}). -\item MPI communication is allowed in the \execout{\_init} and \execout{\_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 which is then broadcasted to all processes. Several restrictions apply: -\begin{itemize} - \item Reading and writing of data must be implemented in a scalable way to perform efficiently from a few to millions of tasks. - \item The MPI communicator to use must be received from the host model through the subroutine's argument table (Listings~\ref{lst_mandatory_variables_by_ccpp} and~\ref{lst_mandatory_variables_by_hostmodel}). - \item The use of MPI is restricted to global communications, for example \execout{barrier}, \execout{broadcast}, \execout{gather}, \execout{scatter}, \execout{reduce}. -\end{itemize} -\item Calls to MPI and OpenMP functions, and the import of the MPI and OpenMP libraries, must be guarded by CPP preprocessor directives as illustrated in the following listing. OpenMP pragmas can be inserted without CPP guards, since they are ignored by the compiler if the OpenMP compiler flag is omitted. -\begin{lstlisting}[language=Fortran] -... - -#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 -\end{lstlisting} - - -\item For Fortran coarrays, consult with the GMTB helpdesk (\url{gmtb-help@ucar.edu}). -\end{itemize} -Scientific Documentation rules: -\begin{itemize} -\item Technically, scientific documentation is not 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 v2.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_v2/}. -\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 GFDL FV3 and GMTB SCM: -\begin{lstlisting}[language=Python] -ccpp/config/ccpp_prebuild_config.py -\end{lstlisting} -in the host model's main repository (NEMSfv3gfs or gmtb-scm, respectively). -\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 and add the new scheme at the place it should be run. SDFs are located in -\begin{lstlisting}[language=Python] -ccpp/suites/suite_FV3_GFS_2017*.xml # FV3 -ccpp/suites/suite_SCM_GFS_2017_updated*.xml # SCM -\end{lstlisting} -\item Done. Note that no further modifications of the build system are required, since the CCPP framework will auto-generate the necessary makefiles that allow the host model to compile the scheme. -\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}. diff --git a/doc/DevelopersGuide/host_cap_template.F90 b/doc/DevelopersGuide/host_cap_template.F90 deleted file mode 100644 index 14f66af8..00000000 --- a/doc/DevelopersGuide/host_cap_template.F90 +++ /dev/null @@ -1,69 +0,0 @@ -module example_ccpp_host_cap - - use ccpp_api, only: ccpp_t, ccpp_init, ccpp_finalize - use ccpp_static_api, only: ccpp_physics_init, ccpp_physics_run, & - ccpp_physics_finalize - - 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 - - ! Initialize the CCPP framework, parse SDF - call ccpp_init(trim(ccpp_suite_name), cdata, ierr=ierr) - if (ierr/=0) then - write(*,'(a)') "An error occurred in ccpp_init" - stop - end if - - ! Initialize CCPP physics (run all _init routines) - call ccpp_physics_init(cdata, suite_name=trim(ccpp_suite_name), & - ierr=ierr) - ! error handling as above - - end subroutine physics_init - - subroutine physics_run(ccpp_suite_name, group) - ! Optional argument group can be used to run a group of schemes & - ! defined in the SDF. Otherwise, run entire suite. - character(len=*), intent(in) :: ccpp_suite_name - character(len=*), optional, intent(in) :: group - - integer :: ierr - ierr = 0 - - if (present(group)) then - call ccpp_physics_run(cdata, suite_name=trim(ccpp_suite_name), & - group_name=group, ierr=ierr) - else - call ccpp_physics_run(cdata, suite_name=trim(ccpp_suite_name), & - ierr=ierr) - end if - ! error handling as above - - end subroutine physics_run - - subroutine physics_finalize(ccpp_suite_name) - character(len=*), intent(in) :: ccpp_suite_name - integer :: ierr - ierr = 0 - - ! Finalize CCPP physics (run all _finalize routines) - call ccpp_physics_finalize(cdata, suite_name=trim(ccpp_suite_name), & - ierr=ierr) - ! error handling as above - call ccpp_finalize(cdata, ierr=ierr) - ! error handling as above - - end subroutine physics_finalize - -end module example_ccpp_host_cap diff --git a/doc/DevelopersGuide/images/ccpp_design_with_ccpp_prebuild.pdf b/doc/DevelopersGuide/images/ccpp_design_with_ccpp_prebuild.pdf deleted file mode 100644 index a36d5e24..00000000 Binary files a/doc/DevelopersGuide/images/ccpp_design_with_ccpp_prebuild.pdf and /dev/null differ diff --git a/doc/DevelopersGuide/images/dtc_logo.png b/doc/DevelopersGuide/images/dtc_logo.png deleted file mode 100644 index 87b0cda6..00000000 Binary files a/doc/DevelopersGuide/images/dtc_logo.png and /dev/null differ diff --git a/doc/DevelopersGuide/main.tex b/doc/DevelopersGuide/main.tex deleted file mode 100644 index 8df6d911..00000000 --- a/doc/DevelopersGuide/main.tex +++ /dev/null @@ -1,39 +0,0 @@ -\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} diff --git a/doc/DevelopersGuide/preface.tex b/doc/DevelopersGuide/preface.tex deleted file mode 100644 index 8dddb80f..00000000 --- a/doc/DevelopersGuide/preface.tex +++ /dev/null @@ -1,28 +0,0 @@ -\chapter*{Preface} -\addcontentsline{toc}{chapter}{Preface} - -\section*{Meaning of typographic changes and symbols} - -Table \ref{tab:pre_typog} describes the type changes and symbols used in this book. - -\begin{table}[h] -\centering -\begin{tabular}{+l^l^l} -\hline -\rowstyle{\bfseries} -Typeface or Symbol & Meaning & Example \\ -\hline -\hlinesep\execout{AaBbCc123} & The names of commands, & Edit your \execout{.bashrc} \\ - & files, and directories; & Use \execout{ls -a} to list all files. \\ - & on-screen computer output & \execout{host\$ You have mail!}. \\ -\hlinesep\exec{AaBbCc123} & What you type, contrasted & \execout{host\$} \exec{su} \\ - & with on-screen computer & \\ - & output & \\ -\hlinesep\execsub{AaBbCc123} & Command line placeholder: & To delete a file, type \\ - & replace with a real name & \execout{rm} \execsub{filename} \\ - & or value & \\ - \hline -\end{tabular} -\caption{Typographic Conventions} -\label{tab:pre_typog} -\end{table} diff --git a/doc/DevelopersGuide/scheme_template.F90 b/doc/DevelopersGuide/scheme_template.F90 deleted file mode 100644 index a038a035..00000000 --- a/doc/DevelopersGuide/scheme_template.F90 +++ /dev/null @@ -1,129 +0,0 @@ -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! CCPP-compliant physics scheme template -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! -! General rules: -! -! - 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 scheme_template -> subroutines scheme_template_{init,finalize,run} -! -! - each .f or .F90 file with one or more CCPP entry point schemes must be accompanied by a -! .meta file containing metadata for the scheme(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 CCPP Technical Documentation available at https://dtcenter.org/community-code/common-community-physics-package-ccpp. -! -! !> \section arg_table_schemename_run Argument Table -! !! \htmlinclude schemename_run.html -! !! -! -! - empty schemes (e.g., scheme_template_init below) do not need metadata -! -! - all external information required by the scheme must be passed in via the -! argument list, i.e. NO 'use EXTERNAL_MODULE' statements -! -! Metadata rules: -! -! - refer to file scheme_template.meta for information about the metadata -! -! Input/output variable (argument) rules: -! -! - for a list of variables available for the specific host model, see files -! doc/DevelopersGuide/CCPP_VARIABLES_XYZ.pdf, where XYZ is the name of the model -! -! - a standard_name cannot be assigned to more than one local variable (local_name) -! -! - all information (units, rank, index ordering) must match the specifications -! on the host model side, but subslices can be used/added in the host model: -! HOST MODEL: real, dimension(:,:,:,:) :: hydrometeors -! -! -! Coding rules: -! -! - code must comply to modern Fortran standards (Fortran 90/95/2003) -! -! - use labeled 'end' statements for modules, subroutines and functions -! module scheme_template -> end module scheme_template -! -! - use implicit none -! -! - all intent(out) variables must be initialized properly inside the subroutine -! -! - NO permanent state inside the module, i.e. no variables carrying the 'save' attribute -! -! - NO 'goto' statements -! -! - errors are handled by the host model using the two mandatory arguments -! errmsg and errflg; in the event of an error, assign a meaningful error -! message to errmsg and set errflg to a value other than 0 -! -! - schemes are NOT allowed to abort/stop the program -! -! - schemes are NOT allowed to perform I/O operations (except for reading -! lookup tables / other information needed to initialize the scheme) -! -! - line lengths of no more than 120 characters are suggested for better readability -! -! Parallel programming rules: -! -! - if OpenMP is used, the number of allowed threads must be provided by the -! host model as an intent(in) argument in the argument list -! -! - if MPI is used, it is restricted to global communications: barrier, broadcast, -! gather, scatter, reduction; the MPI communicator must be provided by the -! host model as an intent(in) argument in the argument list -! - do NOT use MPI_COMM_WORLD -! - do NOT use any point-to-point communication -! -! - if Fortran coarrays are used, consult with the CCPP development team -! -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - 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 -!! \htmlinclude scheme_template_run.html -!! - 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 diff --git a/doc/DevelopersGuide/scheme_template.meta b/doc/DevelopersGuide/scheme_template.meta deleted file mode 100644 index 7a27bb32..00000000 --- a/doc/DevelopersGuide/scheme_template.meta +++ /dev/null @@ -1,81 +0,0 @@ -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! CCPP-compliant physics scheme template metadata -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! -! Metadata rules: -! -! - metadata files (.meta) are in a relaxed config file format and contain metada for one or more CCPP entrypoint schemes. -! There should be one .meta file for each .f or .F90 file -! -! - For each CCPP compliant scheme, the .meta file should have this set of lines -! [ccpp-arg-table] -! name = -! type = -! -! - ccpp-arg-table indicates the start of a new metadata section for a given scheme -! -! - is the name of the corresponding subroutine/module -! -! - type can be scheme, module, DDT, or host -! -! - for empty schemes, the three lines above are sufficient. For non-empty schemes, the metadata should -! describe all input and output arguments to the scheme using the following format: -! [varname] -! standard_name = -! long_name = -! units = -! dimensions = -! type = -! kind = -! intent = -! optional = -! -! - the intent argument is only valid in scheme metadata tables, as it is not applicable to the other types. -! -! - the following attributes are optional: long_name, kind, optional -! -! - lines can be combined using | as a separator, e.g., -! type = real | kind = kind_phys -! -! - is the local name of the variable in the subroutine -! -! - the dimensions attribute should be empty parentheses for scalars or contain the standard_name for the start and end for -! each dimension of an array. ccpp_constant_one is the assumed start for any dimension which only has a single value. -! For example: -! dimensions = () -! dimensions = (ccpp_constant_one:horizontal_loop_extent, vertical_level_dimension) -! dimensions = (horizontal_dimension,vertical_dimension) -! dimensions = (horizontal_dimension,vertical_dimension_of_ozone_forcing_data,number_of_coefficients_in_ozone_forcing_data) -! -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -[ccpp-arg-table] - name = ozphys_init - type = scheme - -######################################################################## -[ccpp-arg-table] - name = ozphys_finalize - type = scheme - -######################################################################## -[ccpp-arg-table] - name = ozphys_run - type = scheme -[errmsg] - standard_name = ccpp_error_message - long_name = error message for error handling in CCPP - units = none - dimensions = () - type = character - kind = len=* - intent = out - optional = F -[errflg] - standard_name = ccpp_error_flag - long_name = error flag for error handling in CCPP - units = flag - dimensions = () - type = integer - intent = out - optional = F diff --git a/doc/DevelopersGuide/title.tex b/doc/DevelopersGuide/title.tex deleted file mode 100644 index 52175e50..00000000 --- a/doc/DevelopersGuide/title.tex +++ /dev/null @@ -1,28 +0,0 @@ -\begin{titlepage} -\renewcommand{\thefootnote}{\fnsymbol{footnote}} - -\vspace*{1em} -\noindent - -\begin{center} -\textcolor{darkgray}{\bigsf Common Community Physics Package\\[0.5ex] (CCPP)} -\vspace*{1em} - -\textcolor{darkgray}{\bigst Developers' Guide\\[0.5ex] v2.0} -\vspace*{1em} - -\large{August 2018}\\[4em] - -Dom Heinzeller, Ligia Bernardet\\ -\textit{\small{CIRES/CU at NOAA/ESRL Global Systems Division and Developmental Testbed Center}}\\[4em] - -Laurie Carson, Grant Firl\\ -\textit{\small{National Center for Atmospheric Research and Developmental Testbed Center}}\\[4em] - -\vspace{4em} - -\includegraphics[width=0.4\textwidth]{images/dtc_logo.png}\\[2em] - -\end{center} -\end{titlepage} -\pagebreak{} diff --git a/scripts/metadata_parser.py b/scripts/metadata_parser.py index 4cf0f772..5be32299 100755 --- a/scripts/metadata_parser.py +++ b/scripts/metadata_parser.py @@ -319,7 +319,7 @@ def parse_variable_tables(filename): metadata[var_name].append(var) else: - raise Exception("Invalid definition of new metadata format in file {0}".format(filename)) + raise Exception("Invalid definition of new metadata format in file {}, \htmlinclude must be preceeded by '!! ' : {}".format(filename, line)) line_counter += 1 continue # Check for blank table @@ -622,6 +622,8 @@ def parse_scheme_tables(filename): ' existing: {0}\n'.format(existing_var.print_debug()) +\ ' vs. new: {0}'.format(var.print_debug())) metadata[var_name].append(var) + else: + raise Exception("Invalid definition of new metadata format in file {}, \htmlinclude must be preceeded by '!! ' : {}".format(filename, lines[header_line_number])) # Next line must denote the end of table, # i.e. look for a line containing only '!!' line_number = header_line_number+1