kintera 2.2.0

Atmospheric Chemistry and Thermodynamics Library

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

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.

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 - [e-mail]
• Sihe Chen