s_phys_pkgs/text/gchem.tex

\subsection {GCHEM Package} 
\label{sec:pkg:gchem}
\begin{rawhtml}
<!-- CMIREDIR:package_gchem: -->
\end{rawhtml}

\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.
For instance there are placeholders for routines
to read in parameters needed for any tracer experiments, a routine
to read in extra fields required for the tracer code, routines
for either external forcing or internal interactions between tracers
and routines for additional diagnostics relating to the tracers.
Note that the gchem package itself is only a means to call
the subroutines used by specific biogeochemical experiments,
and does not "do" anything on its own.

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.


\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. 
An important compiler option is
 \#define GCHEM\_SEPARATE\_FORCING which determined 
how and when the tracer forcing is applied (see discussion
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$ 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
 of {\bf deltaTtracer}$/${\bf nsubtime} for the dependencies
 between tracers. The default is one.
\\
$\bullet$ File names - these are several filenames than can be read in
 for external fields needed in the tracer forcing - for instance
 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}

\noindent
{{\bf INITIALIZATION}}\\
The values set at runtime in data.gchem are read in
using {\it gchem\_readparms.F} which is called from
packages\_readparms.F. This will include any external
forcing files that will be needed by the tracer experiment.

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 \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
which sets fixed parameters, the second should call a subroutine
specific to the tracer experiment
which sets (or initializes) time fields that will vary with time.

\vspace{.5cm}


