--- manual/s_phys_pkgs/text/gchem.tex	2004/10/12 18:16:03	1.2
+++ manual/s_phys_pkgs/text/gchem.tex	2010/08/30 23:09:21	1.12
@@ -1,10 +1,10 @@
-\section {GCHEM Package} 
+\subsection {GCHEM Package} 
 \label{sec:pkg:gchem}
 \begin{rawhtml}
 <!-- CMIREDIR:package_gchem: -->
 \end{rawhtml}
 
-\subsection {Introduction}
+\subsubsection {Introduction}
 This package has been developed as interface to the PTRACERS package.
 The purpose is to provide a structure where various (any)
 tracer experiments can be added to the code.
@@ -17,31 +17,37 @@
 the subroutines used by specific biogeochemical experiments,
 and does not "do" anything on its own.
 
-There are two examples: cfc which looks at 2 tracers with a
-simple external forcing and dic with 5 tracers whose tendency terms
+There are two examples: {\bf cfc} which looks at 2 tracers with a
+simple external forcing and {\bf dic} with 4,5 or 6 tracers 
+whose tendency terms
 are related to one another. We will discuss these here only as
 how they provide examples to use this package.
 
 
-\subsection {Key subroutines and parameters}
+\subsubsection {Key subroutines and parameters}
 
 \noindent
 {{\bf FRAMEWORK}} \\
+The different biogeochemistry frameworks (e.g. cfc of dic)
+are specified in the packages\_conf file.
 {\it GCHEM\_OPTIONS.h} includes the compiler options to be used
-in any experiment. For instance \#define ALLOW\_CFC allows
-the CFC code to be run. An important compiler option is
- \#define PTRACERS\_SEPARATE\_FORCING which determined 
+in any experiment. 
+An important compiler option is
+ \#define GCHEM\_SEPARATE\_FORCING which determined 
 how and when the tracer forcing is applied (see discussion
-on Forcing below).
+on Forcing below). See section on dic for some additional
+flags that can be set for that experiment.
+\\
+
  There are further runtime parameters
 set in {\it data.gchem} and kept in common block {\it GCHEM.h}.
 These runtime options include:\\
-$\bullet$ {\bf tIter0} which is the integer timestep when the tracer experiment
- is initialized. If {\bf nIter0} $=$ {\bf tIter0} then the tracers
- are initialized to zero or from initial files. If {\bf nIter0} $>$
- {\bf tIter0} then tracers (and previous timestep tendency terms)
-  are read in from a the ptracers pickup file. Note that tracers
-  of zeros will be carried around if {\bf nIter0} $<$ {\bf tIter0}.
+$\bullet$ Parameters to set the timing for periodic forcing files to
+be loaded are: {\it gchem\_ForcingPeriod}, {\it gchem\_ForcingCycle}.
+The former is how often to load, the latter is how often to cycle
+through those fields (eg. period couple be monthly and cycle one year).
+This is used in {\it dic} and {\it cfc}, with gchem\_ForcingPeriod=0
+meaning no periodic forcing.
 \\
 $\bullet$ {\bf nsubtime} is the integer number of extra timesteps
  required by the tracer experiment. This will give a timestep
@@ -53,6 +59,13 @@
  wind speed is needed in both DIC and CFC packages to calculate
  the air-sea exchange of gases. Not all file names will be used 
  for every tracer experiment. 
+\\
+$\bullet$ {\bf gchem\_int\_*} are variable names for run-time set integer numbers. (Currently 1 through 5).
+\\
+$\bullet$ {\bf gchem\_rl\_*} are variable names for run-time set real numbers. (Currently 1 through 5).
+\\
+$\bullet$ Note that the old {\bf tIter0} has been replaced by {\bf PTRACERS\_Iter0} which is
+set in data.ptracers instead.
 
 \vspace{.5cm}
 
@@ -65,7 +78,7 @@
 
 There are two routine used to initialize parameters and fields
 needed by the experiment packages. These are
-{\it gchem\_init\_fixed.F} which is called from packages\_init\_fixed.F, and
+{\it gchem\_init\_fixed.F} which is called from \textit{packages\_init\_fixed.F}, and
 {\it gchem\_init\_vari.F} called from 
 packages\_init\_variable.F. The first should
 be used to call a subroutine specific to the tracer experiment
@@ -80,7 +93,7 @@
 {{\bf LOADING FIELDS}}\\
 External forcing fields used by the tracer experiment are read
 in by a subroutine (specific to the tracer experiment) called from
-{\it gchem\_fields\_load.F}. This latter is called from forward\_step.F.
+{\it gchem\_fields\_load.F}. This latter is called from \textit{forward\_step.F}.
 
 \vspace{.5cm}
 
