--- manual/s_phys_pkgs/text/gchem.tex 2004/10/12 18:16:03 1.2 +++ manual/s_phys_pkgs/text/gchem.tex 2008/01/17 18:13:02 1.11 @@ -1,10 +1,10 @@ -\section {GCHEM Package} +\subsection {GCHEM Package} \label{sec:pkg:gchem} \begin{rawhtml} \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{sect: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{sect:eg-cfc_offline} } + +\item{Global Ocean online cfc example in cfc\_example verification directory, +uses gchem and cfc} + + + +\end{itemize}