MICM MPAS Coupling

MICM ↔ MPAS tracer coupling plan

Goals

• Couple MICM state concentrations to MPAS tracers so chemistry operates on the prognostic tracer fields.
• Resize MICM state from a single-column (nVertLevels) layout to all local cells and levels (nCells × nVertLevels).
• Introduce explicit data-move hooks: MICM_from_MPAS before the MICM solve and MICM_to_MPAS after the solve.
• Preserve MPAS time-integration expectations (state/tendency handling, halos) and keep the design per-block and thread-safe.

Current state and gaps

• chemistry_init (chemistry/mpas_atm_chemistry.F) now forwards registry tracer names into musica_init for consistency checks but still passes only nVertLevels, so MICM allocates for one vertical column.
• No use of MPAS tracers (scalars(num_scalars,nVertLevels,nCells)) inside MICM; MICM state is seeded from hard-coded values (ABBA demo) and never synced back.
• chemistry_step(dt) has no access to block/state pools, so it cannot read or write tracer data.

Data layout decision

• Treat one MICM grid_cell as one (iCell,k) pair; flatten with cell_idx = (iCell - 1) * nVertLevels + k so vertical levels stay contiguous within each horizontal cell (matches MPAS memory order).
• MICM state%concentrations will be sized num_species × (nCells_local * nVertLevels) using state%species_strides%grid_cell for addressing.

Species ↔ tracer mapping

• Build a mapping at init between MICM state%species_ordering%name(:) and MPAS tracer indices.
  • Primary source: tracer names from the scalars var_array metadata (constituentNames) if available.
  • Fallback/config: add a namelist list such as config_micm_tracers (ordered by MICM species) to break ties when metadata is missing.
• Validate one-to-one coverage; log and abort on missing or duplicate mappings.
• Store mapping with molar masses/units flags to drive conversions and avoid repeated lookups inside time-critical loops.

API changes

• Update chemistry_init to take block context (block list or domain) so it can read nCells, nVertLevels, num_scalars, and tracer metadata.
• Allocate one MICM object per block (or per rank-block) and call micm%get_state(local_nCells * nVertLevels, error) instead of nVertLevels.
• Change chemistry_step signature to accept the block list/state pools and dt, enabling direct access to tracers and thermodynamic fields.
• Keep musica_init/step/finalize thin wrappers but move data-motion logic into new helpers inside mpas_musica or a dedicated coupling module.

Data transfer routines

• MICM_from_MPAS(block_ctx, mapping, scalars, rho_zz, temperature, pressure, dt_context)
  • Loop (iCell,k); compute cell_idx; copy tracer values into state%concentrations.
  • Apply unit conversion if MICM expects number density (mixing ratio → mass density → number density using rho/mean molar mass, pressure/temperature if needed).
  • Optionally update MICM temperature/pressure/rate-parameter fields if the MICM API exposes setters.
• MICM_to_MPAS(block_ctx, mapping, scalars [, scalars_tend])
  • Read MICM concentrations back to MPAS mixing ratios (inverse conversion).
  • Choose update mode:
    • In-place state update of scalars(:,k,iCell) at time level 2 before advection, or
    • Fill scalars_tend so dynamics applies tendencies consistently with other physics.
  • Enforce non-negative tracer bounds and accumulate simple conservation diagnostics (per-cell sum, optional log for first few cells).

Per-timestep flow

• In atm_do_timestep chemistry branch:
  • For each local block:
    • Call MICM_from_MPAS to refresh MICM state from current tracers (and thermodynamics if required).
    • Call micm%solve(dt, state, ...) on the block-local MICM object.
    • Call MICM_to_MPAS to write back tracer updates.
  • Trigger the appropriate halo exchange group for scalars if dynamics expects up-to-date halos before advection.
• Ensure ordering plays well with physics tendencies (currently physics runs before chemistry); revisit if chemistry should contribute to shared tendency arrays instead of direct state modification.

Units and conservation

• Confirm MICM configuration units (mixing ratio vs. molec cm^-3). Add a conversion utility used by both transfer routines.
• Use dry-air vs. moist-air density consistently with MPAS tracer definitions (scalars are mass mixing ratios).
• Add optional mass budget diagnostics comparing sum over mapped tracers before/after MICM.

Testing and validation

• Add lightweight driver/test that initializes MICM with a few mapped tracers, runs one chemistry step, and checks mapping integrity and sign preservation.
• Compile-time check: build succeeds when MPAS_USE_MUSICA is on and chem is enabled.
• Runtime smoke test: short run with MICM enabled and multiple cells/levels; inspect log for correct grid-cell count and mapping summary.

Open questions/decisions

• Where to source authoritative tracer names (input fields vs. namelist) and how to keep them in sync with MICM configuration files.
• Final choice between in-place tracer updates and tendency-based updates for chemistry.
• Whether MICM needs per-level temperature/pressure inputs; if yes, integrate those fields into the transfer routines now rather than later.