Introduce aerosol chemistry validation and parser support

test/integration/integration_configs/cam_clound_chemistry.json → examples/v1/cam_cloud_chemistry.json

@@ -95,12 +95,12 @@
       "condensed phase": "AQUEOUS",
       "solvent": "H2O",
       "reactants": [
-        { "species": "HSO3m", "coefficient": 1 },
-        { "species": "H2O2",  "coefficient": 1 }
+        { "name": "HSO3m", "coefficient": 1 },
+        { "name": "H2O2",  "coefficient": 1 }
       ],
       "products": [
-        { "species": "SO2OOHm", "coefficient": 1 },
-        { "species": "H2O",     "coefficient": 1 }
+        { "name": "SO2OOHm", "coefficient": 1 },
+        { "name": "H2O",     "coefficient": 1 }
       ],
       "forward rate constants": {
         "CLOUD": { "type": "ARRHENIUS", "A": 3.184e8,  "C": 4430.0 }
@@ -116,11 +116,11 @@
       "condensed phase": "AQUEOUS",
       "solvent": "H2O",
       "reactants": [
-        { "species name": "SO2OOHm", "coefficient": 1 },
-        { "species name": "Hp",      "coefficient": 1 }
+        { "name": "SO2OOHm", "coefficient": 1 },
+        { "name": "Hp",      "coefficient": 1 }
       ],
       "products": [
-        { "species name": "SO4mm", "coefficient": 1 }
+        { "name": "SO4mm", "coefficient": 1 }
       ],
       "rate constants": {
         "CLOUD": { "type": "ARRHENIUS", "A": 1.333e8, "C": 4430.0}
@@ -132,11 +132,11 @@
       "condensed phase": "AQUEOUS",
       "solvent": "H2O",
       "reactants": [
-        { "species": "H2O", "coefficient": 2 }
+        { "name": "H2O", "coefficient": 2 }
       ],
       "products": [
-        { "species": "Hp",  "coefficient": 1 },
-        { "species": "OHm", "coefficient": 1 }
+        { "name": "Hp",  "coefficient": 1 },
+        { "name": "OHm", "coefficient": 1 }
       ],
       "algebraic species": "OHm",
       "equilibrium constant": {
@@ -149,11 +149,11 @@
       "condensed phase": "AQUEOUS",
       "solvent": "H2O",
       "reactants": [
-        { "species": "SO2", "coefficient": 1 }
+        { "name": "SO2", "coefficient": 1 }
       ],
       "products": [
-        { "species": "Hp",    "coefficient": 1 },
-        { "species": "HSO3m", "coefficient": 1 }
+        { "name": "Hp",    "coefficient": 1 },
+        { "name": "HSO3m", "coefficient": 1 }
       ],
       "algebraic species": "HSO3m",
       "equilibrium constant": {
@@ -167,11 +167,11 @@
       "algebraic species": "SO3mm",
       "solvent": "H2O",
       "reactants": [
-        { "species": "HSO3m", "coefficient": 1 }
+        { "name": "HSO3m", "coefficient": 1 }
       ],
       "products": [
-        { "species": "Hp",    "coefficient": 1 },
-        { "species": "SO3mm", "coefficient": 1 }
+        { "name": "Hp",    "coefficient": 1 },
+        { "name": "SO3mm", "coefficient": 1 }
       ],
       "equilibrium constant": {
         "type": "ARRHENIUS_REFERENCE_TEMPERATURE", "A": 1.08e-9, "C [K]": 1120.0, "T0 [K]": 298.15
@@ -184,11 +184,11 @@
       "algebraic species": "SO2",
       "diagnose from state": true,
       "terms": [
-        { "phase": "gas",     "species": "SO2",      "coefficient": 1.0 },
-        { "phase": "AQUEOUS", "species": "SO2",      "coefficient": 1.0 },
-        { "phase": "AQUEOUS", "species": "HSO3m",    "coefficient": 1.0 },
-        { "phase": "AQUEOUS", "species": "SO3mm",    "coefficient": 1.0 },
-        { "phase": "AQUEOUS", "species": "SO2OOHm",  "coefficient": 1.0 }
+        { "phase": "gas",     "name": "SO2",      "coefficient": 1.0 },
+        { "phase": "AQUEOUS", "name": "SO2",      "coefficient": 1.0 },
+        { "phase": "AQUEOUS", "name": "HSO3m",    "coefficient": 1.0 },
+        { "phase": "AQUEOUS", "name": "SO3mm",    "coefficient": 1.0 },
+        { "phase": "AQUEOUS", "name": "SO2OOHm",  "coefficient": 1.0 }
       ]
     },
     {
@@ -198,8 +198,8 @@
       "algebraic species": "H2O2",
       "diagnose from state": true,
       "terms": [
-        { "phase": "gas",     "species": "H2O2", "coefficient": 1.0 },
-        { "phase": "AQUEOUS", "species": "H2O2", "coefficient": 1.0 }
+        { "phase": "gas",     "name": "H2O2", "coefficient": 1.0 },
+        { "phase": "AQUEOUS", "name": "H2O2", "coefficient": 1.0 }
       ]
     },
     {
@@ -209,8 +209,8 @@
       "algebraic species": "O3",
       "diagnose from state": true,
       "terms": [
-        { "phase": "gas",     "species": "O3", "coefficient": 1.0 },
-        { "phase": "AQUEOUS", "species": "O3", "coefficient": 1.0 }
+        { "phase": "gas",     "name": "O3", "coefficient": 1.0 },
+        { "phase": "AQUEOUS", "name": "O3", "coefficient": 1.0 }
       ]
     },
     {
@@ -220,12 +220,12 @@
       "algebraic species": "Hp",
       "constant [mol m-3]": 0.0,
       "terms": [
-        { "phase": "AQUEOUS", "species": "Hp",       "coefficient":  1.0 },
-        { "phase": "AQUEOUS", "species": "OHm",      "coefficient": -1.0 },
-        { "phase": "AQUEOUS", "species": "HSO3m",    "coefficient": -1.0 },
-        { "phase": "AQUEOUS", "species": "SO3mm",    "coefficient": -2.0 },
-        { "phase": "AQUEOUS", "species": "SO4mm",    "coefficient": -2.0 },
-        { "phase": "AQUEOUS", "species": "SO2OOHm",  "coefficient": -1.0 }
+        { "phase": "AQUEOUS", "name": "Hp",      "coefficient":  1.0 },
+        { "phase": "AQUEOUS", "name": "OHm",     "coefficient": -1.0 },
+        { "phase": "AQUEOUS", "name": "HSO3m",   "coefficient": -1.0 },
+        { "phase": "AQUEOUS", "name": "SO3mm",   "coefficient": -2.0 },
+        { "phase": "AQUEOUS", "name": "SO4mm",   "coefficient": -2.0 },
+        { "phase": "AQUEOUS", "name": "SO2OOHm", "coefficient": -1.0 }
       ]
     }
   ]

include/mechanism_configuration/aerosol_types.hpp

@@ -28,9 +28,6 @@ namespace mechanism_configuration::types
     double T0 = 298.15;  ///< Reference temperature [K]
   };
 
-  /// @brief Equilibrium constants use the same reference-temperature form.
-  using EquilibriumConstant = ArrheniusReferenceTemperature;
-
   /// @brief Henry's law constant: HLC(T) = HLC_ref * exp( C * (1/T - 1/T0) )
   ///        Same as ArrheniusReferenceTemperature but with the
   ///        opposite temperature trend (solubility rises as T falls)
@@ -98,7 +95,7 @@ namespace mechanism_configuration::types
     std::map<std::string, RateConstant> forward_rate_constants;
     std::map<std::string, RateConstant> reverse_rate_constants;
     /// @brief Shared, intrinsic equilibrium constant (NOT per representation).
-    std::optional<EquilibriumConstant> equilibrium_constant;
+    std::optional<ArrheniusReferenceTemperature> equilibrium_constant;
   };
 
   struct HenryLawPhaseTransfer
@@ -109,7 +106,6 @@ namespace mechanism_configuration::types
     std::string condensed_species;
     std::string solvent;
     HenryLawConstant henry_law_constant;
-    HenryLawConstant henry_law_constant;
     double diffusion_coefficient;      ///< Gas-phase diffusion coefficient [m2 s-1]
     double accommodation_coefficient;  ///< Mass accommodation coefficient, dimensionless
   };
