dft-learn

Python tools for StoBe-style core-level spectra: parse transitions, cluster by Gaussian peak overlap, and build bond-traceable resonant X-ray optical tensors for angle-resolved NEXAFS (RSoXS, XRR).

Carbon Lab · Hugging Face · X-ray Atlas · PRL · arXiv

Install

pip install -U dft-learn          # or: uv add dft-learn
uv tool install dft-learn         # optional CLI: dftrun

Requires Python 3.12+.

Quick start

import numpy as np
from dftlearn.clustering import TransitionSticks, cluster_by_overlap

sticks = TransitionSticks(
    energy_ev=np.array([284.0, 284.15, 295.0]),
    oscillator_strength=np.array([1.0, 0.9, 0.5]),
    sigma_ev=np.full(3, 0.2),
    site=np.array(["C1", "C1", "C2"]),
    os_xx=np.array([0.1, 0.1, 0.0]),
    os_yy=np.zeros(3),
    os_zz=np.array([0.2, 0.2, 0.5]),
)
result = cluster_by_overlap(sticks, overlap_threshold=50.0)
print(result.n_iterations, result.energy_ev.shape[0])

StoBe workflow CLI:

dftrun build --help
dftrun run --help
dftrun postprocess --help

Demos

Space	Dataset
CuPc optical model (reference)	optical-cupc
ZnPc optical model	optical-znpc

CuPc walks through the publication workflow: sites, DFT sticks (isotropic / xx / zz), clusters, and refinement against experiment.

Package layout

Area	Role
dftlearn.io	StoBe / XYZ parsers
dftlearn.clustering	Overlap matrices, merge, OS elbow, threshold selection
dftlearn.xas	Spectrum reconstruction, C3 symmetry helpers
dftlearn.visualization	Optional figures (viz extras)
dftrun	Build inputs, schedule runs, package spectra
igor/	Legacy Igor reference (not the install target)

Development

git clone https://github.com/WSU-Carbon-Lab/dft-learn.git
cd dft-learn
make install && make verify    # ruff + format check + pytest

Target	Action
make test	pytest
make lint	ruff check
make type-check	ty (advisory)
make fix	ruff check --fix + format
make build	sdist + wheel

Conventions: AGENTS.md.

Release (Trusted Publishing). Configure a GitHub Environment named pypi for the PyPI project dft-learn, bump the version in pyproject.toml, then:

git tag v0.2.0 && git push origin v0.2.0

The Release workflow publishes to PyPI and creates a GitHub Release.

Igor → Python port

Status of the igor/ clustering pipeline in dftlearn (#1 · #2 · #3). Audited against FilteringMain / filterDFT and current library + python_pipeline/ staging.

Summaries show one box per capability and done / total (done = tested or done-untested; out of scope omitted from the total).

tested · done, not tested · in progress · not started · out of scope

Ingest · 4/4

	Capability	Completion	Location	Track
	XrayT*.out / TP *.xas sticks	tested	dftlearn.io	#4
	XYZ geometry & site labels	tested	dftlearn.io
	Delta-KS / FINAL ENERGY / TP LUMO (E^c)	tested	dftlearn.io
	Full ground / excited / TP directory load	tested	dftlearn.io.stobe_run (load_stobe_run; staging stobeLoader remains)	#2

Filter & cluster · 5/8

	Capability	Completion	Location	Track
	Energy window + OS% cull	tested	dftlearn.clustering	#4
	Gaussian peak-overlap matrices	tested	dftlearn.clustering	#4
	Iterative overlap merge (simpleCluster3)	tested	dftlearn.clustering	#4
	OS% elbow cutoff	tested	dftlearn.clustering	#4
	OVP threshold selection (BIC / GP)	tested	dftlearn.clustering	#4
	filterDFT-style end-to-end orchestration	in progress	dftrun postprocess (partial)	#1
	OS × OVP sequential grids (seqThresholds)	not started	—
	Amplitude refit to pre-merge DFT NEXAFS	not started	—	#1
	Alternate %-difference clusterer (pDiff)	out of scope	—

Symmetry · 1/3

	Capability	Completion	Location	Track
	C3 dipole fold / site OS from tensors	tested	dftlearn.xas
	General n-fold TDM symmetry (iso / uni / bi / tri)	not started	—	#1
	TDM frame reorientation (Euler on transitions)	not started	—

Tensors & experiment · 3/5

	Capability	Completion	Location	Track
	TP XAS reconstruction & broadening schedule	tested	dftlearn.xas	#4
	Molecular dipole / Cartesian OS tables	tested	dftlearn.xas	#4
	Bare-atom / Henke step edge	tested	dftlearn.xas.step_edge	#3
	Film tilt / simDFT / angle-resolved model	in progress	python_pipeline/multiSpecFitProcs	#3
	Multi-spectrum experiment fit	in progress	python_pipeline/multiSpecFitProcs	#3

Visualization & UI · 2/3

	Capability	Completion	Location	Track
	Cluster & reconstruction report figures	tested	dftlearn.visualization	#4
	Site / SCF / orbital summary figures	tested	dftlearn.visualization (package_stobe_run)
	Interactive clustering panel parity	not started	HF Space / demos	#5
	Chem3D molecular viewer	out of scope	—
	Igor panel chrome / wave selectors	out of scope	—

Overall: 15/23

Citation

@article{Murcia2026OpticalTensors,
  title   = {Quantitative and Bond-Traceable Resonant X-Ray Optical Tensors of Organic Molecules},
  author  = {Murcia, Victor and Alqahtani, Obaid and Heilman, Harlan and Collins, Brian A.},
  journal = {Phys. Rev. Lett.},
  volume  = {137},
  issue   = {15},
  pages   = {158001},
  year    = {2026},
  doi     = {10.1103/rfgg-ffyz},
  url     = {https://journals.aps.org/prl/abstract/10.1103/rfgg-ffyz}
}

CITATION.cff · lab publications

License

MIT (LICENSE). Maintainer: Harlan Heilman.