API Reference#

These are the public C++ types and functions of the library. Include <mechanism_configuration/mechanism_configuration.hpp> to use all of them.

Parse#

std::expected<Mechanism, Errors> mechanism_configuration::Parse(const std::filesystem::path &config_path)#

Parse a mechanism configuration file, dispatching on its version.

Parameters:: config_path – Path to a configuration file (a std::string converts implicitly), or a directory of version-0 CAMP files.
Returns:: The parsed Mechanism, or all structural and semantic errors encountered.

std::expected<Mechanism, Errors> mechanism_configuration::ParseFromString(const std::string &config)#

Validate#

Errors mechanism_configuration::Validate(const Mechanism &mechanism)#: Validates the semantic invariants of a canonical Mechanism, regardless of whether it was parsed or constructed in code. Combines ValidateGasModel, ValidateAerosolModel, and ValidateEmissionsModel, returning all validation errors.

Errors mechanism_configuration::ValidateGasModel(const Mechanism &mechanism)#: Validates a Mechanism’s species, phases, and gas-phase reactions by converting them to a location-free semantics::ReactionsInput and running ValidateReactionsSemantics.

Errors mechanism_configuration::ValidateAerosolModel(const Mechanism &mechanism)#: Validates aerosol cross-references against the mechanism’s species and phases. Checks phase/species references, representation-keyed rate-constant maps, and required definition-derived properties.

Errors mechanism_configuration::ValidateEmissionsModel(const Mechanism &mechanism)#: Validates a Mechanism’s emissions section by converting it to a location-free semantics::EmissionsInput and running ValidateEmissionsSemantics. Returns no errors if the mechanism has no emissions section.

Mechanism#

struct Mechanism#

Represents a full mechanism definition.

Public Members

std::string name#: Mechanism name (optional)

Version version#: Version of the mechanism configuration format used, in major.minor.patch format.

double relative_tolerance = {1e-6}#: Relative tolerance for solver (optional, default: 1e-6)

std::vector<types::Species> species#: Species list.

std::vector<types::Phase> phases#: Phases list.

types::Reactions reactions#: Represents a collection of different reaction types, each stored in a vector corresponding to a specific mechanism.

Note

Not wrapped in optional: gas-phase chemistry is the default and requires reactions to be present. Reactions may be empty when other chemistry (aerosol, etc.) is used instead, but the field itself is always present.

std::optional<types::Aerosol> aerosol#: Aerosol representations, processes, and constraints (optional)

std::optional<types::EmissionsConfig> emissions#: Emissions configuration (optional)

struct Version#

Errors#

using mechanism_configuration::Errors = std::vector<std::pair<ErrorCode, std::string>>#

enum class mechanism_configuration::ErrorCode#

Values:

enumerator Success#

enumerator None#

enumerator InvalidKey#

enumerator UnknownKey#

enumerator InvalidFilePath#

enumerator ObjectTypeNotFound#

enumerator RequiredKeyNotFound#

enumerator MutuallyExclusiveOption#

enumerator DuplicateSpeciesDetected#

enumerator DuplicatePhasesDetected#

enumerator DuplicateSpeciesInPhaseDetected#

enumerator PhaseRequiresUnknownSpecies#

enumerator ReactionRequiresUnknownSpecies#

enumerator UnknownSpecies#

enumerator UnknownPhase#

enumerator RequestedSpeciesNotRegisteredInPhase#

enumerator TooManyReactionComponents#

enumerator InvalidVersion#

enumerator MissingVersionField#

enumerator InvalidType#

enumerator UnknownType#

enumerator FileNotFound#

enumerator UnexpectedError#

enumerator EmptyObject#

enumerator DuplicateInventoryDetected#

enumerator DuplicateSpeciesMapDetected#

enumerator DuplicateSourceDetected#

enumerator DuplicateCategoryHierarchy#

enumerator SourceRequiresUnknownInventory#

enumerator SourceRequiresUnknownSpeciesMap#

enumerator SpeciesMapScalingExceedsOne#

enumerator OnlineSourcesNotSupported#

enumerator UnsupportedRegriddingType#

enumerator UnsupportedVerticalInjection#

std::string mechanism_configuration::ErrorCodeToString(const ErrorCode &status)#

struct ErrorLocation#

Public Functions

inline ErrorLocation(int line_number, int column_number)#

Constructor that adjusts 0-based indices to 1-based.

Parameters:

line_number – 0-based line number (from YAML::Mark)
column_number – 0-based column number (from YAML::Mark)

Library version#

inline const char *mechanism_configuration::getVersionString()#

inline unsigned mechanism_configuration::getVersionMajor()#

inline unsigned mechanism_configuration::getVersionMinor()#

inline unsigned mechanism_configuration::getVersionPatch()#

Types#

namespace types#

Typedefs

using RateConstant = std::variant<Arrhenius, Equilibrium, std::function<double(double)>>#: A reaction rate constant parsed from config.

using Representation = std::variant<UniformSection, SingleMomentMode, TwoMomentMode>#

using Process = std::variant<DissolvedReaction, DissolvedReversibleReaction, HenrysLawPhaseTransfer>#

