Kintera: Atmospheric Chemistry and Thermodynamics Library

KINTERA is a library for atmospheric chemistry and equation of state calculations, combining C++ performance with Python accessibility through pybind11 bindings.

Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Photochemistry Module
• Testing
• Documentation
• Development
• License

Overview

KINTERA provides efficient implementations of:

• Chemical kinetics calculations (Arrhenius, coagulation, evaporation)
• Photochemistry and photolysis reactions
• Thermodynamic equation of state
• Phase equilibrium computations
• Atmospheric chemistry models

Multiphase Equilibrium

EquilibriumTP is a fixed-temperature, fixed-pressure constrained chemistry solver. The C++/CUDA core accepts component moles and precomputed logarithmic equilibrium constants; the module derives phase membership and stoichiometry from its options. Case-specific thermodynamics remains in Python under kintera.equilibrium.

Equilibrium networks use the repository's top-level phases, species, and reactions YAML layout. Phase species determine component ordering, species compositions validate elemental balance, and reactions with type: equilibrium generate the module's stoichiometric buffer:

from kintera import EquilibriumOptions, EquilibriumTP

options = EquilibriumOptions.from_yaml("equilibrium.yaml")
solver = EquilibriumTP(options)

Nasa9LogK evaluates ideal-gas equilibrium constants from the bundled NASA-9 database. See examples/equilibrium_nasa9.yaml and examples/equilibrium_nasa9.py for a complete YAML-defined sample:

python examples/equilibrium_nasa9.py

The library is written in C++17 with Python bindings, leveraging PyTorch for tensor operations and providing GPU acceleration support via CUDA.

Features

• High Performance: C++17 core with optional CUDA support
• Python Interface: Full Python API via pybind11
• PyTorch Integration: Native tensor operations using PyTorch
• Chemical Kinetics: Comprehensive reaction mechanism support
• Photochemistry: Wavelength-dependent photolysis with multi-branch products
• Thermodynamics: Advanced equation of state calculations
• Cloud Physics: Nucleation and condensation modeling

Prerequisites

System Requirements

• C++ Compiler: Support for C++17 (GCC 9+, Clang 5+, or MSVC 2017+)
• CMake: Version 3.18 or higher
• Python: Version 3.10 or higher
• NetCDF: NetCDF C library

Python Dependencies

