update Users Guide for v5

scm/doc/TechGuide/acknow.tex

@@ -8,11 +8,11 @@
 \textcolor{darkgray}{\LARGE Acknowledgement}
 \vspace*{1cm}\par
 
-If significant help was provided via the helpdesk or support forum for work resulting in a publication, please acknowledge the Developmental Testbed Center team.\\
+If significant help was provided via the helpdesk, email, or support forum for work resulting in a publication, please acknowledge the Developmental Testbed Center team.\\
 \vspace*{1cm}\par
 For referencing this document please use:\\
 \vspace*{1cm}\par
-Firl, G., L. Carson, L. Bernardet, D. Heinzeller, and M. Harrold, 2020. Common Community Physics Package Single Column Model v4.1.0 User and Technical Guide. 38pp. Available at https://dtcenter.org/GMTB/v4.1.0/scm-ccpp-guide-v4.1.0.pdf
+Firl, G., L. Carson, L. Bernardet, D. Heinzeller, and M. Harrold, 2021. Common Community Physics Package Single Column Model v5.0.0 User and Technical Guide. 39pp. Available at https://dtcenter.org/GMTB/v5.0.0/scm-ccpp-guide-v5.0.0.pdf
 
 \end{flushleft}
 \end{titlepage}

scm/doc/TechGuide/chap_cases.tex

@@ -206,7 +206,7 @@ \section{Using other LASSO cases}
 \section{Using UFS Initial Conditions}
 \label{sec:UFS ICs}
 
-A script exists in \execout{scm/etc/scripts/UFS\_IC\_generator.py} to read in UFS Atmosphere cold start initial conditions and generate a case input data file that the SCM can use. Since the Noah LSM is the operational LSM, it is assumed that initial variables for it exist in the UFS Atmosphere initial condition files. Although NoahMP is not a member of any officially supported suite as of this release, if NoahMP is to be used, its initial conditions are generated from the Noah initial conditions using the same algorithm used in the UFS Atmosphere. Note that the script requires a few python packages that may not be found by default in all python installations: \exec{argparse}, \exec{fnmatch}, \exec{logging}, \exec{NetCDF4}, \exec{numpy}, \exec{shapely}, \exec{f90nml}, and \exec{re}. 
+A script exists in \execout{scm/etc/scripts/UFS\_IC\_generator.py} to read in UFS Atmosphere cold start initial conditions and generate a case input data file that the SCM can use. Note that the script requires a few python packages that may not be found by default in all python installations: \exec{argparse}, \exec{fnmatch}, \exec{logging}, \exec{NetCDF4}, \exec{numpy}, \exec{shapely}, \exec{f90nml}, and \exec{re}. 
 
 NOTE: If using NOAA's Hera HPC, the \execout{shapely} python package does not seem to be installed with the version of Anaconda used by the rest of this software package by default so it is installed when users execute \execout{scm/etc/Hera\_setup\_intel.[csh/sh]}. 
 
@@ -221,7 +221,7 @@ \section{Using UFS Initial Conditions}
 \begin{lstlisting}[language=bash]
 ./UFS_IC_generator.py [-h] (-l LOCATION LOCATION | -ij INDEX INDEX) -d
 DATE -i IN_DIR -g GRID_DIR [-t {1,2,3,4,5,6}]
-[-a AREA] [-mp] -n CASE_NAME [-oc]
+[-a AREA] -n CASE_NAME [-oc]
 \end{lstlisting}
 
 Mandatory arguments:
@@ -240,7 +240,6 @@ \section{Using UFS Initial Conditions}
 Optional arguments:
 \begin{enumerate}
 \item \exec{-{}-tile (-t)}: if one already knows the correct tile for the given longitude and latitude OR one is specifying the UFS grid index (\exec{-{}-index} argument)
-\item \exec{-{}-noahmp (-mp)}: flag to generate cold-start initial conditions for NoahMP LSM from Noah LSM initial conditions
 \item \exec{-{}-area (-a)}: area of grid cell in $m^2$ (if known or different than the value calculated from the supergrid file)
 \item \exec{-{}-old\_chgres (-oc)}: flag if UFS initial conditions were generated using older version of chgres (global\_chgres); might be the case for pre-2018 data
 \end{enumerate}
