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