\noindent
{{\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 \textit{forward\_step.F}.

\vspace{.5cm}


\noindent
{{\bf FORCING}}\\
Tracer fields are advected-and-diffused by the ptracer package.
Additional changes (e.g. surface forcing or interactions
between tracers) to these fields are taken care of by the gchem
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\_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 GCHEM\_SEPARATE\_FORCING
does the latter where tracers are forced separately from the
advection-diffusion code, and \#undef GCHEM\_SEPARATE\_FORCING
includes the forcing in the regular timestepping.

\vspace{.5cm}

\noindent
{{\bf DIAGNOSTICS}}\\
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 {\it dic\_biotic\_diags.F} which is called from {\it gchem\_diags.F}.

\subsubsection{GCHEM Diagnostics}
\label{sec:pkg:gchem:diagnostics}

These diagnostics are particularly for the {\bf dic} package.

{\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).

\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}

1	molod	1.4	\subsection {GCHEM Package}
2	edhill	1.2	\label{sec:pkg:gchem}
3			\begin{rawhtml}
4			<!-- CMIREDIR:package_gchem: -->
5			\end{rawhtml}
6	edhill	1.1
7	molod	1.4	\subsubsection {Introduction}
8	edhill	1.1	This package has been developed as interface to the PTRACERS package.
9			The purpose is to provide a structure where various (any)
10			tracer experiments can be added to the code.
11			For instance there are placeholders for routines
12			to read in parameters needed for any tracer experiments, a routine
13			to read in extra fields required for the tracer code, routines
14			for either external forcing or internal interactions between tracers
15			and routines for additional diagnostics relating to the tracers.
16			Note that the gchem package itself is only a means to call
17			the subroutines used by specific biogeochemical experiments,
18			and does not "do" anything on its own.
19
20	stephd	1.9	There are two examples: {\bf cfc} which looks at 2 tracers with a
21			simple external forcing and {\bf dic} with 4,5 or 6 tracers
22			whose tendency terms
23	edhill	1.1	are related to one another. We will discuss these here only as
24			how they provide examples to use this package.
25
26
27	molod	1.4	\subsubsection {Key subroutines and parameters}
28	edhill	1.1
29			\noindent
30			{{\bf FRAMEWORK}} \\
31	stephd	1.9	The different biogeochemistry frameworks (e.g. cfc of dic)
32			are specified in the packages\_conf file.
33	edhill	1.1	{\it GCHEM\_OPTIONS.h} includes the compiler options to be used
34	stephd	1.9	in any experiment.
35			An important compiler option is
36	mlosch	1.3	\#define GCHEM\_SEPARATE\_FORCING which determined
37	edhill	1.1	how and when the tracer forcing is applied (see discussion
38	stephd	1.9	on Forcing below). See section on dic for some additional
39			flags that can be set for that experiment.
40	stephd	1.11	\\
41
42	edhill	1.1	There are further runtime parameters
43			set in {\it data.gchem} and kept in common block {\it GCHEM.h}.
44			These runtime options include:\\
45	stephd	1.9	$\bullet$ Parameters to set the timing for periodic forcing files to
46			be loaded are: {\it gchem\_ForcingPeriod}, {\it gchem\_ForcingCycle}.
47			The former is how often to load, the latter is how often to cycle
48			through those fields (eg. period couple be monthly and cycle one year).
49			This is used in {\it dic} and {\it cfc}, with gchem\_ForcingPeriod=0
50			meaning no periodic forcing.
51	stephd	1.10	\\
52	edhill	1.1	$\bullet$ {\bf nsubtime} is the integer number of extra timesteps
53			required by the tracer experiment. This will give a timestep
54			of {\bf deltaTtracer}$/${\bf nsubtime} for the dependencies
55			between tracers. The default is one.
56			\\
57			$\bullet$ File names - these are several filenames than can be read in
58			for external fields needed in the tracer forcing - for instance
59			wind speed is needed in both DIC and CFC packages to calculate
60			the air-sea exchange of gases. Not all file names will be used
61			for every tracer experiment.
62	stephd	1.9	\\
63			$\bullet$ {\bf gchem\_int\_*} are variable names for run-time set integer numbers. (Currently 1 through 5).
64			\\
65			$\bullet$ {\bf gchem\_rl\_*} are variable names for run-time set real numbers. (Currently 1 through 5).
66	stephd	1.10	\\
67	stephd	1.9	$\bullet$ Note that the old {\bf tIter0} has been replaced by {\bf PTRACERS\_Iter0} which is
68			set in data.ptracers instead.
69	edhill	1.1
70			\vspace{.5cm}
71
72			\noindent
73			{{\bf INITIALIZATION}}\\
74			The values set at runtime in data.gchem are read in
75			using {\it gchem\_readparms.F} which is called from
76			packages\_readparms.F. This will include any external
77			forcing files that will be needed by the tracer experiment.
78
79			There are two routine used to initialize parameters and fields
80			needed by the experiment packages. These are
81	mlosch	1.3	{\it gchem\_init\_fixed.F} which is called from \textit{packages\_init\_fixed.F}, and
82	edhill	1.1	{\it gchem\_init\_vari.F} called from
83			packages\_init\_variable.F. The first should
84			be used to call a subroutine specific to the tracer experiment
85			which sets fixed parameters, the second should call a subroutine
86			specific to the tracer experiment
87			which sets (or initializes) time fields that will vary with time.
88
89			\vspace{.5cm}
90
91
92			\noindent
93			{{\bf LOADING FIELDS}}\\
94			External forcing fields used by the tracer experiment are read
95			in by a subroutine (specific to the tracer experiment) called from
96	mlosch	1.3	{\it gchem\_fields\_load.F}. This latter is called from \textit{forward\_step.F}.
97	edhill	1.1
98			\vspace{.5cm}
99
100
101			\noindent
102			{{\bf FORCING}}\\
103			Tracer fields are advected-and-diffused by the ptracer package.
104			Additional changes (e.g. surface forcing or interactions
105			between tracers) to these fields are taken care of by the gchem
106			interface. For tracers that are essentially passive (e.g. CFC's)
107			but may have some surface boundary conditions
108			this can easily be done within the regular tracer timestep. In this case
109	mlosch	1.3	{\it gchem\_calc\_tendency.F} is called from {\it forward\_step.F}, where the
110			reactive (as opposed to the advective diffusive) tendencies are computed.
111			These tendencies, stored on the 3D field \textbf{gchemTendency}, are added to
112			the passive tracer tendencies \textbf{gPtr} in {\it gchem\_add\_tendency.F},
113			which is called from {\it ptracers\_forcing.F}.
114	edhill	1.1	For tracers with more complicated dependencies on each other,
115			and especially tracers which require a smaller timestep than
116			deltaTtracer, it will be easier to use {\it gchem\_forcing\_sep.F}
117			which is called from forward\_step.F. There is a
118			compiler option set in {\it GCHEM\_OPTIONS.h} that determines
119	mlosch	1.3	which method is used: \#define GCHEM\_SEPARATE\_FORCING
120	edhill	1.1	does the latter where tracers are forced separately from the
121	mlosch	1.3	advection-diffusion code, and \#undef GCHEM\_SEPARATE\_FORCING
122	edhill	1.1	includes the forcing in the regular timestepping.
123
124			\vspace{.5cm}
125
126			\noindent
127			{{\bf DIAGNOSTICS}}\\
128	mlosch	1.3	This package also also used the passive tracer routine {\it ptracers\_monitor.F}
129			which prints out tracer statistics
130			as often as the model dynamic statistic diagnostics (dynsys) are written (or
131			as prescribed by the runtime flag \textbf{PTRACERS\_monitorFreq}, set in {\it data.ptracers}).
132	edhill	1.1	There is also a placeholder for any tracer experiment
133			specific diagnostics to be calculated and printed to files.
134			This is done in {\it gchem\_diags.F}. For instance the time average CO2
135			air-sea fluxes, and sea surface pH (among others) are written
136	mlosch	1.3	out by {\it dic\_biotic\_diags.F} which is called from {\it gchem\_diags.F}.
137	edhill	1.1
138	edhill	1.6	\subsubsection{GCHEM Diagnostics}
139	molod	1.5	\label{sec:pkg:gchem:diagnostics}
140
141	stephd	1.9	These diagnostics are particularly for the {\bf dic} package.
142
143	edhill	1.7	{\footnotesize
144	molod	1.5	\begin{verbatim}
145
146			------------------------------------------------------------------------
147			<-Name->\|Levs\|<-parsing code->\|<-- Units -->\|<- Tile (max=80c)
148			------------------------------------------------------------------------
149			DICBIOA \| 15 \|SM P MR \|mol/m3/sec \|Biological Productivity (mol/m3/s)
150			DICCARB \| 15 \|SM P MR \|mol eq/m3/sec \|Carbonate chg-biol prod and remin (mol eq/m3/s)
151			DICTFLX \| 1 \|SM P L1 \|mol/m3/sec \|Tendency of DIC due to air-sea exch (mol/m3/s)
152			DICOFLX \| 1 \|SM P L1 \|mol/m3/sec \|Tendency of O2 due to air-sea exch (mol/m3/s)
153			DICCFLX \| 1 \|SM P L1 \|mol/m2/sec \|Flux of CO2 - air-sea exch (mol/m2/s)
154			DICPCO2 \| 1 \|SM P M1 \|atm \|Partial Pressure of CO2 (atm)
155			DICPHAV \| 1 \|SM P M1 \|dimensionless \|pH (dimensionless)
156			\end{verbatim}
157	edhill	1.7	}
158	molod	1.5
159	molod	1.4	\subsubsection{Do's and Don'ts}
160	edhill	1.1
161	mlosch	1.3	The pkg ptracer is required with use with this pkg. Also, as usual, the
162			runtime flag \textbf{useGCHEM} must be set to \textbf{.TRUE.} in \textbf{data.pkg}.
163			By itself, gchem pkg will read in \textbf{data.gchem} and will
164			write out gchem diagnostics. It requires tracer experiment
165	edhill	1.1	specific calls to do anything else (for instance the calls
166			to dic and cfc pkgs).
167
168	molod	1.4	\subsubsection{Reference Material}
169	edhill	1.1
170	molod	1.8	\subsubsection{Experiments and tutorials that use gchem}
171			\label{sec:pkg:gchem:experiments}
172
173			\begin{itemize}
174	stephd	1.9	\item{Global Ocean biogeochemical tutorial, in tutorial\_global\_oce\_biogeo verification directory,
175			described in section \ref{sect:eg-biogeochem_tutorial} uses gchem and dic }
176
177			\item{Global Ocean cfc tutorial, in tutorial\_cfc\_offline verification directory,
178			uses gchem and cfc (and offline) described in \ref{sect:eg-cfc_offline} }
179
180			\item{Global Ocean online cfc example in cfc\_example verification directory,
181			uses gchem and cfc}
182
183
184
185	molod	1.8	\end{itemize}
186