@@ -249,9 +248,6 @@ \section{Using UFS Initial Conditions}
 \begin{lstlisting}[language=bash]
 ./UFS_IC_generator.py -l 261.51 38.2 -d 201610030000 -i ../../data/raw_case_input/FV3_C96_example_ICs -g ../../data/raw_case_input/FV3_C96_example_ICs -n fv3_model_point_noah -oc
 \end{lstlisting}
-\begin{lstlisting}[language=bash]
-./UFS_IC_generator.py -l 261.51 38.2 -d 201610030000 -i ../../data/raw_case_input/FV3_C96_example_ICs -g ../../data/raw_case_input/FV3_C96_example_ICs -n fv3_model_point_noahmp -mp -oc
-\end{lstlisting}
 
 Note that the \exec{-{}-in\_dir (-i)} and \exec{-{}-grid\_dir (-g)} arguments are the same in this case (since the supergrid files were copied to the same directory as the initial conditions files for point of example), but they will not in general be the same. Also note that the default behavior of the script is to expect that the NetCDF initial condition files were generated from \execout{chgres\_cube} and not the older \execout{global\_chgres}. If they were generated from the older version (which is likely for pre-2018 data), they will have a slightly different format requiring the \exec{-{}-old\_chgres (-oc)} option to be set in order for the files to be read properly by the script. If you try without the \exec{-{}-old\_chgres (-oc)} flag and receive a ``IndexError: t not found'' error, try the script again with the flag.
 
@@ -261,6 +257,3 @@ \section{Using UFS Initial Conditions}
 \begin{lstlisting}[language=bash]
 ./run_scm.py -c fv3_model_point_noah -s SCM_GFS_v15p2
 \end{lstlisting}
-\begin{lstlisting}[language=bash]
-./run_scm.py -c fv3_model_point_noahmp -s SCM_GFS_v15p2_noahmp -n input_GFS_v15p2_noahmp.nml
-\end{lstlisting}

scm/doc/TechGuide/chap_ccpp.tex

@@ -1,19 +1,19 @@
 \chapter{CCPP Interface}
 \label{chapter: ccpp_interface}
 
-Chapter 6 of the CCPP v4 Technical Documentation (\url{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}) provides a wealth of information on the overall process of connecting a host model to the CCPP framework for calling physics. This chapter describes the particular implementation within this SCM, including how to set up, initialize, call, and change a physics suite using the CCPP framework.
+Chapter 6 of the CCPP v5 Technical Documentation (\url{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}) provides a wealth of information on the overall process of connecting a host model to the CCPP framework for calling physics. This chapter describes the particular implementation within this SCM, including how to set up, initialize, call, and change a physics suite using the CCPP framework.
 
 \section{Setting up a suite}
 
 Setting up a physics suite for use in the CCPP SCM with the CCPP framework involves three steps: preparing data to be made available to physics through the CCPP, running the \execout{ccpp\_prebuild.py} script to reconcile SCM-provided variables with physics-required variables, and preparing a suite definition file.
 
 \subsection{Preparing data from the SCM}
 
