Processes

DissolvedReversibleReaction

class DissolvedReversibleReaction

A dissolved reversible reaction.

Dissolved reversible reactions involve reactants and products in solution, and are characterized by both a forward and reverse rate constant. If an equilibrium constant is provided, only one of the forward or reverse rate constants needs to be specified, and the other is computed from the equilibrium constant.

The reaction takes the form: \( \mathrm{Reactants} \leftrightarrow \mathrm{Products} \)

with forward rate constant \( k_f \) and reverse rate constant \( k_r \). The relationship between the rate constants and the equilibrium constant \( K_{eq} \) is: \( K_{eq} = \frac{k_f}{k_r} = \frac{\prod[\mathrm{Products}]}{\prod[\mathrm{Reactants}]} \).

Both \( k_f \) and \( k_r \) are in units of s⁻¹ after the solvent-normalization conversion from literature molar units: \( k_f = k_{f,lit} \times c_{H_2O}^{n_r - 1} \), \( k_r = k_{r,lit} \times c_{H_2O}^{n_p - 1} \) where \( c_{H_2O} = 55.556 \) mol/L. \( K_{eq} \) is dimensionless: \( K_{eq} = K_{lit} / c_{H_2O}^{n_p - n_r} \).

Public Functions

DissolvedReversibleReaction() = delete

inline DissolvedReversibleReaction(std::function<double(const micm::Conditions &conditions)> forward_rate_constant, std::function<double(const micm::Conditions &conditions)> reverse_rate_constant, const std::vector<micm::Species> &reactants, const std::vector<micm::Species> &products, micm::Species solvent, micm::Phase phase, double solvent_floor = 1.0e-20)

Constructor.

inline DissolvedReversibleReaction CopyWithNewUuid() const

Create a copy of this reaction with a new UUID.

Returns:

A new DissolvedReversibleReaction with the same properties but a unique UUID

inline std::set<std::string> ProcessParameterNames(const std::map<std::string, std::set<std::string>> &phase_prefixes) const

Returns a set of unique parameter names for this process.

Parameters:

phase_prefixes – Map of phase names to sets of state variable prefixes (prefix does not include phase or species names)

Returns:

Set of unique parameter names for this process

inline std::set<std::string> SpeciesUsed(const std::map<std::string, std::set<std::string>> &phase_prefixes) const

Returns participating species’ unique state names.

Parameters:

phase_prefixes – Map of phase names to sets of state variable prefixes (prefix does not include phase or species names)

Returns:

Set of unique state variable names for all species involved in the reaction

inline std::map<std::string, std::vector<AerosolProperty>> RequiredAerosolProperties() const

Returns the aerosol properties required by this process.

DissolvedReversibleReaction does not depend on aerosol properties.

Returns:

Empty map

inline std::set<std::pair<std::size_t, std::size_t>> NonZeroJacobianElements(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_variable_indices) const

Returns a set of Jacobian index pairs for this process.

Parameters:

• phase_prefixes – Map of phase names to sets of state variable prefixes (prefix does not include phase or species names)

• state_variable_indices – Map of state variable names to their corresponding indices in the Jacobian

Returns:

Set of index pairs representing the Jacobian entries affected by this process (dependent, independent)

template<typename DenseMatrixPolicy>
inline std::set<std::pair<std::size_t, std::size_t>> NonZeroJacobianElements(const std::map<std::string, std::set<std::string>> &phase_prefixes, const std::unordered_map<std::string, std::size_t> &state_variable_indices, const std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>>&) const

Returns non-zero Jacobian elements (common interface overload accepting providers)

Delegates to the existing two-argument version; providers are unused.

template<typename DenseMatrixPolicy>
inline std::function<void(const std::vector<micm::Conditions>&, DenseMatrixPolicy&)> UpdateStateParametersFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices) const

Returns a function that updates state parameters for this process.

Parameters:

• phase_prefixes – Map of phase names to sets of state variable prefixes (prefix does not include phase or species names)

• state_parameter_indices – Map of state parameter names to their corresponding indices in the state parameter vector

Returns:

Function that updates state parameters for this process

template<typename DenseMatrixPolicy>
inline std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, DenseMatrixPolicy&)> ForcingFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices, const auto &state_variable_indices, std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>>) const

Returns a function that calculates the forcing terms for this process.

Parameters:

• phase_prefixes – Map of phase names to sets of state variable prefixes (prefix does not include phase or species names)

• state_parameter_indices – Map of state parameter names to their corresponding indices in the state parameter vector

• state_variable_indices – Map of state variable names to their corresponding indices in the state variable vector

Returns:

Function that calculates the forcing terms for this process

template<typename DenseMatrixPolicy>
inline std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, DenseMatrixPolicy&)> ForcingFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices, const auto &state_variable_indices) const

Returns a function that calculates the forcing terms for this process (original)

template<typename DenseMatrixPolicy, typename SparseMatrixPolicy>
inline std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, SparseMatrixPolicy&)> JacobianFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices, const auto &state_variable_indices, const SparseMatrixPolicy &jacobian, std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>>) const