@@ -139,13 +135,13 @@ namespace mechanism_configuration::types
     std::string solvent;
     std::vector<ReactionComponent> reactants;
     std::vector<ReactionComponent> products;
-    EquilibriumConstant equilibrium_constant;
+    ArrheniusReferenceTemperature equilibrium_constant;
   };
 
   struct LinearConstraintTerm
   {
     std::string phase;
-    std::string species;
+    std::string name;
     double coefficient;
   };
 
@@ -169,4 +165,16 @@ namespace mechanism_configuration::types
 
   using Constraint = std::variant<HenryLawEquilibrium, DissolvedEquilibrium, LinearConstraint>;
 
+  // ----------------------------------------
+  // Container
+  // ----------------------------------------
+
+  /// @brief Collection of parsed aerosol entries
+  struct Aerosol
+  {
+    std::vector<Representation> representations;
+    std::vector<Process> processes;
+    std::vector<Constraint> constraints;
+  };
+
 }  // namespace mechanism_configuration::types

include/mechanism_configuration/errors.hpp

@@ -42,6 +42,7 @@ namespace mechanism_configuration
     ReactionRequiresUnknownSpecies,
     UnknownSpecies,
     UnknownPhase,
+    UnknownAerosolRepresentation,
     RequestedSpeciesNotRegisteredInPhase,
     TooManyReactionComponents,
     InvalidVersion,

