Merge pull request #114 from grantfirl/finish_UG_v3.0

Finish U/G for v3.0

scm/doc/TechGuide/acknow.tex

@@ -12,7 +12,7 @@
 \vspace*{1cm}\par
 For referencing this document please use:\\
 \vspace*{1cm}\par
-Firl, G., L. Carson, L. Bernardet, and D. Heinzeller, 2019. Global Model Test Bed Single Column Model v3.0 User and Technical Guide. \hl{26pp}. Available at https://dtcenter.org/gmtb/users/ccpp/docs/SCM-CCPP-Guide\_v3.0.pdf
+Firl, G., L. Carson, L. Bernardet, and D. Heinzeller, 2019. Global Model Test Bed Single Column Model v3.0 User and Technical Guide. 31pp. Available at https://dtcenter.org/GMTB/v3.0/scm-ccpp-guide-v3.pdf
 
 \end{flushleft}
 \end{titlepage}

scm/doc/TechGuide/chap_cases.tex

@@ -117,6 +117,17 @@ \subsection{Case input data file}
                  caption=example netCDF file header for case initialization and forcing data
                  ]{./arm_case_header.txt}
 
+\section{Included Cases}
+Several cases are included in the repository to serve as examples for users to create their own and for basic research. All case configuration namelist files for included cases can be found in \execout{gmtb-scm/scm/etc/case\_config} and represent the following observational field campaigns:
+\begin{itemize}
+\item Tropical Warm Pool -- International Cloud Experiment (TWP-ICE) maritime deep convection
+\item Atmospheric Radiation Measurement (ARM) Southern Great Plains (SGP) Summer 1997 continental deep convection
+\item Atlantic Stratocumulus Transition EXperiment (ASTEX) maritime stratocumulus-to-cumulus transition
+\item Barbados Oceanographic and Meteorological EXperiment (BOMEX) maritime shallow convection
+\item LES ARM Symbiotic Simulation and Observation (LASSO) for May 18, 2016 (with capability to run all LASSO dates - see \ref{sec:lasso}) continental shallow convection
+\end{itemize}
+For the ARM SGP case, several case configuration files representing different time periods of the observational dataset are included, denoted by a trailing letter. The LASSO case may be run with different forcing applied, so three case configuration files corresponding to these different forcing are included.
+
 \section{How to set up new cases}
 
 Setting up a new case involves preparing the two types of files listed above. For the case initialization and forcing data file, this typically involves writing a custom script or program to parse the data from its original format to the format that the SCM expects, listed above. An example of this type of script written in python is included in \execout{/gmtb-scm/scm/etc/scripts/twpice\_forcing\_file\_generator.py}. The script reads in the data as supplied from its source, converts any necessary variables, and writes a netCDF (version 4) file in the format described in subsection \ref{subsection: case input}. For reference, the following formulas are used:
@@ -161,12 +172,10 @@ \section{How to set up new cases}
 	\end{itemize}
 \end{itemize}
 
-For the case configuration file, it is most efficient to copy an existing file in \execout{gmtb-scm/scm/etc/case\_config} and edit it to suit one's case. Recall from subsections \ref{subsection: case config} and \ref{subsection: physics config} that this file is used to configure both the SCM framework parameters (including how forcing is applied) and some physics suite parameters. Be sure to check that model timing parameters such as the time step and output frequency are appropriate for the physics suite being used. There is likely some stability criterion that governs the maximum time step based on the chosen parameterizations and number of vertical levels (grid spacing). The \execout{case\_name} parameter should match the name of the case input data file that was configured for the case (without the file extension). The \execout{runtime} parameter should be less than or equal to the length of the forcing data unless the desired behavior of the simulation is to proceed with the last specified forcing values after the length of the forcing data has been surpassed. The initial date and time should fall within the forcing period specified in the case input data file. If the case input data is specified to a lower altitude than the vertical domain, the remainder of the column will be filled in with values from a reference profile. There is a tropical profile and mid-latitude summer profile provided, although one may add more choices by adding a data file to \execout{gmtb-scm/scm/data/processed\_case\_input} and adding a parser section to the subroutine \execout{get\_reference\_profile} in \execout{gmtb-scm/scm/src/gmtb\_scm\_input.f90}. Surface fluxes can either be specified in the case input data file or calculated using a surface scheme using surface properties. If surface fluxes are specified from data, set \execout{sfc\_flux\_spec} to \exec{.true.} and specify \execout{sfc\_roughness\_length\_cm} for the surface over which the column resides. Otherwise, specify a \execout{sfc\_type}.
+For the case configuration file, it is most efficient to copy an existing file in \execout{gmtb-scm/scm/etc/case\_config} and edit it to suit one's case. Recall from subsection \ref{subsection: case config} that this file is used to configure the SCM framework parameters for a given case. Be sure to check that model timing parameters such as the time step and output frequency are appropriate for the physics suite being used. There is likely some stability criterion that governs the maximum time step based on the chosen parameterizations and number of vertical levels (grid spacing). The \execout{case\_name} parameter should match the name of the case input data file that was configured for the case (without the file extension). The \execout{runtime} parameter should be less than or equal to the length of the forcing data unless the desired behavior of the simulation is to proceed with the last specified forcing values after the length of the forcing data has been surpassed. The initial date and time should fall within the forcing period specified in the case input data file. If the case input data is specified to a lower altitude than the vertical domain, the remainder of the column will be filled in with values from a reference profile. There is a tropical profile and mid-latitude summer profile provided, although one may add more choices by adding a data file to \execout{gmtb-scm/scm/data/processed\_case\_input} and adding a parser section to the subroutine \execout{get\_reference\_profile} in \execout{gmtb-scm/scm/src/gmtb\_scm\_input.f90}. Surface fluxes can either be specified in the case input data file or calculated using a surface scheme using surface properties. If surface fluxes are specified from data, set \execout{sfc\_flux\_spec} to \exec{.true.} and specify \execout{sfc\_roughness\_length\_cm} for the surface over which the column resides. Otherwise, specify a \execout{sfc\_type}. In addition, one must specify a \execout{column\_area} for each column.
 
 To control the forcing method, one must choose how the momentum and scalar variable forcing are applied. The three methods of Randall and Cripe (1999, JGR) have been implemented: ``revealed forcing'' where total (horizontal $+$ vertical) advective tendencies are applied (type 1), ``horizontal advective forcing'' where horizontal advective tendencies are applied and vertical advective tendencies are calculated from a prescribed vertical velocity and the calculated (modeled) profiles (type 2), and ``relaxation forcing'' where nudging to observed profiles replaces horizontal advective forcing combined with vertical advective forcing from prescribed vertical velocity (type 3). If relaxation forcing is chosen, a \execout{relaxation\_time} that represents the timescale over which the profile would return to the nudging profiles must be specified.
 
-The \execout{physics\_config} namelist portion of the case configuration file provides a place to specify which physics are called. One needs to specify the path where the CCPP suite definition file is located in the \execout{physics\_suite\_dir} parameter. If one has specified that more than one (independent) columns be simulated, one also need to specify the name of the physics suite to be used for each column (corresponding to a suite definition file without the file extension) and a namelist that contains physics suite parameters for each column. The physics suite parameter namelist files are read as part of the suite initialization subroutine specified in the suite definition file. In addition, one must specify a \execout{column\_area} for each column. As of this release, multiple column functionality is limited to changes in the physics -- one can run multiple different physics suites using the same initial conditions and forcing, perform sensitivity test through multiple physics suite parameter namelists, and/or sensitivity tests with different representative column areas.
-
 \section{Using other LASSO cases}
 \label{sec:lasso}