spektran 0.5.1

English | 中文

The MNIST of Gas Sensing

AI Agent-Ready simulation engine + ML benchmark for optical gas sensing
HITRAN-grade physics. 9 tasks. 14 baselines. Full pipeline via natural language.

Documentation  ·  Interactive Demo  ·  Leaderboard  ·  Dataset  ·  Baselines

You don't need to be a spectroscopist.  If you work on regression, denoising, domain generalization, or anomaly detection, SPEKTRAN gives you 9 ready-to-use benchmark tasks backed by real physics — with the same convenience as MNIST, but grounded in a domain where ML has direct industrial impact.

You don't even need to type code.  SPEKTRAN is fully AI Agent-ready — tell Claude Code, Cursor, or any coding agent what you want, and it operates the entire pipeline through natural language. See AGENTS.md.

Highlights

Quick Start

Zero-install — load data from Hugging Face in one line:

from datasets import load_dataset
ds = load_dataset("spektran/spektran-ch4-v0")

Full engine — simulate spectra locally:

pip install spektran

from spektran.physics import simulate_absorbance

nu, absorbance = simulate_absorbance(
    molecule="CH4", concentration_ppm=100.0,
    temperature_K=296.0, pressure_atm=1.0,
    path_length_m=10.0,
    wavenumber_start_cm1=6046.0, wavenumber_end_cm1=6048.0,
)

from spektran.physics.wms import WMSConfig, simulate_wms

from spektran.physics import absorption_coefficient
from spektran.physics.hitran import demo_ch4_2nu3, demo_h2o

alpha_ch4 = absorption_coefficient(nu, demo_ch4_2nu3(), 100e-6, 296.0, 1.0)
alpha_h2o = absorption_coefficient(nu, demo_h2o(), 0.01, 296.0, 1.0)

spektran info --json                      # Project discovery (agent bootstrap)
spektran list tasks --json                # Available benchmark tasks
spektran train --baseline ridge --json    # Train with auto data generation
spektran generate configs/datasets/ch4-t1-train-v0.yaml --out data --json
spektran benchmark --task T1-concentration --truth data/test.h5 --predictions preds.csv

AI Agent Ready

SPEKTRAN is designed from the ground up for the AI agent era. Every CLI command outputs structured JSON, every resource is discoverable, and the full ML pipeline — simulate → generate → train → evaluate — runs with zero manual steps.

Works with: Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, and any agent that can run shell commands.

Agent interface: AGENTS.md — the agent reads this file and immediately understands how to operate the entire project.

You: "Train the ridge baseline on T1 and show me the scores"

Agent: spektran train --baseline ridge --task T1 --json
       → {"baseline": "ridge", "scores": {"T1": {"mae_ppm": 2.84, "mape_pct": 29.87}}}

spektran info --json           # What is this project? What's available?
spektran list tasks --json     # 9 tasks with metrics and available baselines
spektran list baselines --json # 14 baselines with pre-computed scores
spektran status --json         # What data exists? What's been trained?

spektran train --baseline ridge --json        # Auto-generates data if missing
spektran train --baseline transformer --json  # Works for any registered baseline
spektran train --baseline cnn1d --task T1 --json  # Target a specific task

for baseline in ridge cnn1d transformer; do
  spektran train --baseline $baseline --task T1 --json
done

# Agent generates training code using spektran.io.read_records
# Agent writes predictions CSV
spektran benchmark --task T1-concentration \
  --truth data/ch4-t1-test-v0.h5 \
  --predictions my_model_predictions.csv

Benchmark Tasks

Leaderboard

T1 Concentration + T3 Cross-Instrument (v0 splits, CH4 DA):

Model complexity correlates with instrument overfitting: Ridge 1.31x → Transformer 1.46x → CNN 1.82x. Can you build a model that breaks this pattern?

Full leaderboard →  ·  Submit results →

Real-World Impact

SPEKTRAN's benchmarks mirror problems that matter in industry and environmental science:

• Methane leak detection — oil & gas facilities, landfills, livestock operations (T1, T3)
• Industrial emissions monitoring — continuous stack gas analysis for SO2, NO, CO (T4, T8)
• Medical breath analysis — trace-gas biomarkers at ppb levels (T1, T9)
• Instrument-agnostic deployment — models that transfer across hardware without recalibration (T3, T7)
• Drift-resilient field sensors — long-term autonomous monitoring in harsh environments (T5)

How It Works

 HITRAN line data        Instrument configs         Benchmark
 ───────────────        ──────────────────         ─────────
 Line positions    ──►  Virtual instruments   ──►  Official splits
 Line strengths         (noise, fringes,           (train/val/test/
 Broadening params       drift, chirp)              held-out)
        │                      │                       │
        ▼                      ▼                       ▼
   Forward physics  ──►  Noisy spectra   ──►   Evaluate & rank
   (Voigt / HTP)         with provenance       on leaderboard

Physics You Can Trust

• Dual-implementation validation — independent reference implementations cross-checked against HITRAN/hapi
• Literature-anchored noise — instrument noise parameters surveyed from 18 published systems
• Sim-to-real gap report — known gap sources documented in G5 report
• Automated quality gates — G1–G5 checkpoints enforced in CI

Citing

@software{spektran,
  title     = {SPEKTRAN: Simulation Engine and ML Benchmark for Optical Gas Sensing},
  url       = {https://github.com/spektran/spektran},
  doi       = {10.5281/zenodo.21790394},
  version   = {0.5.1},
  license   = {Apache-2.0}
}

See CITATION.cff or use the DOI: 10.5281/zenodo.21790394.

Star History

Contributing

See CONTRIBUTING.md. We welcome new baselines, modalities, and line lists.