include/mechanism_configuration/mechanism.hpp

@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include <mechanism_configuration/aerosol_types.hpp>
 #include <mechanism_configuration/types.hpp>
 
 #include <filesystem>
@@ -14,9 +15,8 @@
 
 namespace mechanism_configuration
 {
-  // Trying to build on linux for the python release, I learned that glibc had a bug which defined
-// a macro called major and minor. This caused a conflict with the Version struct. To fix this, I
-// undefine the macros before defining the struct and then redefine them after the struct.
+// glibc defines `major` and `minor` as macros, which conflict with the `Version` struct fields.
+// Temporarily undefine the macros before the struct definition and restore them afterward.
 // https://stackoverflow.com/a/22253389/5217293
 #pragma push_macro("major")
 #undef major
@@ -87,6 +87,8 @@ namespace mechanism_configuration
     /// @brief Represents a collection of different reaction types, each stored in a vector
     ///        corresponding to a specific mechanism
     types::Reactions reactions;
+    /// @brief Aerosol representations, processes, and constraints
+    types::Aerosol aerosol;
     /// @brief Version of the mechanism configuration format used, in major.minor.patch format
     Version version;
     /// @brief Relative tolerance for solver (optional, default: 1e-6)

include/mechanism_configuration/mechanism_configuration.hpp

@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include <mechanism_configuration/aerosol_types.hpp>
 #include <mechanism_configuration/errors.hpp>
 #include <mechanism_configuration/mechanism.hpp>
 #include <mechanism_configuration/parse.hpp>

include/mechanism_configuration/types.hpp

@@ -37,6 +37,7 @@ namespace mechanism_configuration::types
   {
     std::string name;
     std::optional<double> diffusion_coefficient;
+    std::optional<double> density;
     /// @brief Unknown properties, prefixed with two underscores (__)
     std::unordered_map<std::string, std::string> unknown_properties;
   };

include/mechanism_configuration/validate.hpp

@@ -13,10 +13,15 @@
 
 namespace mechanism_configuration
 {
-  // Intermediate over which all semantic validation runs. Both a parsed document and an
-  // in-code Mechanism produce one of these and hand it to ValidateSemantics, so the rules
-  // live in exactly one place. A parsed document fills in source locations (so errors carry
-  // line:col); an in-code Mechanism leaves them empty. The domain types stay location-free.
+
+  // Intermediate over which the core semantic validation (species, phases, gas-phase reactions)
+  // runs. Both a parsed document and an in-code Mechanism lower into one of these and hand it to
+  // ValidateSemantics, so those rules live in exactly one place. A parsed document fills in source
+  // locations (so errors carry line:col); an in-code Mechanism leaves them empty.
+  //
+  // Aerosol cross-references are validated separately by ValidateAerosolModel, which works on the
+  // domain structs directly because it needs phase membership and optional-property values that
+  // this name-only view cannot carry.
   namespace semantics
   {
     struct NamedRef
@@ -79,17 +84,31 @@ namespace mechanism_configuration
       std::vector<ReactionRef> reactions;
       std::optional<EmissionsRef> emissions;  // nullopt only when there's no emissions at all
     };
+
   }  // namespace semantics
 
-  /// @brief The single home for the mechanism's semantic rules. Errors include `line:col`
-  ///        for any element whose source location was supplied.
+  /// @brief The single home for the core (species / phase / gas-phase reaction) semantic rules.
+  ///        Errors include `line:col` for any element whose source location was supplied.
   Errors ValidateSemantics(const semantics::Input& input);
 
-  /// @brief Validates the semantic invariants of a canonical Mechanism, independent of how it
-  ///        was produced (parsed from any version, or constructed in code). Convenience wrapper
-  ///        that builds a location-free semantics::Input and calls ValidateSemantics.
-  ///
-  /// Structural/deserialization concerns (YAML keys, types, formatting) are the responsibility
-  /// of the version-specific parsers and are not repeated here.
+/// @brief Validates a Mechanism's species, phases, and gas-phase reactions by
+///        converting them to a location-free semantics::Input and running
+///        ValidateSemantics.
+  Errors ValidateGasModel(const Mechanism& mechanism);
+
+/// @brief 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. These validations require full domain
+///        information unavailable to ValidateSemantics. Returns no errors if the mechanism
+///        has no aerosol section.
+  Errors ValidateAerosolModel(const Mechanism& mechanism);
+
+/// @brief Validates the semantic invariants of a canonical Mechanism, regardless of whether it
+///        was parsed or constructed in code. Combines ValidateGasModel and
+///        ValidateAerosolModel, returning all validation errors.
+///
+///        Excludes structural/deserialization validation, which is handled by version-specific parsers.
   Errors Validate(const Mechanism& mechanism);
+
 }  // namespace mechanism_configuration

