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 species O3 and HNO3.

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 computing H2SO4 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 computing HNO3. 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 computing SO2 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 which WD_LiqAndGas is true.

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 which WD_LiqAndGas is true, 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$$ kelvin

• WD_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 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 if BackgroundVV 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.

MP_SizeResAer

Indicates that the species is a size-resolved aerosol species (true), or isn’t (false). Used only by simulations using either APM or TOMAS microphysics packages.

MP_SizeResNum

Indicates that the species is a size-resolved aerosol number (true), or isn’t (false). Used only by simulations using either APM or TOMAS microphysics packages.

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.

Indices stored in the Species derived type

Index

Description

ModelId

Model species index

AdvectId

AerosolId

Aerosol species index

DryAltId

Dry dep species at altitude Id

DryDepId

Dry deposition species index

GasSpcId

Gas-phase species index

HygGrthId

Hygroscopic growth species index

KppVarId

KPP variable species index

KppFixId

KPP fixed spcecies index

KppSpcId

KPP species index

PhotolId

Photolyis species index

RadNuclId

WetDepId

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