Metadata-Version: 2.4
Name: kintera
Version: 2.3.3
Summary: Atmospheric Chemistry and Thermodynamics Library
Author-email: Cheng Li <chengcli@umich.edu>, Sihe Chen <sihechen@caltech.edu>
License: LICENSE
Project-URL: Homepage, https://github.com/chengcli/kintera
Project-URL: Documentation, https://kintera.readthedocs.io
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pyharp>=2.2.0
Dynamic: license-file

# 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](#overview)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Photochemistry Module](#photochemistry-module)
- [Testing](#testing)
- [Documentation](#documentation)
- [Development](#development)
- [License](#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)

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

#### macOS

```bash
brew update
brew install cmake netcdf
```

## Installation

### Quick Start

```bash
# 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:

```yaml
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

```cpp
#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

```python
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

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

### Photochemistry Tests

Run photochemistry-specific tests:

```bash
# 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](https://kintera.readthedocs.io)

To build documentation locally:

```bash
cd docs
pip install -r requirements.txt
make html
```

### Dependency Cache

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

```bash
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

```bash
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`](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](LICENSE) file for details.

## Authors

- **Cheng Li** - [chengcli@umich.edu](mailto:chengcli@umich.edu)
- **Sihe Chen**
