Concepts

Concepts#

MIAM (Model-Independent Aerosol Module) is organized around three core abstractions: Representations, Processes, and the Model that orchestrates them.

Architecture Overview#

┌─────────────────────────────────────┐
│            MICM Solver              │
│       (Rosenbrock, BDF, etc.)       │
├─────────────────────────────────────┤
│  ExternalModelProcessSet interface  │
│    ForcingFunction(params, vars)    │
│    JacobianFunction(params, vars)   │
├─────────────────────────────────────┤
│            MIAM Model               │
│  ┌───────────────┐ ┌──────────────┐ │
│  │Representations│ │  Processes   │ │
│  │               │ │              │ │
│  │ - Modes       │ │ - Dissolved  │ │
│  │ - Sections    │ │   Reactions  │ │
│  │               │ │ - Phase      │ │
│  │ Providers:    │ │   Transfer   │ │
│  │  r_eff, N,    │◄┤              │ │
│  │  φ_p          │ │              │ │
│  └───────────────┘ └──────────────┘ │
└─────────────────────────────────────┘

Representations#

A representation describes a particle size distribution. It owns a set of phases (e.g., aqueous, organic), each containing species whose concentrations are state variables. Representations provide:

  • State variables — species concentrations plus (for TwoMomentMode) a number concentration variable.

  • State parameters — fixed distribution parameters (geometric mean radius, geometric standard deviation, section bounds).

  • Aerosol property providers — functions that compute effective radius, number concentration, and phase volume fraction from the state, along with their partial derivatives for the Jacobian.

MIAM provides three representation types:

Type

Description

SingleMomentMode

Log-normal distribution with fixed size parameters (GMD, GSD). Number concentration is diagnosed from total volume.

TwoMomentMode

Log-normal distribution with prognostic number concentration. Effective radius depends on both volume and number.

UniformSection

Sectional bin with fixed radius bounds. Number concentration is diagnosed from total volume.

Processes#

A process describes a transformation of species concentrations. Each process implements a common interface that provides:

  • Forcing function — the ODE right-hand side contribution.

  • Jacobian function — the partial derivatives of the forcing with respect to state variables (stored as −J per MICM convention).

  • State parameter management — temperature-dependent rate constants are updated each time step before the solver iterates.

Processes can require aerosol properties from representations. When they do, the Model automatically builds and routes the appropriate providers.

MIAM currently provides two process types:

Type

Description

DissolvedReversibleReaction

Equilibrium reactions within a condensed phase (e.g., H₂O ⇌ OH⁻ + H⁺). Does not require aerosol properties.

HenryLawPhaseTransfer

Gas ⇌ condensed-phase mass transfer governed by Henry’s Law. Requires effective radius, number concentration, and phase volume fraction from the representation.

Model#

The Model is the top-level container. It:

  1. Stores representations and processes.

  2. Collects all state variable and parameter names for the solver.

  3. Builds aerosol property providers by matching process requirements to the representations that own each phase prefix.

  4. Returns forcing and Jacobian functions that iterate over all processes in a single loop.

A Model is registered with MICM as an ExternalModelSystem and ExternalModelProcessSet, making MIAM’s state seamlessly part of the coupled solver state.

Data Flow#

Each solver time step follows this sequence:

  1. Conditions update — the host model sets temperature and pressure on the MICM State.

  2. Rate constant calculation — solver.CalculateRateConstants(state) calls MIAM’s UpdateStateParametersFunction, which evaluates temperature-dependent constants (HLC, K_eq, k_f, k_r) and writes them into state parameter columns.

  3. Solver iteration — the Rosenbrock solver calls MIAM’s ForcingFunction and JacobianFunction at each internal stage. These functions:

    1. Query aerosol property providers for r_eff, N, φ_p (and their partial derivatives, for the Jacobian).

    2. Compute condensation/evaporation rates.

    3. Accumulate forcing terms and Jacobian entries.

  4. State update — the solver writes the updated concentrations back into the State object.

Species Naming Convention#

State variable names follow a hierarchical pattern:

<mode_name>.<phase_name>.<species_name>

For example, a model named "CLOUD" with a SingleMomentMode named "DROPLET" containing an aqueous phase produces variables like:

  • DROPLET.AQUEOUS.CO2

  • DROPLET.AQUEOUS.H2O

Gas-phase species are registered directly by MICM with their short name (e.g., CO2). When passed to MICM’s System constructor, the model name is not prepended — only the representation and phase names form the prefix.

Two-moment modes also introduce a number concentration variable:

  • AITKEN.number_concentration