How azureleon1/diffspectra works
1. What this repo is
- DiffSpectra is a conditional molecular diffusion system for structure elucidation from spectra.
- The core task is: given one or more spectral modalities, generate a molecule with both 2D connectivity and 3D geometry.
- The repository is centered on the QM9S dataset and on evaluating generated molecules against ground truth structures.
2. Top-level execution path
- main.py is the entry point.
- It dispatches between training and evaluation modes and loads experiment configuration from configs/.
- run_lib.py appears to hold the higher-level orchestration for model initialization, training loops, validation, and checkpoint handling.
- The experiment outputs, checkpoints, and evaluation artifacts live under exp/.
3. Modeling split: spectrum encoder + molecular diffusion model
- The architecture has two major model subsystems:
- SpecFormer (models/specformer.py, models/specformer_layers.py): a spectral encoder for multi-modal spectral input.
- DMT / Diffusion Molecule Transformer (models/dmt.py, with alternatives like dmt_wo_eq.py, cdgs.py): the denoiser/generator that reconstructs molecular structure.
- This split is the main boundary in the system: spectra are encoded first, then the resulting conditioning signal drives the molecule diffusion process.
4. Conditional diffusion core
- diffusion/noise_schedule.py defines the forward noising schedule used by the generative process.
- losses.py likely implements the denoising objectives used during training.
- sampling.py handles reverse-time generation, turning a spectrum-conditioned latent/noisy molecule state into final molecular samples.
- This is the key data flow for inference: spectra → spectral embeddings → diffusion denoising steps → sampled molecule.
5. 2D/3D molecular representation
- The model is explicitly designed to model both graph topology and geometry.
- The DMT-related files and models/layers.py suggest a graph/geometry-aware backbone, with SE(3)-equivariant behavior emphasized in the README.
- models/ema.py indicates an exponential moving average of weights for more stable diffusion training/sampling, which is a common boundary between optimization state and inference state.
6. Dataset and preprocessing boundary
- datasets/ contains the data pipeline, with qm9s_dataset.py as the concrete dataset implementation.
- datasets/build_dataset.py and datasets/datasets_config.py indicate dataset construction is config-driven and likely supports different spectra variants.
- The README and config names show the dataset can be switched between all spectra, IR, Raman, and UV-Vis, so the input schema is a major configurable boundary.
7. Configuration structure
- configs/base_qm9.py defines the shared molecular dataset/training defaults.
- configs/diffspectra_qm9s.py defines the DiffSpectra-specific setup.
- The repo is designed so that spectrum modality, model type, checkpoint paths, and evaluation parameters are all controlled externally via config overrides rather than hard-coded behavior.
8. Training and checkpoint lifecycle
- Training is launched through main.py with a work directory under exp/.
- The pretrained SpecFormer option in the README implies the encoder can be loaded separately from the diffusion model.
- This creates two checkpoint boundaries:
- SpecFormer pretraining/transfer
- Diffusion model training and sampling
- The scripts/ directory provides batch wrappers for running repeated train/eval jobs.
9. Evaluation subsystem
- evaluation/ contains chemistry and geometry metrics:
- rdkit_metric.py for molecular validity/similarity-style metrics via RDKit
- bond_analyze.py, cal_geometry.py, stability.py for structural checks
- mmd.py and mose_metric.py for distribution-level comparison
- eval_sampled_mols/ provides post-processing metrics on generated molecules, including rmsd.py for 3D structural deviation.
- The evaluation flow is therefore: generated molecules → RDKit/geometry metric computation → results saved under exp/{run}/eval/.
10. Visualization and analysis
- visualize.py is a separate analysis/output path for inspecting generated molecules.
- compute_metrics.py appears to consolidate evaluation reporting outside the main training/eval loop.
- assets/ contains figures used in the paper, not runtime code, so the repository cleanly separates research artifacts from the executable pipeline.
11. Technology and runtime shape
- The repo is a Python research codebase, likely built around deep learning and molecular chemistry tooling.
- RDKit is a material external dependency because the evaluation stack depends on chemically meaningful validation and similarity metrics.
- GPU execution is assumed from the training/eval commands and CUDA_VISIBLE_DEVICES, so compute-heavy generation is designed for multi-GPU local or cluster runs.
12. Architectural summary for a diagram
- Draw the system as four layers:
- Data/config layer: QM9S dataset + modality-specific configs
- Conditioning layer: SpecFormer spectral encoder
- Generative layer: diffusion/noise schedule + DMT denoiser + EMA
- Evaluation layer: RDKit/geometry/stability metrics + saved outputs in exp/
- The most important arrows are:
- spectra to SpecFormer
- SpecFormer embeddings to DMT
- DMT through diffusion sampling to molecules
- molecules into evaluation/visualization pipelines
Main entry points: run_lib.py Run lib · dmt.py DMT · sampling.py Sampling · specformer.py SpecFormer
Components 29
Data / config
Dataset construction and experiment configuration for QM9S and spectrum modalities.
- Base QM9 · Shared dataset and training defaults.
configs/base_qm9.py - DiffSpectra QM9S · Repository-specific experiment configuration for spectrum-conditioned runs.
configs/diffspectra_qm9s.py - QM9S dataset · Concrete spectral-to-molecule dataset implementation.
datasets/qm9s_dataset.py - Build dataset · Constructs dataset instances from configuration.
datasets/build_dataset.py - Dataset config · Defines available dataset and modality variants.
datasets/datasets_config.py
Conditioning
Spectral encoder that turns multi-modal spectra into conditioning features.
- SpecFormer · Encodes multi-modal spectra into conditioning embeddings.
models/specformer.py - Spec layers · Building blocks used by the spectral encoder.
models/specformer_layers.py
Generative core
Diffusion model, noise schedule, sampling, and training orchestration.
- main.py · Launches training or evaluation from configuration.
main.py - Run lib · High-level experiment setup, training loop, validation, and checkpoint handling.
run_lib.py - DMT · Diffusion Molecule Transformer that denoises and generates molecular structure.
models/dmt.py - DMT no-eq · Alternative DMT variant without equivariant behavior.
models/dmt_wo_eq.py - CDGS · Alternative diffusion/generation backbone.
models/cdgs.py - Model layers · Shared molecular graph and geometry-aware layers.
models/layers.py - Noise schedule · Defines the forward noising process for diffusion training and sampling.
diffusion/noise_schedule.py - Sampling · Reverse diffusion process that turns conditioned noise into molecules.
sampling.py - Losses · Denoising and optimization objectives for diffusion training.
losses.py - EMA · Exponential moving average weights for stable training and inference.
models/ema.py
Evaluation / outputs
Chemical, geometric, and reporting tools for generated molecules and run artifacts.
- Eval suite · Chemistry, geometry, and stability metrics for generated molecules.
- RDKit metrics · Validity and similarity-style molecular metrics.
evaluation/rdkit_metric.py - Bond analyze · Bond-level structural analysis for generated molecules.
evaluation/bond_analyze.py - Geometry calc · Computes structural geometry measures.
evaluation/cal_geometry.py - Stability · Checks molecular structural stability.
evaluation/stability.py - MMD · Distribution-level comparison metric.
evaluation/mmd.py - MOSE metric · Benchmark-style evaluation metric.
evaluation/mose_metric.py - Sampled mols · Metrics for generated samples, including RMSD.
eval_sampled_mols - RMSD · Measures 3D structural deviation of sampled molecules.
eval_sampled_mols/rmsd.py - Compute metrics · Aggregates evaluation reporting outside the main loop.
compute_metrics.py - Visualize · Inspects and renders generated molecules.
visualize.py - exp/ · Run outputs, checkpoints, and evaluation artifacts.
exp
Connections 33
- main.py → Base QM9: loads defaults
- main.py → DiffSpectra QM9S: applies experiment cfg
- main.py → Run lib: dispatches
- Run lib → Build dataset: builds data
- Build dataset → Dataset config: uses schema
- Build dataset → QM9S dataset: instantiates
- QM9S dataset → DiffSpectra QM9S: modalities from cfg
- Run lib → SpecFormer: initializes encoder
- SpecFormer → Spec layers: composes layers
- Run lib → DMT: initializes generator
- DMT → Model layers: uses
- DMT → DMT no-eq: variant
- DMT → CDGS: variant
- Run lib → Noise schedule: sets diffusion
- Run lib → Losses: trains with
- Run lib → EMA: tracks weights
- QM9S dataset → SpecFormer: spectra input
- SpecFormer → DMT: conditioning embeddings
- DMT → Sampling: reverse denoising
- Noise schedule → Sampling: guides steps
- Sampling → exp/: writes samples
- Run lib → exp/: saves checkpoints
- Sampling → Eval suite: generated molecules
- Eval suite → RDKit metrics: includes
- Eval suite → Bond analyze: includes
- Eval suite → Geometry calc: includes
- Eval suite → Stability: includes
- Eval suite → MMD: includes
- Eval suite → MOSE metric: includes
- Sampling → Sampled mols: postprocesses
- Sampled mols → RMSD: includes
- Eval suite → Compute metrics: aggregated by
- Sampling → Visualize: renders for inspection