zsysuyang/XAS_SPT

SPT: model checkpoints

Checkpoints accompanying Inferring structural descriptor information from X-ray absorption spectra through adaptive multiscale learning.

Suyang Zhong, Boying Huang, Pengwei Xu, Fanjie Xu, Yuhao Zhao,
Jun Cheng, Fujie Tang, Weinan E, Zhong-Qun Tian

Code · Dataset · Overview · Download & use · Weight index · Experiment guide · Citation

📖 Overview

This collection provides the experiment-specific checkpoints and configurations for SPT and the comparison models used in the reported analyses. SPT combines adaptive Fourier lifting with energy-aware graph aggregation to infer electronic and geometric descriptors from XANES. Expert models predict one descriptor, while Joint models share an encoder across the applicable descriptors.

The framework connects energy–intensity inputs to descriptor predictions through the adaptive Fourier lifting and graph branches. The diagram is reproduced from the accompanying manuscript.

Repository access

Collection	Branch	Companion code
Model checkpoints and configurations	main	SPT main
Data and reference results	main	SPT main

📊 Descriptor tasks

The computed-spectrum benchmark comprises all 12 descriptor tasks below: eight classification tasks and four regression tasks. Expert SPT has the highest test-set point estimates among the ten compared models across these 12 tasks, using weighted F1 for classification and R² for regression. The dataset collection provides the reference predictions and numerical summaries.

Absorbing sites	Classification	Regression
Non-oxygen	OS, CN, OCN, CN2, SGN	NNRS, MOOD
Oxygen	CN, CN2, SGN	NNRS, NNOSM

OS denotes oxidation state, CN first-shell coordination number, OCN oxygen coordination number, CN2 two-hop neighbourhood count, and SGN space-group number. NNRS describes first-shell bond-length dispersion, MOOD the minimum nonzero oxygen–oxygen distance, and NNOSM the mean oxidation state of neighbouring atoms. Full definitions and data fields are given in the dataset card.

🗂️ Select a checkpoint

The weight index maps each experiment and descriptor to its model ID, checkpoint and configuration. Use the designated checkpoint for the intended experiment. The registry resolves registered model IDs; application settings, experiment settings and transfer configurations select the models for each application or numerical experiment.

Directory	Use
checkpoints/benchmark/	Computed-spectrum benchmark
checkpoints/ablations/	Module and fixed-transform comparisons
checkpoints/applications/	Measured and computed application cohorts
checkpoints/robustness/	Gaussian-noise comparisons
checkpoints/interpretability/	Spectral-band and energy-window interventions
checkpoints/uncertainty/	Uncertainty analyses
checkpoints/runtime/	Runtime measurements
checkpoints/transfer/	Source and target-domain transfer models

The collection contains 415 indexed checkpoint files: 343 PyTorch .pth files and 72 serialized .joblib estimators. ASSET_MANIFEST.json lists paths and file sizes. Configuration snapshots are included in configs/; they retain the preprocessing, class maps, architecture settings and experiment associations used by the corresponding checkpoints. These models run through the SPT package, not the Transformers AutoModel interface or a hosted inference endpoint.

🔬 Inputs and outputs

Prepared prediction inputs contain 256 energy–intensity pairs and an absorbing-element symbol. Energy is supplied in eV. The selected configuration defines energy scaling, intensity normalization and descriptor encoding.

Classification outputs are physical class labels and class scores. Regression outputs follow the descriptor units in the associated configuration. The model outputs are electronic and geometric descriptors of the absorbing environment, not a reconstructed atomic structure.

📥 Run an application

Use the main branches of the SPT code repository and the corresponding XAS_SPT data collection. Follow the code repository's installation guide, then download the data and weights:

git clone --branch main https://github.com/zsy-suyang/SPT.git
cd SPT
python -m pip install -e .
python -m pip install -U huggingface_hub

hf download zsysuyang/XAS_SPT --repo-type model \
  --revision main --local-dir ../spt-models
hf download zsysuyang/XAS_SPT --repo-type dataset \
  --revision main --local-dir ../spt-data

Merge spt-models/checkpoints/ into the code checkout's checkpoints/, and retain the matching configs/. Merge datasets/, data/, reference_predictions/ and reference_results/ from spt-data into the checkout. Keep the code README and licence at its root. The download guide describes the assembled layout. From the assembled checkout, run:

spt verify-assets --all-assets
spt application --cohort ni_fe_activation \
  --tasks OS CN OCN NNRS MOOD \
  --output outputs/ni_fe_activation.csv

The command selects the five designated Ni–Fe checkpoints and applies CPU float32 inference with four PyTorch threads. The resulting CSV contains predictions and class scores; its companion metadata records the models and execution settings. Use a new output filename for each run.

The numerical-experiment guide provides commands for the computed benchmark, Gaussian noise, interventions and uncertainty analyses. Those reference runs use their documented device and arithmetic settings. Transfer commands are documented separately.

⚙️ Evaluation and training

The data collection includes per-spectrum reference predictions and numerical summaries. Use the public experiment commands with their fixed partitions to evaluate the supplied models. Supported neural-model training configurations can also be used with spt train; tree-model evaluation uses the benchmark command and supplied estimators. Configuration and training-partition mappings are in the weight index and the code repository's checkpoint guide.

⚖️ Licence

The repository retains its Apache 2.0 licence for author-provided material; see LICENSE. Third-party components retain their respective terms, as documented in the code repository's third-party notices. Load serialized checkpoints and estimators only from trusted sources.

📝 Citation and contact

Please cite the accompanying manuscript and this checkpoint collection. CITATION.cff contains the author information and manuscript title.

@misc{spt_models_2026,
  author = {Zhong, Suyang and Huang, Boying and Xu, Pengwei and Xu, Fanjie and Zhao, Yuhao and Cheng, Jun and Tang, Fujie and E, Weinan and Tian, Zhong-Qun},
  title = {SPT model checkpoints and configurations},
  year = {2026},
  url = {https://huggingface.co/zsysuyang/XAS_SPT}
}

For usage questions, open a GitHub issue or a discussion in this repository.