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.

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:

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

License

See LICENSE file for details.

Authors

Cheng Li - chengcli@umich.edu
Sihe Chen

Metadata

Release files for kintera 2.6.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for kintera 2.6.6
File	Interpreter	ABI	Platform	Reset
kintera-2.6.6-cp313-cp313-manylinux_2_27_x86_64.whl 46.4 MB Oct 21, 2026 Without provenance	CPython 3.13	CPython 3.13	Linux glibc 2.27+ x86-64	Details
kintera-2.6.6-cp313-cp313-macosx_15_0_arm64.whl 4.3 MB Oct 21, 2026 Without provenance	CPython 3.13	CPython 3.13	macOS 15.0+ ARM64	Details
kintera-2.6.6-cp312-cp312-manylinux_2_27_x86_64.whl 46.4 MB Oct 21, 2026 Without provenance	CPython 3.12	CPython 3.12	Linux glibc 2.27+ x86-64	Details
kintera-2.6.6-cp312-cp312-macosx_15_0_arm64.whl 4.3 MB Oct 21, 2026 Without provenance	CPython 3.12	CPython 3.12	macOS 15.0+ ARM64	Details
kintera-2.6.6-cp311-cp311-manylinux_2_27_x86_64.whl 46.1 MB Oct 21, 2026 Without provenance	CPython 3.11	CPython 3.11	Linux glibc 2.27+ x86-64	Details
kintera-2.6.6-cp311-cp311-macosx_15_0_arm64.whl 4.3 MB Oct 21, 2026 Without provenance	CPython 3.11	CPython 3.11	macOS 15.0+ ARM64	Details
kintera-2.6.6-cp310-cp310-manylinux_2_27_x86_64.whl 46.1 MB Oct 21, 2026 Without provenance	CPython 3.10	CPython 3.10	Linux glibc 2.27+ x86-64	Details
kintera-2.6.6-cp310-cp310-macosx_15_0_arm64.whl 4.3 MB Oct 21, 2026 Without provenance	CPython 3.10	CPython 3.10	macOS 15.0+ ARM64	Details

Total release size: 202.3 MB

Release files / kintera-2.6.6-cp313-cp313-manylinux_2_27_x86_64.whl

Download URL	kintera-2.6.6-cp313-cp313-manylinux_2_27_x86_64.whl
Size	46.4 MB
Tags	CPython 3.13 Linux glibc 2.27+ x86-64
SHA-256 checksum How to use checksums	`d095bcbf44c54dbd022049f463c3f528442eb49ea3f365b0b8bf0b9fe2caa526`
BLAKE2b-256 checksum How to use checksums	`2a62933865124f203e0560f7f671e0272631a5f02a8d7f6bb2d8ede7f74ccec5`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp313-cp313-macosx_15_0_arm64.whl

Download URL	kintera-2.6.6-cp313-cp313-macosx_15_0_arm64.whl
Size	4.3 MB
Tags	CPython 3.13 macOS 15.0+ ARM64
SHA-256 checksum How to use checksums	`4213fdf8732b5c00e38a86bdef61493adb5790448cf186d1b380e8192e9fdc31`
BLAKE2b-256 checksum How to use checksums	`f47219d55b0bf946d46830769c79e89bab09535d127525db6d7977f4bf35414e`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp312-cp312-manylinux_2_27_x86_64.whl

Download URL	kintera-2.6.6-cp312-cp312-manylinux_2_27_x86_64.whl
Size	46.4 MB
Tags	CPython 3.12 Linux glibc 2.27+ x86-64
SHA-256 checksum How to use checksums	`b21ecc5aa3874f0a666db56861eb437fcfc8b814752c52fb8a85897017d04761`
BLAKE2b-256 checksum How to use checksums	`50c5e50de19b9c440bd4c67a466606015e082b63eda74c8e9e98cf2a0ee720ff`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp312-cp312-macosx_15_0_arm64.whl

Download URL	kintera-2.6.6-cp312-cp312-macosx_15_0_arm64.whl
Size	4.3 MB
Tags	CPython 3.12 macOS 15.0+ ARM64
SHA-256 checksum How to use checksums	`cae8da1e38b3eb023b403f02a95a0ebe06d57a4f6110ee832348c6359ee8a0ac`
BLAKE2b-256 checksum How to use checksums	`be731b87d3d047c671a5f076492822c8a5134839fbde2c9c2a34ad94de5adde3`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp311-cp311-manylinux_2_27_x86_64.whl

Download URL	kintera-2.6.6-cp311-cp311-manylinux_2_27_x86_64.whl
Size	46.1 MB
Tags	CPython 3.11 Linux glibc 2.27+ x86-64
SHA-256 checksum How to use checksums	`a9714808aae5052118bd88842e31f9844bf9b7ca68edc27320a6e5657959bfb2`
BLAKE2b-256 checksum How to use checksums	`270c641949afbe04fb80a4c442997478574b490f79beac34e3c2b55c70ceadd2`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp311-cp311-macosx_15_0_arm64.whl

Download URL	kintera-2.6.6-cp311-cp311-macosx_15_0_arm64.whl
Size	4.3 MB
Tags	CPython 3.11 macOS 15.0+ ARM64
SHA-256 checksum How to use checksums	`9e648c7edbd9a392e6447fe8117285a187975c0fcab70fe0bdf645619f6543c9`
BLAKE2b-256 checksum How to use checksums	`e28b39b18300495050ead66da23ab8ce889986b4430599688cd50cfba40c323b`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp310-cp310-manylinux_2_27_x86_64.whl

Download URL	kintera-2.6.6-cp310-cp310-manylinux_2_27_x86_64.whl
Size	46.1 MB
Tags	CPython 3.10 Linux glibc 2.27+ x86-64
SHA-256 checksum How to use checksums	`a053380d7470a8cb8a38bb970aade0c041af3d69c6d66140ab59f5710237c7a0`
BLAKE2b-256 checksum How to use checksums	`ce3aff09313b0bb098ca14958af65c5b5f510f6c64f2d4c288b3b177533ea52b`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / kintera-2.6.6-cp310-cp310-macosx_15_0_arm64.whl

Download URL	kintera-2.6.6-cp310-cp310-macosx_15_0_arm64.whl
Size	4.3 MB
Tags	CPython 3.10 macOS 15.0+ ARM64
SHA-256 checksum How to use checksums	`a66d3bc88bac52781449d498dc384c583712bdd8c0bd022fc76880889c7e5500`
BLAKE2b-256 checksum How to use checksums	`ce06b0714800d8b32bebf5b74a46460ff7d0870b75591e74e524a573e27fe92c`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Security for kintera 2.6.6

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.