Chemical Mechanism Configurations

An attempt at defining a model-independent configuration schema for atmospheric chemical systems in JSON and YAML.

Copyright (C) 2017–2026 University Corporation for Atmospheric Research, University of Illinois at Urbana–Champaign, Barcelona Supercomputing Center

The documentation is at mechanismconfiguration.readthedocs.io.

Usage

Everything goes through the canonical mechanism_configuration::Mechanism. You can either parse a configuration file (the version is detected and dispatched automatically), or build a Mechanism in code and validate it. Validate() runs the same semantic checks the parser uses, so it applies to any mechanism regardless of where it came from.

#include <mechanism_configuration/mechanism_configuration.hpp>

#include <iostream>

using namespace mechanism_configuration;

void print_errors(const Errors& errors)
{
  for (const auto& [code, message] : errors)
    std::cerr << "  [" << ErrorCodeToString(code) << "] " << message << '\n';
}

int main()
{
  int status = 0;

  // 1) Parse from a file (YAML or JSON; v0 or v1). Returns std::expected<Mechanism, Errors>
  //    with both structural and semantic errors reported.
  if (auto parsed = Parse("examples/v1/full_configuration.yaml"))
  {
    const Mechanism& mechanism = *parsed;
    std::cout << "Parsed '" << mechanism.name << "': " << mechanism.species.size()
              << " species, " << mechanism.reactions.arrhenius.size() << " Arrhenius reactions\n";
  }
  else
  {
    std::cerr << "Failed to parse file:\n";
    print_errors(parsed.error());
    status = 1;
  }

  // 2) Build a Mechanism in code and validate it (species exist, reactants are in their
  //    phase, no duplicate names, ...).
  Mechanism mechanism;
  mechanism.name = "example";
  mechanism.species = { { .name = "A" }, { .name = "B" } };
  mechanism.phases = { { .name = "gas", .species = { { .name = "A" }, { .name = "B" } } } };

  types::Arrhenius reaction;
  reaction.name = "A -> B";
  reaction.gas_phase = "gas";
  reaction.reactants = { { .name = "A" } };  // reactants must be registered in the phase
  reaction.products = { { .name = "B" } };   // products may reference any phase
  mechanism.reactions.arrhenius = { reaction };

  if (Errors errors = Validate(mechanism); errors.empty())
    std::cout << "In-code mechanism is valid\n";
  else
  {
    std::cerr << "In-code mechanism is invalid:\n";
    print_errors(errors);
    status = 1;
  }

  return status;
}

Building the Documentation

The documentation needs Python and Doxygen. From the root of the repository, run:

pip install -r docs/requirements.txt
mkdir build && cd build
cmake -DMECH_CONFIG_BUILD_DOCS=ON ..
make docs

Then open build/docs/sphinx/index.html in a browser.