-As described in sections 6.1 and 6.2 of the \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation} a host model must allocate memory and provide metadata for variables that are passed into and out of the schemes within the physics suite. As of this release, in practice this means that a host model must do this for all variables needed by all physics schemes that are expected to be used with the host model. For this SCM, all variables needed by the physics schemes are allocated and documented in the file \execout{ccpp-scm/scm/src/scm\_type\_defs.f90} and are contained within the \execout{physics} derived data type. This derived data type initializes its component variables in a \execout{create} type-bound procedure. As mentioned in section 6.2 of the \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation}, a table containing all required metadata was constructed for describing all variables in the \execout{physics} derived data type. The standard names of all variables in this table must match with a corresponding variable within one or more of the physics schemes. A list of all standard names used can be found in \execout{ccpp/framework/doc/DevelopersGuide/CCPP\_VARIABLES\_SCM.pdf}. The \execout{local\_name} for each variable corresponds to how a variable is referenced from the point in the code where \execout{ccpp\_field\_add()} statements are made. For this SCM, then, all \execout{local\_name}s begin with the \execout{physics} derived data type. Nested within most of the \execout{local\_name}s is also the name of a derived data type used within the UFS Atmosphere cap (re-used here for expediency). Since the \execout{ccpp\_field\_add()} statements are made within a loop over all columns within \execout{scm.F90}, most \execout{local\_name}s are also referenced with \execout{i} as an array index.
+As described in sections 6.1 and 6.2 of the \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation} a host model must allocate memory and provide metadata for variables that are passed into and out of the schemes within the physics suite. As of this release, in practice this means that a host model must do this for all variables needed by all physics schemes that are expected to be used with the host model. For this SCM, all variables needed by the physics schemes are allocated and documented in the file \execout{ccpp-scm/scm/src/scm\_type\_defs.f90} and are contained within the \execout{physics} derived data type. This derived data type initializes its component variables in a \execout{create} type-bound procedure. As mentioned in section 6.2 of the \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation}, a table containing all required metadata was constructed for describing all variables in the \execout{physics} derived data type. The standard names of all variables in this table must match with a corresponding variable within one or more of the physics schemes. A list of all standard names used can be found in \execout{ccpp/framework/doc/DevelopersGuide/CCPP\_VARIABLES\_SCM.pdf}. The \execout{local\_name} for each variable corresponds to how a variable is referenced from the point in the code where \execout{ccpp\_field\_add()} statements are made. For this SCM, then, all \execout{local\_name}s begin with the \execout{physics} derived data type. Nested within most of the \execout{local\_name}s is also the name of a derived data type used within the UFS Atmosphere cap (re-used here for expediency). 
 
 \subsection{Editing and running \exec{ccpp\_prebuild.py}}
 
-General instructions for configuring and running the \execout{ccpp\_prebuild.py} script can be found in chapter 8 of the \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation}. The script expects to be run with a host-model-dependent configuration file, passed as argument \execout{--config=path\_to\_config\_file}. Within this configuration file are variables that hold paths to the variable definition files (where metadata tables can be found on the host model side), the scheme files (a list of paths to all source files containing scheme entry points), the auto-generated physics schemes makefile snippet, the auto-generated physics scheme caps makefile snippet, the file where \execout{ccpp\_modules.inc} and \execout{ccpp\_fields.inc} are included, and the directory where the auto-generated physics caps should be written out to. Other variables less likely to be modified by a user are included in this configuration file as well, such as code sections to be included in the auto-generated scheme caps. As mentioned in section \ref{section: compiling}, this script must be run to reconcile data provided by the SCM with data required by the physics schemes before compilation by following step 1 in that section.
+General instructions for configuring and running the \execout{ccpp\_prebuild.py} script can be found in chapter 8 of the \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation}. The script expects to be run with a host-model-dependent configuration file, passed as argument \execout{--config=path\_to\_config\_file}. Within this configuration file are variables that hold paths to the variable definition files (where metadata tables can be found on the host model side), the scheme files (a list of paths to all source files containing scheme entry points), the auto-generated physics schemes makefile snippet, the auto-generated physics scheme caps makefile snippet, the file where \execout{ccpp\_modules.inc} and \execout{ccpp\_fields.inc} are included, and the directory where the auto-generated physics caps should be written out to. Other variables less likely to be modified by a user are included in this configuration file as well, such as code sections to be included in the auto-generated scheme caps. As mentioned in section \ref{section: compiling}, this script must be run to reconcile data provided by the SCM with data required by the physics schemes before compilation by following step 1 in that section.
 
 \subsection{Preparing a suite definition file}
 The suite definition file is a text file read by the model at compile time. It is used to specify the physical parameterization suite, and includes information about the number of parameterization groupings, which parameterizations that are part of each of the groups, the order in which the parameterizations should be run, and whether subcycling will be used to run any of the parameterizations with shorter timesteps.
@@ -25,29 +25,29 @@ \subsection{Preparing a suite definition file}
 For this release, supported suite definition files used with this SCM are found in \execout{ccpp-scm/ccpp/suites}. For all of these suites, the physics schemes have been organized into 3 groupings following how the physics are called in the UFS Atmosphere model, although no code is executed in the SCM time loop between execution of the grouped schemes. Several ``interstitial'' schemes are included in the suite definition file to execute code that previously was part of a hard-coded physics driver. Some of these schemes may eventually be rolled into the schemes themselves, improving portability.
 
 \section{Initializing/running a suite}