using Constraint = std::variant<HenrysLawEquilibrium, DissolvedEquilibrium, LinearConstraint>#

Enums

enum class SourceMode#

Values:

enumerator Offline#

enum class SourceType#

Values:

enumerator Anthropogenic#

enumerator Fire#

enumerator Biogenic#

enumerator Dust#

enumerator SeaSalt#

enumerator Lightning#

enum class TemporalInterpolation#

Values:

enumerator Linear#

enumerator Nearest#

enumerator None#

enum class VerticalInjection#

Values:

enumerator Surface#

enum class RegriddingType#

Values:

enumerator None#

struct Aerosol#: #include <mechanism_configuration/types/aerosol.hpp>

Collection of parsed aerosol entries.

struct Arrhenius#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double A = {1}#: Pre-exponential factor [(mol m−3)^(−(𝑛−1)) s−1].

double B = {0}#: Unitless exponential factor.

double C = {0}#: Activation threshold, expected to be the negative activation energy divided by the boltzman constant [-E_a / k_b), K].

double D = {300}#: A factor that determines temperature dependence [K].

double E = {0}#: A factor that determines pressure dependence [Pa-1].

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct Branched#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double X#: pre-exponential factor

double Y#: exponential factor

double a0#: branching factor

int n#: number of heavy atoms in the RO2 reacting species (excluding the peroxy moiety)

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> nitrate_products#: A list of nitrate products.

std::vector<ReactionComponent> alkoxy_products#: A list of alkoxy products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct DiagnoseFromState#: #include <mechanism_configuration/types/aerosol.hpp>

Computed per representation instance.

struct DissolvedEquilibrium#: #include <mechanism_configuration/types/aerosol.hpp>

struct DissolvedReaction#: #include <mechanism_configuration/types/aerosol.hpp>

struct DissolvedReversibleReaction#

#include <mechanism_configuration/types/aerosol.hpp>

Public Members

std::optional<RateConstant> forward_rate_constant#: Supply exactly two of {forward, reverse, equilibrium}; the third is derived.

std::optional<Equilibrium> equilibrium_constant#: Shared, intrinsic equilibrium constant (NOT per representation).

struct Emission#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double scaling_factor = {1.0}#: Scaling factor to apply to user-provided rate constants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct EmissionsConfig#: #include <mechanism_configuration/types/emissions.hpp>

struct Equilibrium#

#include <mechanism_configuration/types/aerosol.hpp>

Equilibrium constant with reference-temperature Arrhenius form f(T) = A * exp( C * (1/T0 - 1/T) ) (C = +Ea/R, positive)

Public Members

double A#: Value at the reference temperature T0 [units vary by use].

double C = 0.0#: Temperature-dependence parameter [K] (C = +Ea/R)

double T0 = 298.15#: Reference temperature [K].

struct FirstOrderLoss#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double scaling_factor = {1.0}#: Scaling factor to apply to user-provided rate constants.

ReactionComponent reactants#: A single reactant.

std::vector<ReactionComponent> products#: A list of products, optional for first-order loss reactions.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct FixedConstant#: #include <mechanism_configuration/types/aerosol.hpp>

RHS constant C of a LinearConstraint: G = sum(coeff_i * [species_i]) - C = 0 Choose exactly one mode (mutually exclusive): Fixed value [mol m-3], shared by all instances.

struct HenrysLawConstant#

#include <mechanism_configuration/types/aerosol.hpp>

Henry’s law constant: HLC(T) = HLC_ref * exp( C * (1/T - 1/T0) ) Same as Equilibrium but with the opposite temperature trend.

Public Members

double HLC_ref#: Reference HLC at T0 [mol m-3 Pa-1].

double C = 0.0#: Temperature-dependence parameter [K].

double T0 = 298.15#: Reference temperature [K].

struct HenrysLawEquilibrium#

#include <mechanism_configuration/types/aerosol.hpp>

Public Members

double solvent_molecular_weight#: [kg mol-1]

double solvent_density#: [kg m-3]

struct HenrysLawPhaseTransfer#

#include <mechanism_configuration/types/aerosol.hpp>

Public Members

double diffusion_coefficient#: Gas-phase diffusion coefficient [m2 s-1].

double accommodation_coefficient#: Mass accommodation coefficient, dimensionless.

struct Inventory#: #include <mechanism_configuration/types/emissions.hpp>

struct LambdaRateConstant#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

std::string lambda_function#: A lambda function as a string, expected to be a function of temperature (T) and optionally pressure (P)

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct LinearConstraint#: #include <mechanism_configuration/types/aerosol.hpp>

struct LinearConstraintTerm#: #include <mechanism_configuration/types/aerosol.hpp>

struct Phase#

#include <mechanism_configuration/types/species.hpp>

Public Members

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct PhaseSpecies#

#include <mechanism_configuration/types/species.hpp>

Public Members

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct Photolysis#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double scaling_factor = {1.0}#: Scaling factor to apply to user-provided rate constants.

std::vector<ReactionComponent> reactants#: Reactants (at most one; empty for a pure production term, e.g. an emission)

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct ReactionComponent#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct Reactions#: #include <mechanism_configuration/types/reactions.hpp>

