# azureleon1/diffspectra architecture

> Architecture diagram of the GitHub repository azureleon1/diffspectra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azureleon1/diffspectra
- Repository: https://github.com/azureleon1/diffspectra

## Overview

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`](https://github.com/azureleon1/diffspectra/blob/main/run_lib.py) (Run lib), [`models/dmt.py`](https://github.com/azureleon1/diffspectra/blob/main/models/dmt.py) (DMT), [`sampling.py`](https://github.com/azureleon1/diffspectra/blob/main/sampling.py) (Sampling), [`models/specformer.py`](https://github.com/azureleon1/diffspectra/blob/main/models/specformer.py) (SpecFormer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_data_config["Data / config"]
  node_configs_base_qm9["Base QM9<br/>config<br/>[base_qm9.py]"]
  node_configs_diffspectra_qm9s["DiffSpectra QM9S<br/>config"]
  node_datasets_qm9s_dataset[("QM9S dataset<br/>[qm9s_dataset.py]")]
  node_datasets_build_dataset["Build dataset<br/>factory<br/>[build_dataset.py]"]
  node_datasets_config["Dataset config<br/>schema<br/>[datasets_config.py]"]
end

subgraph group_group_conditioning["Conditioning"]
  node_specformer_py["SpecFormer<br/>spectral encoder<br/>[specformer.py]"]
  node_specformer_layers_py["Spec layers<br/>encoder layers"]
end

subgraph group_group_generative["Generative core"]
  node_main_py["main.py<br/>entrypoint<br/>[main.py]"]
  node_run_lib_py["Run lib<br/>orchestration<br/>[run_lib.py]"]
  node_dmt_py["DMT<br/>diffusion model<br/>[dmt.py]"]
  node_dmt_wo_eq_py["DMT no-eq<br/>variant<br/>[dmt_wo_eq.py]"]
  node_cdgs_py["CDGS<br/>variant<br/>[cdgs.py]"]
  node_layers_py["Model layers<br/>geometry layers<br/>[layers.py]"]
  node_noise_schedule_py["Noise schedule<br/>diffusion schedule<br/>[noise_schedule.py]"]
  node_sampling_py["Sampling<br/>generation<br/>[sampling.py]"]
  node_losses_py["Losses<br/>training loss<br/>[losses.py]"]
  node_ema_py["EMA<br/>training state<br/>[ema.py]"]
end

subgraph group_group_eval["Evaluation / outputs"]
  node_evaluation_suite["Eval suite<br/>metrics"]
  node_rdkit_metric_py["RDKit metrics<br/>chem metrics<br/>[rdkit_metric.py]"]
  node_bond_analyze_py["Bond analyze<br/>geometry check<br/>[bond_analyze.py]"]
  node_cal_geometry_py["Geometry calc<br/>geometry metric<br/>[cal_geometry.py]"]
  node_stability_py["Stability<br/>[stability.py]"]
  node_mmd_py["MMD<br/>distribution metric<br/>[mmd.py]"]
  node_mose_metric_py["MOSE metric<br/>benchmark metric<br/>[mose_metric.py]"]
  node_eval_sampled_mols["Sampled mols<br/>postprocess"]
  node_rmsd_py["RMSD<br/>3d metric<br/>[rmsd.py]"]
  node_compute_metrics_py["Compute metrics<br/>reporting<br/>[compute_metrics.py]"]
  node_visualize_py["Visualize<br/>analysis<br/>[visualize.py]"]
  node_exp_dir[("exp/<br/>artifacts")]
end

node_main_py -->|"loads defaults"| node_configs_base_qm9
node_main_py -->|"applies experiment cfg"| node_configs_diffspectra_qm9s
node_main_py -->|"dispatches"| node_run_lib_py
node_run_lib_py -->|"builds data"| node_datasets_build_dataset
node_datasets_build_dataset -->|"uses schema"| node_datasets_config
node_datasets_build_dataset -->|"instantiates"| node_datasets_qm9s_dataset
node_datasets_qm9s_dataset -.->|"modalities from cfg"| node_configs_diffspectra_qm9s
node_run_lib_py -->|"initializes encoder"| node_specformer_py
node_specformer_py -->|"composes layers"| node_specformer_layers_py
node_run_lib_py -->|"initializes generator"| node_dmt_py
node_dmt_py -->|"uses"| node_layers_py
node_dmt_py -.->|"variant"| node_dmt_wo_eq_py
node_dmt_py -.->|"variant"| node_cdgs_py
node_run_lib_py -->|"sets diffusion"| node_noise_schedule_py
node_run_lib_py -->|"trains with"| node_losses_py
node_run_lib_py -->|"tracks weights"| node_ema_py
node_datasets_qm9s_dataset -->|"spectra input"| node_specformer_py
node_specformer_py -->|"conditioning embeddings"| node_dmt_py
node_dmt_py -->|"reverse denoising"| node_sampling_py
node_noise_schedule_py -->|"guides steps"| node_sampling_py
node_sampling_py -->|"writes samples"| node_exp_dir
node_run_lib_py -->|"saves checkpoints"| node_exp_dir
node_sampling_py -->|"generated molecules"| node_evaluation_suite
node_evaluation_suite -->|"includes"| node_rdkit_metric_py
node_evaluation_suite -->|"includes"| node_bond_analyze_py
node_evaluation_suite -->|"includes"| node_cal_geometry_py
node_evaluation_suite -->|"includes"| node_stability_py
node_evaluation_suite -->|"includes"| node_mmd_py
node_evaluation_suite -->|"includes"| node_mose_metric_py
node_sampling_py -->|"postprocesses"| node_eval_sampled_mols
node_eval_sampled_mols -->|"includes"| node_rmsd_py
node_evaluation_suite -.->|"aggregated by"| node_compute_metrics_py
node_sampling_py -.->|"renders for inspection"| node_visualize_py

click node_main_py "https://github.com/azureleon1/diffspectra/blob/main/main.py"
click node_run_lib_py "https://github.com/azureleon1/diffspectra/blob/main/run_lib.py"
click node_configs_base_qm9 "https://github.com/azureleon1/diffspectra/blob/main/configs/base_qm9.py"
click node_configs_diffspectra_qm9s "https://github.com/azureleon1/diffspectra/blob/main/configs/diffspectra_qm9s.py"
click node_datasets_qm9s_dataset "https://github.com/azureleon1/diffspectra/blob/main/datasets/qm9s_dataset.py"
click node_datasets_build_dataset "https://github.com/azureleon1/diffspectra/blob/main/datasets/build_dataset.py"
click node_datasets_config "https://github.com/azureleon1/diffspectra/blob/main/datasets/datasets_config.py"
click node_specformer_py "https://github.com/azureleon1/diffspectra/blob/main/models/specformer.py"
click node_specformer_layers_py "https://github.com/azureleon1/diffspectra/blob/main/models/specformer_layers.py"
click node_dmt_py "https://github.com/azureleon1/diffspectra/blob/main/models/dmt.py"
click node_dmt_wo_eq_py "https://github.com/azureleon1/diffspectra/blob/main/models/dmt_wo_eq.py"
click node_cdgs_py "https://github.com/azureleon1/diffspectra/blob/main/models/cdgs.py"
click node_layers_py "https://github.com/azureleon1/diffspectra/blob/main/models/layers.py"
click node_noise_schedule_py "https://github.com/azureleon1/diffspectra/blob/main/diffusion/noise_schedule.py"
click node_sampling_py "https://github.com/azureleon1/diffspectra/blob/main/sampling.py"
click node_losses_py "https://github.com/azureleon1/diffspectra/blob/main/losses.py"
click node_ema_py "https://github.com/azureleon1/diffspectra/blob/main/models/ema.py"
click node_rdkit_metric_py "https://github.com/azureleon1/diffspectra/blob/main/evaluation/rdkit_metric.py"
click node_bond_analyze_py "https://github.com/azureleon1/diffspectra/blob/main/evaluation/bond_analyze.py"
click node_cal_geometry_py "https://github.com/azureleon1/diffspectra/blob/main/evaluation/cal_geometry.py"
click node_stability_py "https://github.com/azureleon1/diffspectra/blob/main/evaluation/stability.py"
click node_mmd_py "https://github.com/azureleon1/diffspectra/blob/main/evaluation/mmd.py"
click node_mose_metric_py "https://github.com/azureleon1/diffspectra/blob/main/evaluation/mose_metric.py"
click node_eval_sampled_mols "https://github.com/azureleon1/diffspectra/tree/main/eval_sampled_mols"
click node_rmsd_py "https://github.com/azureleon1/diffspectra/blob/main/eval_sampled_mols/rmsd.py"
click node_compute_metrics_py "https://github.com/azureleon1/diffspectra/blob/main/compute_metrics.py"
click node_visualize_py "https://github.com/azureleon1/diffspectra/blob/main/visualize.py"
click node_exp_dir "https://github.com/azureleon1/diffspectra/tree/main/exp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_configs_base_qm9,node_configs_diffspectra_qm9s,node_datasets_qm9s_dataset,node_datasets_build_dataset,node_datasets_config toneBlue
class node_specformer_py,node_specformer_layers_py toneAmber
class node_main_py,node_run_lib_py,node_dmt_py,node_dmt_wo_eq_py,node_cdgs_py,node_layers_py,node_noise_schedule_py,node_sampling_py,node_losses_py,node_ema_py toneMint
class node_evaluation_suite,node_rdkit_metric_py,node_bond_analyze_py,node_cal_geometry_py,node_stability_py,node_mmd_py,node_mose_metric_py,node_eval_sampled_mols,node_rmsd_py,node_compute_metrics_py,node_visualize_py,node_exp_dir toneRose
```

