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

lat_zone¶: The tracer sink term will be applied only within the latitude range specified by Snk_Lats.

Snk_Lats¶: Defines the latitude range [min_latitude, max_latitude] for the tracer sink term. Will only be used if Snk_Horiz is set to lat_zone.

Snk_Mode¶

Specifies how the tracer sink term will be applied. Allowable values are:

constant¶: The tracer sink term is a constant value (specified by Snk_Value).

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.

lat_zone¶: The tracer source term will only be applied within the latitude range specified by Src_Lats.

Src_Lats¶: Defines the latitude range [min_latitude, max_latitude] for the tracer source term. Will only be applied if Src_Horiz is set to lat_zone.

Src_Mode¶

Describes the type of tracer source term. Allowable values are:

constant¶: The tracer source term is a constant value (specified by Src_Value).

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 if Src_Vert is set to pressures.

Units¶: Specifies the default units of the tracers (e.g. aoa, aoa_nh, aoa_bl are carried in units days, while all other species in GEOS-Chem are kg/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 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`	Advected species index
`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`	Radionuclide index
`TracerId`	Transport tracer index
`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