Returns a function that calculates the Jacobian contributions for this process (common interface overload)

template<typename DenseMatrixPolicy, typename SparseMatrixPolicy>
inline std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, SparseMatrixPolicy&)> JacobianFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices, const auto &state_variable_indices, const SparseMatrixPolicy &jacobian) const

Returns a function that calculates the Jacobian contributions for this process (original)

Public Members

std::function<double(const micm::Conditions &conditions)> forward_rate_constant_

Forward rate constant function.

std::function<double(const micm::Conditions &conditions)> reverse_rate_constant_

Reverse rate constant function.

std::vector<micm::Species> reactants_

Reactant species.

std::vector<micm::Species> products_

Product species.

micm::Species solvent_

Solvent species.

micm::Phase phase_

Phase in which the reaction occurs.

std::string uuid_

Unique identifier for the reaction.

double solvent_floor_{1.0e-20}

Floor [mol m⁻³] added to [S] in ([S]+δ)^n denominator to prevent singularity as [S] → 0.

class DissolvedReversibleReactionBuilder

A dissolved reversible reaction builder.

Builder class for constructing DissolvedReversibleReaction objects.

Public Functions

DissolvedReversibleReactionBuilder() = default

inline DissolvedReversibleReactionBuilder &SetPhase(const micm::Phase &phase)

Sets the phase in which the reaction occurs.

inline DissolvedReversibleReactionBuilder &SetReactants(const std::vector<micm::Species> &reactants)

Sets the reactant species.

inline DissolvedReversibleReactionBuilder &SetProducts(const std::vector<micm::Species> &products)

Sets the product species.

inline DissolvedReversibleReactionBuilder &SetSolvent(const micm::Species &solvent)

Sets the solvent species.

inline DissolvedReversibleReactionBuilder &SetSolventFloor(double solvent_floor)

Sets the floor \(\delta\) [mol m⁻³] added to the solvent in the denominator to prevent singularity as \([S] \to 0\). Default: 1e-20.

inline DissolvedReversibleReactionBuilder &SetForwardRateConstant(const auto &forward_rate_constant)

Sets the forward rate constant function.

inline DissolvedReversibleReactionBuilder &SetReverseRateConstant(const auto &reverse_rate_constant)

Sets the reverse rate constant function.

inline DissolvedReversibleReactionBuilder &SetReverseRateConstant(const micm::ArrheniusRateConstantParameters &params)

Sets the reverse rate constant from Arrhenius parameters.

inline DissolvedReversibleReactionBuilder &SetEquilibriumConstant(const auto &equilibrium_constant)

Sets the equilibrium constant function.

inline DissolvedReversibleReaction Build() const

Builds and returns the DissolvedReversibleReaction object.

HenryLawPhaseTransfer

class HenryLawPhaseTransfer

Henry’s Law phase transfer process.

Represents the transfer of a gas-phase species into a condensed phase (and its re-evaporation) governed by Henry’s Law equilibrium. The net rate is:

d[A]_gas/dt = -φ_p · k_cond · [A]_gas + φ_p · k_evap · [A]_aq / f_v d[A]_aq/dt = +φ_p · k_cond · [A]_gas - φ_p · k_evap · [A]_aq / f_v

where k_evap = k_cond / (HLC · R · T), f_v = [solvent] · solvent_molecular_weight / solvent_density [m³ mol⁻¹], and φ_p is the phase volume fraction.

Public Functions

HenryLawPhaseTransfer() = delete

inline HenryLawPhaseTransfer(std::function<double(const micm::Conditions &conditions)> henry_law_constant, const micm::Species &gas_species, const micm::Species &condensed_species, const micm::Species &solvent, const micm::Phase &condensed_phase, double diffusion_coefficient, double accommodation_coefficient, double gas_molecular_weight, double solvent_molecular_weight, double solvent_density)

Constructor.

inline HenryLawPhaseTransfer CopyWithNewUuid() const

Create a copy with a new UUID.

inline std::set<std::string> ProcessParameterNames(const std::map<std::string, std::set<std::string>> &phase_prefixes) const

Returns unique parameter names for this process.

inline std::set<std::string> SpeciesUsed(const std::map<std::string, std::set<std::string>> &phase_prefixes) const

Returns participating species’ unique state names.

inline std::map<std::string, std::vector<AerosolProperty>> RequiredAerosolProperties() const

Returns the aerosol properties required by this process.

inline std::set<std::pair<std::size_t, std::size_t>> NonZeroJacobianElements(const std::map<std::string, std::set<std::string>> &phase_prefixes, const std::unordered_map<std::string, std::size_t> &state_variable_indices) const

Returns non-zero Jacobian element positions.

template<typename DenseMatrixPolicy>
inline std::set<std::pair<std::size_t, std::size_t>> NonZeroJacobianElements(const std::map<std::string, std::set<std::string>> &phase_prefixes, const std::unordered_map<std::string, std::size_t> &state_variable_indices, const std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>> &providers) const

Returns non-zero Jacobian elements (common interface overload with providers)