## Components

### Data / config

Dataset construction and experiment configuration for QM9S and spectrum modalities.

- [Base QM9](https://github.com/azureleon1/diffspectra/blob/main/configs/base_qm9.py): config · Shared dataset and training defaults. · `configs/base_qm9.py`
- [DiffSpectra QM9S](https://github.com/azureleon1/diffspectra/blob/main/configs/diffspectra_qm9s.py): config · Repository-specific experiment configuration for spectrum-conditioned runs. · `configs/diffspectra_qm9s.py`
- [QM9S dataset](https://github.com/azureleon1/diffspectra/blob/main/datasets/qm9s_dataset.py): dataset · Concrete spectral-to-molecule dataset implementation. · `datasets/qm9s_dataset.py`
- [Build dataset](https://github.com/azureleon1/diffspectra/blob/main/datasets/build_dataset.py): factory · Constructs dataset instances from configuration. · `datasets/build_dataset.py`
- [Dataset config](https://github.com/azureleon1/diffspectra/blob/main/datasets/datasets_config.py): schema · Defines available dataset and modality variants. · `datasets/datasets_config.py`

### Conditioning

Spectral encoder that turns multi-modal spectra into conditioning features.

- [SpecFormer](https://github.com/azureleon1/diffspectra/blob/main/models/specformer.py): spectral encoder · Encodes multi-modal spectra into conditioning embeddings. · `models/specformer.py`
- [Spec layers](https://github.com/azureleon1/diffspectra/blob/main/models/specformer_layers.py): encoder layers · Building blocks used by the spectral encoder. · `models/specformer_layers.py`

### Generative core

Diffusion model, noise schedule, sampling, and training orchestration.

- [main.py](https://github.com/azureleon1/diffspectra/blob/main/main.py): entrypoint · Launches training or evaluation from configuration. · `main.py`
- [Run lib](https://github.com/azureleon1/diffspectra/blob/main/run_lib.py): orchestration · High-level experiment setup, training loop, validation, and checkpoint handling. · `run_lib.py`
- [DMT](https://github.com/azureleon1/diffspectra/blob/main/models/dmt.py): diffusion model · Diffusion Molecule Transformer that denoises and generates molecular structure. · `models/dmt.py`
- [DMT no-eq](https://github.com/azureleon1/diffspectra/blob/main/models/dmt_wo_eq.py): variant · Alternative DMT variant without equivariant behavior. · `models/dmt_wo_eq.py`
- [CDGS](https://github.com/azureleon1/diffspectra/blob/main/models/cdgs.py): variant · Alternative diffusion/generation backbone. · `models/cdgs.py`
- [Model layers](https://github.com/azureleon1/diffspectra/blob/main/models/layers.py): geometry layers · Shared molecular graph and geometry-aware layers. · `models/layers.py`
- [Noise schedule](https://github.com/azureleon1/diffspectra/blob/main/diffusion/noise_schedule.py): diffusion schedule · Defines the forward noising process for diffusion training and sampling. · `diffusion/noise_schedule.py`
- [Sampling](https://github.com/azureleon1/diffspectra/blob/main/sampling.py): generation · Reverse diffusion process that turns conditioned noise into molecules. · `sampling.py`
- [Losses](https://github.com/azureleon1/diffspectra/blob/main/losses.py): training loss · Denoising and optimization objectives for diffusion training. · `losses.py`
- [EMA](https://github.com/azureleon1/diffspectra/blob/main/models/ema.py): training state · 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**: metrics · Chemistry, geometry, and stability metrics for generated molecules.
- [RDKit metrics](https://github.com/azureleon1/diffspectra/blob/main/evaluation/rdkit_metric.py): chem metrics · Validity and similarity-style molecular metrics. · `evaluation/rdkit_metric.py`
- [Bond analyze](https://github.com/azureleon1/diffspectra/blob/main/evaluation/bond_analyze.py): geometry check · Bond-level structural analysis for generated molecules. · `evaluation/bond_analyze.py`
- [Geometry calc](https://github.com/azureleon1/diffspectra/blob/main/evaluation/cal_geometry.py): geometry metric · Computes structural geometry measures. · `evaluation/cal_geometry.py`
- [Stability](https://github.com/azureleon1/diffspectra/blob/main/evaluation/stability.py): stability metric · Checks molecular structural stability. · `evaluation/stability.py`
- [MMD](https://github.com/azureleon1/diffspectra/blob/main/evaluation/mmd.py): distribution metric · Distribution-level comparison metric. · `evaluation/mmd.py`
- [MOSE metric](https://github.com/azureleon1/diffspectra/blob/main/evaluation/mose_metric.py): benchmark metric · Benchmark-style evaluation metric. · `evaluation/mose_metric.py`
- [Sampled mols](https://github.com/azureleon1/diffspectra/tree/main/eval_sampled_mols): postprocess · Metrics for generated samples, including RMSD. · `eval_sampled_mols`
- [RMSD](https://github.com/azureleon1/diffspectra/blob/main/eval_sampled_mols/rmsd.py): 3d metric · Measures 3D structural deviation of sampled molecules. · `eval_sampled_mols/rmsd.py`
- [Compute metrics](https://github.com/azureleon1/diffspectra/blob/main/compute_metrics.py): reporting · Aggregates evaluation reporting outside the main loop. · `compute_metrics.py`
- [Visualize](https://github.com/azureleon1/diffspectra/blob/main/visualize.py): analysis · Inspects and renders generated molecules. · `visualize.py`
- [exp/](https://github.com/azureleon1/diffspectra/tree/main/exp): artifacts · Run outputs, checkpoints, and evaluation artifacts. · `exp`

## Connections

- 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
