- Python 54.9%
- Jupyter Notebook 44.5%
- Shell 0.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- Title: "Score Matching" → "Model" (matches published title) - Add Nature Computational Science badge with DOI - Add DOI to bibtex citation - Fix LICENSE badge link (refactoring → master) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
| configs | ||
| data/qm9m_raw | ||
| reproducible | ||
| scripts | ||
| src | ||
| .gitignore | ||
| __init__.py | ||
| accelerate_config.yaml | ||
| LICENSE | ||
| README.md | ||
Riemannian Denoising Model for Molecular Structure Optimization
Official implementation of "Riemannian denoising model for molecular structure optimization with chemical accuracy".
R-DSM optimizes molecular geometries from force-field (MMFF) to quantum-chemical (DFT) accuracy using a score-based diffusion model on the Riemannian manifold of internal coordinates.
Installation
Tested environment: Python 3.11.15, CUDA 12.1
conda create -n neural_opt python=3.11 -y
conda activate neural_opt
# PyTorch 2.5.1 + CUDA 12.1
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu121
# PyG 2.7.0
pip install torch_geometric==2.7.0
pip install torch_scatter==2.1.2 torch_sparse==0.6.18 -f https://data.pyg.org/whl/torch-2.5.0+cu121.html
# Other dependencies
pip install rdkit==2025.09.6 ase==3.27.0 omegaconf==2.3.0 \
accelerate==1.13.0 wandb==0.25.1 safetensors==0.7.0 \
scipy==1.17.1 numpy==2.3.5 tqdm==4.67.3
Verify installation:
python -c "from src.diffusion.model import DiffusionModel; print('OK')"
Dataset
Option A: Download processed data (recommended)
Pre-processed PyG datasets are available on Zenodo: https://zenodo.org/records/15561806
After downloading, place the data so that the directory structure matches:
neural_opt/
├── data/
│ ├── qm9m_raw/
│ │ ├── MMFFtoDFT_input/ # 133,885 xyz files (MMFF + DFT geometries)
│ │ ├── riemannian_xyz/combined/ # Riemannian-sampled xyz files (3 seeds)
│ │ ├── data_split.pkl # train/val/test indices
│ │ └── riemannian_data_sampling/ # Riemannian sampling scripts
│ ├── qm9m_MMFFtoDFT/processed/ # Cached PyG data (Stages 1 & 2)
│ │ ├── train_proc.pt, valid_proc.pt, test_proc.pt
│ └── qm9m_riemannian_3seeds/processed/ # Cached PyG data (Stage 3)
│ ├── train_proc.pt, valid_proc.pt
Option B: Process from scratch
1. Download and preprocess QM9M
cd data/qm9m_raw
# Download raw SDF files from https://yzhang.hpc.nyu.edu/IMA/
mkdir qm9_mmff && tar -xvjf qm9_mmff.tar.bz2 -C qm9_mmff
# Convert SDF → xyz (with both DFT and MMFF geometries)
python preprocessing.py --sdf_path ./qm9_mmff --save_dir ./MMFFtoDFT_input
# Generate train/val/test split
python data_split.py
# → data_split.pkl (100k train / 23,885 val / 10k test)
# Identify problematic samples
python process_wrong_samples.py
# → wrong_samples.pkl
2. Generate Riemannian training data (for Stage 3)
Riemannian noise sampling produces training pairs on the internal-coordinate manifold. Three random seeds provide structural diversity.
Each seed processes 1,000 batches, and each batch involves Jacobian pseudo-inverse (SVD) computation on CPU.
Use run_parallel.sh to split batches across multiple workers for parallelism:
cd data/qm9m_raw/riemannian_data_sampling
# Seed 42 (parallel with 8 workers)
bash run_parallel.sh --num_workers 8 \
--config_yaml riemannian_data_sampling.yaml \
--sampling_type riemannian \
--alpha 1.7 --beta 0.01 --svd_tol 1e-2 \
--t_start 0 --t_end 0.03 \
--save_xyz xyz_seed42 \
--save_csv sampling_seed42.csv \
--seed 42 --dataloader train
# Seed 1
bash run_parallel.sh --num_workers 8 \
--config_yaml riemannian_data_sampling.yaml \
--sampling_type riemannian \
--alpha 1.7 --beta 0.01 --svd_tol 1e-2 \
--t_start 0 --t_end 0.03 \
--save_xyz xyz_seed1 \
--save_csv sampling_seed1.csv \
--seed 1 --dataloader train
# Seed 2
bash run_parallel.sh --num_workers 8 \
--config_yaml riemannian_data_sampling.yaml \
--sampling_type riemannian \
--alpha 1.7 --beta 0.01 --svd_tol 1e-2 \
--t_start 0 --t_end 0.03 \
--save_xyz xyz_seed2 \
--save_csv sampling_seed2.csv \
--seed 2 --dataloader train
Note
: Without parallelization, a single seed takes ~8 hours. With 8 workers, each seed completes in ~1 hour. Worker logs are saved to
/tmp/riemannian_worker_*.log. CSV files from each worker are automatically merged after completion.
Or run sequentially without the parallel launcher:
python riemannian_data_sampling.py \
--config_yaml riemannian_data_sampling.yaml \
--sampling_type riemannian \
--alpha 1.7 --beta 0.01 --svd_tol 1e-2 \
--t_start 0 --t_end 0.03 \
--save_xyz xyz_seed42 --seed 42 --dataloader train
Combine the three seeds into a single directory:
mkdir -p ../riemannian_xyz/combined
cp xyz_seed42/* xyz_seed1/* xyz_seed2/* ../riemannian_xyz/combined/
PyG dataset objects (train_proc.pt, etc.) are automatically generated on the first training run.
Training
R-DSM uses a 3-stage training pipeline:
Stage 1: E-DSM (Euclidean) → Stage 2: R-DSM (Riemannian) → Stage 3: Finetuning
3000 epochs 3000 epochs 6000 epochs
eq_transform projection_dq2dx projection_dq2dx
lambda_x=1, lambda_q=0 lambda_x=0, lambda_q=1 lambda_x=0, lambda_q=1
data: MMFFtoDFT data: MMFFtoDFT data: riemannian_3seeds
All commands should be run from the neural_opt/ directory.
Multi-GPU setup
Create accelerate_config.yaml:
compute_environment: LOCAL_MACHINE
distributed_type: MULTI_GPU
num_machines: 1
num_processes: 4 # number of GPUs
mixed_precision: 'no'
main_training_function: main
For single-GPU training, omit the accelerate launch prefix and run python scripts/train.py directly.
Stage 1: E-DSM
Pre-training with Euclidean noise sampling on MMFF→DFT data.
accelerate launch --config_file accelerate_config.yaml \
scripts/train.py configs/training.qm9.edsm.yaml
Stage 2: R-DSM
Riemannian training, initialized from Stage 1 best checkpoint:
accelerate launch --config_file accelerate_config.yaml \
scripts/train.py configs/training.qm9.rdsm.yaml \
--resume_pl checkpoints/qm9.edsm/best
--resume_pl loads model weights only (no optimizer/scheduler state).
Stage 3: Finetuning
Finetuning on Riemannian-sampled data, initialized from Stage 2 best checkpoint:
accelerate launch --config_file accelerate_config.yaml \
scripts/train.py configs/finetuning.qm9.rdsm.yaml \
--resume_pl checkpoints/training.qm9.rdsm/best
Resuming interrupted training
If training is interrupted, resume with full state (optimizer, scheduler, EMA, epoch counter):
accelerate launch --config_file accelerate_config.yaml \
scripts/train.py configs/training.qm9.rdsm.yaml \
--resume checkpoints/training.qm9.rdsm/last
Key training details
| Parameter | Stage 1 (E-DSM) | Stage 2 (R-DSM) | Stage 3 (Finetune) |
|---|---|---|---|
| Config | training.qm9.edsm |
training.qm9.rdsm |
finetuning.qm9.rdsm |
| Epochs | 3000 | 3000 | 6000 |
| Batch size | 300 | 500 | 100 |
| Learning rate | 3e-4 | 3e-4 | 3e-4 |
| noise_type | diffusion | diffusion | diffusion_custom |
| transform | eq_transform | projection_dq2dx | projection_dq2dx |
| Data | MMFFtoDFT | MMFFtoDFT | riemannian_3seeds |
| EMA decay | 0.999 | 0.999 | 0.999 |
| Grad clipping | 100.0 | 100.0 | 100.0 |
Sampling
Generate optimized molecular geometries using the trained model. Four sampling methods are available, all operating on the same time-independent model:
| Method | Paper name | --sampler |
Description |
|---|---|---|---|
| Flow-matching ODE | FM ODE | fm_ode |
dx = f/t dt (default, best median RMSD) |
| Diffusion ODE | Prob-flow ODE | diffusion_ode |
dx = 0.5 dσ²/dt · f/σ² dt |
| Diffusion SDE | Reverse SDE | diffusion_sde |
Diffusion ODE + Langevin noise |
| Fixed-point ODE | FP ODE | fp_ode |
dx = f dτ (time-independent iteration) |
Quick start (FM ODE, default)
python scripts/sample.py configs/sampling.qm9.rdsm.yaml
Running different samplers
Use --sampler to select the sampling method:
# FM ODE (default, 128 steps, t: 1→0)
python scripts/sample.py configs/sampling.qm9.rdsm.yaml --sampler fm_ode
# Diffusion ODE (probability-flow, 128 NFE, start_time=0.03)
python scripts/sample.py configs/sampling.qm9.rdsm.langevin.yaml --sampler diffusion_ode
# Diffusion SDE (reverse SDE with Langevin noise)
python scripts/sample.py configs/sampling.qm9.rdsm.langevin.yaml --sampler diffusion_sde
# Fixed-point ODE (gradient descent, τ: 0→6)
python scripts/sample.py configs/sampling.qm9.rdsm.fixed_point.yaml --sampler fp_ode
Sampling configurations
Each sampler has a dedicated config with appropriate parameters:
| Config | Sampler | Key parameters |
|---|---|---|
sampling.qm9.rdsm.yaml |
FM ODE | sde_steps: 128, score_type: cfm |
sampling.qm9.rdsm.langevin.yaml |
Diffusion SDE/ODE | nfe: 128, start_time: 0.03 |
sampling.qm9.rdsm.fixed_point.yaml |
FP ODE | total_time: 6, dt: 0.05 |
Expected results on QM9 (MMFF initial structures)
| Method | RMSD mean (Å) | RMSD median (Å) |
|---|---|---|
| FM ODE | 0.105 | 0.032 |
| Diffusion ODE | 0.109 | 0.035 |
| Diffusion SDE | 0.109 | 0.036 |
| FP ODE | 0.104 | 0.032 |
Using different checkpoints
Edit the general.test_only field in the config:
general:
# Use retrained checkpoint
test_only: ./checkpoints/finetuning.qm9.rdsm/best
# Or use published checkpoint
# test_only: ./reproducible/checkpoints/rdsm.qm9.finetuned.ckpt
Quick test on a single batch
python scripts/sample.py configs/sampling.qm9.rdsm.yaml --batch_idx_end 1
Evaluation
python scripts/evaluate_accuracy.py \
--config_yaml configs/sampling.qm9.rdsm.yaml \
--prb_pt save_dynamic.qm9.rdsm.finetuned.pt \
--align_target RMSD
Results on QM9
| Metric | Retrained | Published checkpoint | Target |
|---|---|---|---|
| RMSD median (Å) | 0.028 | ~0.034 | ≤ 0.04 |
| D-MAE median | 0.009 | — | — |
Pre-trained Checkpoints
Published checkpoints are available in reproducible/checkpoints/:
| Dataset | E-DSM | R-DSM (pretrained) | R-DSM (finetuned) |
|---|---|---|---|
| QM9 | edsm.qm9.ckpt |
rdsm.qm9.pretrained.ckpt |
rdsm.qm9.finetuned.ckpt |
| GEOM-QM9 | — | rdsm.geom_qm9.pretrained.ckpt |
rdsm.geom_qm9.finetuned.ckpt |
| QM7-X | edsm.qm7x.ckpt |
rdsm.qm7x.pretrained.ckpt |
rdsm.qm7x.finetuned.ckpt |
Project Structure
neural_opt/
├── src/
│ ├── diffusion/
│ │ ├── model.py # DiffusionModel (forward, noise sampling, transform)
│ │ ├── sampling.py # Sampling functions (CFM, Langevin, Fixed-point)
│ │ ├── continuous_scheduler.py # SigmoidDiffusionScheduler (VP continuous-time)
│ │ └── noise_scheduler.py # Scheduler loader and legacy discrete schedulers
│ ├── dataset/
│ │ └── data_module.py # DataModule with DDP DistributedSampler
│ ├── manifold/
│ │ ├── solver.py # GeodesicSolver (dq2dx, projection, Jacobian)
│ │ └── graph.py # MolGraph, DynamicMolGraph
│ ├── metrics/
│ │ └── metrics.py # RMSD, D-MAE, Q-NORM evaluation
│ ├── model/
│ │ ├── schnet.py # SchNet graph encoder
│ │ └── edge.py # Edge-level score network
│ └── utils/
│ └── ema.py # Exponential Moving Average
├── scripts/
│ ├── train.py # Accelerate-based training loop
│ ├── sample.py # Standalone sampling script
│ └── evaluate_accuracy.py # RMSD/D-MAE/Q-NORM evaluation
├── configs/ # Training and sampling configurations
├── data/
│ └── qm9m_raw/
│ ├── preprocessing.py # SDF → xyz conversion
│ ├── data_split.py # Train/val/test split generation
│ └── riemannian_data_sampling/
│ └── riemannian_data_sampling.py # Manifold noise sampling
├── reproducible/checkpoints/ # Published model checkpoints
└── accelerate_config.yaml # Multi-GPU DDP configuration
Hardware Requirements
| Task | VRAM per GPU | Wall time (4x RTX 3090) |
|---|---|---|
| Stage 1 (E-DSM, bs=300) | ~5 GB | ~9 hours |
| Stage 2 (R-DSM, bs=500) | ~8 GB | ~9 hours |
| Stage 3 (Finetune, bs=100) | ~10 GB | ~3-7 days |
| Sampling (10k molecules) | ~13 GB | ~70 min |
Citation
@article{woo2026riemannian,
title={Riemannian denoising model for molecular structure optimization with chemical accuracy},
author={Woo, Jeheon and Kim, Seonghwan and Kim, Jun Hyeong and Kim, Woo Youn},
journal={Nature Computational Science},
pages={1--11},
year={2026},
publisher={Nature Publishing Group US New York},
doi={10.1038/s43588-025-00919-1}
}
License
This project is licensed under the MIT License. See LICENSE for details.
