GCPM: GEOS-Chem PM2.5 Calculator

GCPM: GEOS-Chem PM2.5 Calculator#

GCPM is a Python tool that calculates fine particulate matter (PM2.5) mass concentrations from GEOS-Chem chemical transport model output. It converts species volume mixing ratios (VMR) to mass concentrations in μg/m3 and aggregates them into PM2.5 components.

See the GCPM GitHub repository for full documentation covering the calculation method, species categories, scheme variants, PM2.5 size cuts, optional species (HMS, INDIOL), the ALT1 surface diagnostic, and AOD calculation.

For help with GCPM, contact Yuanjian Zhang.

Quick start#

Clone the repository:

$ git clone https://github.com/yuanjianz/GCPM.git

Basic usage:

from GCPM import AerosolCalculator

calculator = AerosolCalculator(ds)        # schemes auto-detected from ds
pm25 = calculator.calculate_mass('PM25')  # total PM2.5 (wet), in ug/m3

calculate_mass accepts a single name or a list, and returns an xarray.Dataset whose variables are prefixed AeroMassFine_* (units: μg/m3):

# Individual species and common groups
out = calculator.calculate_mass(['SO4', 'SIA', 'POA', 'SOA', 'BC', 'Dust', 'SS'])

# Dry (no hygroscopic growth) — dry is a runtime option, not a constructor flag
pm25_dry = calculator.calculate_mass('PM25', dry=True)

AerosolCalculator parameters#

calculator = AerosolCalculator(
    ds,                          # xarray Dataset read from GEOS-Chem diagnostic
    poa_scheme="auto",           # "auto" | "SVPOA" | "NVPOA"
    soa_scheme="auto",           # "auto" | "simple" | "complex"
    dust_scheme="auto",          # "auto" | "DEAD" | "L23"
    use_alt="auto",              # "auto" | True | False
    include_hms=False,           # Include HMS in SIA
    include_indiol=False,        # Include INDIOL in SOA
    growth_factors=None,         # Override dict, e.g. {"SIA": 1.05, "ORG": 1.02, "SS": 1.2}
    omoc_ratios=None,            # Override dict, e.g. {"POA": 1.6, "OPOA": 2.3}
)

The "auto" defaults let GCPM pick a reasonable configuration by probing variable names in the dataset, so most users don’t need to set these explicitly:

  • poa_scheme — Primary organic aerosol scheme. "auto" selects "SVPOA" (semi-volatile, POA1/POA2/OPOA1/OPOA2) if SpeciesConcVV_POA1 is in the dataset, or "NVPOA" (non-volatile, OCPO/OCPI) if SpeciesConcVV_OCPI is present.

  • soa_scheme — Secondary organic aerosol scheme. "auto" selects "complex" (volatility basis set: ASOA, TSOA, SOAIE, SOAGX, LVOCOA) if SpeciesConcVV_ASOA1 is in the dataset, or "simple" (lumped SOAS) if SpeciesConcVV_SOAS is present.

  • dust_scheme — Dust binning. "auto" selects "L23" (7-bin Kok et al. scheme) if SpeciesConcVV_DSTbin1 is present, otherwise "DEAD" (4-bin DEAD scheme).

  • use_alt — Whether to read SpeciesConcALT1_* fields (surface concentrations derived via dry deposition, available for secondary species only). "auto" enables this when ALT1 fields are present in the dataset. Pass True/False to force on/off.

  • include_hms — Include hydroxymethanesulfonate (HMS) in SIA. Off by default because its classification as PM2.5 depends on the analysis context.

  • include_indiol — Include INDIOL (hydrolysis product of organonitrates) in SOA under the complex scheme. Off by default because current GEOS-Chem treatment likely overestimates isoprene-derived organic aerosol.

  • growth_factors — Override hygroscopic growth factors per group (SIA, ORG, SS) for sensitivity analysis. Defaults are loaded from species_config.yaml.

  • omoc_ratios — Override OM/OC ratios per POA subtype (POA, OPOA, SOA). Defaults are loaded from species_config.yaml.

A legacy AeroMassFine(ds, spcs, dry=False, **kwargs) wrapper is also available for backward compatibility; extra keyword arguments are forwarded to AerosolCalculator.

Contents