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: cfc which looks at 2 tracers with a
simple external forcing and dic with 5 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}} \\
{\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 GCHEM\_SEPARATE\_FORCING which determined 
how and when the tracer forcing is applied (see discussion
on Forcing below).
 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$ {\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. 

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

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			There are two examples: cfc which looks at 2 tracers with a
21			simple external forcing and dic with 5 tracers whose tendency terms
22			are related to one another. We will discuss these here only as
23			how they provide examples to use this package.
24
25
26	molod	1.4	\subsubsection {Key subroutines and parameters}
27	edhill	1.1
28			\noindent
29			{{\bf FRAMEWORK}} \\
30			{\it GCHEM\_OPTIONS.h} includes the compiler options to be used
31			in any experiment. For instance \#define ALLOW\_CFC allows
32			the CFC code to be run. An important compiler option is
33	mlosch	1.3	\#define GCHEM\_SEPARATE\_FORCING which determined
34	edhill	1.1	how and when the tracer forcing is applied (see discussion
35			on Forcing below).
36			There are further runtime parameters
37			set in {\it data.gchem} and kept in common block {\it GCHEM.h}.
38			These runtime options include:\\
39			$\bullet$ {\bf tIter0} which is the integer timestep when the tracer experiment
40			is initialized. If {\bf nIter0} $=$ {\bf tIter0} then the tracers
41			are initialized to zero or from initial files. If {\bf nIter0} $>$
42			{\bf tIter0} then tracers (and previous timestep tendency terms)
43			are read in from a the ptracers pickup file. Note that tracers
44			of zeros will be carried around if {\bf nIter0} $<$ {\bf tIter0}.
45			\\
46			$\bullet$ {\bf nsubtime} is the integer number of extra timesteps
47			required by the tracer experiment. This will give a timestep
48			of {\bf deltaTtracer}$/${\bf nsubtime} for the dependencies
49			between tracers. The default is one.
50			\\
51			$\bullet$ File names - these are several filenames than can be read in
52			for external fields needed in the tracer forcing - for instance
53			wind speed is needed in both DIC and CFC packages to calculate
54			the air-sea exchange of gases. Not all file names will be used
55			for every tracer experiment.
56
57			\vspace{.5cm}
58
59			\noindent
60			{{\bf INITIALIZATION}}\\
61			The values set at runtime in data.gchem are read in
62			using {\it gchem\_readparms.F} which is called from
63			packages\_readparms.F. This will include any external
64			forcing files that will be needed by the tracer experiment.
65
66			There are two routine used to initialize parameters and fields
67			needed by the experiment packages. These are
68	mlosch	1.3	{\it gchem\_init\_fixed.F} which is called from \textit{packages\_init\_fixed.F}, and
69	edhill	1.1	{\it gchem\_init\_vari.F} called from
70			packages\_init\_variable.F. The first should
71			be used to call a subroutine specific to the tracer experiment
72			which sets fixed parameters, the second should call a subroutine
73			specific to the tracer experiment
74			which sets (or initializes) time fields that will vary with time.
75
76			\vspace{.5cm}
77
78
79			\noindent
80			{{\bf LOADING FIELDS}}\\
81			External forcing fields used by the tracer experiment are read
82			in by a subroutine (specific to the tracer experiment) called from
83	mlosch	1.3	{\it gchem\_fields\_load.F}. This latter is called from \textit{forward\_step.F}.
84	edhill	1.1
85			\vspace{.5cm}
86
87
88			\noindent
89			{{\bf FORCING}}\\
90			Tracer fields are advected-and-diffused by the ptracer package.
91			Additional changes (e.g. surface forcing or interactions
92			between tracers) to these fields are taken care of by the gchem
93			interface. For tracers that are essentially passive (e.g. CFC's)
94			but may have some surface boundary conditions
95			this can easily be done within the regular tracer timestep. In this case
96	mlosch	1.3	{\it gchem\_calc\_tendency.F} is called from {\it forward\_step.F}, where the
97			reactive (as opposed to the advective diffusive) tendencies are computed.
98			These tendencies, stored on the 3D field \textbf{gchemTendency}, are added to
99			the passive tracer tendencies \textbf{gPtr} in {\it gchem\_add\_tendency.F},
100			which is called from {\it ptracers\_forcing.F}.
101	edhill	1.1	For tracers with more complicated dependencies on each other,
102			and especially tracers which require a smaller timestep than
103			deltaTtracer, it will be easier to use {\it gchem\_forcing\_sep.F}
104			which is called from forward\_step.F. There is a
105			compiler option set in {\it GCHEM\_OPTIONS.h} that determines
106	mlosch	1.3	which method is used: \#define GCHEM\_SEPARATE\_FORCING
107	edhill	1.1	does the latter where tracers are forced separately from the
108	mlosch	1.3	advection-diffusion code, and \#undef GCHEM\_SEPARATE\_FORCING
109	edhill	1.1	includes the forcing in the regular timestepping.
110
111			\vspace{.5cm}
112
113			\noindent
114			{{\bf DIAGNOSTICS}}\\
115	mlosch	1.3	This package also also used the passive tracer routine {\it ptracers\_monitor.F}
116			which prints out tracer statistics
117			as often as the model dynamic statistic diagnostics (dynsys) are written (or
118			as prescribed by the runtime flag \textbf{PTRACERS\_monitorFreq}, set in {\it data.ptracers}).
119	edhill	1.1	There is also a placeholder for any tracer experiment
120			specific diagnostics to be calculated and printed to files.
121			This is done in {\it gchem\_diags.F}. For instance the time average CO2
122			air-sea fluxes, and sea surface pH (among others) are written
123	mlosch	1.3	out by {\it dic\_biotic\_diags.F} which is called from {\it gchem\_diags.F}.
124	edhill	1.1
125	molod	1.4	\subsubsection{Do's and Don'ts}
126	edhill	1.1
127	mlosch	1.3	The pkg ptracer is required with use with this pkg. Also, as usual, the
128			runtime flag \textbf{useGCHEM} must be set to \textbf{.TRUE.} in \textbf{data.pkg}.
129			By itself, gchem pkg will read in \textbf{data.gchem} and will
130			write out gchem diagnostics. It requires tracer experiment
131	edhill	1.1	specific calls to do anything else (for instance the calls
132			to dic and cfc pkgs).
133
134	molod	1.4	\subsubsection{Reference Material}
135	edhill	1.1