Features and Architecture

Features and Architecture

The coupling is configured by the MICM mechanism and MPAS namelist rather than by a fixed chemistry registry. The mechanism determines the chemical species, advected subset, reactions, tolerances, and host parameters that exist in a run.

Coupled step

MPAS dry-air MMR state
        |
        v
host fields + unit conversion ---> TUV-x photolysis
        |                              |
        +----------> MICM state <------+
                         ^
                         |
                  MIEM + lightning NOx
                         |
                         v
                    MICM solve
                         |
                         v
             MPAS dry-air MMR state

At initialization, CheMPAS-A reads the mechanism, queries MUSICA for species and rate ordering, injects the necessary MPAS variables, and resolves host-bound species. It seeds the chemistry tracers from the mechanism's initial concentrations only when all of them are empty: if any non-host-bound tracer already carries values, either spatial structure or a uniform nonzero background, no tracer is seeded. Configuration errors fail before the prognostic chemistry state is partially changed.

Runtime MPAS variables

The framework runtime-variable layer creates fields after the static Registry.xml has been processed. CheMPAS-A uses it for:

• MICM-selected q<species> scalars and their indices;
• j_<reaction> photolysis diagnostics;
• output-only vmr_<species> fields; and
• emis_<species> totals plus requested sector, category, and layer diagnostics.

Runtime fields participate in MPAS pools and streams like registered fields. Names are checked for collisions and invalid metadata before use.

Chemistry state and units

Advected chemistry scalars are dry-air mass mixing ratios in kg kg-1. CheMPAS-A converts those values to the molar concentrations required by MICM using dry-air density, then converts the solved state back. Total moist-air number density remains available for third-body chemistry.

The dry-air mass mixing ratios are authoritative for transport and restart. Requested volume-mixing-ratio units create diagnostics only; they never replace the transported state. Supported output units are fraction, percent, ppmv, ppbv, and pptv.

H2O is always bound read-only to MPAS qv; mechanism metadata can also bind O2 and N2 to host state. In the expanded global example, the third body M uses the cell-local air density, avoiding duplicate transported tracers.

MICM and MUSICA

config_micm_file activates chemistry and supplies the mechanism. CheMPAS-A supports:

• an adjustable MICM relative tolerance;
• multiple chemistry substeps inside one MPAS step;
• a chemistry interval independent of the dynamics step;
• an optional duplicate reference solve for coupling diagnostics; and
• a limit on consecutive recoverable step failures.

An empty mechanism path leaves chemistry inactive.

TUV-x photolysis

When config_tuvx_config_file is set, CheMPAS-A supplies TUV-x with MPAS temperature, pressure, air, O2, O3, height, solar geometry, and available cloud and rain opacity. TUV-x reaction names must exactly match MICM photolysis parameter names.

The upper-column choices are:

Mode	Required input	Purpose
none	none	Use only the model column
legacy_static	upper-atmosphere CSV	Apply one static profile to every column
spatial_climatology	exact-grid prescribed-field NetCDF	Interpolate a cyclic monthly upper-O3 field by cell

With TUV-x disabled, a positive config_j_no2_max drives jNO2 = jmax * max(0, cos(SZA)). A zero value supplies no photolysis parameters.

MIEM emissions

MIEM reads a MUSICA mechanism-configuration file containing an emissions section. CheMPAS-A supports multiple inventories and source groups, linear or nearest temporal interpolation, surface or configured layer profiles, and per-source scaling.

Runtime horizontal regridding is intentionally not performed. An inventory must already have the exact global MPAS cells and indexToCellID ordering. The coupling validates its mesh fingerprint/geometry and reads only the cells owned by each MPI rank.

By default, fluxes are nonnegative upward sources. Species explicitly listed in config_miem_net_flux_species may also have negative downward uptake. Integrated source mass is tracked through the conversion into tracer tendency.

Lightning NOx

The host parameterization injects an NO source, in ppbv s-1, into qNO; it does nothing if the mechanism has no qNO. Both modes apply the source only where vertical velocity exceeds config_lnox_w_threshold:

• altitude mode: a linear function of vertical velocity above the threshold, restricted to a height range above mean sea level; or
• isotherm mode: a constant source between configured temperature bounds.

An optional NOx loss timescale updates matching MICM LOSS.* parameters. A zero source rate disables lightning NOx.

MPI, I/O, and restart

Every rank derives the same species and parameter ordering from the mechanism file. MIEM and prescribed fields validate exact-grid identity against the distributed mesh. Restart reads preserve the transported chemistry scalars, while runtime diagnostics are reconstructed.

The current chemistry implementation requires one local MPAS block per MPI task. Multi-block chemistry stops with a fatal error. MIEM additionally requires a Gregorian calendar.