Difference between revisions of "GEOS-Chem species database"

From Geos-chem
Jump to: navigation, search
(GEOS-Chem v10-01 and prior versions)
Line 10: Line 10:
  
  
== Overview ==
+
This content has been migrated to the [https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/species-guide.html '''View GEOS-Chem Species Properties''' chapter of <tt>geos-chem.readthedocs.io</tt>]
 
+
On this page we describe the GEOS-Chem species database object.  This object stores [[Physical properties of GEOS-Chem species|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 v11-01 and later versions ===
+
 
+
We decided to create a data structure&mdash;the GEOS-Chem species database&mdash; that could hold the various [[Physical properties of GEOS-Chem species|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|dry deposition module]], [[Wet deposition|wet deposition module]], [[HEMCO|HEMCO emissions module]], and chemistry solver.  This allows us to replace much of the confusing legacy <tt>IF-THEN-ELSE-ENDIF</tt> code structure with one that uses much less <tt>IF</tt> 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, [[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. 
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:07, 6 May 2016 (UTC)
+
 
+
== The SPECIES derived type ==
+
 
+
The <tt>Species</tt> derived type allows you to specify physical properties for a single GEOS-Chem species.  The type declaration is contained in GEOS-Chem module <tt>Headers/species_mod.F90</tt>.  The tables below define the physical parameters that are contained in the <tt>Species</tt> type, subdivided by category.
+
 
+
=== ID numbers, names, etc. ===
+
 
+
Please also see our [[Species indexing in GEOS-Chem|our ''Species indexing in GEOS-Chem'' wiki page]] for more information on how you can get the species index information from the Species Database.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>ModelID</tt> || <tt>INTEGER</tt> || 1 ||Species ID
+
 
+
|-valign="top"
+
|<tt>AdvectID</tt> ||<tt>INTEGER</tt> || 1 ||Advected species ID
+
 
+
|-valign="top"
+
|<tt>DryDepID</tt> ||<tt>INTEGER</tt> || 1 ||Dry deposition species ID
+
 
+
|-valign="top"
+
|<tt>WetDepID</tt> ||<tt>INTEGER</tt> || 1 ||Wet deposition species ID
+
 
+
|-valign="top"
+
|<tt>KppVarId</tt> ||<tt>INTEGER</tt> || 1 ||KPP variable species ID (i.e. index for the KPP VAR array)
+
*NOTE: To be added in [[GEOS-Chem v11-01#v11-01g|GEOS-Chem v11-01g]]
+
 
+
|-valign="top"
+
|<tt>KppFixId</tt> ||<tt>INTEGER</tt> || 1 ||KPP variable species ID (i.e. index for the KPP FIX array)
+
*NOTE: To be added in [[GEOS-Chem v11-01#v11-01g|GEOS-Chem v11-01g]]
+
 
+
|-valign="top"
+
|<tt>Name</tt> ||<tt>CHARACTER(31)</tt> || N/A ||Short species name
+
 
+
|-valign="top"
+
|<tt>FullName</tt> ||<tt>CHARACTER(80)</tt> || N/A  ||Long species name
+
*<tt>FullName</tt> can be used for the netCDF <tt>long_name</tt> and/or <tt>standard_name</tt> variable attributes.
+
 
+
|-valign="top"
+
|<tt>NameHash</tt> ||<tt>INTEGER</tt> || N/A ||Unique [https://en.wikipedia.org/wiki/Hash_function integer hash value]  that corresponds to the <tt>Name</tt> field
+
*NOTE: This number can be positive OR negative.
+
 
+
|-valign="top"
+
|<tt>Is_Gas</tt> ||<tt>LOGICAL</tt> || 1  ||Gas or aerosol flag
+
*If TRUE, the species is gas. 
+
*If FALSE, the species is an aerosol.
+
 
+
|-valign="top"
+
|<tt>Is_Advected</tt> ||<tt>LOGICAL</tt> || 1  ||If TRUE, the species undergoes the following operations:
+
*[[Advection scheme TPCORE|Transport]],
+
*[[Cloud convection]], and/or
+
*[[Boundary layer mixing]]
+
 
+
|-valign="top"
+
|<tt>Is_DryDep</tt> ||<tt>LOGICAL</tt> || 1  ||If TRUE, the species [[Dry deposition|dry deposits]].
+
 
+
|-valign="top"
+
|<tt>Is_WetDep</tt> ||<tt>LOGICAL</tt> || 1  ||If TRUE, the species is soluble and [[Wet deposition|wet deposits]].
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 14:47, 27 June 2016 (UTC)
+
 
+
=== Molecular weight, density, radius ===
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>MW_g</tt> ||<tt>REAL(fp)</tt> || g mol<sup>-1</sup> ||Molecular weight of the species
+
 
+
|-valign="top"
+
|<tt>EmMW_g</tt> ||<tt>REAL(fp)</tt> ||g mol<sup>-1</sup> ||Emitted molecular weight of the species
+
*Several GEOS-Chem hydrocarbon species are emitted and transported as equivalent C atoms. 
+
*For these hydrocarbon species, set <tt>EmMW_g</tt> = 12.0 (molecular weight of 1 carbon atom).
+
 
+
|-valign="top"
+
|<tt>Density</tt> ||<tt>REAL(fp)</tt> || kg m<sup>-3</sup> ||Density of the species
+
 
+
|-valign="top"
+
|<tt>Radius</tt> ||<tt>REAL(fp)</tt> || m ||Radius of the species
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:02, 23 November 2021 (UTC)
+
 
+
=== Henry's law constants ===
+
 
+
Please also see our [[Physical properties of GEOS-Chem species#Henry's law|list of Henry's law constants]] for GEOS-Chem species on [[Physical properties of GEOS-Chem species|our ''Physical properties of GEOS_Chem species'' wiki page]].
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>Henry_K0</tt> ||<tt>REAL(f8)</tt> ||M atm<sup>-1</sup> ||Henry's law solubility constant
+
 
+
|-valign="top"
+
|<tt>Henry_CR</tt> ||<tt>REAL(f8)</tt> ||K ||Henry's law volatility constant
+
 
+
|-valign="top"
+
|<tt>Henry_pKa</tt> ||<tt>REAL(f8)</tt> ||1 ||Henry's law pH correction factor
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 19:12, 9 October 2015 (UTC)
+
 
+
=== Dry deposition parameters ===
+
 
+
Please also see our [[Physical properties of GEOS-Chem species#Dry deposition|list of dry deposition parameters]] for GEOS-Chem species on [[Physical properties of GEOS-Chem species|our ''Physical properties of GEOS_Chem species'' wiki page]].
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>DD_AeroDryDep</tt> ||<tt>LOGICAL</tt> ||1 ||For sea salt species, set this to TRUE.  This will use dry deposition routine <tt>AERO_SFCRSII</tt> to perform aerodynamic dry deposition accounting for hygroscopic growth.
+
 
+
|-valign="top"
+
|<tt>DD_DustDryDep</tt> ||<tt>LOGICAL</tt> ||1 ||For mineral dust species, set this to TRUE.  This will use dry deposition routine <tt>DUST_SFCRSII</tt> to perform aerodynamic dry deposition omitting hygroscopic growth.
+
 
+
|-valign="top"
+
|<tt>DD_DvzAerSnow</tt> ||<tt>REAL(fp)</tt> ||cm/s ||For certain aerosol species, <tt>DD_DvzAerSnow</tt> specifies the dry deposition velocity over ice and snow.  This usually 0.03 cm/s.
+
 
+
|-valign="top"
+
|<tt>DD_DvzMinVal</tt> ||<tt>REAL(fp)</tt> ||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).
+
*<tt>DD_DvzMinVal(1)</tt>: Specifies minimum drydep velocity over snow/ice
+
*<tt>DD_DvzMinVal(2)</tt>: Specifies minimum drydep velocity over land
+
 
+
|-valign="top"
+
|<tt>DD_Hstar_old</tt> ||<tt>REAL(fp)</tt> ||M atm<sup>-1</sup> ||Specifies the Henry's law <tt>K0</tt> constant that is used in dry deposition.  This is saved in the <tt>HSTAR</tt> variable in the GEOS-Chem dry deposition module <tt>GeosCore/drydep_mod.F</tt>.
+
*NOTE: We will eventually replace <tt>DD_Hstar_old</tt> this with the common Henry's law parameters (i.e. <tt>Henry_K0</tt>, <tt>Henry_CR</tt>, <tt>Henry_pKa</tt>.) 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 <tt>INIT_DRYDEP</tt>.  Therefore, we have added <tt>DD_Hstar_old</tt> as a temporary placeholder for the <tt>HSTAR</tt> quantity from <tt>drydep_mod.F</tt>.  We will remove this later on.
+
 
+
|-valign="top"
+
|<tt>DD_F0</tt> ||<tt>REAL(fp)</tt> ||1 ||Reactivity factor for oxidation of biological substances
+
 
+
|-valign="top"
+
|<tt>DD_KOA</tt> ||<tt>REAL(fp)</tt> ||1 ||Octanol-air partition coefficient, used for the <tt>POPG</tt> tracer in [[POPs simulation|Persistant Organic Pollutant (POPs) specialty simulations]].
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 19:13, 9 October 2015 (UTC)
+
 
+
=== Wet deposition parameters ===
+
 
+
Please also see our [[Physical properties of GEOS-Chem species#Wet deposition|list of wet deposition parameters]] for GEOS-Chem species on [[Physical properties of GEOS-Chem species|our ''Physical properties of GEOS_Chem species'' wiki page]].
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>WD_Is_HNO3</tt> ||<tt>LOGICAL</tt> ||1 ||Flag to determine if the species is HNO3. 
+
*Rainout/washout of HNO3 needs to be handled separately from other gas-phase species.
+
*<tt>WD_Is_HNO3</tt> will be automatically determined, depending on the value of <tt>Name</tt>.
+
 
+
|-valign="top"
+
|<tt>WD_Is_SO2</tt> ||<tt>LOGICAL</tt> ||1 ||Flag to determine if the species is SO2. 
+
*Rainout/washout of HNO3 separately from other gas-phase species.
+
*<tt>WD_Is_SO2</tt> will be automatically determined, depending on the value of <tt>Name</tt>.
+
 
+
|-valign="top"
+
|<tt>WD_Is_H2SO4</tt> ||<tt>LOGICAL</tt> ||1 ||Flag to determine if the species is H2SO4. 
+
*Rainout/washout of H2SO4 needs to be handled separately from other gas-phase species.
+
*<tt>WD_Is_H2SO4</tt> will be automatically determined, depending on the value of <tt>Name</tt>.
+
*H2SO4 is a species in TOMAS aerosol microphysics only.
+
 
+
|-valign="top"
+
|<tt>WD_CoarseAer</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to indicate that the species is a coarse aerosol (i.e. having a radius > 1 &mu;m)
+
*Washout of coarse aerosols is handled separately from the washout of fine aerosols.
+
 
+
|-valign="top"
+
|<tt>WD_LiqAndGas</tt> ||<tt>LOGICAL</tt> ||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 [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf 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 <tt>WD_LiqAndGas</tt> = TRUE.
+
*If FALSE, the ice-to-gas ratio for this species will be set to zero.
+
 
+
|-valign="top"
+
|<tt>WD_ConvFacI2G</tt> ||<tt>REAL(fp)</tt> ||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 [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf Jacob et al, 2000]).
+
*<tt>WD_ConvFacI2G</tt> only needs to be specified for those species having <tt>WD_LiqAndGas</tt> = TRUE.
+
 
+
|-valign="top"
+
|<tt>WD_RetFactor</tt> ||<tt>REAL(fp)</tt> ||1 ||Specifies the retention efficiency <tt>R<sub>i</sub></tt> of tracer in the liquid cloud condensate as it is converted to precipitation. (<tt>R<sub>i</sub></tt> < 1 accounts for volatization during riming.)  The retention factor is defined in Eq. 1 of [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf Jacob et al, 2000].
+
 
+
|-valign="top"
+
|<tt>WD_AerScavEff</tt> ||<tt>REAL(fp)</tt> || 1 ||Specifies the aerosol scavenging efficiency.  This factor multiplies <tt>F</tt>, the fraction of aerosol species that is lost to convective updraft scavenging (cf Eq. 2 of [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf Jacob et al 2000]). 
+
*For most aerosol species, <tt>WD_AerScavEff</tt> = 1.0.
+
*For secondary organic aerosol species, <tt>WD_AerScavEff</tt> = 0.8.
+
*For hydrophobic species (e.g. MOPO), <tt>WD_AerScavEff</tt> = 0.0.
+
 
+
<tt>WD_AerScavEff</tt> is applied in routine <tt>COMPUTE_F</tt> of GEOS-Chem module <tt>GeosCore/wetscav_mod.F</tt>.
+
 
+
|-valign="top"
+
|<tt>WD_KcScaleFac</tt> ||<tt>REAL(fp)</tt> ||1 ||Specifies a temperature-dependent scale factor that is used to multiply <tt>K</tt> (aka <tt>Kc</tt>), the rate constant for conversion of cloud condensate to precipitation (cf Eq. 1 of [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf Jacob et al, 2000]). 
+
 
+
<tt>WD_KcScaleFac</tt> is defined as a 3-element vector, where:
+
*<tt>WD_KcScaleFac(1)</tt> multiplies <tt>K</tt> when T < 237 K.
+
*<tt>WD_KcScaleFac(2)</tt> multiplies <tt>K</tt> when 237 K <= T < 258 K.
+
*<tt>WD_KcScaleFac(3)</tt> multiplies <tt>K</tt> when T >= 258K.
+
 
+
This allows us to better simulate scavenging by snow, where, for most species, we need to halve the <tt>K</tt> rate when 237 K <= T < 258 K.  This can be easily done by setting the value <tt>KcScaleFac(2) = 0.5</tt>.
+
 
+
<tt>WD_KcScaleFac</tt> is applied in routine <tt>F_AEROSOL</tt> of GEOS_Chem module <tt>GeosCore/wetscav_mod.F</tt>.
+
 
+
|-valign="top"
+
|<tt>WD_RainoutEff</tt> ||<tt>REAL(fp)</tt> ||1 ||Specifies a temperature-dependent scale factor that is used to multiply <tt>F<sub>i</sub></tt> (aka <tt>RAINFRAC</tt>), the fraction of species scavenged by rainout (cf Eq. 1 of [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf Jacob et al, 2000]). 
+
 
+
<tt>WD_RainoutEff</tt> is defined as a 3-element vector, where:
+
*<tt>WD_RainoutEff(1)</tt> multiplies <tt>F<sub>i</sub></tt> when T < 237 K.
+
*<tt>WD_RainoutEff(2)</tt> multiplies <tt>F<sub>i</sub></tt> when 237 K <= T < 258 K.
+
*<tt>WD_RainoutEff(3)</tt> multiplies <tt>F<sub>i</sub></tt> 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 <tt>RainoutEff(2)</tt> = 0.
+
 
+
<tt>WD_RainoutEff</tt> is applied in routine <tt>APPLY_RAINOUT_EFF</tt> of GEOS_Chem module <tt>GeosCore/wetscav_mod.F</tt>.
+
 
+
NOTE: For secondary organic aerosol species, the maximum value of <tt>WD_RainoutEff</tt> will be 0.8 instead of 1.0.
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 19:14, 9 October 2015 (UTC)
+
 
+
=== Microphysics parameters ===
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>MP_SizeResAer</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to TRUE to indicate that the species is a size-resolved aerosol species (used in microphysics simulations).
+
 
+
|-valign="top"
+
|<tt>MP_SizeResAer</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to TRUE to indicate that the species is a size-resolved aerosol number (used in microphysics simulations).
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 20:44, 9 October 2015 (UTC)
+
 
+
=== Tagged Hg index variables ===
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
 
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Quantity
+
!width="110px"|Type
+
!width="65px"|Units
+
!width="635px"|Description
+
 
+
|-valign="top"
+
|<tt>Is_Hg0</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to TRUE to denote a total Hg0 regional tagged Hg0 species.
+
 
+
|-valign="top"
+
|<tt>Is_Hg2</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to TRUE to denote a total Hg2 regional tagged Hg2 species.
+
 
+
|-valign="top"
+
|<tt>Is_HgP</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to TRUE to denote a total HgP regional tagged HgP species.
+
 
+
|-valign="top"
+
|<tt>Hg_Cat</tt> ||<tt>LOGICAL</tt> ||1 ||Indicates the tagged Hg category number (<tt>1..State_Chm%N_Hg_CATS</tt>)
+
 
+
|-valign="top"
+
|<tt>Is_Hg0</tt> ||<tt>LOGICAL</tt> ||1 ||Set this flag to TRUE to denote a total Hg0 regional tagged Hg0 species.
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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 <tt>Species</tt>.  The following sections describe how we create the GEOS-Chem species database object:
+
 
+
=== The SPCPTR derived type ===
+
 
+
The <tt>SpecPtr</tt> derived type (located in GEOS-Chem module <tt>Headers/species_mod.F90</tt>) lets you to create a pointer variable of type <tt>Species</tt>.
+
 
+
  TYPE, PUBLIC :: SpcPtr
+
    TYPE(Species),    POINTER :: Info  ! Species type
+
  END TYPE SpcPtr
+
 
+
=== The GEOS-Chem species database object ===
+
 
+
We use the <tt>SpcPtr</tt> to create the GEOS-Chem species database as a sub-object of the <tt>State_Chm</tt> "Chemistry State" object.  The <tt>State_Chm</tt> object is built according to the <tt>ChmState</tt> 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'
+
+
    <span style="color:red">! Physical properties about tracers & species
+
    TYPE(SpcPtr),      POINTER :: SpcData(:)          ! Species database</span>
+
+
    ... etc ...
+
+
  END TYPE ChmState
+
 
+
Therefore, the GEOS-Chem species database is referred to as <tt>State_Chm%SpcData</tt>. 
+
 
+
Routine <tt>Init_Species_Database</tt> in GEOS-Chem module <tt>Headers/species_database_mod.F90</tt> allocates the <tt>State_Chm%SpcData</tt> object and populates it with [[Physical properties of GEOS-Chem species|the relevant physical parameters for each GEOS-Chem species]].
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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, <span style="color:green">State_Chm%nSpecies</span>
+
+
          ! Get Henry's law parameters
+
          K0  = <span style="color:red">State_Chm%SpcData(N)%Info</span>%Henry_K0
+
          CR  = <span style="color:red">State_Chm%SpcData(N)%Info</span>%Henry_CR
+
          pKA = <span style="color:red">State_Chm%SpcData(N)%Info</span>%Henry_pKa
+
+
      ENDDO
+
 
+
Routine <tt>Init_Species_Database</tt> will also save the number of GEOS-Chem species as the variable <span style="color:green"><tt>State_Chm%nSpecies</tt></span>.  So you can use that as the upper bound of DO loops.
+
 
+
To simplify the coding, you can create an object of type <tt>Species</tt> to point to each entry in the species database.  For example this code
+
 
+
      <span style="color:blue">USE Species_Mod, ONLY : Species
+
+
      TYPE(Species), POINTER :: ThisSpc</span>
+
+
      DO N = 1, <span style="color:green">State_Chm%nSpecies</span>
+
         
+
          <span style="color:blue">ThisSpc =></span> <span style="color:red">State_Chm%SpcData(N)%Info</span>
+
+
          ! Get Henry's law parameters
+
          K0  =  <span style="color:blue">ThisSpc</span>%Henry_K0
+
          CR  =  <span style="color:blue">ThisSpc</span>%Henry_CR
+
          pKA =  <span style="color:blue">ThisSpc</span>%Henry_pKa
+
+
          <span style="color:blue">ThisSpc => NULL()</span>     
+
+
      ENDDO
+
 
+
 
+
is much less wordy and easier to read.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 18:42, 15 June 2016 (UTC)
+
 
+
=== Defining molecular weight fields of the Input_Opt object from the species database ===
+
 
+
<span style="color:green">'''''This update was validated with the 1-month benchmark simulation [[GEOS-Chem v11-01 benchmark history#v11-01e|v11-01e]] (approved 04 Jan 2016).'''''</span>
+
 
+
In [[GEOS-Chem v11-01#v11-01d|GEOS-Chem v11-01d]] and prior versions, molecular weights for each emitted species (shown in <span style="color:red">RED</span>) were specified in the <tt>input.geos</tt> file:
+
 
+
%%% TRACER MENU %%%    :
+
Type of simulation      : 3
+
Number of Tracers      : 119
+
Tracer Entries -------> : TR#  Name  <span style="color:red">g/mole</span>  Tracer Members; () = emitted
+
Tracer #1              :  1  NO      <span style="color:red">30.0</span>  (NO)
+
Tracer #2              :  2  O3      <span style="color:red">48.0</span>  (O3)
+
Tracer #3              :  3  PAN    <span style="color:red">121.0</span>
+
Tracer #4              :  4  CO      <span style="color:red">28.0</span>  (CO)
+
 
+
These molecular weights were then saved into [[Derived_type_objects_used_by_GEOS-Chem#The_Input_Options_object|the Input Options object]] field <tt>Input_Opt%TRACER_MW_G</tt>.  They also initialized the related quantities <tt>Input_Opt%TRACER_MW_KG</tt>, <tt>Input_Opt%TCVV</tt>, and <tt>Input_Opt%XNUMOL</tt>.
+
 
+
Historically, other GEOS-Chem modules (especially dry deposition) had defined molecular weights as internal module variables.  For some species, these locally-defined molecular weights [[Physical_properties_of_GEOS-Chem_species#Discrepancies_found_in_the_dry_deposition_module|conflicted with the molecular weights stored in the <tt>Input_Opt</tt> object]].  Some of these inconsistencies went undetected for several years.
+
 
+
To avoid further discrepancies like this, we modified [[GEOS-Chem v11-01#v11-01e|GEOS-Chem v11-01e]] to pass molecular weight values from the species database to the relevant fields of <tt>Input_Opt</tt>.  This ensures that a single molecular weight for each species will be used everywhere throughout GEOS-Chem. 
+
 
+
The following code was added to routine <tt>INIT_GIGC_STATE_CHM</tt> (in module <tt>GeosCore/gigc_state_chm_mod.F90</tt>).  Code lines in <span style="color:green">GREEN</span> show where the emitted molecular weight for each species is passed from the species dataabase to the <tt>Input_Opt</tt> 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
+
+
      <span style="color:green">! 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)</span>
+
+
      ! 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
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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#12.9.0|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, [https://github.com/geoschem/geos-chem/blob/main/run/shared/species_database.yml follow this link].
+
 
+
== Adding new species to the GEOS-Chem species database (in 12.8.1 and prior) ==
+
 
+
You can define [[Physical properties of GEOS-Chem species|physical properties for GEOS-Chem species]] in routine <tt>Spc_Info</tt> (located in module <tt>Headers/species_database_mod.F90</tt>).  Near the top of the routine you will see a loop over the number of species and a <tt>SELECT CASE</tt> statement, <span style="color:red">highlighted in RED below</span>.
+
 
+
!
+
! !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 )
+
+
        <span style="color:red">! Test for species name
+
        SELECT CASE( TRIM ( <span style="color:brown">NameAllCaps</span> ) )
+
       
+
          CASE( <span style="color:brown">'ACET'</span> )
+
              CALL Spc_Create( ... )
+
+
          CASE( <span style="color:brown">'ALD2'</span> )
+
              CALL Spc_Create( ... )
+
+
        ... etc ...</span>
+
 
+
In each <tt>CASE</tt> block, there is a call to the routine <tt>Spc_Create</tt> (contained in module <tt>Headers/species_mod.F90</tt>).  The <tt>Spc_Create</tt> 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 <tt>CASE</tt> blocks&mdash;with calls to <tt>Spc_Create</tt>&mdash;to the <tt>SELECT_CASE</tt> 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:
+
 
+
*<span style="color:brown">BROWN denotes species names</span>
+
*<span style="color:red">RED denotes species molecular weights, densities, and radii</span>
+
*<span style="color:orange">ORANGE denotes the gas vs. aerosol flag</span>
+
*<span style="color:blue">BLUE denotes dry deposition settings</span>
+
*<span style="color:green">GREEN denotes wet deposition settings</span>
+
*<span style="color:purple">PURPLE denotes Henry's law constants</span>
+
 
+
To simplify the coding, in all the examples below, we use the parameters <tt>T</tt> and <tt>F</tt> instead of having to type out the logical values <tt>.TRUE.</tt> and <tt>.FALSE.</tt>.  A complete list of species physical properties may be found on [[Physical properties of GEOS-Chem species|our ''Physical properties of GEOS-Chem species'' wiki page]].
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|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 <tt>Spc_Create</tt> routine with these settings:
+
 
+
          CASE( <span style="color:brown">'CCL4'</span> )
+
            CALL Spc_Create( am_I_Root    = am_I_Root,                    &
+
                              ThisSpc      = SpcData(N)%Info,              &
+
                              ModelID      = N,                            &
+
                              <span style="color:brown">Name          = 'CCl4',                      &
+
                              FullName      = 'Carbon tetrachloride',      &</span>
+
                              <span style="color:red">MW_g          = 152.0_fp,                    &</span>
+
                              Is_Advected  = T,                            &
+
                              <span style="color:orange">Is_Gas        = T,                            &</span>
+
                              <span style="color:blue">Is_Drydep    = F,                            &</span>
+
                              <span style="color:green">Is_Wetdep    = F,                            &</span>
+
                              RC            = RC )
+
 
+
NOTES:
+
#The <span style="color:brown">name of the species</span> in the <tt>CASE</tt> 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 <span style="color:brown"><tt>Name</tt></span> argument.  This will preserve element names such as Br, Cl, etc.
+
#*Example: <tt>CASE( <span style="color:brown">'CCL4'</span> )</tt> but <span style="color:brown"><tt>Name = 'CCl4'</tt></span>
+
#Most species parameters use the GEOS-Chem flexible precision (i.e. <tt>REAL(fp)</tt>.)
+
#*Adding <tt>_fp</tt> to the end of a number signifies it is a constant of type <tt>REAL(fp)</tt>.
+
#You don't have to specify all of the possible settings. 
+
#*Settings that are omitted will be assigned a "missing data" value (<tt>-999</tt> for numeric values, or <tt>.FALSE.</tt> for logical values), unless specified otherwise.
+
#If you omit <span style="color:red"><tt>EmMW_g</tt></span> (emitted molecular weight), it will be assigned the same value as <span style="color:red"><tt>MW_g</tt></span> (actual molecular weight).
+
#If you omit <span style="color:red"><tt>MolecRatio</tt></span> (carbon atoms per species), it will be assigned a default value of <tt>1.0</tt>.
+
#Routine <tt>Spc_Create</tt> will automatically update the <tt>ModelID</tt> and <tt>AdvectID</tt> ID's for you.
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|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( <span style="color:brown">'H2O2'</span> )
+
            CALL Spc_Create( am_I_Root    = am_I_Root,                    &
+
                              ThisSpc      = SpcData(N)%Info,              &
+
                              ModelID      = N,                            &
+
                              <span style="color:brown">Name          = NameAllCaps,                  &
+
                              FullName      = 'Hydrogen peroxide',          &</span>
+
                              <span style="color:red">MW_g          = 34.0_fp,                      &</span>
+
                              Is_Advected  = T,                            &
+
                              <span style="color:orange">Is_Gas        = T,                            &</span>
+
                              <span style="color:blue">Is_Drydep    = T,                            &</span>
+
                              <span style="color:green">Is_Wetdep    = T,                            &</span>
+
                              <span style="color:blue">DD_F0        = 1.0_fp,                      &                             
+
                              DD_Hstar_old  = 1e+5_fp,                      &</span>
+
                              <span style="color:purple">Henry_K0      = 8.30e+4_f8,                  &
+
                              Henry_CR      = 7400.0_f8,                    &</span>
+
                              <span style="color:green">WD_RetFactor  = 5e-2_fp,                      &
+
                              WD_LiqAndGas  = T,                            &
+
                              WD_ConvFacI2G = 4.36564e-1_fp,                &</span>
+
                              RC            = RC )
+
 
+
NOTES:
+
#Because H2O2 is not a hydrocarbon that is carried as equivalent carbons, we only have to specify the <span style="color:red"><tt>MW_g</tt></span> (actual molecular weight) setting.
+
#*The related properties <span style="color:red"><tt>EmMW_g</tt></span> and <span style="color:red"><tt>MolecRatio</tt></span> will be updated accordingly.
+
#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.
+
#*<span style="color:blue"><tt>DD_Hstar_old</tt></span> sets the Henry's law K0 used for dry deposition
+
#*<span style="color:purple"><tt>Henry_K0</tt></span> 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.
+
#H2O2 is also a species for which the ice to gas ratio is computed by co-condensation in the wet deposition module
+
#*<span style="color:green"><tt>WD_LiqAndGas</tt></span> is TRUE for H2O2. 
+
#*<span style="color:green"><tt>WD_ConvFacI2G</tt></span> specifies the conversion factor (the ratio of sticking coefficients on the ice surface) as described in Eq. 9 of [http://acmg.seas.harvard.edu/geos/wiki_docs/deposition/wetdep.jacob_etal_2000.pdf Jacob et al 2000].
+
#*For most other species, you can omit <span style="color:green"><tt>WD_LiqAndGas</tt></span> and <span style="color:green"><tt>WD_LiqAndGas</tt></span>, as the ice-to-gas ratio for most species is zero.
+
#The <span style="color:purple">Henry's law parameters</span> are defined as 8-byte floating point variables (<tt>REAL(f8)</tt>).
+
#*This provides better numerical stability, as several of the Henry's law computations involve exponentials.
+
#*Adding <tt>_f8</tt> to the end of a number signifies it is a constant of type <tt>REAL(f8)</tt>.
+
#All other settings that are omitted will be assigned a "missing data" value (<tt>-999</tt> for numeric values, or <tt>.FALSE.</tt> for logical values),
+
#Routine <tt>Init_Species_Database</tt> will automatically update the <tt>ModelID</tt>, <tt>AdvectID</tt>, <tt>DryDepID</tt>, and <tt>WetDepID</tt> for you.
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|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 <tt>Init_Species_Database</tt> routine ...
+
+
    ! Arrays
+
    REAL(fp)            :: DvzMinVal(2)
+
    REAL(fp)            :: KcScale(3)
+
    REAL(fp)            :: RainEff(3)
+
+
    ... and this is the case statement for NIT ...
+
+
          CASE( <span style="color:brown">'NIT'</span> )
+
+
            <span style="color:green">! 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 /)</span>
+
+
            <span style="color:blue">! 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 /)</span>
+
+
            CALL Spc_Create( am_I_Root    = am_I_Root,                    &
+
                              ThisSpc      = SpcData(N)%Info,              &
+
                              ModelID      = N,                            &
+
                              <span style="color:brown">Name          = NameAllCaps,                  &
+
                              FullName      = 'Inorganic nitrates',        &</span>
+
                              <span style="color:red">MW_g          = 62.0_fp,                      &</span>
+
                              Is_Advected  = T,                            &
+
                              <span style="color:orange">Is_Gas        = F,                            &</span>
+
                              <span style="color:blue">Is_Drydep    = T,                            &</span>
+
                              <span style="color:green">Is_Wetdep    = T,                            &</span>
+
                              <span style="color:blue">DD_DvzAerSnow = 0.03_fp,                      &
+
                              DD_DvzMinVal  = DvzMinVal,                    &
+
                              DD_F0        = 0.0_fp,                      &
+
                              DD_Hstar_Old  = 0.0_fp,                      &</span>
+
                              <span style="color:green">WD_AerScavEff = 1.0_fp,                      &
+
                              WD_KcScaleFac = KcScale,                      &
+
                              WD_RainoutEff = RainEff,                      &</span>
+
                              RC            = RC )
+
 
+
NOTES:
+
#We denote that this species is an aerosol with <span style="color:orange"><tt>Is_Gas = F</tt></span>.
+
#Drydep parameters <span style="color:blue"><tt>DD_F0</tt></span> and <span style="color:blue"><tt>DD_Hstar_Old</tt></span> 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 (<tt>-999</tt> for these parameters.
+
#On ice and snow surfaces, we manually set the dry deposition velocity of NIT to 0.03 cm/s.  This is specified with the <span style="color:blue"><tt>DD_DvzAerSnow</tt></span> setting.
+
#Following the methodology of the GOCART model, we use the <span style="color:blue"><tt>DD_DvzMinVal</tt></span> vector to specify a minimum dry deposition velocity over snow/ice vs. land.
+
#The <tt>WD_KcScaleFac</tt> 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.
+
#The <tt>WD_RainoutEff</tt> 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.
+
#For some species (e.g. mineral dust and sea salt aerosols) you also need to specify the <span style="color:red"><tt>Radius</tt></span> and <span style="color:red"><tt>Density</tt></span> settings.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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( <span style="color:brown">'ACET'</span> )
+
              CALL Spc_Create( am_I_Root    = am_I_Root,                    &
+
                              ThisSpc      = SpcData(N)%Info,              &
+
                              ModelID      = N,                            &
+
                              <span style="color:brown">Name          = NameAllCaps,                  &
+
                              FullName      = 'Acetone',                    &</span>
+
                              <span style="color:red">MW_g          = 58.08_fp,                    &
+
                              EmMW_g        = 12.00_fp,                    &
+
                              MolecRatio    = 3.0_fp,                      &</span>
+
                              Is_Advected  = T,                            &
+
                              <span style="color:orange">Is_Gas        = T,                            &</span>
+
                              <span style="color:blue">Is_Drydep    = T,                            &</span>
+
                              <span style="color:green">Is_Wetdep    = F,                            &</span>
+
                              <span style="color:blue">DD_F0        = 1.0_fp,                      &
+
                              DD_Hstar_Old  = 1e5_fp,                      &</span>
+
                              <span style="color:purple">Henry_K0      = 2.7e+1_f8,                    &
+
                              Henry_CR      = 5300.0_f8,                    &</span>
+
                              RC            = RC )
+
 
+
NOTES:
+
#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 (<span style="color:red"><tt>MW_g</tt></span>) to 58.08
+
#*Set the emitted molecular weight (<span style="color:red"><tt>EmMW_g</tt></span>) to 12.0
+
#*Set the number of carbons per species (<span style="color:red"><tt>MolecRatio</tt></span>) to 3.0
+
#Although acetone does not wet deposit, we still specify its <span style="color:purple">Henry's law constants</span> for the [[HEMCO]] sea-air exchange module.
+
#All other settings that are omitted will be assigned a "missing data" value (<tt>-999</tt> for numeric values, or <tt>.FALSE.</tt> for logical values),
+
#Routine <tt>Spc_Create</tt> will automatically update the <tt>ModelID</tt>, <tt>AdvectID</tt>, and <tt>DryDepID</tt> for you.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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 <tt>Spc_Create</tt> will define all of these tracers:
+
 
+
          CASE( <span style="color:brown">'DST2', 'DSTAL2', 'NITD2', 'SO4D2'</span> )
+
             
+
              <span style="color:brown">! 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</span>
+
+
              <span style="color:green">! 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 /)</span>
+
+
              CALL Spc_Create( am_I_Root    = am_I_Root,                    &
+
                              ThisSpc      = SpcData(N)%Info,              &
+
                              ModelID      = N,                            &
+
                              <span style="color:brown">Name          = NameAllCaps,                  &
+
                              FullName      = FullName,                    &</span>
+
                              MW_g          = 29.0_fp,                      &
+
                              Is_Advected  = T,                            &
+
                              <span style="color:orange">Is_Gas        = F,                            &</span>
+
                              <span style="color:blue">Is_Drydep    = T,                            &</span>
+
                              <span style="color:green">Is_Wetdep    = T,                            &
+
                              <span style="color:red">Density      = 2650.0_fp,                    &
+
                              Radius        = 1.4e-6_fp,                    &</span>
+
                              <span style="color:blue">DD_DustDryDep = T,                            &
+
                              DD_F0        = 0.0_fp,                      &
+
                              DD_Hstar_Old  = 0.0_fp,                      &</span>
+
                              <span style="color:green">WD_AerScavEff = 1.0_fp,                      &
+
                              WD_CoarseAer  = T,                            &
+
                              WD_KcScaleFac = KcScale,                      &
+
                              WD_RainoutEff = RainEff,                      &</span>
+
                              RC            = RC )
+
 
+
NOTES:
+
#The second <tt>SELECT CASE</tt> statement is used to assign a unique <span style="color:brown"><tt>FullName</tt></span> to each of these tracers.  Otherwise, the species all share the same properties.
+
#The flag <span style="color:green"><tt>WD_CoarseAer</tt></span> is used to denote species having a radius >= 1&mu;m.  This is needed in subroutine <tt>WASHOUT</tt> in (<tt>GeosCore/wetscav_mod.F</tt>), where coarse aerosol washout is handled differently than fine aerosol washout.
+
#The <span style="color:blue"><tt>DD_DustDryDep</tt></span> denotes that these are mineral dust species, for which dry deposition is handled by routine <tt>DUST_SFRSCII</tt> in <tt>drydep_mod.F</tt>.  This routine ignores hygroscopic growth.
+
#*The similar flag <span style="color:blue"><tt>DD_AeroDryDep</tt></span> denotes sea salt species, for which dry deposition is handled by routine <tt>AERO_SFRSCII</tt> in <tt>drydep_mod.F</tt>.  This routine will account for hygroscopic growth.
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 14:45, 14 October 2015 (UTC)
+
  
  
 
----
 
----
 
'''''[[Physical properties of GEOS-Chem species|Previous]] | [[GEOS-Chem species units|Next]] | [[Guide to species in GEOS-Chem]]'''''
 
'''''[[Physical properties of GEOS-Chem species|Previous]] | [[GEOS-Chem species units|Next]] | [[Guide to species in GEOS-Chem]]'''''

Revision as of 21:20, 9 August 2022

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


This content has been migrated to the View GEOS-Chem Species Properties chapter of geos-chem.readthedocs.io



Previous | Next | Guide to species in GEOS-Chem