View GEOS-Chem species properties¶
Properties for GEOS-Chem species are stored in the GEOS-Chem
Species Database, which is a YAML file
(species_database.yml
) that is placed into each GEOS-Chem run
directory.
View species properties from the current stable GEOS-Chem version:
Species properties defined¶
The following sections contain a detailed description of GEOS-Chem species properties.
Required default properties¶
All GEOS-Chem species should have these properties defined:
Name:
FullName: full name of the species
Formula: chemical formula of the species
MW_g: molecular weight of the species in grams
EITHER Is_Gas: true
OR Is_Aerosol: true
All other properties are species-dependent. You may omit properties
that do not apply to a given species. GEOS-Chem will assign a “missing
value” (e.g. false
, -999
, -999.0
, or,
UNKNOWN
) to these properties when it reads the
species_database.yml
file from disk.
Identification¶
-
Name
¶
Species short name (e.g.
ISOP
).
-
Formula
¶
Species chemical formula (e.g.
CH2=C(CH3)CH=CH2
). This is used to define the species’formula
attribute, which gets written to GEOS-Chem diagnostic files and restart files.
-
FullName
¶
Species long name (e.g.
Isoprene
). This is used to define the species’long_name
attribute, which gets written to GEOS-Chem diagnostic files and restart files.
-
Is_Aerosol
¶
Indicates that the species is an aerosol (
true
), or isn’t (false
).
-
Is_Advected
¶
Indicates that the species is advected (
true
), or isn’t (false
).
-
Is_DryAlt
¶
Indicates that dry deposition diagnostic quantities for the species can be archived at a specified altitude above the surface (
true
), or can’t (false
).Note
The
Is_DryAlt
flag only applies to speciesO3
andHNO3
.
-
Is_DryDep
¶
Indicates that the species is dry deposited (
true
), or isn’t (false
).
-
Is_HygroGrowth
¶
Indicates that the species is an aerosol that is capable of hygroscopic growth (
true
), or isn’t (false
).
-
Is_Gas
¶
Indicates that the species is a gas (
true
), or isn’t (false
).
-
Is_Hg0
¶
Indicates that the species is elemental mercury (
true
), or isn’t (false
).
-
Is_Hg2
¶
Indicates that the species is a mercury compound with oxidation state +2 (
true
), or isn’t (false
).
-
Is_HgP
¶
Indicates that the species is a particulate mercury compound (
true
), or isn’t (false
).
-
Is_Photolysis
¶
Indicates that the species is photolyzed (
true
), or isn’t (false
).
-
Is_RadioNuclide
¶
Indicates that the species is a radionuclide (
true
), or isn’t (false
).
Physical properties¶
-
Density
¶
Density (\(kg\ m^{-3}\)) of the species. Typically defined only for aerosols.
-
Henry_K0
¶
Henry’s law solubility constant (\(M\ atm^{-1}\)), used by the default wet depositon scheme.
-
Henry_K0_Luo
¶
Henry’s law solubility constant (\(M\ atm^{-1}\)) used by the Luo et al. [2020] wet deposition scheme.
-
Henry_CR
¶
Henry’s law volatility constant (\(K\)) used by the default wet deposition scheme.
-
Henry_CR_Luo
¶
Henry’s law volatility constant (\(K\)) used by the Luo et al. [2020] wet deposition scheme.
-
Henry_pKa
¶
Henry’s Law pH correction factor.
-
MW_g
¶
Molecular weight (\(g\ mol^{-1}\)) of the species.
-
Radius
¶
Radius (\(m\)) of the species. Typically defined only for aerosols.
Dry deposition properties¶
-
DD_AeroDryDep
¶
Indicates that dry deposition should consider hygroscopic growth for this species (
true
), or shouldn’t (false
).Note
DD_AeroDryDep
is only defined for sea salt aerosols.
-
DD_DustDryDep
¶
Indicates that dry deposition should exclude hygroscopic growth for this species (
true
), or shouldn’t (false
).Note
DD_DustDryDep
is only defined for mineral dust aerosols.
-
DD_DvzAerSnow
¶
Specifies the dry deposition velocity (\(cm\ s^{-1}\)) over ice and snow for certain aerosol species. Typically,
DD_DvzAerSnow = 0.03
.
-
DD_DvzAerSnow_Luo
¶
Specifies the dry deposition velocity (\(cm\ s^{-1}\)) over ice and snow for certain aerosol species.
Note
DD_DvzAerSnow_Luo
is only used when the Luo et al. [2020] wet scavenging scheme is activated.
-
DD_DvzMinVal
¶
Specfies minimum dry deposition velocities (\(cm\ s^{-1}\)) for sulfate species (
SO2
,SO4
,MSA
,NH3
,NH4
,NIT
). This follows the methodology of the GOCART model.DD_DvzMinVal
is defined as a two-element vector:DD_DvzMinVal(1)
sets a minimum dry deposition velocity onto snow and ice.DD_DvzMinVal(2)
sets a minimum dry deposition velocity over land.
-
DD_Hstar_Old
¶
Specifies the Henry’s law constant (\(K_0\)) that is used in dry deposition. This will be used to assign the
HSTAR
variable in the GEOS-Chem dry deposition module.Note
The value of the
DD_Hstar_old
parameter was tuned for each species so that the dry deposition velocity would match observations.
-
DD_F0
¶
Specifies the reactivity factor for oxidation of biological substances in dry deposition.
-
DD_KOA
¶
Specifies the octanal-air partition coefficient, used for the dry deposition of species
POPG
.Note
DD_KOA
is only used in the POPs simulation.
Wet deposition properties¶
-
WD_Is_H2SO4
¶
Indicates that the species is
H2SO4
(true
), or isn’t (false)
. This allows the wet deposition code to perform special calculations when computingH2SO4
rainout and washout.
-
WD_Is_HNO3
¶
Indicates that the species is
HNO3
(true
), or isn’t (false)
. This allows the wet deposition code to perform special calculations when computingHNO3
. rainout and washout.
-
WD_Is_SO2
¶
Indicates that the species is
SO2
(true
), or isn’t (false)
. This allows the wet deposition code to perform special calculations when computingSO2
rainout and washout.
-
WD_CoarseAer
¶
Indicates that the species is a coarse aerosol (
true
), or isn’t (false
). For wet deposition purposes, the definition of coarse aerosol is radius > 1 \(\mu m\).
-
WD_LiqAndGas
¶
Indicates that the the ice-to-gas ratio can be computed for this species by co-condensation (
true
), or can’t (false
).
-
WD_ConvFacI2G
¶
Specifies the conversion factor (i.e. ratio of sticking coefficients on the ice surface) for computing the ice-to-gas ratio by co-condensation, as used in the default wet deposition scheme.
Note
WD_ConvFacI2G
only needs to be defined for those species for whichWD_LiqAndGas
istrue
.
-
WD_ConvFacI2G_Luo
¶
Specifies the conversion factor (i.e. ratio of sticking coefficients on the ice surface) for computing the ice-to-gas ratio by co-condensation, as used in the Luo et al. [2020] wet deposition scheme.
Note
WD_ConvFacI2G_Luo
only needs to be defined for those species for whichWD_LiqAndGas
istrue
, and is only used when the Luo et al. [2020] wet deposition scheme is activated.
-
WD_RetFactor
¶
Specifies the retention efficiency \(R_i\) of species in the liquid cloud condensate as it is converted to precipitation. \(R_i\) < 1 accounts for volatization during riming.
-
WD_AerScavEff
¶
Specifies the aerosol scavenging efficiency. This factor multiplies \(F\), the fraction of aerosol species that is lost to convective updraft scavenging.
WD_AerScavEff = 1.0
for most aerosols.WD_AerScavEff = 0.8
for secondary organic aerosols.WD_AerScavEff = 0.0
for hydrophobic aerosols.
-
WD_KcScaleFac
¶
Specifies a temperature-dependent scale factor that is used to multiply \(K\) (aka \(K_c\)), the rate constant for conversion of cloud condensate to precipitation.
WD_KcScaleFac
is defined as a 3-element vector:WD_KcScaleFac(1)
multiplies \(K\) when \(T < 237\) kelvin.WD_KcScaleFac(2)
multiplies \(K\) when \(237 \le T < 258\) kelvinWD_KcScaleFac(3)
multiplies \(K\) when \(T \ge 258\) kelvin.
-
WD_KcScaleFac_Luo
¶
Specifies a temperature-dependent scale factor that is used to multiply \(K\), aka \(K_c\), the rate constant for conversion of cloud condensate to precipitation.
Used only in the Luo et al. [2020] wet deposition scheme.
WD_KcScaleFac_Luo
is defined as a 3-element vector:WD_KcScaleFac_Luo(1)
multiplies \(K\) when \(T < 237\) kelvin.WD_KcScaleFac_Luo(2)
multiplies \(K\) when \(237 \le T < 258\) kelvin.WD_KcScaleFac_Luo(3)
multiplies \(K\) when \(T \ge 258\) kelvin.
-
WD_RainoutEff
¶
Specifies a temperature-dependent scale factor that is used to multiply \(F_i\) (aka
RAINFRAC
), the fraction of species scavenged by rainout.WD_RainoutEff
is defined as a 3-element vector:WD_RainoutEff(1)
multiplies \(F_i\) when \(T < 237\) kelvin.WD_RainoutEff(2)
multiplies \(F_i\) when \(237 \le T < 258\) kelvin.RainoutEff(3)
multiplies \(F_i\) when \(T \ge 258\) kelvin.
This allows us to better simulate scavenging by snow and impaction scavenging of BC. For most species, we need to be able to turn off rainout when \(237 \le T < 258\) kelvin. This can be easily done by setting
RainoutEff(2) = 0
.Note
For SOA species, the maximum value of
WD_RainoutEff
will be 0.8 instead of 1.0.
-
WD_RainoutEff_Luo
¶
Specifies a temperature-dependent scale factor that is used to multiply \(F_i\) (aka
RAINFRAC
), the fraction of species scavenged by rainout. (Used only in the [Luo et al., 2020] wet deposition scheme).WD_RainoutEff_Luo
is defined as a 3-element vector:WD_RainoutEff_Luo(1)
multiplies \(F_i\) when \(T < 237\) kelvin.WD_RainoutEff_Luo(2)
multiplies \(F_i\) when \(237 \le T < 258\) kelvin.RainoutEff_Luo(3)
multiplies \(F_i\) when \(T \ge 258\) kelvin.
This allows us to better simulate scavenging by snow and impaction scavenging of BC. For most species, we need to be able to turn off rainout when \(237 \le T < 258\) kelvin. This can be easily done by setting
RainoutEff(2) = 0
.Note
For SOA species, the maximum value of
WD_RainoutEff_Luo
will be 0.8 instead of 1.0.
Transport tracer properties¶
These properties are defined for species used in the TransportTracers simulation. We will refer to these species as tracers.
-
Is_Tracer
¶
Indicates that the species is a transport tracer (
true
), or is not (false
).
-
Snk_Horiz
¶
Specifies the horizontal domain of the tracer sink term. Allowable values are:
-
all
¶
The tracer sink term will be applied throughout the entire horizonatal domain of the simulation grid.
-
-
Snk_Lats
¶
Defines the latitude range
[min_latitude, max_latitude]
for the tracer sink term. Will only be used ifSnk_Horiz
is set tolat_zone
.
-
Snk_Mode
¶
Specifies how the tracer sink term will be applied. Allowable values are:
-
efolding
¶
The tracer sink term has an e-folding decay constant (specified in
Snk_Period
).
-
halflife
¶
A tracer sink term has a half-life (specified in
Snk_Period
).
-
none
¶
The tracer does not have a sink term.
-
-
Snk_Period
¶
Specifies the period (in days) for which the tracer sink term will be applied.
-
Snk_Value
¶
Specifies a value for the tracer sink term.
-
Snk_Vert
¶
Specifies the vertical domain of the tracer sink term. Allowable values are:
-
all
¶
The tracer sink term will be applied throughout the entire vertical domain of the simulation grid.
-
boundary_layer
¶
The tracer sink term will only be applied within the planetary boundary layer.
-
surface
¶
The tracer sink term will only be applied at the surface.
-
troposphere
¶
The tracer sink term will only be applied within the troposphere.
-
-
Src_Add
¶
Specifies whether the tracer has a source term (
true
) or not (false
).
-
Src_Horiz
¶
Specifies the horizontal domain of the tracer source term. Allowable values are:
-
all
¶
The tracer source term will be applied across the entire horizontal extent of the simulation grid.
-
-
Src_Lats
¶
Defines the latitude range
[min_latitude, max_latitude]
for the tracer source term. Will only be applied ifSrc_Horiz
is set tolat_zone
.
-
Src_Mode
¶
Describes the type of tracer source term. Allowable values are:
-
decay_of_another_species
¶
The tracer source term comes from the decay of another species (e.g. Pb210 source comes from Rn222 decay).
-
HEMCO
¶
The tracer source term will be read from a file via HEMCO.
-
maintain_mixing_ratio
¶
The tracer source term will be calculated as needed to maintain a constant mixing ratio at the surface.
-
none
¶
The tracer does not have a source term.
-
-
Src_Unit
¶
Specifies the unit of the source term that will be applied to the tracer.
-
ppbv
¶
The source term has units of parts per billion by volume.
-
timestep
¶
The source term has units of per emissions timestep.
-
-
Src_Value
¶
Specifies a value for the tracer source term in
Src_Units
.
-
Src_Vert
¶
Specifies the vertical domain of the tracer source term. Allowable values are:
-
all
¶
The tracer source term will be applied throughout the entire vertical domain of the simulation grid.
-
pressures
¶
The tracer source term will only be applied within the pressure range specified in
Src_Pressures
.
-
stratosphere
¶
The tracer source term will only be applied in the stratosphere.
-
troposphere
¶
The tracer source term will only be applied in the troposphere.
-
surface
¶
The tracer source term will only be applied at the surface.
-
-
Src_Pressures
¶
Defines the pressure range
[min_pressure, max_pressure]
, in hPa for the tracer source term. Will only be used ifSrc_Vert
is set topressures
.
-
Units
¶
Specifies the default units of the tracers (e.g.
aoa
,aoa_nh
,aoa_bl
are carried in unitsdays
, while all other species in GEOS-Chem arekg/kg dry air
).
Properties used by each transport tracer¶
The list below shows the various transport tracer properties that are used in the current TransportTracers simulation.
Is_Tracer
- true : all
Snk_Horiz:
- lat_zone : aoa_nh
- all : all others
Snk_Lats
- 30 50 : aoa_nh
Snk_Mode
- constant : aoa, aoa_bl, aoa_nh
- efolding : CH3I, CO_25
- none : SF6
- halflife : Be7, Be7s, Be10, Be10s
Snk_Period (days)
- 5 : CH3I
- 25 : CO_25
- 50 : CO_50
- 90 : e90, e90_n, e90_s
- 11742.8 : Pb210, Pb210s
- 5.5 : Rn222
- 53.3 : Be7, Be7s
- 5.84e8 : Be10, Be10s
Snk_Value
- 0 : aoa, aoa_bl, aoa_nh
Snk_Vert
- boundary_layer : aoa_bl
- surface : aoa, aoa_nh
- troposphere : stOx
- all : all others
Src_Add
- false : Passive, stOx, st80_25
- true : all others
Src_Horiz
- lat_zone : e90_n, e90_s, nh_5, nh_50
- all : all others
Src_Lats
- [ 40.0, 91.0] : e90_n
- [-91.0, -40.0] : e90_s
- [ 30.0, 50.0] : nh_5, nh_50
Src_Mode
- constant : aoa, aoa_bl, aoa_nh, nh_50, nh_5, st80_25
- file2d : CH3I, CO_25, CO_50, Rn222, SF6 - HEMCO
- file3d : Be10, Be7 - HEMCO
- maintain_mixing_ratio : e_90, e90_n, e90_s
- decay_of_another_species : Pb210, Pb210s
Src_Unit
- ppbv : e90, e90_n, e90_s, st80_25
- timestep : aoa, aoa_bl, aoa_nh
Src_Value
- 1 : aoa, aoa_bl, aoa_nh
- 100 : e90, e90_n, e90_s
- 200 : st80_25
Src_Vert
- all : aoa, aoa_bl, aoa_nh, Pb210
- pressures : st80_25
- stratosphere : Be10s, Be7s, Pb210s, stOx
- surface : all others (not specified when Src_Mode: HEMCO)
Src_Pressures
- [0, 80] : st80_25
Units
- days : aoa, aoa_bl, aoa_bl
Other properties¶
-
BackgroundVV
¶
If a restart file does not contain an global initial concentration field for a species, GEOS-Chem will attempt to set the initial concentration (in \(vol\ vol^{-1}\) dry air) to the value specified in
BackgroundVV
globally. But ifBackgroundVV
has not been specified, GEOS-Chem will set the initial concentration for the species to \(10^{-20} vol\ vol^{-1}\) dry air instead.Note
Recent versions of GCHP may require that all initial conditions for all species to be used in a simulation be present in the restart file. See gchp.readthedocs.io for more information.
Access species properties in GEOS-Chem¶
In this section we will describe the derived types and objects that are used to store GEOS-Chem species properties. We will also describe how you can extract species properties from the GEOS-Chem Species Database when you create new GEOS-Chem code routines.
The Species derived type¶
The Species
derived type (defined in module Headers/species_mod.F90
)
describes a complete set of properties for a single GEOS-Chem
species. In addition to the fields mentioned in the preceding sections, the
Species
derived type also contains several species indices.
Index |
Description |
---|---|
|
Model species index |
|
Advected species index |
|
Aerosol species index |
|
Dry dep species at altitude Id |
|
Dry deposition species index |
|
Gas-phase species index |
|
Hygroscopic growth species index |
|
KPP variable species index |
|
KPP fixed spcecies index |
|
KPP species index |
|
Photolyis species index |
|
Radionuclide index |
|
Transport tracer index |
|
Wet deposition index |
The SpcPtr derived type¶
The SpcPtr
derived type (also defined in Headers/species_mod.F90
)
describes a container for an object of type Species.
TYPE, PUBLIC :: SpcPtr
TYPE(Species), POINTER :: Info ! Single entry of Species Database
END TYPE SpcPtr
The GEOS-Chem Species Database object¶
The GEOS-Chem Species database is stored in the
State_Chm%SpcData
object. It describes an array, where each
element of the array is of type SpcPtr (which is a container for an object of type
type Species.
TYPE(SpcPtr), POINTER :: SpcData(:) ! GC Species database
Species index lookup with Ind_()¶
Use function Ind_()
(in module
Headers/state_chm_mod.F90
) to look up species indices by
name. For example:
SUBROUTINE MySub( ..., State_Chm, ... )
USE State_Chm_Mod, ONLY : Ind_
! Local variables
INTEGER :: id_O3, id_Br2, id_CO
! Find tracer indices with function the Ind_() function
id_O3 = Ind_( 'O3' )
id_Br2 = Ind_( 'Br2' )
id_CO = Ind_( 'CO' )
! Print tracer concentrations
print*, 'O3 at (23,34,1) : ', State_Chm%Species(id_O3 )%Conc(23,34,1)
print*, 'Br2 at (23,34,1) : ', State_Chm%Species(id_Br2)%Conc(23,34,1)
print*, 'CO at (23,34,1) : ', State_Chm%Species(id_CO )%Conc(23,34,1)
! Print the molecular weight of O3 (obtained from the Species Database object)
print*, 'Mol wt of O3 [g]: ', State_Chm%SpcData(id_O3)%Info%MW_g
END SUBROUTINE MySub
Once you have obtained the species ID (aka ModelId
) you can
use that to access the individual fields in the Species Database
object. In the example above, we use the species ID for O3
(stored in
id_O3
) to look up the molecular weight of O3
from
the Species Database.
You may search for other model indices with Ind_()
by passing
an optional second argument:
! Position of HNO3 in the list of advected species
AdvectId = Ind_( 'HNO3', 'A' )
! Position of HNO3 in the list of gas-phase species
AdvectId = Ind_( 'HNO3', 'G' )
! Position of HNO3 in the list of dry deposited species
DryDepId = Ind_( 'HNO3', 'D' )
! Position of HNO3 in the list of wet deposited species
WetDepId = Ind_( 'HNO3', 'W' )
! Position of HNO3 in the lists of fixed KPP, active, & overall KPP species
KppFixId = Ind_( 'HNO3', 'F' )
KppVarId = Ind_( 'HNO3', 'V' )
KppVarId = Ind_( 'HNO3', 'K' )
! Position of SALA in the list of hygroscopic growth species
HygGthId = Ind_( 'SALA', 'H' )
! Position of Pb210 in the list of radionuclide species
HygGthId = Ind_( 'Pb210', 'N' )
! Position of ACET in the list of photolysis species
PhotolId = Ind( 'ACET', 'P' )
Ind_()
will return -1 if a species does not belong to any of
the above lists.
Tip
For maximum efficiency, we recommend that you use Ind_()
to obtain the species indices during the initialization phase of a
GEOS-Chem simulation. This will minimize the number of
name-to-index lookup operations that need to be performed, thus
reducing computational overhead.
Implementing the tip mentioned above:
MODULE MyModule
IMPLICIT NONE
. . .
! Species ID of CO. All subroutines in MyModule can refer to id_CO.
INTEGER, PRIVATE :: id_CO
CONTAINS
. . . other subroutines . . .
SUBROUTINE Init_MyModule
! This subroutine only gets called at startup
. . .
! Store ModelId in the global id_CO variable
id_CO = Ind_('CO')
. . .
END SUBROUTINE Init_MyModule
END MODULE MyModule
Species lookup within a loop¶
If you need to access species properties from within a loop, it is
better not to use the Ind_()
function, as repeated
name-to-index lookups will incur computational overhead. Instead, you
can access the species properties directly from the GEOS-Chem Species
Database object, as shown here.
SUBROUTINE MySub( ..., State_Chm, ... )
!%%% MySub is an example of species lookup within a loop %%%
! Uses
USE Precision_Mod
USE State_Chm_Mod, ONLY : ChmState
USE Species_Mod, ONLY : Species
! Chemistry state object (which also holds the species database)
TYPE(ChmState), INTENT(INOUT) :: State_Chm
! Local variables
INTEGER :: N
TYPE(Species), POINTER :: ThisSpc
INTEGER :: ModelId, DryDepId, WetDepId
REAL(fp) :: Mw_g
REAL(f8) :: Henry_K0, Henry_CR, Henry_pKa
! Loop over all species
DO N = 1, State_Chm%nSpecies
! Point to the species database entry for this species
! (this makes the coding simpler)
ThisSpc => State_Chm%SpcData(N)%Info
! Get species properties
ModelId = ThisSpc%ModelId
DryDepId = ThisSpc%DryDepId
WetDepId = ThisSpc%WetDepId
MW_g = ThisSpc%MW_g
Henry_K0 = ThisSpc%Henry_K0
Henry_CR = ThisSpc%Henry_CR
Henry_pKa = ThisSpc%Henry_pKA
IF ( ThisSpc%Is_Gas )
! ... The species is a gas-phase species
! ... so do something appropriate
ELSE
! ... The species is an aerosol
! ... so do something else appropriate
ENDIF
IF ( ThisSpc%Is_Advected ) THEN
! ... The species is advected
! ... (i.e. undergoes transport, PBL mixing, cloud convection)
ENDIF
IF ( ThisSpc%Is_DryDep ) THEN
! ... The species is dry deposited
ENDIF
IF ( ThisSpc%Is_WetDep ) THEN
! ... The species is soluble and wet deposits
! ... it is also scavenged in convective updrafts
! ... it probably has defined Henry's law properties
ENDIF
... etc ...
! Free the pointer
ThisSpc => NULL()
ENDDO
END SUBROUTINE MySub