• numpy
• torch (version 2.10.0)
• pyharp (version 2.2.0+
• pytest (for testing)

Platform-Specific Setup

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y build-essential cmake libnetcdf-dev

macOS

brew update
brew install cmake netcdf

Installation

Quick Start

# 1. Install Python dependencies
pip install numpy 'torch==2.10.0' 'pyharp>=2.2.0'

# 2. Clone the repository
git clone https://github.com/chengcli/kintera.git
cd kintera

# 3. Configure and build the C++ library
cmake -B build
cmake --build build --parallel

# 4. Install the Python toolkit
pip install .

Photochemistry Module

KINTERA includes a complete photochemistry module for modeling photolysis reactions in planetary atmospheres.

Architecture

src/photolysis/
├── photolysis.hpp           # PhotolysisOptions and PhotolysisImpl definitions
├── photolysis.cpp           # Implementation with YAML parsing and rate computation
├── actinic_flux.hpp         # Actinic flux helper functions
├── load_xsection_kin7.cpp   # KINETICS7 cross-section loader
├── load_xsection_yaml.cpp   # YAML cross-section loader
├── jacobian_photolysis.hpp  # Photolysis Jacobian declarations
└── jacobian_photolysis.cpp  # Species-space Jacobian helper implementation

Key Components

Component	Description
PhotolysisOptions	Configuration: wavelength grid, cross-sections, branches
Photolysis	PyTorch module computing rates via wavelength integration
actinic_flux.hpp helpers	Flux construction and wavelength interpolation helpers
jacobian_photolysis_species()	Species-space Jacobian helper for implicit solvers

Thermochemistry Data

NASA-9 polynomial data is stored with SpeciesThermoImpl as structured per-species coefficient tables and converted to tensors on demand when reversible kinetics needs equilibrium constants. KineticsImpl no longer owns separate cached NASA-9 buffers.

Kinetics Species Layout

KineticsOptions.from_yaml(...) registers kinetics species using reaction-active vapors plus cloud species, rather than every species listed in the YAML file. In practice this means inert dry carrier species are not included in the concentration tensor passed to Kinetics.forward(...) or Kinetics.forward_nogil(...) unless they also participate in the reaction mechanism. Callers that derive kinetics concentrations from a larger thermo state should narrow or reorder species explicitly to the kinetics species list.

Rate Calculation

Photolysis rates are computed by integrating cross-sections weighted by actinic flux:

k = ∫ σ(λ,T) · F(λ) dλ

where σ is the cross-section [cm² molecule⁻¹], F is the actinic flux [photons cm⁻² s⁻¹ nm⁻¹], and λ is wavelength [nm].

YAML Configuration

Photolysis reactions are defined in YAML format:

reactions:
- equation: CH4 => CH3 + H + (1)CH2 + H2
  type: photolysis
  branches:
    - "CH4:1"           # photoabsorption
    - "CH3:1 H:1"       # CH3 + H branch
    - "(1)CH2:1 H2:1"   # singlet CH2 + H2 branch
  cross-section:
    - format: KINETICS7
      filename: "CH4.dat2"
    # Or inline YAML format:
    - format: YAML
      temperature: 300.
      data:
        - [100., 1.e-18, 0.5e-18]
        - [150., 2.e-18, 1.0e-18]

C++ Usage

#include <kintera/photolysis/photolysis.hpp>
#include <kintera/photolysis/actinic_flux.hpp>

// Create options
auto opts = PhotolysisOptionsImpl::create();
opts->wavelength() = {100., 150., 200.};
opts->reactions().push_back(Reaction("N2 => N2"));
opts->cross_section() = {1.e-18, 2.e-18, 1.e-18};

// Create module and move to GPU
Photolysis module(opts);
module->to(torch::kCUDA, torch::kFloat64);

auto temp = torch::tensor({300.0}, module->wavelength.options());

// Create actinic flux on the module wavelength grid
auto flux = create_solar_flux(module->wavelength, 1.e14);

// Refresh the temperature-dependent cache before forward()
module->update_xs_diss_stacked(temp);
auto rate = module->forward(temp, flux);

Python Usage

from kintera import (
    PhotolysisOptions, Photolysis, Reaction,
    create_solar_flux, set_species_names
)
import torch

# Initialize species list
set_species_names(["N2", "O2", "CH4"])

# Configure photolysis
opts = PhotolysisOptions()
opts.wavelength([100., 150., 200.])
opts.reactions([Reaction("N2 => N2")])
opts.cross_section([1e-18, 2e-18, 1e-18])

# Create module
module = Photolysis(opts)

temp = torch.tensor([300.0], dtype=module.wavelength.dtype,
                    device=module.wavelength.device)

# Create flux on the module wavelength grid and compute rates
flux = create_solar_flux(module.wavelength, 1e14)
module.update_xs_diss_stacked(temp)
rate = module.forward(temp, flux)

Cross-Section File Formats

The module supports multiple cross-section formats:

Format	Description
YAML	Inline wavelength/cross-section data
KINETICS7	NCAR KINETICS7 format files
VULCAN	VULCAN photochemistry format

Testing

KINTERA includes comprehensive C++ and Python tests.

Running All Tests

ctest --test-dir build/tests --output-on-failure

Photochemistry Tests

Run photochemistry-specific tests:

# Focused C++ tests
./build/tests/test_photolysis_options.release
./build/tests/test_ch4_photolysis.release

# Python tests
pytest tests/test_photolysis.py -v

Device Coverage

Parameterized C++ tests are generated for CPU and CUDA builds. MPS test instantiations have been removed from the default test matrix.

Test Coverage

Test File	Coverage
test_photolysis_options.cpp	YAML parsing, cross-section loading
test_photolysis_kinetics.cpp	Kinetics integration, stoichiometry
test_actinic_flux.cpp	Flux interpolation, tensor shapes
test_ch4_photolysis.cpp	End-to-end CH4 photolysis, Jacobian
test_photolysis.py	Python bindings integration

Documentation

Full documentation is available at: https://kintera.readthedocs.io

To build documentation locally:

cd docs
pip install -r requirements.txt
make html

Dependency Cache

A successful build saves cache files in .cache/. To force a clean rebuild:

rm -rf .cache build

Development

Project Structure

kintera/
├── src/
│   ├── kinetics/       # Kinetics modules (Arrhenius, falloff, three-body, etc.)
│   ├── photolysis/     # Photolysis, actinic flux, and Jacobian helpers
│   ├── diffusion/      # Diffusion operators
│   ├── units/          # Unit conversion helpers
│   ├── thermo/         # Thermodynamics
│   └── math/           # Interpolation utilities
├── python/
│   ├── csrc/           # pybind11 bindings
│   ├── kintera.pyi     # Type stubs
│   └── py.typed        # PEP 561 marker
├── tests/              # C++ and Python tests
├── examples/           # Usage examples
└── data/               # Test data (cross-sections, YAML configs)

Code Style

pip install pre-commit
pre-commit install
pre-commit run --all-files

Type Hints

KINTERA provides full type hint support through Python stub files:

• IDE autocomplete in VS Code, PyCharm
• Type checking with mypy or pyright

See python/STUB_FILES.md for details.

Continuous Integration

GitHub Actions CI pipeline:

1. Pre-commit checks (formatting, linting)
2. Build on Linux and macOS
3. Run all C++ and Python tests

License

See LICENSE file for details.

Authors

• Cheng Li - chengcli@umich.edu
• Sihe Chen