s_phys_pkgs/text/gchem.tex

\section {GCHEM Package} 

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


\subsection {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 PTRACERS\_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 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 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\_forcing\_int.F} is called from ptracers\_integrate.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
does the latter where tracers are forced separately from the
advection-diffusion code, and \#undef PTRACERS\_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.
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.

\subsection{Do's and Don'ts}

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
specific calls to do anything else (for instance the calls
to dic and cfc pkgs).

\subsection{Reference Material}

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