• 6.8.1.1 Introduction
• 6.8.1.2 Key subroutines and parameters
• 6.8.1.3 GCHEM Diagnostics
• 6.8.1.4 Do's and Don'ts
• 6.8.1.5 Reference Material
• 6.8.1.6 Experiments and tutorials that use gchem

6.8.1 GCHEM Package

6.8.1.1 Introduction

There are two examples: cfc which looks at 2 tracers with a simple external forcing and 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.

6.8.1.2 Key subroutines and parameters

FRAMEWORK
The different biogeochemistry frameworks (e.g. cfc of dic) are specified in the packages_conf file. 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 data.gchem and kept in common block GCHEM.h. These runtime options include:
Parameters to set the timing for periodic forcing files to be loaded are: gchem_ForcingPeriod, 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 dic and cfc, with gchem_ForcingPeriod=0 meaning no periodic forcing.
nsubtime is the integer number of extra timesteps required by the tracer experiment. This will give a timestep of deltaTtracer nsubtime for the dependencies between tracers. The default is one.
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.
gchem_int_* are variable names for run-time set integer numbers. (Currently 1 through 5).
gchem_rl_* are variable names for run-time set real numbers. (Currently 1 through 5).
Note that the old tIter0 has been replaced by PTRACERS_Iter0 which is set in data.ptracers instead.

INITIALIZATION
The values set at runtime in data.gchem are read in using 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 gchem_init_fixed.F which is called from packages_init_fixed.F, and 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.

LOADING FIELDS
External forcing fields used by the tracer experiment are read in by a subroutine (specific to the tracer experiment) called from gchem_fields_load.F. This latter is called from forward_step.F.

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 gchem_calc_tendency.F is called from forward_step.F, where the reactive (as opposed to the advective diffusive) tendencies are computed. These tendencies, stored on the 3D field gchemTendency, are added to the passive tracer tendencies gPtr in gchem_add_tendency.F, which is called from 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 gchem_forcing_sep.F which is called from forward_step.F. There is a compiler option set in 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.

DIAGNOSTICS
This package also also used the passive tracer routine 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 PTRACERS_monitorFreq, set in data.ptracers). There is also a placeholder for any tracer experiment specific diagnostics to be calculated and printed to files. This is done in 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.

6.8.1.3 GCHEM Diagnostics

These diagnostics are particularly for the dic package.

------------------------------------------------------------------------
<-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)

6.8.1.4 Do's and Don'ts

The pkg ptracer is required with use with this pkg. Also, as usual, the runtime flag useGCHEM must be set to .TRUE. in data.pkg. By itself, gchem pkg will read in 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).

6.8.1.5 Reference Material

6.8.1.6 Experiments and tutorials that use gchem

• Global Ocean biogeochemical tutorial, in tutorial_global_oce_biogeo verification directory, described in section 3.17 uses gchem and dic

• Global Ocean cfc tutorial, in tutorial_cfc_offline verification directory, uses gchem and cfc (and offline) described in 3.20.5

• Global Ocean online cfc example in cfc_example verification directory, uses gchem and cfc

Copyright © 2006 Massachusetts Institute of Technology

Last update 2011-01-09