.. _spcguide: ################################# View GEOS-Chem species properties ################################# Properties for GEOS-Chem species are stored in the **GEOS-Chem Species Database**, which is a `YAML `_ file (:file:`species_database.yml`) that is placed into each GEOS-Chem run directory. View species properties from the current stable GEOS-Chem version: - `View properties for most GEOS-Chem species `_ - `View properties for APM microphysics species `_ - `View properties for TOMAS microphysics species `_ .. _spcguide-defs-id: ========================= Identification properties ========================= All GEOS-Chem species should have these properties defined, at minimum: .. code-block:: YAML Name: FullName: full name of the species Formula: chemical formula of the species MW_g: molecular weight of the species in grams EITHER Is_Gas: true OR Is_Aerosol: true All other properties are species-dependent. You may omit properties that do not apply to a given species. GEOS-Chem will assign a "missing value" (e.g. :code:`false`, :code:`-999`, :code:`-999.0`, or, :code:`UNKNOWN`) to these properties when it reads the :file:`species_database.yml` file from disk. Name ---- Species short name (e.g. :literal:`ISOP`). Formula ------- Species chemical formula (e.g. :literal:`CH2=C(CH3)CH=CH2`). This is used to define the species' :literal:`formula` attribute, which gets written to GEOS-Chem diagnostic files and restart files. FullName -------- Species long name (e.g. :literal:`Isoprene`). This is used to define the species' :literal:`long_name` attribute, which gets written to GEOS-Chem diagnostic files and restart files. Is_Aerosol ---------- Indicates that the species is an aerosol (:literal:`true`), or isn't (:literal:`false`). This is used to activate special handling for aerosols in dry depositon. Is_DryAlt --------- Indicates that dry deposition diagnostic quantities for the species can be archived at a specified altitude above the surface (:literal:`true`), or can't (:literal:`false`). .. note:: The :code:`Is_DryAlt` flag only applies to species :literal:`O3` and :literal:`HNO3`. Is_DryDep --------- Indicates that the species is dry deposited (:literal:`true`), or isn't (:literal:`false`). Is_HygroGrowth -------------- Indicates that the species is an aerosol that is capable of hygroscopic growth (:literal:`true`), or isn't (:literal:`false`). Is_Gas ------ Indicates that the species is a gas (:literal:`true`), or isn't (:literal:`false`). Is_Hg0 ------ Indicates that the species is elemental mercury (:literal:`true`), or isn't (:literal:`false`). Is_Hg2 ------ Indicates that the species is a mercury compound with oxidation state +2 (:literal:`true`), or isn't (:literal:`false`). Is_HgP ------ Indicates that the species is a particulate mercury compound (:literal:`true`), or isn't (:literal:`false`). Is_Photolysis ------------- Indicates that the species is photolyzed (:literal:`true`), or isn't (:literal:`false`). Is_RadioNuclide --------------- Indicates that the species is a radionuclide (:literal:`true`), or isn't (:literal:`false`). .. _spcguide-defs-physprop: =================== Physical properties =================== Density ------- Density (:math:`kg\ m^{-3}`) of the species. Typically defined only for aerosols. Henry_K0 -------- Henry's law solubility constant (:math:`M\ atm^{-1}`), used by the default wet depositon scheme. Henry_K0_Luo ------------ Henry's law solubility constant (:math:`M\ atm^{-1}`) used by the Luo wet deposition scheme (cf. :cite:t:`Luo_et_al._2020`, :cite:t:`Luo_and_Yu_2023`). Henry_CR -------- Henry's law volatility constant (:math:`K`) used by the default wet deposition scheme. Henry_CR_Luo ------------ Henry's law volatility constant (:math:`K`) used by the :cite:t:`Luo_et_al._2020` wet deposition scheme. Henry_pKa --------- Henry's Law pH correction factor. MW_g ---- Molecular weight (:math:`g\ mol^{-1}`) of the species. .. note:: Some aerosol-phase species (such as MONITA and IONITA) are given the molar mass corresponding to the number of nitrogens that they carry, whereas gas-phase species (MONITS and MONITU) get the full molar mass of the compounds that they represent. This treatment has its origins in `J. Fisher et al [2016] `_. Radius ------ Radius (:math:`m`) of the species. Typically defined only for aerosols. .. _spcguide-defs-drydep: ========================= Dry deposition properties ========================= DD_AeroDryDep ------------- Indicates that dry deposition should consider hygroscopic growth for this species (:literal:`true`), or shouldn't (:literal:`false`). .. note:: :code:`DD_AeroDryDep` is only defined for sea salt aerosols. DD_DustDryDep ------------- Indicates that dry deposition should exclude hygroscopic growth for this species (:literal:`true`), or shouldn't (:literal:`false`). .. note:: :code:`DD_DustDryDep` is only defined for mineral dust aerosols. DD_DvzAerSnow ------------- Specifies the dry deposition velocity (:math:`cm\ s^{-1}`) over ice and snow for certain aerosol species. Typically, :code:`DD_DvzAerSnow = 0.03`. DD_DvzAerSnow_Luo ----------------- Specifies the dry deposition velocity (:math:`cm\ s^{-1}`) over ice and snow for certain aerosol species. .. note:: :code:`DD_DvzAerSnow_Luo` is only used when the :cite:t:`Luo_et_al._2020` wet scavenging scheme is activated. DD_DvzMinVal ------------ Specfies minimum dry deposition velocities (:math:`cm\ s^{-1}`) for sulfate species (:literal:`SO2`, :literal:`SO4`, :literal:`MSA`, :literal:`NH3`, :literal:`NH4`, :literal:`NIT`). This follows the methodology of the GOCART model. :code:`DD_DvzMinVal` is defined as a two-element vector: .. list-table:: :header-rows: 1 :widths: 25 75 * - Vector element - Description * - :code:`DD_DvzMinVal(1)` - Sets a minimum dry deposition velocity onto snow and ice. * - :code:`DD_DvzMinVal(2)` - Sets a minimum dry deposition velocity over land. DD_Hstar_Old ------------ Specifies the Henry's law constant (:math:`K_0`) that is used in dry deposition. This will be used to assign the :code:`HSTAR` variable in the GEOS-Chem dry deposition module. .. note:: The value of the :code:`DD_Hstar_old` parameter was tuned for each species so that the dry deposition velocity would match observations. DD_F0 ----- Specifies the reactivity factor for oxidation of biological substances in dry deposition. DD_KOA ------ Specifies the octanal-air partition coefficient, used for the dry deposition of species :code:`POPG`. .. note:: :code:`DD_KOA` is only used in the `POPs simulation `_. .. _spcguide-defs-wetdep: ========================= Wet deposition properties ========================= WD_Is_H2SO4 ----------- Indicates that the species is :literal:`H2SO4` (:literal:`true`), or isn't (:literal:`false)`. This allows the wet deposition code to perform special calculations when computing :literal:`H2SO4` rainout and washout. WD_Is_HNO3 ---------- Indicates that the species is :literal:`HNO3` (:literal:`true`), or isn't (:literal:`false)`. This allows the wet deposition code to perform special calculations when computing :literal:`HNO3`. rainout and washout. WD_Is_SO2 --------- Indicates that the species is :literal:`SO2` (:literal:`true`), or isn't (:literal:`false)`. This allows the wet deposition code to perform special calculations when computing :literal:`SO2` rainout and washout. WD_CoarseAer ------------ Indicates that the species is a coarse aerosol (:literal:`true`), or isn't (:literal:`false`). For wet deposition purposes, the definition of coarse aerosol is radius > 1 :math:`\mu m`. WD_LiqAndGas ------------ Indicates that the the ice-to-gas ratio can be computed for this species by co-condensation (:literal:`true`), or can't (:literal:`false`). WD_ConvFacI2G ------------- Specifies the conversion factor (i.e. ratio of sticking coefficients on the ice surface) for computing the ice-to-gas ratio by co-condensation, as used in the default wet deposition scheme. .. note:: :code:`WD_ConvFacI2G` only needs to be defined for those species for which :code:`WD_LiqAndGas` is :literal:`true`. WD_ConvFacI2G_Luo ----------------- Specifies the conversion factor (i.e. ratio of sticking coefficients on the ice surface) for computing the ice-to-gas ratio by co-condensation, as used in the Luo wet deposition scheme (cf. :cite:t:`Luo_et_al._2020`, :cite:t:`Luo_and_Yu_2023`). .. note:: :code:`WD_ConvFacI2G_Luo` only needs to be defined for those species for which :code:`WD_LiqAndGas` is :literal:`true`, and is only used when the :cite:t:`Luo_et_al._2020` wet deposition scheme is activated. WD_RetFactor ------------ Specifies the retention efficiency :math:`R_i` of species in the liquid cloud condensate as it is converted to precipitation. :math:`R_i` < 1 accounts for volatization during riming. WD_AerScavEff ------------- Specifies the aerosol scavenging efficiency. This factor multiplies :math:`F`, the fraction of aerosol species that is lost to convective updraft scavenging. .. list-table:: :header-rows: 1 * - Value of :literal:`WD_AerScavEff` - Used for this type of aerosol * - 1.0 - Most aerosols * - 0.8 - Secondary organic aerosols * - 0.0 - Hydrophobic aerosols WD_KcScaleFac ------------- Specifies a temperature-dependent scale factor that is used to multiply :math:`K` (aka :math:`K_c`), the rate constant for conversion of cloud condensate to precipitation. :code:`WD_KcScaleFac` is defined as a 3-element vector: .. list-table:: :header-rows: 1 :widths: 33 33 34 * - Vector element - Multiplies this variable - In this temperature range * - :literal:`WD_KcScaleFac(1)` - :math:`K` - :math:`T \le 237\ K` * - :literal:`WD_KcScaleFac(2)` - :math:`K` - :math:`237 \ K \le T \lt 258 \ K` * - :literal:`WD_KcScaleFac(3)` - :math:`K` - :math:`T \ge 258 \ K` WD_KcScaleFac_Luo ----------------- Specifies a temperature-dependent scale factor that is used to multiply :math:`K`, aka :math:`K_c`, the rate constant for conversion of cloud condensate to precipitation. Used only in the Luo wet deposition scheme (cf. :cite:t:`Luo_et_al._2020`, :cite:t:`Luo_and_Yu_2023`). :code:`WD_KcScaleFac_Luo` is defined as a 3-element vector: .. list-table:: :header-rows: 1 :widths: 33 33 34 * - Vector element - Multiplies this variable - In this temperature range * - :literal:`WD_KcScaleFac_Luo(1)` - :math:`K` - :math:`T \le 237\ K` * - :literal:`WD_KcScaleFac_Luo(2)` - :math:`K` - :math:`237 \ K \le T \lt 258 \ K` * - :literal:`WD_KcScaleFac_Luo(3)` - :math:`K` - :math:`T \ge 258\ K` WD_RainoutEff ------------- Specifies a temperature-dependent scale factor that is used to multiply :math:`F_i` (aka :literal:`RAINFRAC`), the fraction of species scavenged by rainout. :code:`WD_RainoutEff` is defined as a 3-element vector: .. list-table:: :header-rows: 1 :widths: 33 33 34 * - Vector element - Multiplies this variable - In this temperature range * - :literal:`WD_RainoutEff(1)` - :math:`F_i` - :math:`T \le 237\ K` * - :literal:`WD_RainoutEff(2)` - :math:`F_i` - :math:`237 \ K \le T \lt 258 \ K` * - :literal:`WD_RainoutEff(3)` - :math:`F_i` - :math:`T \ge 258 \ K` 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 :math:`237 \le T < 258` kelvin. This can be easily done by setting :code:`RainoutEff(2) = 0`. .. note:: For SOA species, the maximum value of :code:`WD_RainoutEff` will be 0.8 instead of 1.0. WD_RainoutEff_Luo ----------------- Specifies a temperature-dependent scale factor that is used to multiply :math:`F_i` (aka :literal:`RAINFRAC`), the fraction of species scavenged by rainout. Used only in the Luo wet deposition scheme (cf. :cite:t:`Luo_et_al._2020`, :cite:t:`Luo_and_Yu_2023`). :code:`WD_RainoutEff_Luo` is defined as a 3-element vector: .. list-table:: :header-rows: 1 :widths: 33 33 34 * - Vector element - Multiplies this variable - In this temperature range * - :literal:`WD_RainoutEff_Luo(1)` - :math:`F_i` - :math:`T \le 237\ K` * - :literal:`WD_RainoutEff_Luo(2)` - :math:`F_i` - :math:`237 \ K \le T \lt 258 \ K` * - :literal:`WD_RainoutEff_Luo(3)` - :math:`F_i` - :math:`T \ge 258 \ K` 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 :math:`237 \le T < 258` kelvin. This can be easily done by setting :code:`RainoutEff(2) = 0`. .. note:: For SOA species, the maximum value of :code:`WD_RainoutEff_Luo` will be 0.8 instead of 1.0. WD_WashoutRainPara ------------------ Specifies terms used in the computation of the washout rate constant for dust aerosols by rain, as defined in :cite:t:`Zhang_et_al._2025`. This rate constant is computed as :math:`a \times P^b`, where :math:`P` is precipitation in :math:`mm \ h^{-1}`. :literal:`WD_WashoutRainPara` is defined as a 2-element vector: .. list-table:: :header-rows: 1 :widths: 33 33 34 * - Vector element - Description - Used in this temperature range * - :literal:`WD_WashoutSnowPara(1)` - Coefficient (:math:`a`) - :math:`T \ge 268\ K` * - :literal:`WD_RainoutEff_Luo(2)` - Exponent (:math:`b`) - :math:`T \ge 268\ K` WD_WashoutSnowPara ------------------ Specifies terms used in the computation of the washout rate constant for dust aerosols by snow, as defined in :cite:t:`Zhang_et_al._2025`. This rate constant is computed as :math:`a \times P^b`, where :math:`P` is precipitation in :math:`mm \ h^{-1}`. :literal:`WD_WashoutSnowPara` is defined as a 2-element vector: .. list-table:: :header-rows: 1 :widths: 33 33 34 * - Vector element - Description - Used in this temperature range * - :literal:`WD_WashoutSnowPara(1)` - Coefficient (:math:`a`) - :math:`T \lt 268\ K` * - :literal:`WD_RainoutEff_Luo(2)` - Exponent (:math:`b`) - :math:`T \lt 268\ K` .. _spcguide-defs-tracer: =========================== TransportTracers properties =========================== These properties are defined for species used in the :ref:`transport-sim`. We will refer to these species as **tracers**. .. _spcguide-defs-tracer-is-tracer: Is_Tracer --------- Indicates that the species is a transport tracer (:literal:`true`), or is not (:literal:`false`). .. _spcguide-defs-tracer-snk-horiz: Snk_Horiz --------- Specifies the horizontal domain of the tracer sink term. Allowable values are: .. list-table:: :header-rows: 1 :widths: 20 80 * - Value - Description * - all - The tracer sink term will be applied throughout the entire horizonatal domain of the simulation grid. * - lat_zone - The tracer sink term will be applied only within the latitude range specified by :ref:`spcguide-defs-tracer-snk-lats`. .. _spcguide-defs-tracer-snk-lats: Snk_Lats -------- Defines the latitude range :literal:`[min_latitude, max_latitude]` for the tracer sink term. Will only be used if :ref:`spcguide-defs-tracer-snk-horiz` is set to :literal:`lat_zone`. .. _spcguide-defs-tracer-snk-mode: Snk_Mode -------- Specifies how the tracer sink term will be applied. Allowable values are: .. list-table:: :header-rows: 1 :widths: 20 80 * - Value - Description * - constant - The tracer sink term is a constant value (specified by :ref:`spcguide-defs-tracer-snk-value`). * - efolding - The tracer sink term has an e-folding decay constant (specified in :ref:`spcguide-defs-tracer-snk-period`). * - halflife - The tracer sink term has a half-life (specified in :ref:`spcguide-defs-tracer-snk-period`). * - none - The tracer does not have a sink term. .. _spcguide-defs-tracer-snk-period: Snk_Period ---------- Specifies the period (in days) for which the tracer sink term will be applied. .. _spcguide-defs-tracer-snk-value: Snk_Value --------- Specifies a value for the tracer sink term. .. _spcguide-defs-tracer-snk-vert: Snk_Vert -------- Specifies the vertical domain of the tracer sink term. Allowable values are: .. list-table:: :header-rows: 1 :widths: 20 80 * - Value - Description * - all - The tracer sink term will be applied throughout the entire vertical domain of the simulation grid. * - boundary_layer - The tracer sink term will only be applied within the planetary boundary layer. * - surface - The tracer sink term will only be applied at the surface. * - troposphere - The tracer sink term will only be applied within the troposphere. .. _spcguide-defs-tracer-src-add: Src_Add ------- Specifies whether the tracer has a source term (:literal:`true`) or not (:literal:`false`). .. _spcguide-defs-tracer-src-horiz: Src_Horiz --------- Specifies the horizontal domain of the tracer source term. Allowable values are: .. list-table:: :header-rows: 1 :widths: 20 80 * - Value - Description * - all - The tracer source term will be applied across the entire horizontal extent of the simulation grid. * - lat_zone - The tracer source term will only be applied within the latitude range specified by :ref:`spcguide-defs-tracer-src-lats` .. _spcguide-defs-tracer-src-lats: Src_Lats -------- Defines the latitude range :literal:`[min_latitude, max_latitude]` for the tracer source term. Will only be applied if :ref:`spcguide-defs-tracer-src-horiz` is set to :literal:`lat_zone`. .. _spcguide-defs-tracer-src-mode: Src_Mode -------- Describes the type of tracer source term. Allowable values are: .. list-table:: :header-rows: 1 :widths: 30 70 * - Value - Description * - constant - The tracer source term is a constant value (specified by :ref:`spcguide-defs-tracer-src-value`). * - decay_of_another_species - The tracer source term comes from the decay of another species (e.g. Pb210 source comes from Rn222 decay). * - HEMCO - The tracer source term will be read from a file via HEMCO. * - maintain_mixing_ratio - The tracer source term will be calculated as needed to maintain a constant mixing ratio at the surface. * - none - The tracer does not have a source term. .. _spcguide-defs-tracer-src-unit: Src_Unit -------- Specifies the unit of the source term that will be applied to the tracer. .. list-table:: :header-rows: 1 :widths: 20 80 * - Value - Description * - ppbv - The source term has units of parts per billion by volume. * - timestep - The source term has units of per emissions timestep. .. _spcguide-defs-tracer-src-value: Src_Value --------- Specifies a value for the tracer source term in :ref:`spcguide-defs-tracer-src-unit`. .. _spcguide-defs-tracer-src-vert: Src_Vert -------- Specifies the vertical domain of the tracer source term. Allowable values are: .. list-table:: :header-rows: 1 :widths: 20 80 * - Value - Description * - all - The tracer source term will be applied throughout the entire vertical domain of the simulation grid. * - pressures - The tracer source term will only be applied within the pressure range specified in :ref:`spcguide-defs-tracer-src-pressures`. * - stratosphere - The tracer source term will only be applied in the stratosphere. * - troposphere - The tracer source term will only be applied in the troposphere. * - surface - The tracer source term will only be applied at the surface. .. _spcguide-defs-tracer-src-pressures: Src_Pressures ------------- Defines the pressure range :literal:`[min_pressure, max_pressure]`, in hPa for the tracer source term. Will only be used if :ref:`spcguide-defs-tracer-src-vert` is set to :literal:`pressures`. .. _spcguide-defs-tracer-units: Units ----- Specifies the default units of the tracers (e.g. :literal:`aoa`, :literal:`aoa_nh`, :literal:`aoa_bl` are carried in units :literal:`days`, while all other species in GEOS-Chem are :literal:`kg/kg dry air`). .. _spcguide-defs-tracer-prop: Properties used by each transport tracer ---------------------------------------- The list below shows the various :ref:`transport tracer properties ` that are used in the current TransportTracers simulation. .. code-block:: none Is_Tracer - true : all Snk_Horiz: - lat_zone : aoa_nh - all : all others Snk_Lats - 30 50 : aoa_nh Snk_Mode - constant : aoa, aoa_bl, aoa_nh - efolding : CH3I, CO_25 - none : SF6 - halflife : Be7, Be7s, Be10, Be10s Snk_Period (days) - 5 : CH3I - 25 : CO_25 - 50 : CO_50 - 90 : e90, e90_n, e90_s - 11742.8 : Pb210, Pb210s - 5.5 : Rn222 - 53.3 : Be7, Be7s - 5.84e8 : Be10, Be10s Snk_Value - 0 : aoa, aoa_bl, aoa_nh Snk_Vert - boundary_layer : aoa_bl - surface : aoa, aoa_nh - troposphere : stOx - all : all others Src_Add - false : Passive, stOx, st80_25 - true : all others Src_Horiz - lat_zone : e90_n, e90_s, nh_5, nh_50 - all : all others Src_Lats - [ 40.0, 91.0] : e90_n - [-91.0, -40.0] : e90_s - [ 30.0, 50.0] : nh_5, nh_50 Src_Mode - constant : aoa, aoa_bl, aoa_nh, nh_50, nh_5, st80_25 - file2d : CH3I, CO_25, CO_50, Rn222, SF6 - HEMCO - file3d : Be10, Be7 - HEMCO - maintain_mixing_ratio : e_90, e90_n, e90_s - decay_of_another_species : Pb210, Pb210s Src_Unit - ppbv : e90, e90_n, e90_s, st80_25 - timestep : aoa, aoa_bl, aoa_nh Src_Value - 1 : aoa, aoa_bl, aoa_nh - 100 : e90, e90_n, e90_s - 200 : st80_25 Src_Vert - all : aoa, aoa_bl, aoa_nh, Pb210 - pressures : st80_25 - stratosphere : Be10s, Be7s, Pb210s, stOx - surface : all others (not specified when Src_Mode: HEMCO) Src_Pressures - [0, 80] : st80_25 Units - days : aoa, aoa_bl, aoa_bl .. _spcguide-defs-other: ================ Other properties ================ .. _spcguide-defs-other-bkgdvv: BackgroundVV ------------ If a restart file does not contain an global initial concentration field for a species, GEOS-Chem will attempt to set the initial concentration (in :math:`vol\ vol^{-1}` dry air) to the value specified in :code:`BackgroundVV` globally. But if :code:`BackgroundVV` has not been specified, GEOS-Chem will set the initial concentration for the species to :math:`10^{-20} vol\ vol^{-1}` dry air instead. .. note:: Recent versions of GCHP may require that all initial conditions for all species to be used in a simulation be present in the restart file. See `gchp.readthedocs.io `_ for more information. MP_SizeResAer ------------- Indicates that the species is a size-resolved aerosol species (:literal:`true`), or isn't (:literal:`false`). Used only by simulations using either `APM `_ or `TOMAS `_ microphysics packages. MP_SizeResNum ------------- Indicates that the species is a size-resolved aerosol number (:literal:`true`), or isn't (:literal:`false`). Used only by simulations using either `APM `_ or `TOMAS `_ microphysics packages. .. _spcguide-using: ====================================== Access species properties in GEOS-Chem ====================================== In this section we will describe the derived types and objects that are used to store GEOS-Chem species properties. We will also describe how you can extract species properties from the GEOS-Chem Species Database when you create new GEOS-Chem code routines. .. _spcguide-access-spctype: The Species derived type ------------------------- The `Species `_ derived type (defined in module :file:`Headers/species_mod.F90`) describes a complete set of properties for a single GEOS-Chem species. In addition to the fields mentioned in the preceding sections, the :code:`Species` derived type also contains several species indices. .. list-table:: Indices stored in the :code:`Species` derived type :header-rows: 1 :widths: 25 75 :align: center * - Index - Description * - :code:`ModelId` - Model species index * - :code:`AdvectId` - Advected species index * - :code:`AerosolId` - Aerosol species index * - :code:`DryAltId` - Dry dep species at altitude Id * - :code:`DryDepId` - Dry deposition species index * - :code:`GasSpcId` - Gas-phase species index * - :code:`HygGrthId` - Hygroscopic growth species index * - :code:`KppVarId` - KPP variable species index * - :code:`KppFixId` - KPP fixed spcecies index * - :code:`KppSpcId` - KPP species index * - :code:`PhotolId` - Photolyis species index * - :code:`RadNuclId` - Radionuclide index * - :code:`TracerId` - Transport tracer index * - :code:`WetDepId` - Wet deposition index .. _spcguide-access-spcptrtype: The SpcPtr derived type ----------------------- The `SpcPtr `_ derived type (also defined in :file:`Headers/species_mod.F90`) describes a container for an object of type :ref:`Species `. .. code-block:: fortran TYPE, PUBLIC :: SpcPtr TYPE(Species), POINTER :: Info ! Single entry of Species Database END TYPE SpcPtr .. _spcguide-access-spcdata: The GEOS-Chem Species Database object ------------------------------------- The GEOS-Chem Species database is stored in the :code:`State_Chm%SpcData` object. It describes an array, where each element of the array is of type :ref:`SpcPtr ` (which is a container for an object of type type :ref:`Species `. .. code-block:: fortran TYPE(SpcPtr), POINTER :: SpcData(:) ! GC Species database .. _spcguide-access-lookup-ind: Species index lookup with Ind_() -------------------------------- Use function :code:`Ind_()` (in module :code:`Headers/state_chm_mod.F90`) to look up species indices by name. For example: .. code-block:: fortran SUBROUTINE MySub( ..., State_Chm, ... ) USE State_Chm_Mod, ONLY : Ind_ ! Local variables INTEGER :: id_O3, id_Br2, id_CO ! Find tracer indices with function the Ind_() function id_O3 = Ind_( 'O3' ) id_Br2 = Ind_( 'Br2' ) id_CO = Ind_( 'CO' ) ! Print tracer concentrations print*, 'O3 at (23,34,1) : ', State_Chm%Species(id_O3 )%Conc(23,34,1) print*, 'Br2 at (23,34,1) : ', State_Chm%Species(id_Br2)%Conc(23,34,1) print*, 'CO at (23,34,1) : ', State_Chm%Species(id_CO )%Conc(23,34,1) ! Print the molecular weight of O3 (obtained from the Species Database object) print*, 'Mol wt of O3 [g]: ', State_Chm%SpcData(id_O3)%Info%MW_g END SUBROUTINE MySub Once you have obtained the species ID (aka :code:`ModelId`) you can use that to access the individual fields in the Species Database object. In the example above, we use the species ID for :literal:`O3` (stored in :code:`id_O3`) to look up the molecular weight of :literal:`O3` from the Species Database. You may search for other model indices with :code:`Ind_()` by passing an optional second argument: .. code-block:: fortran ! Position of HNO3 in the list of advected species AdvectId = Ind_( 'HNO3', 'A' ) ! Position of HNO3 in the list of gas-phase species AdvectId = Ind_( 'HNO3', 'G' ) ! Position of HNO3 in the list of dry deposited species DryDepId = Ind_( 'HNO3', 'D' ) ! Position of HNO3 in the list of wet deposited species WetDepId = Ind_( 'HNO3', 'W' ) ! Position of HNO3 in the lists of fixed KPP, active, & overall KPP species KppFixId = Ind_( 'HNO3', 'F' ) KppVarId = Ind_( 'HNO3', 'V' ) KppVarId = Ind_( 'HNO3', 'K' ) ! Position of SALA in the list of hygroscopic growth species HygGthId = Ind_( 'SALA', 'H' ) ! Position of Pb210 in the list of radionuclide species HygGthId = Ind_( 'Pb210', 'N' ) ! Position of ACET in the list of photolysis species PhotolId = Ind( 'ACET', 'P' ) :code:`Ind_()` will return -1 if a species does not belong to any of the above lists. .. tip:: For maximum efficiency, we recommend that you use :code:`Ind_()` to obtain the species indices during the initialization phase of a GEOS-Chem simulation. This will minimize the number of name-to-index lookup operations that need to be performed, thus reducing computational overhead. Implementing the tip mentioned above: .. code-block:: fortran MODULE MyModule IMPLICIT NONE . . . ! Species ID of CO. All subroutines in MyModule can refer to id_CO. INTEGER, PRIVATE :: id_CO CONTAINS . . . other subroutines . . . SUBROUTINE Init_MyModule ! This subroutine only gets called at startup . . . ! Store ModelId in the global id_CO variable id_CO = Ind_('CO') . . . END SUBROUTINE Init_MyModule END MODULE MyModule .. _spcguide-access-loop: Species lookup within a loop ---------------------------- If you need to access species properties from within a loop, it is better not to use the :code:`Ind_()` function, as repeated name-to-index lookups will incur computational overhead. Instead, you can access the species properties directly from the GEOS-Chem Species Database object, as shown here. .. code-block:: fortran SUBROUTINE MySub( ..., State_Chm, ... ) !%%% MySub is an example of species lookup within a loop %%% ! Uses USE Precision_Mod USE State_Chm_Mod, ONLY : ChmState USE Species_Mod, ONLY : Species ! Chemistry state object (which also holds the species database) TYPE(ChmState), INTENT(INOUT) :: State_Chm ! Local variables INTEGER :: N TYPE(Species), POINTER :: ThisSpc INTEGER :: ModelId, DryDepId, WetDepId REAL(fp) :: Mw_g REAL(f8) :: Henry_K0, Henry_CR, Henry_pKa ! Loop over all species DO N = 1, State_Chm%nSpecies ! Point to the species database entry for this species ! (this makes the coding simpler) ThisSpc => State_Chm%SpcData(N)%Info ! Get species properties ModelId = ThisSpc%ModelId DryDepId = ThisSpc%DryDepId WetDepId = ThisSpc%WetDepId MW_g = ThisSpc%MW_g Henry_K0 = ThisSpc%Henry_K0 Henry_CR = ThisSpc%Henry_CR Henry_pKa = ThisSpc%Henry_pKA IF ( ThisSpc%Is_Gas ) ! ... The species is a gas-phase species ! ... so do something appropriate ELSE ! ... The species is an aerosol ! ... so do something else appropriate ENDIF IF ( ThisSpc%Is_Advected ) THEN ! ... The species is advected ! ... (i.e. undergoes transport, PBL mixing, cloud convection) ENDIF IF ( ThisSpc%Is_DryDep ) THEN ! ... The species is dry deposited ENDIF IF ( ThisSpc%Is_WetDep ) THEN ! ... The species is soluble and wet deposits ! ... it is also scavenged in convective updrafts ! ... it probably has defined Henry's law properties ENDIF ... etc ... ! Free the pointer ThisSpc => NULL() ENDDO END SUBROUTINE MySub