src/detail/v1/aerosol_keys.hpp

@@ -25,7 +25,7 @@ namespace mechanism_configuration::v1::keys
 
   inline constexpr std::string_view SingleMomentMode_key = "SINGLE_MOMENT_MODE";
   inline constexpr std::string_view geometric_mean_radius = "geometric mean radius [m]";
-  inline constexpr std::string_view geometric_standard_deviation = "geometric standard deviation [-]";
+  inline constexpr std::string_view geometric_standard_deviation = "geometric standard deviation";
 
   inline constexpr std::string_view TwoMomentMode_key = "TWO_MOMENT_MODE";
   // also: geometric_standard_deviation
@@ -39,6 +39,8 @@ namespace mechanism_configuration::v1::keys
   inline constexpr std::string_view equilibrium_constant = "equilibrium constant";
   inline constexpr std::string_view reference_temperature = "T0 [K]";
 
+  inline constexpr std::string_view ArrheniusReferenceTemperature_key = "ARRHENIUS_REFERENCE_TEMPERATURE";
+
   inline constexpr std::string_view henry_law_constant = "Henry's law constant";
   inline constexpr std::string_view HLC_ref = "HLC_ref [mol m-3 Pa-1]";
   inline constexpr std::string_view henry_law_C = "C [K]";
@@ -52,7 +54,7 @@ namespace mechanism_configuration::v1::keys
   // also: gas_phase, gas_phase_species, condensed_phase, condensed_phase_species, solvent,
   //       henry_law_constant, diffusion_coefficient
   inline constexpr std::string_view HenryLawPhaseTransfer_key = "HENRY_LAW_PHASE_TRANSFER";
-  inline constexpr std::string_view accommodation_coefficient = "accommodation coefficient [-]";
+  inline constexpr std::string_view accommodation_coefficient = "accommodation coefficient";
 
   // DissolvedReaction
   // also: condensed_phase, solvent, reactants, products, rate_constants
@@ -79,7 +81,7 @@ namespace mechanism_configuration::v1::keys
   inline constexpr std::string_view algebraic_species = "algebraic species";
 
   // LinearConstraint
-  // also: name; terms carry coefficient and species
+  // also: name; terms carry coefficient and name
   inline constexpr std::string_view LinearConstraint_key = "LINEAR_CONSTRAINT";
   inline constexpr std::string_view algebraic_phase = "algebraic phase";
   inline constexpr std::string_view terms = "terms";