template<typename DenseMatrixPolicy>
inline std::function<void(const std::vector<micm::Conditions>&, DenseMatrixPolicy&)> UpdateStateParametersFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices) const

Returns a function that updates state parameters (HLC and temperature)

template<typename DenseMatrixPolicy>
inline std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, DenseMatrixPolicy&)> ForcingFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices, const auto &state_variable_indices, std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>> providers) const

Returns a function that calculates the forcing terms (common interface with providers)

template<typename DenseMatrixPolicy, typename SparseMatrixPolicy>
inline std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, SparseMatrixPolicy&)> JacobianFunction(const std::map<std::string, std::set<std::string>> &phase_prefixes, const auto &state_parameter_indices, const auto &state_variable_indices, const SparseMatrixPolicy &jacobian, std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>> providers) const

Returns a function that calculates Jacobian contributions (common interface with providers)

Public Members

std::function<double(const micm::Conditions &conditions)> henry_law_constant_

HLC(T) function [mol m⁻³ Pa⁻¹].

micm::Species gas_species_

Gas-phase species.

micm::Species condensed_species_

Condensed-phase solute species.

micm::Species solvent_

Condensed-phase solvent species.

micm::Phase condensed_phase_

The condensed phase.

double diffusion_coefficient_

Gas-phase diffusion coefficient [m² s⁻¹].

double accommodation_coefficient_

Mass accommodation coefficient [dimensionless].

double gas_molecular_weight_

Gas-phase molecular weight [kg mol⁻¹].

double solvent_molecular_weight_

Solvent molecular weight [kg mol⁻¹].

double solvent_density_

Solvent density [kg m⁻³].

std::string uuid_

Unique identifier.

class HenryLawPhaseTransferBuilder

Builder for HenryLawPhaseTransfer processes.

Public Functions

HenryLawPhaseTransferBuilder() = default

inline HenryLawPhaseTransferBuilder &SetCondensedPhase(const micm::Phase &phase)

Sets the condensed phase in which the solute dissolves.

inline HenryLawPhaseTransferBuilder &SetGasSpecies(const micm::Species &species)

Sets the gas-phase species.

inline HenryLawPhaseTransferBuilder &SetCondensedSpecies(const micm::Species &species)

Sets the condensed-phase solute species.

inline HenryLawPhaseTransferBuilder &SetSolvent(const micm::Species &solvent)

Sets the condensed-phase solvent species.

inline HenryLawPhaseTransferBuilder &SetHenrysLawConstant(const auto &henry_law_constant)

Sets the Henry’s Law constant.

inline HenryLawPhaseTransferBuilder &SetDiffusionCoefficient(double diffusion_coefficient)

Sets the gas-phase diffusion coefficient [m² s⁻¹].

inline HenryLawPhaseTransferBuilder &SetAccommodationCoefficient(double accommodation_coefficient)

Sets the mass accommodation coefficient [dimensionless, 0–1].

inline HenryLawPhaseTransfer Build() const

Builds and returns the HenryLawPhaseTransfer object.

MiamProcessSet

template<typename DenseMatrixPolicy, typename SparseMatrixPolicy>
struct MiamProcessSet

Type-erased wrapper around any MIAM process.

Follows the same pattern MICM uses for ExternalModelProcessSet. Allows the Model to store all process types in a single collection and iterate them generically through a common interface.

Template Parameters:

• DenseMatrixPolicy – The dense matrix type used for state data

• SparseMatrixPolicy – The sparse matrix type used for Jacobian data

Public Types

using PhaseMap = std::map<std::string, std::set<std::string>>

using IndexMap = std::unordered_map<std::string, std::size_t>

using ProviderMap = std::map<std::string, std::map<AerosolProperty, AerosolPropertyProvider<DenseMatrixPolicy>>>

Public Functions

template<typename ProcessType>
inline MiamProcessSet(ProcessType &&process)

Construct a MiamProcessSet from any process type that satisfies the common interface.

Template Parameters:

ProcessType – The concrete process type

Parameters:

process – The process instance to wrap

Public Members

std::function<std::set<std::string>(const PhaseMap&)> process_parameter_names_

std::function<std::set<std::string>(const PhaseMap&)> species_used_

std::function<std::map<std::string, std::vector<AerosolProperty>>()> required_aerosol_properties_

std::function<std::set<std::pair<std::size_t, std::size_t>>(const PhaseMap&, const IndexMap&, const ProviderMap&)> non_zero_jacobian_elements_

std::function<std::function<void(const std::vector<micm::Conditions>&, DenseMatrixPolicy&)>(const PhaseMap&, const IndexMap&)> update_state_parameters_function_

std::function<std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, DenseMatrixPolicy&)>(const PhaseMap&, const IndexMap&, const IndexMap&, ProviderMap)> get_forcing_function_

std::function<std::function<void(const DenseMatrixPolicy&, const DenseMatrixPolicy&, SparseMatrixPolicy&)>(const PhaseMap&, const IndexMap&, const IndexMap&, const SparseMatrixPolicy&, ProviderMap)> get_jacobian_function_