Represents a collection of different reaction types.

struct Regridding#: #include <mechanism_configuration/types/emissions.hpp>

struct SingleMomentMode#

#include <mechanism_configuration/types/aerosol.hpp>

Public Members

double geometric_mean_radius#: [m]

double geometric_standard_deviation#: dimensionless

struct SourceDescriptor#: #include <mechanism_configuration/types/emissions.hpp>

struct Species#

#include <mechanism_configuration/types/species.hpp>

Public Members

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct SpeciesMap#: #include <mechanism_configuration/types/emissions.hpp>

struct SpeciesMapping#: #include <mechanism_configuration/types/emissions.hpp>

struct Surface#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double reaction_probability = {1.0}#: Reaction probability (0-1) [unitless].

ReactionComponent gas_phase_species#: A single gas-phase species.

std::vector<ReactionComponent> gas_phase_products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::string condensed_phase#: An identifier for the condensed phase where this reaction occurs.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct TaylorSeries#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double A = {1}#: Pre-exponential factor [(mol m−3)^(−(𝑛−1)) s−1].

double B = {0}#: Unitless exponential factor.

double C = {0}#: Activation threshold, expected to be the negative activation energy divided by the boltzman constant [-E_a / k_b), K].

double D = {300}#: A factor that determines temperature dependence [K].

double E = {0}#: A factor that determines pressure dependence [Pa-1].

std::vector<double> taylor_coefficients = {1.0}#: An array of coefficients for the Taylor series expansion.

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct TernaryChemicalActivation#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double k0_A = 1.0#: low-pressure pre-exponential factor

double k0_B = 0.0#: low-pressure temperature-scaling parameter

double k0_C = 0.0#: low-pressure exponential factor

double kinf_A = 1.0#: high-pressure pre-exponential factor

double kinf_B = 0.0#: high-pressure temperature-scaling parameter

double kinf_C = 0.0#: high-pressure exponential factor

double Fc = 0.6#: TernaryChemicalActivation F_c parameter.

double N = 1.0#: TernaryChemicalActivation N parameter.

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct TernaryChemicalActivationJPL19#

#include <mechanism_configuration/types/reactions.hpp>

Ternary chemical activation as defined in JPL-19: the sum of a Troe term and a chemical activation term.

Public Members

double k0_A = 1.0#: low-pressure limit pre-exponential factor

double k0_B = 0.0#: low-pressure limit temperature-scaling parameter

double k0_C = 0.0#: low-pressure limit exponential factor

double k0_D = 298.0#: low-pressure limit reference temperature [K]

double kinf_A = 1.0#: high-pressure limit pre-exponential factor

double kinf_B = 0.0#: high-pressure limit temperature-scaling parameter

double kinf_C = 0.0#: high-pressure limit exponential factor

double kinf_D = 298.0#: high-pressure limit reference temperature [K]

double kint_A = 1.0#: chemical activation (k_int) pre-exponential factor

double kint_B = 0.0#: chemical activation (k_int) temperature-scaling parameter

double kint_C = 0.0#: chemical activation (k_int) exponential factor

double kint_D = 298.0#: chemical activation (k_int) reference temperature [K] (does not affect the result when kint_B = 0)

double Fc = 0.6#: TernaryChemicalActivationJPL19 F_c parameter.

double N = 1.0#: TernaryChemicalActivationJPL19 N parameter.

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct Troe#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double k0_A = 1.0#: low-pressure pre-exponential factor

double k0_B = 0.0#: low-pressure temperature-scaling parameter

double k0_C = 0.0#: low-pressure exponential factor

double kinf_A = 1.0#: high-pressure pre-exponential factor

double kinf_B = 0.0#: high-pressure temperature-scaling parameter

double kinf_C = 0.0#: high-pressure exponential factor

double Fc = 0.6#: Troe F_c parameter.

double N = 1.0#: Troe N parameter.

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct Tunneling#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double A = 1.0#: Pre-exponential factor [(mol m−3)^(−(𝑛−1)) s−1].

double B = 0.0#: Linear temperature-dependent parameter [K].

double C = 0.0#: Cubed temperature-dependent parameter [K^3].

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)

struct TwoMomentMode#

#include <mechanism_configuration/types/aerosol.hpp>

Public Members

double geometric_standard_deviation#: dimensionless

struct UniformSection#

#include <mechanism_configuration/types/aerosol.hpp>

Public Members

double min_radius#: [m]

double max_radius#: [m]

struct UserDefined#

#include <mechanism_configuration/types/reactions.hpp>

Public Members

double scaling_factor = {1.0}#: Scaling factor to apply to user-provided rate constants.

std::vector<ReactionComponent> reactants#: A list of reactants.

std::vector<ReactionComponent> products#: A list of products.

std::string name#: An identifier, optional, uniqueness not enforced.

std::string gas_phase#: An identifier indicating which gas phase this reaction takes place in.

std::unordered_map<std::string, std::string> unknown_properties#: Unknown properties, prefixed with two underscores (__)