-The process for initializing and running a suite in this SCM is described in sections \ref{section: physics init} and \ref{section: time integration}, respectively. A more general description of the process for performing suite initialization and running can also be found in sections 6.4 and 6.5 of the \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation}.
+The process for initializing and running a suite in this SCM is described in sections \ref{section: physics init} and \ref{section: time integration}, respectively. A more general description of the process for performing suite initialization and running can also be found in sections 6.4 and 6.5 of the \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation}.
 
 \section{Changing a suite}
 
 \subsection{Replacing a scheme with another}
 
-When the CCPP has reached a state of maturity, the process for modifying the contents of an existing physics suite will be a very straightforward process, consisting of merely changing the name of the scheme in the suite definition file. As of this release, which consists of one scheme of each ``type'' in the pool of CCPP-compliant physics schemes with many short interstitial schemes, the process requires some consideration. Of course, prior to being able to swap a scheme within a suite, one must first add a CCPP-compliant scheme to the pool of available schemes in the CCPP physics repository. This process is described in chapter 2 of the \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation}.
+When the CCPP has reached a state of maturity, the process for modifying the contents of an existing physics suite will be a very straightforward process, consisting of merely changing the name of the scheme in the suite definition file. As of this release, which consists of one scheme of each ``type'' in the pool of CCPP-compliant physics schemes with many short interstitial schemes, the process requires some consideration. Of course, prior to being able to swap a scheme within a suite, one must first add a CCPP-compliant scheme to the pool of available schemes in the CCPP physics repository. This process is described in chapter 2 of the \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation}.
 
 Once a CCPP-compliant scheme has been added to the CCPP physics repository, the process for modifying an existing suite should take the following steps into account:
 
 \begin{itemize}
 \item Examine and compare the arguments of the scheme being replaced and the replacement scheme.
 \begin{itemize}
 \item Are there any new variables that the replacement scheme needs from the host application? If so, these new variables must be added to the host model cap. For the SCM, this involves adding a component variable to the \execout{physics} derived data type and a corresponding entry in the metadata table. The new variables must also be allocated and initialized in the \execout{physics\%create} type-bound procedure.
-\item Do any of the new variables need to be calculated in an interstitial scheme? If so, one must be written and made CCPP-compliant itself. The \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation} will help in this endeavor, and the process outlined in its chapter 2 should be followed.
+\item Do any of the new variables need to be calculated in an interstitial scheme? If so, one must be written and made CCPP-compliant itself. The \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation} will help in this endeavor, and the process outlined in its chapter 2 should be followed.
 \item Do other schemes in the suite rely on output variables from the scheme being replaced that are no longer being supplied by the replacement scheme? Do these output variables need to be derived/calculated in an interstitial scheme? If so, see the previous bullet about adding one.
 \end{itemize}
 \item Examine existing interstitial schemes related to the scheme being replaced.
 \begin{itemize}
 \item There may be scheme-specific interstitial schemes (needed for one specific scheme) and/or type-generic interstitial schemes (those that are called for all schemes of a given type, i.e. all PBL schemes). Does one need to write analogous scheme-specific interstitial schemes for the replacement?
 \item Are the type-generic interstitial schemes relevant or do they need to be modified?
 \end{itemize}
-\item Depending on the answers to the above considerations, edit the suite definition file as necessary. Typically, this would involve finding the \execout{<scheme>} elements associated with the scheme to be replaced and its associated interstitial \execout{<scheme>} elements and simply replacing the scheme names to reflect their replacements. See chapter 4 of the \href{https://ccpp-techdoc.readthedocs.io/en/v4.1.0/}{CCPP Technical Documentation} for further details.
+\item Depending on the answers to the above considerations, edit the suite definition file as necessary. Typically, this would involve finding the \execout{<scheme>} elements associated with the scheme to be replaced and its associated interstitial \execout{<scheme>} elements and simply replacing the scheme names to reflect their replacements. See chapter 4 of the \href{https://ccpp-techdoc.readthedocs.io/en/v5.0.0/}{CCPP Technical Documentation} for further details.
 \end{itemize}
 
 \subsection{Modifying ``groups'' of parameterizations}