@@ -93,37 +106,81 @@
 interface. For tracers that are essentially passive (e.g. CFC's)
 but may have some surface boundary conditions
 this can easily be done within the regular tracer timestep. In this case
-{\it gchem\_forcing\_int.F} is called from ptracers\_integrate.F.
+{\it gchem\_calc\_tendency.F} is called from {\it forward\_step.F}, where the 
+reactive (as opposed to the advective diffusive) tendencies are computed.
+These tendencies, stored on the 3D field \textbf{gchemTendency}, are added to
+the passive tracer tendencies \textbf{gPtr} in {\it gchem\_add\_tendency.F}, 
+which is called from {\it ptracers\_forcing.F}.
 For tracers with more complicated dependencies on each other,
 and especially tracers which require a smaller timestep than
 deltaTtracer, it will be easier to use {\it gchem\_forcing\_sep.F}
 which is called from forward\_step.F. There is a 
 compiler option set in {\it GCHEM\_OPTIONS.h} that determines
-which method is used: \#define PTRACERS\_SEPARATE\_FORCING
+which method is used: \#define GCHEM\_SEPARATE\_FORCING
 does the latter where tracers are forced separately from the
-advection-diffusion code, and \#undef PTRACERS\_SEPARATE\_FORCING
+advection-diffusion code, and \#undef GCHEM\_SEPARATE\_FORCING
 includes the forcing in the regular timestepping.
 
 \vspace{.5cm}
 
 \noindent
 {{\bf DIAGNOSTICS}}\\
-This package also includes routines {\it gchem\_monitor.F} and 
-{\it gchem\_mon\_print.F} which print out tracer statistics
-as often as the model dynamic statistic diagnostics (dynsys) are written.
+This package also also used the passive tracer routine {\it ptracers\_monitor.F}
+which prints out tracer statistics 
+as often as the model dynamic statistic diagnostics (dynsys) are written (or
+as prescribed by the runtime flag \textbf{PTRACERS\_monitorFreq}, set in {\it data.ptracers}).
 There is also a placeholder for any tracer experiment
 specific diagnostics to be calculated and printed to files.
 This is done in {\it gchem\_diags.F}. For instance the time average CO2
 air-sea fluxes, and sea surface pH (among others) are written
-out by dic\_biotic\_diags.F which is called from gchem\_diags.F.
+out by {\it dic\_biotic\_diags.F} which is called from {\it gchem\_diags.F}.
+
+\subsubsection{GCHEM Diagnostics}
+\label{sec:pkg:gchem:diagnostics}
 
-\subsection{Do's and Don'ts}
+These diagnostics are particularly for the {\bf dic} package.
 
-The pkg ptracer is required with use with this pkg.
-By itself, gchem pkg will read in {\bf data.gchem} and will
-write out ptracer diagnostics. It requires tracer experiment
+{\footnotesize
+\begin{verbatim}
+
+------------------------------------------------------------------------
+<-Name->|Levs|<-parsing code->|<--  Units   -->|<- Tile (max=80c) 
+------------------------------------------------------------------------
+DICBIOA | 15 |SM P    MR      |mol/m3/sec      |Biological Productivity (mol/m3/s)
+DICCARB | 15 |SM P    MR      |mol eq/m3/sec   |Carbonate chg-biol prod and remin (mol eq/m3/s)
+DICTFLX |  1 |SM P    L1      |mol/m3/sec      |Tendency of DIC due to air-sea exch (mol/m3/s)
+DICOFLX |  1 |SM P    L1      |mol/m3/sec      |Tendency of O2 due to air-sea exch (mol/m3/s)
+DICCFLX |  1 |SM P    L1      |mol/m2/sec      |Flux of CO2 - air-sea exch (mol/m2/s)
+DICPCO2 |  1 |SM P    M1      |atm             |Partial Pressure of CO2 (atm)
+DICPHAV |  1 |SM P    M1      |dimensionless   |pH (dimensionless)
+\end{verbatim}
+}
+
+\subsubsection{Do's and Don'ts}
+
+The pkg ptracer is required with use with this pkg. Also, as usual, the
+runtime flag \textbf{useGCHEM} must be set to \textbf{.TRUE.} in \textbf{data.pkg}.
+By itself, gchem pkg will read in \textbf{data.gchem} and will
+write out gchem diagnostics. It requires tracer experiment
 specific calls to do anything else (for instance the calls
 to dic and cfc pkgs).
 
-\subsection{Reference Material}
+\subsubsection{Reference Material}
+
+\subsubsection{Experiments and tutorials that use gchem}
+\label{sec:pkg:gchem:experiments}
+
+\begin{itemize}
+\item{Global Ocean biogeochemical tutorial, in tutorial\_global\_oce\_biogeo verification directory,   
+described in section \ref{sec:eg-biogeochem_tutorial} uses gchem and dic }
+
+\item{Global Ocean cfc tutorial, in tutorial\_cfc\_offline verification directory,   
+uses gchem and cfc (and offline) described in \ref{sec:eg-offline-cfc} }
+
+\item{Global Ocean online cfc example in cfc\_example verification directory,   
+uses gchem and cfc}
+
+
+
+\end{itemize}
 
