GSF-χ is a Graph Transformer for chiral molecules. It represents central and axial stereogenic units as fields over molecular atoms and uses handedness to control relative query–key rotations. Its ECD readout separates mirror-even peak counts and positions from mirror-odd peak signs.
This repository contains the model, data preparation scripts, and configurations for R/S classification, enantiomer ranking, optical rotation, and central and axial ECD prediction.
Requires Python 3.10 or later.
git clone https://github.com/OpenMOSS/GSF-chi.git
cd GSF-chi
python -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'Install a PyTorch build compatible with your CUDA runtime for GPU training.
Rebuilding RotA stereogenic-unit annotations also needs pip install -e '.[automatic]'.
Follow DATA.md to obtain the datasets and place them under data/.
Run commands from the repository root; paths in configurations are relative to
the working directory.
python scripts/check_data.py --dataset coreBuild the central-ECD cache with python scripts/prepare_central_ecd.py.
The R/S and Ranking tasks prepare their caches on first use.
Each task has a configuration in configs/paper.
gsf-chi axial_rotation --config configs/paper/axial_rotation.json
gsf-chi axial_ecd --config configs/paper/axial_ecd.json
gsf-chi rs --config configs/paper/rs.json
gsf-chi ranking --config configs/paper/ranking.json
gsf-chi central_ecd --config configs/paper/central_ecd.jsonpython -m gsf_chi is equivalent to gsf-chi. Add --dry-run to inspect the
resolved arguments. Command-line options override configuration values:
gsf-chi axial_ecd --config configs/paper/axial_ecd.json --device cpu --dry-run| File | Purpose |
|---|---|
attention.py |
Global field, pair gates, and Chiral-RoPE correction |
model.py |
Graph Transformer and molecular readout |
ecd.py |
Shared encoder and parity-projected ECD heads |
ecd_metrics.py |
ECD losses, decoders, and evaluation |
data/ |
Molecular features and benchmark loaders |
tasks/ |
Training and checkpoint selection |
controls.py |
Interaction masks and reduced-supervision protocols |
configs/ablations contains the component and representation controls; configs/controls contains equal-support and one-enantiomer experiments. configs/matched records the separate replication configurations.
For MoleculeNet, run gsf-chi moleculenet --help. RotA preparation and evaluation
are in scripts/prepare_rota.py and scripts/evaluate_rota.py.
pytest -q -m 'not data'
# With ACMP, central ECD and Ranking data prepared:
pytest -q
python scripts/audit_reflection.py --helpTests cover rotation inversion, atom and unit permutations, achiral reduction, mirror parity, gradient isolation, and the support and supervision controls.
Datasets and comparison methods come from ChiDeK, ChIRo, ECDFormer, and ChiralFinder. See DATA.md for revisions and checksums. Dataset files and trained weights are obtained separately.
The code is released under the MIT license.