Difference between revisions of "GEOS-Chem species database"

From Geos-chem
Jump to: navigation, search
(→‎Adding new species to the GEOS-Chem species database (in 12.9.0 and later))
(→‎GEOS-Chem v11-01 and later versions)
Line 89: Line 89:
 
Furthermore, having all of the physical properties for GEOS-Chem species defined in a single location makes GEOS-Chem much more robust.  During the process of implementing the species database, [[Physical_properties_of_GEOS-Chem_species#Discrepancies_found_in_the_dry_deposition_module|we found that some physical properties (e.g. molecular weights) were being defined differently in dry deposition than in other areas of the code]]. This is a legacy of the dry deposition module being developed independently from other modules.
 
Furthermore, having all of the physical properties for GEOS-Chem species defined in a single location makes GEOS-Chem much more robust.  During the process of implementing the species database, [[Physical_properties_of_GEOS-Chem_species#Discrepancies_found_in_the_dry_deposition_module|we found that some physical properties (e.g. molecular weights) were being defined differently in dry deposition than in other areas of the code]]. This is a legacy of the dry deposition module being developed independently from other modules.
  
−
The species database was introduced in [[GEOS-Chem v11-01#v11-01d|GEOS-Chem v11-01d]] and extended in [[GEOS-Chem v11-01#v11-01e|v11-01e]] It will be included in the [[GEOS-Chem v11-01]] public release.  The table below shows the various stages of implementation:
+
The species database was introduced in [[GEOS-Chem v11-01#v11-01d|GEOS-Chem v11-01d]] and extended in [[GEOS-Chem v11-01#v11-01e|v11-01e]] It will be included in the [[GEOS-Chem v11-01]] public release.   
−
 
+
−
{| border=1 cellspacing=0 cellpadding=5
+
−
 
+
−
|-valign="top" bgcolor="#CCCCCC"
+
−
!width="65px"|Version
+
−
!width="800px"|Description
+
−
!width="200px"|Status
+
−
 
+
−
|-valign="top"
+
−
|[[GEOS-Chem v11-01#v11-01d|v11-01d]]
+
−
|Phase 1: Initial implementation
+
−
*Define species database object as a sub-object of the [[Derived_type_objects_used_by_GEOS-Chem#The_Chemistry_State_object|Chemistry State object]]
+
−
*Use the same values for molecular weights, Henry's law constants, drydep and wetdep properties as in [[GEOS-Chem v11-01#v11-01c|v11-01c]]
+
−
*Pass of consistent values of physical properties to [[Dry deposition|dry deposition]], [[Wet deposition|wet deposition]], and [[HEMCO|HEMCO emisisons component]]
+
−
*Removal of redundant and confusing code in the following routines:
+
−
**<tt>INIT_DRYDEP, INIT_WETDEP, WETDEPID, COMPUTE_F, RAINOUT, WASHOUT</tt>
+
−
|
+
−
*Approved 12 Dec 2015
+
−
 
+
−
|-valign="top"
+
−
|[[GEOS-Chem v11-01#v11-01e|v11-01e]]
+
−
|Phase 2a: Standardization
+
−
*[[Physical_properties_of_GEOS-Chem_species#Discrepancies_found_in_the_dry_deposition_module|Remove inconsistencies in the definitions of physical properties of GEOS-Chem species]];
+
−
*[[Sea_salt_aerosols#Molecular_weight_discrepancy_in_drydep_mod.F|Use proper molecular weights for sea salt aerosols in the dry deposition module]]; and
+
−
*[[Sulfate_aerosols#Give_SO4s_and_NITs_the_same_molecular_weight_as_SALC|Give SO4s and NITs the same molecular weight as SALC]].
+
−
*[[GEOS-Chem_species_database#Defining_molecular_weight_fields_of_the_Input_Opt_object_from_the_species_database|Define molecular weight fields of the <tt>Input_Opt</tt> object from the GEOS-Chem species database]]
+
−
|
+
−
*Approved 04 Jan 2016
+
−
 
+
−
|-valign="top"
+
−
|[[GEOS-Chem v11-01#v11-01e|v11-01e]]
+
−
|Phase 2b: Standardization
+
−
*[[Wet_deposition#Now_use_the_same_Henry.27s_law_functions_that_are_used_in_HEMCO|Update the wetdep module to use the same Henry's law functions as are used in HEMCO, for consistency's sake]]
+
−
|
+
−
*Approved 04 Jan 2016
+
−
 
+
−
|-valign="top"
+
−
|TBD
+
−
|Phase 3: Updating values
+
−
*Update the Henry's law constants to the most recent values from the literature (cf. Sander 2015), based on input from the appropriate GEOS-Chem Working Groups
+
−
|
+
−
*Will commence once [[FlexChem]] is implemented
+
−
 
+
−
|}
+
  
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:07, 6 May 2016 (UTC)
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:07, 6 May 2016 (UTC)

Revision as of 17:45, 23 November 2021

Previous | Next | Guide to species in GEOS-Chem

  1. Species in GEOS-Chem
  2. Physical properties of GEOS-Chem species
  3. GEOS-Chem species database
  4. GEOS-Chem species units
  5. Adding passive species to GEOS-Chem
  6. Species indexing in GEOS-Chem


Overview

On this page we describe the GEOS-Chem species database object. This object stores physical properties (e.g. molecular weights, densities, Henry's law constants, etc.) for GEOS-Chem species in a single location.

The following sections describe how we specify physical properties for GEOS-Chem species prior to and after the introduction of the species database.

GEOS-Chem v10-01 and prior versions

In GEOS-Chem v10-01 and prior versions, physical properties for GEOS-Chem species were defined in many different locations, as shown in the table below:

Property Units Where defined Description
TRACER_MW_G g -1 input.geos file Emitted species molecular weight (i.e. the molecular weight of the emitted species, if there is more than one species per tracer).
TRACER_COEFF g -1 GeosCore/tracerid_mod.F file Number of carbon atoms per species (for hydrocarbons that are carried as equivalent carbon atoms)
Dry deposition properties
A_RADI m INIT_DRYDEP (in GeosCore/drydep_mod.F) Aerosol radius used in dry deposition
A_DEN kg m-3 INIT_DRYDEP (in GeosCore/drydep_mod.F Aerosol density used in dry deposition
NDVZIND m INIT_DRYDEP (in GeosCore/drydep_mod.F) Dry deposition species ID (i.e. slot of the DVEL array)
HSTAR M atm-1 INIT_DRYDEP (in GeosCore/drydep_mod.F) Henry's law K0 used in dry deposition
F0 1 INIT_DRYDEP (in GeosCore/drydep_mod.F) Reactivity factor for oxidation of biological substances
XMW kg mol-1 INIT_DRYDEP (in GeosCore/drydep_mod.F) Species molecular weight
Wet deposition properties
IDWETD 1 INIT_WETSCAV (in GeosCore/wetscav_mod.F) Wet deposition ID
Kstar298
aka K0 		M atm-1 COMPUTE_F and RAINOUT
(both in GeosCore/wetscav_mod.F) 		Henry's law solubility constant
H298_R
aka CR 		K COMPUTE_F and RAINOUT
(both in GeosCore/wetscav_mod.F) 		Henry's law volatility constant


Furthermore, in the wet deposition module (GeosCore/wetscav_mod.F several confusing IF-THEN-ELSE-ENDIF blocks were used to perform species-specific computations, including:

  • Multiplying the fraction Fi (Eq. 1, Jacob et al 2000) by 0.8 for SOA aerosol species
  • Turning off rainout for several aerosol species when 237 <= T < 258 K
  • Halving the rate of conversion of cloud condensate to precipitation (aka K or Kc, Eq. 1 of Jacob et al 2000) for certain species.
  • Computing rainout fractions for gases vs. aerosols
  • Computing washout fractions for gases vs. coarse aerosols vs. fine aerosols

As we move towards the high-performance GEOS-Chem, we wanted to try to avoid such species-specific settings deep into the dry deposition and wet deposition modules.

--Bob Y. (talk) 16:36, 20 October 2015 (UTC)

GEOS-Chem v11-01 and later versions

We decided to create a data structure—the GEOS-Chem species database— that could hold the various species-specific physical properties that are used throughout GEOS-Chem. The species database is populated at GEOS-Chem startup, and it is used to pass the consistent physical properties to the dry deposition module, wet deposition module, HEMCO emissions module, and chemistry solver. This allows us to replace much of the confusing legacy IF-THEN-ELSE-ENDIF code structure with one that uses much less IF tests.

Furthermore, having all of the physical properties for GEOS-Chem species defined in a single location makes GEOS-Chem much more robust. During the process of implementing the species database, we found that some physical properties (e.g. molecular weights) were being defined differently in dry deposition than in other areas of the code. This is a legacy of the dry deposition module being developed independently from other modules.

The species database was introduced in GEOS-Chem v11-01d and extended in v11-01e It will be included in the GEOS-Chem v11-01 public release.

--Bob Yantosca (talk) 16:07, 6 May 2016 (UTC)

The SPECIES derived type

The Species derived type allows you to specify physical properties for a single GEOS-Chem species. The type declaration is contained in GEOS-Chem module Headers/species_mod.F90. The tables below define the physical parameters that are contained in the Species type, subdivided by category.

ID numbers, names, etc.

Please also see our our Species indexing in GEOS-Chem wiki page for more information on how you can get the species index information from the Species Database.

Quantity Type Units Description
ModelID INTEGER 1 Species ID
AdvectID INTEGER 1 Advected species ID
DryDepID INTEGER 1 Dry deposition species ID
WetDepID INTEGER 1 Wet deposition species ID
KppVarId INTEGER 1 KPP variable species ID (i.e. index for the KPP VAR array)
KppFixId INTEGER 1 KPP variable species ID (i.e. index for the KPP FIX array)
Name CHARACTER(31) N/A Short species name
FullName CHARACTER(80) N/A Long species name
  • FullName can be used for the netCDF long_name and/or standard_name variable attributes.
NameHash INTEGER N/A Unique integer hash value that corresponds to the Name field
  • NOTE: This number can be positive OR negative.
Is_Gas LOGICAL 1 Gas or aerosol flag
  • If TRUE, the species is gas.
  • If FALSE, the species is an aerosol.
Is_Advected LOGICAL 1 If TRUE, the species undergoes the following operations:
Is_DryDep LOGICAL 1 If TRUE, the species dry deposits.
Is_WetDep LOGICAL 1 If TRUE, the species is soluble and wet deposits.

--Bob Yantosca (talk) 14:47, 27 June 2016 (UTC)

Molecular weight, density, radius

Quantity Type Units Description
MW_g REAL(fp) g mol-1 Molecular weight of the species
EmMW_g REAL(fp) g mol-1 Emitted molecular weight of the species
  • Several GEOS-Chem hydrocarbon species are emitted and transported as equivalent C atoms.
  • For these hydrocarbon species, set EmMW_g = 12.0 (molecular weight of 1 carbon atom).
Density REAL(fp) kg m-3 Density of the species
Radius REAL(fp) m Radius of the species

--Bob Yantosca (talk) 17:02, 23 November 2021 (UTC)

Henry's law constants

Please also see our list of Henry's law constants for GEOS-Chem species on our Physical properties of GEOS_Chem species wiki page.

Quantity Type Units Description
Henry_K0 REAL(f8) M atm-1 Henry's law solubility constant
Henry_CR REAL(f8) K Henry's law volatility constant
Henry_pKa REAL(f8) 1 Henry's law pH correction factor

--Bob Y. (talk) 19:12, 9 October 2015 (UTC)

Dry deposition parameters

Please also see our list of dry deposition parameters for GEOS-Chem species on our Physical properties of GEOS_Chem species wiki page.

Quantity Type Units Description
DD_AeroDryDep LOGICAL 1 For sea salt species, set this to TRUE. This will use dry deposition routine AERO_SFCRSII to perform aerodynamic dry deposition accounting for hygroscopic growth.
DD_DustDryDep LOGICAL 1 For mineral dust species, set this to TRUE. This will use dry deposition routine DUST_SFCRSII to perform aerodynamic dry deposition omitting hygroscopic growth.
DD_DvzAerSnow REAL(fp) cm/s For certain aerosol species, DD_DvzAerSnow specifies the dry deposition velocity over ice and snow. This usually 0.03 cm/s.
DD_DvzMinVal REAL(fp) cm/s A 2-element vector that specifies the minimum dry deposition velocity for sulfate species SO2, SO4, MSA, NH3, NH4, NIT. This follows the methodology of the GOCART model).
  • DD_DvzMinVal(1): Specifies minimum drydep velocity over snow/ice
  • DD_DvzMinVal(2): Specifies minimum drydep velocity over land
DD_Hstar_old REAL(fp) M atm-1 Specifies the Henry's law K0 constant that is used in dry deposition. This is saved in the HSTAR variable in the GEOS-Chem dry deposition module GeosCore/drydep_mod.F.
  • NOTE: We will eventually replace DD_Hstar_old this with the common Henry's law parameters (i.e. Henry_K0, Henry_CR, Henry_pKa.) But in order to replicate the behavior of the previous version of GEOS-Chem during testing, we need to supply the dry deposition code with the same HSTAR values that are currently set in INIT_DRYDEP. Therefore, we have added DD_Hstar_old as a temporary placeholder for the HSTAR quantity from drydep_mod.F. We will remove this later on.
DD_F0 REAL(fp) 1 Reactivity factor for oxidation of biological substances
DD_KOA REAL(fp) 1 Octanol-air partition coefficient, used for the POPG tracer in Persistant Organic Pollutant (POPs) specialty simulations.

--Bob Y. (talk) 19:13, 9 October 2015 (UTC)

Wet deposition parameters

Please also see our list of wet deposition parameters for GEOS-Chem species on our Physical properties of GEOS_Chem species wiki page.

Quantity Type Units Description
WD_Is_HNO3 LOGICAL 1 Flag to determine if the species is HNO3.
  • Rainout/washout of HNO3 needs to be handled separately from other gas-phase species.
  • WD_Is_HNO3 will be automatically determined, depending on the value of Name.
WD_Is_SO2 LOGICAL 1 Flag to determine if the species is SO2.
  • Rainout/washout of HNO3 separately from other gas-phase species.
  • WD_Is_SO2 will be automatically determined, depending on the value of Name.
WD_Is_H2SO4 LOGICAL 1 Flag to determine if the species is H2SO4.
  • Rainout/washout of H2SO4 needs to be handled separately from other gas-phase species.
  • WD_Is_H2SO4 will be automatically determined, depending on the value of Name.
  • H2SO4 is a species in TOMAS aerosol microphysics only.
WD_CoarseAer LOGICAL 1 Set this flag to indicate that the species is a coarse aerosol (i.e. having a radius > 1 μm)
  • Washout of coarse aerosols is handled separately from the washout of fine aerosols.
WD_LiqAndGas LOGICAL 1 Set this flag to indicate that the ice-to-gas ratio needs to be computed for this species by co-condensation (cf. Eq. 9 of Jacob et al, 2000).
  • If TRUE, then the ice-to-gas ratio will be computed for this species.
    • Currently, CH2O and NH3 are the only species for which WD_LiqAndGas = TRUE.
  • If FALSE, the ice-to-gas ratio for this species will be set to zero.
WD_ConvFacI2G REAL(fp) 1 Specifies the conversion factor (i.e. the ratio of sticking coefficients on the ice surface) for computing the ice-to-gas-ratio by co-condensation (cf. Eq. 9 of Jacob et al, 2000).
  • WD_ConvFacI2G only needs to be specified for those species having WD_LiqAndGas = TRUE.
WD_RetFactor REAL(fp) 1 Specifies the retention efficiency Ri of tracer in the liquid cloud condensate as it is converted to precipitation. (Ri < 1 accounts for volatization during riming.) The retention factor is defined in Eq. 1 of Jacob et al, 2000.
WD_AerScavEff REAL(fp) 1 Specifies the aerosol scavenging efficiency. This factor multiplies F, the fraction of aerosol species that is lost to convective updraft scavenging (cf Eq. 2 of Jacob et al 2000).
  • For most aerosol species, WD_AerScavEff = 1.0.
  • For secondary organic aerosol species, WD_AerScavEff = 0.8.
  • For hydrophobic species (e.g. MOPO), WD_AerScavEff = 0.0.

WD_AerScavEff is applied in routine COMPUTE_F of GEOS-Chem module GeosCore/wetscav_mod.F.

WD_KcScaleFac REAL(fp) 1 Specifies a temperature-dependent scale factor that is used to multiply K (aka Kc), the rate constant for conversion of cloud condensate to precipitation (cf Eq. 1 of Jacob et al, 2000).

WD_KcScaleFac is defined as a 3-element vector, where:

  • WD_KcScaleFac(1) multiplies K when T < 237 K.
  • WD_KcScaleFac(2) multiplies K when 237 K <= T < 258 K.
  • WD_KcScaleFac(3) multiplies K when T >= 258K.

This allows us to better simulate scavenging by snow, where, for most species, we need to halve the K rate when 237 K <= T < 258 K. This can be easily done by setting the value KcScaleFac(2) = 0.5.

WD_KcScaleFac is applied in routine F_AEROSOL of GEOS_Chem module GeosCore/wetscav_mod.F.

WD_RainoutEff REAL(fp) 1 Specifies a temperature-dependent scale factor that is used to multiply Fi (aka RAINFRAC), the fraction of species scavenged by rainout (cf Eq. 1 of Jacob et al, 2000).

WD_RainoutEff is defined as a 3-element vector, where:

  • WD_RainoutEff(1) multiplies Fi when T < 237 K.
  • WD_RainoutEff(2) multiplies Fi when 237 K <= T < 258 K.
  • WD_RainoutEff(3) multiplies Fi when T >= 258K.

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 K <= T < 258 K. This can be easily done by setting RainoutEff(2) = 0.

WD_RainoutEff is applied in routine APPLY_RAINOUT_EFF of GEOS_Chem module GeosCore/wetscav_mod.F.

NOTE: For secondary organic aerosol species, the maximum value of WD_RainoutEff will be 0.8 instead of 1.0.

--Bob Y. (talk) 19:14, 9 October 2015 (UTC)

Microphysics parameters

Quantity Type Units Description
MP_SizeResAer LOGICAL 1 Set this flag to TRUE to indicate that the species is a size-resolved aerosol species (used in microphysics simulations).
MP_SizeResAer LOGICAL 1 Set this flag to TRUE to indicate that the species is a size-resolved aerosol number (used in microphysics simulations).

--Bob Y. (talk) 20:44, 9 October 2015 (UTC)

Tagged Hg index variables

Quantity Type Units Description
Is_Hg0 LOGICAL 1 Set this flag to TRUE to denote a total Hg0 regional tagged Hg0 species.
Is_Hg2 LOGICAL 1 Set this flag to TRUE to denote a total Hg2 regional tagged Hg2 species.
Is_HgP LOGICAL 1 Set this flag to TRUE to denote a total HgP regional tagged HgP species.
Hg_Cat LOGICAL 1 Indicates the tagged Hg category number (1..State_Chm%N_Hg_CATS)
Is_Hg0 LOGICAL 1 Set this flag to TRUE to denote a total Hg0 regional tagged Hg0 species.

--Bob Yantosca (talk) 16:05, 6 May 2016 (UTC)

Creating the GEOS-Chem species database object

The GEOS-Chem species database object is actually a vector, whose length is the same as the number of GEOS-Chem species that are defined for a given simulation. Each element of the vector is an object of type Species. The following sections describe how we create the GEOS-Chem species database object:

The SPCPTR derived type

The SpecPtr derived type (located in GEOS-Chem module Headers/species_mod.F90) lets you to create a pointer variable of type Species. 

 TYPE, PUBLIC :: SpcPtr
    TYPE(Species),     POINTER :: Info  ! Species type
 END TYPE SpcPtr

The GEOS-Chem species database object

We use the SpcPtr to create the GEOS-Chem species database as a sub-object of the State_Chm "Chemistry State" object. The State_Chm object is built according to the ChmState derived-type object: 

 !=========================================================================
 ! Derived type for Chemistry State
 !=========================================================================
 TYPE, PUBLIC :: ChmState

    ! Number of species
    INTEGER                    :: nSpecies             ! # of species
    INTEGER                    :: nAdvect              ! # of advected species
    INTEGER                    :: nDrydep              ! # of drydep species
    INTEGER                    :: nKppSpc              ! # of KPP chem species
    INTEGER                    :: nWetDep              ! # of wetdep species

    ! Mapping vectors to subset types of species
    INTEGER,           POINTER :: Map_Advect (:      ) ! Advected species ID's
    INTEGER,           POINTER :: Map_DryDep (:      ) ! Drydep species ID's
    INTEGER,           POINTER :: Map_KppSpc (:      ) ! KPP chem species ID's
    INTEGER,           POINTER :: Map_WetDep (:      ) ! Wetdep species IDs'

    ! Physical properties about tracers & species
    TYPE(SpcPtr),      POINTER :: SpcData(:)           ! Species database

    ... etc ...

 END TYPE ChmState

Therefore, the GEOS-Chem species database is referred to as State_Chm%SpcData.

Routine Init_Species_Database in GEOS-Chem module Headers/species_database_mod.F90 allocates the State_Chm%SpcData object and populates it with the relevant physical parameters for each GEOS-Chem species.

--Bob Yantosca (talk) 16:19, 20 March 2017 (UTC)

Obtaining information from the species database

To get the physical properties for a given species from the species database, you can use code such as: 

      DO N = 1, State_Chm%nSpecies

         ! Get Henry's law parameters
         K0  = State_Chm%SpcData(N)%Info%Henry_K0
         CR  = State_Chm%SpcData(N)%Info%Henry_CR
         pKA = State_Chm%SpcData(N)%Info%Henry_pKa

      ENDDO

Routine Init_Species_Database will also save the number of GEOS-Chem species as the variable State_Chm%nSpecies. So you can use that as the upper bound of DO loops.

To simplify the coding, you can create an object of type Species to point to each entry in the species database. For example this code 

      USE Species_Mod, ONLY : Species

      TYPE(Species), POINTER :: ThisSpc

      DO N = 1, State_Chm%nSpecies
         
         ThisSpc => State_Chm%SpcData(N)%Info

         ! Get Henry's law parameters
         K0  =  ThisSpc%Henry_K0
         CR  =  ThisSpc%Henry_CR
         pKA =  ThisSpc%Henry_pKa

         ThisSpc => NULL()      

      ENDDO


is much less wordy and easier to read.

--Bob Yantosca (talk) 18:42, 15 June 2016 (UTC)

Defining molecular weight fields of the Input_Opt object from the species database

This update was validated with the 1-month benchmark simulation v11-01e (approved 04 Jan 2016).

In GEOS-Chem v11-01d and prior versions, molecular weights for each emitted species (shown in RED) were specified in the input.geos file: 

%%% TRACER MENU %%%     : 
Type of simulation      : 3
Number of Tracers       : 119
Tracer Entries -------> : TR#   Name   g/mole   Tracer Members; () = emitted 
Tracer #1               :   1   NO       30.0   (NO)
Tracer #2               :   2   O3       48.0   (O3)
Tracer #3               :   3   PAN     121.0
Tracer #4               :   4   CO       28.0   (CO)

These molecular weights were then saved into the Input Options object field Input_Opt%TRACER_MW_G. They also initialized the related quantities Input_Opt%TRACER_MW_KG, Input_Opt%TCVV, and Input_Opt%XNUMOL.

Historically, other GEOS-Chem modules (especially dry deposition) had defined molecular weights as internal module variables. For some species, these locally-defined molecular weights conflicted with the molecular weights stored in the Input_Opt object. Some of these inconsistencies went undetected for several years.

To avoid further discrepancies like this, we modified GEOS-Chem v11-01e to pass molecular weight values from the species database to the relevant fields of Input_Opt. This ensures that a single molecular weight for each species will be used everywhere throughout GEOS-Chem.

The following code was added to routine INIT_GIGC_STATE_CHM (in module GeosCore/gigc_state_chm_mod.F90). Code lines in GREEN show where the emitted molecular weight for each species is passed from the species dataabase to the Input_Opt object. 

   !=======================================================================
   ! Now use the molecular weights from the species database and overwrite
   ! the molecular weight-related fields of the Input_Opt object.  Also
   ! echo to screen the TRACER MENU quantities that used to be printed
   ! in routine READ_INPUT_FILE (in GeosCore/input_mod.F).
   !=======================================================================
   IF ( am_I_Root ) THEN
      WRITE( 6,'(/,a)' ) 'TRACER MENU (==> denotes SMVGEAR emitted species)'
      WRITE( 6,'(  a)' ) REPEAT( '-', 48 )
      WRITE( 6,'(  a)' ) '  # Tracer          g/mole'
   ENDIF

   ! Loop over the number of tracers
   DO N = 1, Input_Opt%N_TRACERS

      ! Get emitted molecular weight from the species database
      EmMW_g                    = State_Chm%SpcData(N)%Info%EmMW_g

      ! Now use MW from the species database instead of from the
      ! input.geos file.  This eliminates discrepancies. (bmy, 12/16/15)
      Input_Opt%TRACER_MW_g(N)  = EmMW_g
      Input_Opt%TRACER_MW_kg(N) = EmMW_g * 1e-3_fp

      ! Ratio of MW dry air / MW tracer
      Input_Opt%TCVV(N)         = 28.97e+0_fp  / Input_Opt%TRACER_MW_G(N)

      ! Molecules tracer / kg tracer
      Input_Opt%XNUMOL(N)       = 6.022e+23_fp / Input_Opt%TRACER_MW_KG(N)

      ! Print to screen
      IF ( am_I_Root ) THEN

         ! Write tracer number, name, & mol wt
         WRITE( 6, 100 ) Input_Opt%ID_TRACER(N),              &
                         Input_Opt%TRACER_NAME(N),            &
                         Input_Opt%TRACER_MW_G(N)

         ! If a family tracer (or just a tracer w/ emission)
         ! then also print info about species
         IF ( Input_Opt%TRACER_N_CONST(N) > 1   .or.          &
              Input_Opt%ID_EMITTED(N) > 0     ) THEN

            ! Loop over member species
            DO C = 1, Input_Opt%TRACER_N_CONST(N)

               ! Also flag which is the emitted tracer
               IF ( Input_Opt%ID_EMITTED(N) == C ) THEN
                  WRITE( 6,110 ) Input_Opt%TRACER_COEFF(N,C), &
                                 Input_Opt%TRACER_CONST(N,C)
               ELSE
                  WRITE( 6,120 ) Input_Opt%TRACER_COEFF(N,C), &
                                 Input_Opt%TRACER_CONST(N,C)
               ENDIF
            ENDDO
         ENDIF
      ENDIF
   ENDDO

--Bob Yantosca (talk) 21:44, 16 December 2015 (UTC)

Adding new species to the GEOS-Chem species database (in 12.9.0 and later)

In GEOS-Chem 12.9.0 and later, the GEOS-Chem species database is stored in a YAML file that can be edited directly.

For the current GEOS-Chem species database, follow this link.

Adding new species to the GEOS-Chem species database (in 12.8.1 and prior)

You can define physical properties for GEOS-Chem species in routine Spc_Info (located in module Headers/species_database_mod.F90). Near the top of the routine you will see a loop over the number of species and a SELECT CASE statement, highlighted in RED below. 

!
! !DEFINED PARAMETERS
!
    LOGICAL,  PARAMETER :: T        = .TRUE.         ! Yes
    LOGICAL,  PARAMETER :: F        = .FALSE.        ! No
    . . .

    !=======================================================================
    ! Init_Species_Database begins here!
    !=======================================================================

    . . .

    ! Number of species
    nSpecies      = Input_Opt%N_TRACERS

    ! Initialize the species vector
    CALL SpcData_Init( am_I_Root, nSpecies, SpcData, RC )
    IF ( RC /= GIGC_SUCCESS ) THEN
       PRINT*, '### Could not initialize species vector!'
       CALL EXIT( -999 )
    ENDIF
    
    ! Loop over all species
    DO N = 1, nSpecies

       ! Translate species name to uppercase
       NameAllCaps = TRIM( Input_Opt%TRACER_NAME(N) )
       CALL TranUc( NameAllCaps )

       ! Test for species name
       SELECT CASE( TRIM ( NameAllCaps ) )
       
          CASE( 'ACET' ) 
             CALL Spc_Create( ... )

          CASE( 'ALD2' ) 
             CALL Spc_Create( ... )

       ... etc ...

In each CASE block, there is a call to the routine Spc_Create (contained in module Headers/species_mod.F90). The Spc_Create routine accepts species physical properties as optional arguments and passes them to the species database object. You can add new species to the database by adding more CASE blocks—with calls to Spc_Create—to the SELECT_CASE statement.

We shall provide a few examples below of how to define GEOS-Chem species with different properties. In our examples, we shall color-code groups of species properties as follows:

  • BROWN denotes species names
  • RED denotes species molecular weights, densities, and radii
  • ORANGE denotes the gas vs. aerosol flag
  • BLUE denotes dry deposition settings
  • GREEN denotes wet deposition settings
  • PURPLE denotes Henry's law constants

To simplify the coding, in all the examples below, we use the parameters T and F instead of having to type out the logical values .TRUE. and .FALSE.. A complete list of species physical properties may be found on our Physical properties of GEOS-Chem species wiki page.

--Bob Y. (talk) 19:44, 9 October 2015 (UTC)

Example 1: Add a species that is only advected

Several GEOS-Chem species are advected (i.e. they undergo transport, convection and PBL mixing) but do not dry-deposit or wet-deposit. Species of this type include the stratospherically-important bromine and chlorine species from the UCX chemistry mechanism.

To add a species of this type (such as carbon tetrachloride), call the Spc_Create routine with these settings: 

         CASE( 'CCL4' )
            CALL Spc_Create( am_I_Root     = am_I_Root,                    &
                             ThisSpc       = SpcData(N)%Info,              &
                             ModelID       = N,                            &
                             Name          = 'CCl4',                       &
                             FullName      = 'Carbon tetrachloride',       &
                             MW_g          = 152.0_fp,                     &
                             Is_Advected   = T,                            &
                             Is_Gas        = T,                            &
                             Is_Drydep     = F,                            &
                             Is_Wetdep     = F,                            &
                             RC            = RC )

NOTES:

  1. The name of the species in the CASE block should be in ALL CAPITALS. This makes the name search easier.
    • You can redefine the species name by passing a MIXED CASE string via the Name argument. This will preserve element names such as Br, Cl, etc.
    • Example: CASE( 'CCL4' ) but Name = 'CCl4'
  2. Most species parameters use the GEOS-Chem flexible precision (i.e. REAL(fp).)
    • Adding _fp to the end of a number signifies it is a constant of type REAL(fp).
  3. You don't have to specify all of the possible settings.
    • Settings that are omitted will be assigned a "missing data" value (-999 for numeric values, or .FALSE. for logical values), unless specified otherwise.
  4. If you omit EmMW_g (emitted molecular weight), it will be assigned the same value as MW_g (actual molecular weight).
  5. If you omit MolecRatio (carbon atoms per species), it will be assigned a default value of 1.0.
  6. Routine Spc_Create will automatically update the ModelID and AdvectID ID's for you.

--Bob Y. (talk) 14:39, 14 October 2015 (UTC)

Example 2: Add a gas-phase species that is advected, dry-deposited, and wet-deposited

Hydrogen peroxide is an example of a GEOS-Chem species that is advected, dry-deposited, and wet-deposited. It is defined with the following settings: 

         CASE( 'H2O2' )
            CALL Spc_Create( am_I_Root     = am_I_Root,                    &
                             ThisSpc       = SpcData(N)%Info,              &
                             ModelID       = N,                            &
                             Name          = NameAllCaps,                  &
                             FullName      = 'Hydrogen peroxide',          &
                             MW_g          = 34.0_fp,                      &
                             Is_Advected   = T,                            &
                             Is_Gas        = T,                            &
                             Is_Drydep     = T,                            &
                             Is_Wetdep     = T,                            &
                             DD_F0         = 1.0_fp,                       &                               
                             DD_Hstar_old  = 1e+5_fp,                      &
                             Henry_K0      = 8.30e+4_f8,                   &
                             Henry_CR      = 7400.0_f8,                    &
                             WD_RetFactor  = 5e-2_fp,                      &
                             WD_LiqAndGas  = T,                            &
                             WD_ConvFacI2G = 4.36564e-1_fp,                &
                             RC            = RC )

NOTES:

  1. Because H2O2 is not a hydrocarbon that is carried as equivalent carbons, we only have to specify the MW_g (actual molecular weight) setting.
    • The related properties EmMW_g and MolecRatio will be updated accordingly.
  2. H2O2 is an example of a species that had been using a different Henry's law K0 value for dry deposition than for wet deposition.
    • DD_Hstar_old sets the Henry's law K0 used for dry deposition
    • Henry_K0 sets the Henry's law K0 used in wet deposition
    • Eventually we will use the same K0 everywhere, but for now we need to retain the prior behavior of the code.
  3. H2O2 is also a species for which the ice to gas ratio is computed by co-condensation in the wet deposition module
    • WD_LiqAndGas is TRUE for H2O2.
    • WD_ConvFacI2G specifies the conversion factor (the ratio of sticking coefficients on the ice surface) as described in Eq. 9 of Jacob et al 2000.
    • For most other species, you can omit WD_LiqAndGas and WD_LiqAndGas, as the ice-to-gas ratio for most species is zero.
  4. The Henry's law parameters are defined as 8-byte floating point variables (REAL(f8)).
    • This provides better numerical stability, as several of the Henry's law computations involve exponentials.
    • Adding _f8 to the end of a number signifies it is a constant of type REAL(f8).
  5. All other settings that are omitted will be assigned a "missing data" value (-999 for numeric values, or .FALSE. for logical values),
  6. Routine Init_Species_Database will automatically update the ModelID, AdvectID, DryDepID, and WetDepID for you.

--Bob Y. (talk) 14:41, 14 October 2015 (UTC)

Example 3: Add an aerosol species that is advected, dry-deposited, and wet-deposited

NIT (inorganic nitrates) is part of the sulfate aerosol module in GEOS_Chem. It can serve as an example of how to define an aerosol species that is transported, dry-deposits, and wet-deposits. 

    ... these arrays are defined at the top of the Init_Species_Database routine ...

    ! Arrays
    REAL(fp)            :: DvzMinVal(2)
    REAL(fp)            :: KcScale(3)
    REAL(fp)            :: RainEff(3)

    ... and this is the case statement for NIT ...

         CASE( 'NIT' )

            ! Halve the Kc (cloud condensate -> precip) rate
            ! for the temperature range 237 K <= T < 258 K.
            KcScale = (/ 1.0_fp, 0.5_fp, 1.0_fp /)

            ! Turn off rainout only when 237 K <= T < 258K.
            RainEff = (/ 1.0_fp, 0.0_fp, 1.0_fp /)

            ! Enforce minimum dry deposition velocity (Vd) for NIT
            ! (cf. Mian Chin's GOCART model)
            ! Minimum Vd over snow/ice : 0.01 cm/s
            ! Minimum Vd over land     : 0.01 cm/s
            DvzMinVal = (/ 0.01_fp, 0.01_fp /)

            CALL Spc_Create( am_I_Root     = am_I_Root,                    &
                             ThisSpc       = SpcData(N)%Info,              &
                             ModelID       = N,                            &
                             Name          = NameAllCaps,                  &
                             FullName      = 'Inorganic nitrates',         &
                             MW_g          = 62.0_fp,                      &
                             Is_Advected   = T,                            &
                             Is_Gas        = F,                            &
                             Is_Drydep     = T,                            &
                             Is_Wetdep     = T,                            &
                             DD_DvzAerSnow = 0.03_fp,                      &
                             DD_DvzMinVal  = DvzMinVal,                    &
                             DD_F0         = 0.0_fp,                       &
                             DD_Hstar_Old  = 0.0_fp,                       &
                             WD_AerScavEff = 1.0_fp,                       &
                             WD_KcScaleFac = KcScale,                      &
                             WD_RainoutEff = RainEff,                      &
                             RC            = RC )

NOTES:

  1. We denote that this species is an aerosol with Is_Gas = F.
  2. Drydep parameters DD_F0 and DD_Hstar_Old only apply to gas-phase species, so we can set them to zero.
    • This will ensure that the dry deposition module will not get "missing data" values (-999 for these parameters.
  3. On ice and snow surfaces, we manually set the dry deposition velocity of NIT to 0.03 cm/s. This is specified with the DD_DvzAerSnow setting.
  4. Following the methodology of the GOCART model, we use the DD_DvzMinVal vector to specify a minimum dry deposition velocity over snow/ice vs. land.
  5. The WD_KcScaleFac vector allows us to halve the rate of conversion of cloud condensate to precipitation in the temperature range 237 <= T < 258 K.
    • This algorithm (cf. Qiaoqiao Wang) better simulates scavenging of aerosol species in ice/snow.
  6. The WD_RainoutEff vector allows us to turn off rainout in the temperature range 237 <= T < 258 K.
    • This algorithm (cf. Qiaoqiao Wang) better simulates scavenging of aerosol species in ice/snow.
  7. For some species (e.g. mineral dust and sea salt aerosols) you also need to specify the Radius and Density settings.

--Bob Yantosca (talk) 17:13, 4 February 2016 (UTC)

Example 4: Add a hydrocarbon species carried as equivalent carbon atoms

Several GEOS-Chem hydrocarbon species (e.g. acetone, isoprene, etc.) are emitted and transported as equivalent carbon atoms instead of a single molecule. These are defined as follows: 

          CASE( 'ACET' )
             CALL Spc_Create( am_I_Root     = am_I_Root,                    &
                              ThisSpc       = SpcData(N)%Info,              &
                              ModelID       = N,                            &
                              Name          = NameAllCaps,                  &
                              FullName      = 'Acetone',                    &
                              MW_g          = 58.08_fp,                     &
                              EmMW_g        = 12.00_fp,                     &
                              MolecRatio    = 3.0_fp,                       &
                              Is_Advected   = T,                            &
                              Is_Gas        = T,                            &
                              Is_Drydep     = T,                            &
                              Is_Wetdep     = F,                            &
                              DD_F0         = 1.0_fp,                       &
                              DD_Hstar_Old  = 1e5_fp,                       &
                              Henry_K0      = 2.7e+1_f8,                    &
                              Henry_CR      = 5300.0_f8,                    & 
                              RC            = RC )

NOTES:

  1. Acetone is emitted and transported as an equivalent number of carbon atoms. Therefore, we need to set these values explicitly:
    • Set the actual molecular weight (MW_g) to 58.08
    • Set the emitted molecular weight (EmMW_g) to 12.0
    • Set the number of carbons per species (MolecRatio) to 3.0
  2. Although acetone does not wet deposit, we still specify its Henry's law constants for the HEMCO sea-air exchange module.
  3. All other settings that are omitted will be assigned a "missing data" value (-999 for numeric values, or .FALSE. for logical values),
  4. Routine Spc_Create will automatically update the ModelID, AdvectID, and DryDepID for you.

--Bob Yantosca (talk) 17:14, 4 February 2016 (UTC)

Example 5: Adding several species with similar properties at the same time

Several GEOS-Chem species have similar properties. For example, the DST{1,2,3,4}, DSTAL{1,2,3,4}, NITD{1,2,3,4}, and SO4D{1,2,3,4} tracers are all mineral dust tracers with the same molecular weights, radii, density, drydep properties, and wetdep properties. Therefore, we can group them together so that a single call to Spc_Create will define all of these tracers: 

          CASE( 'DST2', 'DSTAL2', 'NITD2', 'SO4D2' )
             
             ! These have identical properties except for the names
             SELECT CASE( NameAllCaps )
                CASE( 'DST2' )
                   FullName = 'Dust aerosol, Reff = 1.4 microns'
                CASE( 'DSTAL2' )
                   FullName = 'Dust alkalinity, Reff = 1.4 microns'
                CASE( 'NITD2' )
                   FullName = 'Nitrate on dust, Reff = 1.4 microns'
                CASE( 'SO4D2' )
                   FullName = 'Sulfate on dust, Reff = 1.4 microns'
             END SELECT

             ! Do not reduce the Kc (cloud condensate -> precip) rate
             KcScale = (/ 1.0_fp, 1.0_fp, 1.0_fp /)

             ! Allow rainout of dust when T < 258K, becasue dust
             ! is considered to be IN. 
             RainEff = (/ 1.0_fp, 1.0_fp, 1.0_fp /)

             CALL Spc_Create( am_I_Root     = am_I_Root,                    &
                              ThisSpc       = SpcData(N)%Info,              &
                              ModelID       = N,                            &
                              Name          = NameAllCaps,                  &
                              FullName      = FullName,                     &
                              MW_g          = 29.0_fp,                      &
                              Is_Advected   = T,                            &
                              Is_Gas        = F,                            &
                              Is_Drydep     = T,                            &
                              Is_Wetdep     = T,                            &
                              Density       = 2650.0_fp,                    &
                              Radius        = 1.4e-6_fp,                    &
                              DD_DustDryDep = T,                            &
                              DD_F0         = 0.0_fp,                       &
                              DD_Hstar_Old  = 0.0_fp,                       &
                              WD_AerScavEff = 1.0_fp,                       &
                              WD_CoarseAer  = T,                            &
                              WD_KcScaleFac = KcScale,                      &
                              WD_RainoutEff = RainEff,                      &
                              RC            = RC )

NOTES:

  1. The second SELECT CASE statement is used to assign a unique FullName to each of these tracers. Otherwise, the species all share the same properties.
  2. The flag WD_CoarseAer is used to denote species having a radius >= 1μm. This is needed in subroutine WASHOUT in (GeosCore/wetscav_mod.F), where coarse aerosol washout is handled differently than fine aerosol washout.
  3. The DD_DustDryDep denotes that these are mineral dust species, for which dry deposition is handled by routine DUST_SFRSCII in drydep_mod.F. This routine ignores hygroscopic growth.
    • The similar flag DD_AeroDryDep denotes sea salt species, for which dry deposition is handled by routine AERO_SFRSCII in drydep_mod.F. This routine will account for hygroscopic growth.

--Bob Y. (talk) 14:45, 14 October 2015 (UTC)


Previous | Next | Guide to species in GEOS-Chem

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=GEOS-Chem_species_database&oldid=50317"