Warning, /doc/phys_pkgs/gchem.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit bf89a37a on 2019-03-17 03:29:27 UTC
bf89a37abc Phob*0001 .. _sub_phys_pkg_gchem:
0002
9ce7d74115 Jeff*0003 GCHEM Package
0004 -------------
0005
0006 Introduction
0007 ~~~~~~~~~~~~
0008
0009 This package has been developed as interface to the PTRACERS package.
0010 The purpose is to provide a structure where various (any) tracer
0011 experiments can be added to the code. For instance there are
0012 placeholders for routines to read in parameters needed for any tracer
0013 experiments, a routine to read in extra fields required for the tracer
0014 code, routines for either external forcing or internal interactions
0015 between tracers and routines for additional diagnostics relating to the
0016 tracers. Note that the gchem package itself is only a means to call the
0017 subroutines used by specific biogeochemical experiments, and does not
0018 “do” anything on its own.
0019
0020 There are two examples: **cfc** which looks at 2 tracers with a simple
0021 external forcing and **dic** with 4,5 or 6 tracers whose tendency terms
0022 are related to one another. We will discuss these here only as how they
0023 provide examples to use this package.
0024
0025 Key subroutines and parameters
0026 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0027
0028 | **FRAMEWORK**
0029 | The different biogeochemistry frameworks (e.g. cfc of dic) are
0030 specified in the packages\_conf file. *GCHEM\_OPTIONS.h* includes the
0031 compiler options to be used in any experiment. An important compiler
0032 option is #define GCHEM\_SEPARATE\_FORCING which determined how and
0033 when the tracer forcing is applied (see discussion on Forcing below).
0034 See section on dic for some additional flags that can be set for that
0035 experiment.
0036 | There are further runtime parameters set in *data.gchem* and kept in
0037 common block *GCHEM.h*. These runtime options include:
0038 | :math:`\bullet` Parameters to set the timing for periodic forcing
0039 files to be loaded are: *gchem\_ForcingPeriod*, *gchem\_ForcingCycle*.
0040 The former is how often to load, the latter is how often to cycle
0041 through those fields (eg. period couple be monthly and cycle one
0042 year). This is used in *dic* and *cfc*, with gchem\_ForcingPeriod=0
0043 meaning no periodic forcing.
0044 | :math:`\bullet` **nsubtime** is the integer number of extra timesteps
0045 required by the tracer experiment. This will give a timestep of
0046 **deltaTtracer**\ :math:`/`\ **nsubtime** for the dependencies between
0047 tracers. The default is one.
0048 | :math:`\bullet` File names - these are several filenames than can be
0049 read in for external fields needed in the tracer forcing - for
0050 instance wind speed is needed in both DIC and CFC packages to
0051 calculate the air-sea exchange of gases. Not all file names will be
0052 used for every tracer experiment.
0053 | :math:`\bullet` **gchem\_int\_** are variable names for run-time set
0054 integer numbers. (Currently 1 through 5).
0055 | :math:`\bullet` **gchem\_rl\_** are variable names for run-time set
0056 real numbers. (Currently 1 through 5).
0057 | :math:`\bullet` Note that the old **tIter0** has been replaced by
0058 **PTRACERS\_Iter0** which is set in data.ptracers instead.
0059 |
0060 | **INITIALIZATION**
0061 | The values set at runtime in data.gchem are read in using
0062 *gchem\_readparms.F* which is called from packages\_readparms.F. This
0063 will include any external forcing files that will be needed by the
0064 tracer experiment.
0065 | There are two routine used to initialize parameters and fields needed by
0066 the experiment packages. These are *gchem\_init\_fixed.F* which is
0067 called from *packages\_init\_fixed.F*, and *gchem\_init\_vari.F* called
0068 from packages\_init\_variable.F. The first should be used to call a
0069 subroutine specific to the tracer experiment which sets fixed
0070 parameters, the second should call a subroutine specific to the tracer
0071 experiment which sets (or initializes) time fields that will vary with
0072 time.
0073 |
0074 | **LOADING FIELDS**
0075 | External forcing fields used by the tracer experiment are read in by a
0076 subroutine (specific to the tracer experiment) called from
0077 *gchem\_fields\_load.F*. This latter is called from *forward\_step.F*.
0078 |
0079 | **FORCING**
0080 | Tracer fields are advected-and-diffused by the ptracer package.
0081 Additional changes (e.g. surface forcing or interactions between
0082 tracers) to these fields are taken care of by the gchem interface. For
0083 tracers that are essentially passive (e.g. CFC’s) but may have some
0084 surface boundary conditions this can easily be done within the regular
0085 tracer timestep. In this case *gchem\_calc\_tendency.F* is called from
0086 *forward\_step.F*, where the reactive (as opposed to the advective
0087 diffusive) tendencies are computed. These tendencies, stored on the 3D
0088 field **gchemTendency**, are added to the passive tracer tendencies
0089 **gPtr** in *gchem\_add\_tendency.F*, which is called from
0090 *ptracers\_forcing.F*. For tracers with more complicated dependencies
0091 on each other, and especially tracers which require a smaller timestep
0092 than deltaTtracer, it will be easier to use *gchem\_forcing\_sep.F*
0093 which is called from forward\_step.F. There is a compiler option set
0094 in *GCHEM\_OPTIONS.h* that determines which method is used: #define
0095 GCHEM\_SEPARATE\_FORCING does the latter where tracers are forced
0096 separately from the advection-diffusion code, and #undef
0097 GCHEM\_SEPARATE\_FORCING includes the forcing in the regular
0098 timestepping.
0099 |
0100 | **DIAGNOSTICS**
0101 | This package also also used the passive tracer routine
0102 *ptracers\_monitor.F* which prints out tracer statistics as often as
0103 the model dynamic statistic diagnostics (dynsys) are written (or as
0104 prescribed by the runtime flag **PTRACERS\_monitorFreq**, set in
0105 *data.ptracers*). There is also a placeholder for any tracer
0106 experiment specific diagnostics to be calculated and printed to files.
0107 This is done in *gchem\_diags.F*. For instance the time average CO2
0108 air-sea fluxes, and sea surface pH (among others) are written out by
0109 *dic\_biotic\_diags.F* which is called from *gchem\_diags.F*.
0110 |
0111
0112 .. _gchem_diagnostics:
0113
0114 GCHEM Diagnostics
0115 ~~~~~~~~~~~~~~~~~
0116
0117 These diagnostics are particularly for the **dic** package.
0118
0119 ::
0120
0121
0122 ------------------------------------------------------------------------
0123 <-Name->|Levs|<-parsing code->|<-- Units -->|<- Tile (max=80c)
0124 ------------------------------------------------------------------------
0125 DICBIOA | 15 |SM P MR |mol/m3/sec |Biological Productivity (mol/m3/s)
0126 DICCARB | 15 |SM P MR |mol eq/m3/sec |Carbonate chg-biol prod and remin (mol eq/m3/s)
0127 DICTFLX | 1 |SM P L1 |mol/m3/sec |Tendency of DIC due to air-sea exch (mol/m3/s)
0128 DICOFLX | 1 |SM P L1 |mol/m3/sec |Tendency of O2 due to air-sea exch (mol/m3/s)
0129 DICCFLX | 1 |SM P L1 |mol/m2/sec |Flux of CO2 - air-sea exch (mol/m2/s)
0130 DICPCO2 | 1 |SM P M1 |atm |Partial Pressure of CO2 (atm)
0131 DICPHAV | 1 |SM P M1 |dimensionless |pH (dimensionless)
0132
0133 Do’s and Don’ts
0134 ~~~~~~~~~~~~~~~
0135
0136 The pkg ptracer is required with use with this pkg. Also, as usual, the
0137 runtime flag **useGCHEM** must be set to **.TRUE.** in **data.pkg**. By
0138 itself, gchem pkg will read in **data.gchem** and will write out gchem
0139 diagnostics. It requires tracer experiment specific calls to do anything
0140 else (for instance the calls to dic and cfc pkgs).
0141
0142 Reference Material
0143 ~~~~~~~~~~~~~~~~~~
0144
0145 Experiments and tutorials that use gchem
0146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0147
0148 - Global Ocean biogeochemical tutorial, in
0149 tutorial\_global\_oce\_biogeo verification directory, described in
0150 section [sec:eg-biogeochem\_tutorial] uses gchem and dic
0151
0152 - Global Ocean cfc tutorial, in tutorial\_cfc\_offline verification
0153 directory, uses gchem and cfc (and offline) described in
0154 [sec:eg-offline-cfc]
0155
0156 - Global Ocean online cfc example in cfc\_example verification
0157 directory, uses gchem and cfc
