Alchemi

Thermodynamic routing of multi-reference quantum chemistry.

Alchemi builds a C/T skeleton from MP2 natural orbital occupation numbers (NOONs), classifies each electron pair into an H^k stratum, and routes the computation to the right method — automatically, without fitting parameters.

The routing threshold δ* = (π/4)√α is derived from the MGE cost-accuracy tradeoff — not tuned on a validation set.

Quickstart

from pyscf import gto, scf, mp
from alchemi import Skeleton, Router

# Run a cheap MP2 calculation
mol = gto.M(atom="N 0 0 0; N 0 0 1.1", basis="cc-pVDZ", verbose=0)
mf  = scf.RHF(mol).run()
mp2 = mp.MP2(mf).run()

# Build the C/T skeleton
skel = Skeleton.from_pyscf(mol, mp2)
skel.report()

# Get the recommended CASSCF active space
active_orbs, n_elec = skel.active_space()
print(f"Active space: CAS({n_elec},{len(active_orbs)})")

# Soft MGE routing with β_eff
router = Router(skel, homo_lumo_gap=0.43, spin_multiplicity=1)
router.report()

Installation

pip install alchemi            # core (numpy/scipy only)
pip install alchemi[pyscf]     # with PySCF integration
pip install alchemi[dev]       # with test/lint tools

Theory

Alchemi implements the theoretical framework of:

• Paper 588 — The Topological Active Space: Weak Lifting and C/T Skeleton Pre-Screening for CASSCF. doi:10.5281/zenodo.21300667

• Paper 491 — Galois Chemistry as the Tropical Degeneration of Density Functional Theory. doi:10.5281/zenodo.21224113

• Paper 596 — Weyl Chamber Homology as a DFT Failure Detector. (in preparation)

The routing is based on the Maslov-Gibbs Einsum (MGE) at finite inverse temperature β_eff = Δ_HL / (corr_scale · (2S+1)). Hard thresholds (autoCAS, AVAS) are recovered at β_eff → ∞. Alchemi gives the correct soft blend near the H¹/H² boundary.

Related tools

• spectrafold — Racah spectroscopy from the quantum numbers that Alchemi computes
• thermion — the shared ISA engine underlying both packages

Citation

@software{alchemi2026,
  author  = {Buckley, Ian R. C.},
  title   = {Alchemi: Thermodynamic Routing of Multi-Reference Quantum Chemistry},
  year    = {2026},
  url     = {https://github.com/roguetrainer/alchemi},
}