# facebookresearch/adjoint_sampling architecture

> Architecture diagram of the GitHub repository facebookresearch/adjoint_sampling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/adjoint_sampling
- Repository: https://github.com/facebookresearch/adjoint_sampling

## Overview

##### Project type and purpose
- This is a research-oriented, full-stack machine-learning framework for diffusion-based sampling of molecular conformers (“Adjoint Sampling”).
- It includes modules for dataset preprocessing, energy evaluation, sampler definition, training loops, and evaluation loops.
- It uses Hydra for configuration, external model checkpoints from Hugging Face, and molecular conformer data from SPICE/GEOM.

##### File structure
- Top-level scripts:
– train.py: entry‐point for training experiments (uses hydra).
– eval.py / eval_distributed.sh: entry-points for evaluation.
– cache_dataset.py: dataset preprocessing & caching.
– download_models.py: download pretrained checkpoints from Hugging Face.
- Configuration directory: configs/ (nested per component: dataset, energy, controller, noise_schedule, experiment, train.yaml).
- Core library: adjoint_sampling/
– components/: building blocks (SDEs, samplers, controllers, buffers, noise schedules)
– energies/: energy functions (fairchem, regularizers)
– sampletorsion/: torsional‐specific sampling pipeline (featurizers, rotations, score models)
– train_loop.py / eval_loop.py: orchestrate epochs, logging, checkpointing
– utils/: distributed training helpers, data utils, visualization, evaluation helpers
- Data directory: data/ contains raw molecule lists & conformer files (drugs, spice).
- models/ (created at runtime) holds downloaded & trained checkpoints.
- environment.yml / pyproject.toml: dependencies and build config.

##### README for additional insights
- Hydra config is central—each script uses `python train.py experiment=…` style overrides.
- External dependencies: CREST program for obtaining conformers, Hugging Face token for energy model checkpoints (eSEN).
- Distributed training uses a shared directory (`shared_dir`) via hydra.

a. Main components
- CLI layer: train.py, eval.py, cache_dataset.py, download_models.py
- Config & orchestration: Hydra config (configs/)
- Data layer: raw data (data/*.txt, conformers) → cached dataset
- Model & sampling layer:
– Sampler components (SDE, noise schedule, controllers, sample_buffer)
– Energy functions (fairchem_energy)
– Torsion‐specific pipeline (sampletorsion/)
- Training loop: builds model, computes loss (adjoint matching), updates parameters
- Evaluation loop: loads checkpoint, samples, compares to true conformers
- External services:
– Hugging Face model hub (download_models.py)
– CREST binary for conformer generation
b. Relationships & interactions
- CLI → Hydra → Core library modules → Data & Models → Output (checkpoints, metrics)
- Training loop calls sampler + energy → backprop → updates → checkpoint → model folder
- Evaluation loop loads checkpoint → sampler → metrics → results folder
- cache_dataset preprocesses raw .txt → stores cache in shared_dir → data_utils loads cache
- download_models fetches from HF → saves to models/ → train/eval use checkpoints
c. Architectural patterns & design principles
- Modular design: separation of sampler components, energy functions, dataset loading, training logic, evaluation logic
- Configuration as code: Hydra config directory with per‐component YAML files
- Distributed training: torch distributed via utils/distributed_mode.py, shared cache directory
- Extensibility: plug in new energy functions, noise schedules, controllers via components/
d. Key technologies, frameworks, libraries
- Python, Hydras (hydra-core), PyTorch (deep learning), joblib (ourjoblib), external CREST tool, Hugging Face Hub, micromamba, eSEN energy model

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        train["train.py (CLI)"]:::script
        eval_py["eval.py (CLI)"]:::script
        eval_sh["eval_distributed.sh (CLI)"]:::script
        cache["cache_dataset.py (CLI)"]:::script
        download["download_models.py (CLI)"]:::script
    end

    %% Config & Orchestration
    subgraph "Config & Orchestration"
        config["Hydra Configs (configs/)"]:::config
    end

    %% Data Layer
    subgraph "Data Layer"
        raw["Raw Data (data/)"]:::data
        cache_ds["Cached Dataset (shared_dir)"]:::data
    end

    %% Core Library
    subgraph "Core Library"
        components["Components (adjoint_sampling/components/)"]:::module
        energies["Energies (adjoint_sampling/energies/)"]:::module
        sampletorsion["Sampletorsion (adjoint_sampling/sampletorsion/)"]:::module
        utils["Utils (adjoint_sampling/utils/)"]:::module
    end

    %% Training & Evaluation Loops
    train_loop["adjoint_sampling/train_loop.py"]:::module
    eval_loop["adjoint_sampling/eval_loop.py"]:::module

    %% External Services
    externalHF["Hugging Face Hub"]:::external
    externalCREST["CREST Binary"]:::external

    %% Runtime Outputs
    subgraph "Outputs"
        models["Models & Checkpoints (models/)"]:::output
        metrics["Metrics & Results"]:::output
    end

    %% Relationships
    train -->|"uses"| config
    eval_py -->|"uses"| config
    eval_sh -->|"uses"| config
    cache -->|"uses"| config
    cache -->|"reads"| raw
    cache -->|"writes"| cache_ds
    config -->|"params"| train_loop
    config -->|"params"| eval_loop
    train -->|"triggers"| train_loop
    train_loop -->|"loads"| components
    train_loop -->|"loads"| energies
    train_loop -->|"loads"| sampletorsion
    train_loop -->|"uses"| utils
    train_loop -->|"writes"| models
    train_loop -->|"writes"| metrics
    eval_py -->|"triggers"| eval_loop
    eval_sh -->|"triggers"| eval_loop
    eval_loop -->|"reads"| models
    eval_loop -->|"uses"| sampletorsion
    eval_loop -->|"writes"| metrics
    download -->|"fetches from"| externalHF
    download -->|"saves to"| models
    cache -->|"calls"| externalCREST

    %% Click Events
    click train "https://github.com/facebookresearch/adjoint_sampling/blob/main/train.py"
    click eval_py "https://github.com/facebookresearch/adjoint_sampling/blob/main/eval.py"
    click eval_sh "https://github.com/facebookresearch/adjoint_sampling/blob/main/eval_distributed.sh"
    click cache "https://github.com/facebookresearch/adjoint_sampling/blob/main/cache_dataset.py"
    click download "https://github.com/facebookresearch/adjoint_sampling/blob/main/download_models.py"
    click config "https://github.com/facebookresearch/adjoint_sampling/tree/main/configs/"
    click raw "https://github.com/facebookresearch/adjoint_sampling/tree/main/data/"
    click components "https://github.com/facebookresearch/adjoint_sampling/tree/main/adjoint_sampling/components/"
    click energies "https://github.com/facebookresearch/adjoint_sampling/tree/main/adjoint_sampling/energies/"
    click sampletorsion "https://github.com/facebookresearch/adjoint_sampling/tree/main/adjoint_sampling/sampletorsion/"
    click utils "https://github.com/facebookresearch/adjoint_sampling/tree/main/adjoint_sampling/utils/"
    click train_loop "https://github.com/facebookresearch/adjoint_sampling/blob/main/adjoint_sampling/train_loop.py"
    click eval_loop "https://github.com/facebookresearch/adjoint_sampling/blob/main/adjoint_sampling/eval_loop.py"
    click models "https://github.com/facebookresearch/adjoint_sampling/tree/main/models/"

    %% Styles
    classDef script fill:#D0E6FF,stroke:#0366d6,stroke-width:1px;
    classDef config fill:#FFF4C1,stroke:#D6A500,stroke-width:1px;
    classDef module fill:#DFFFE0,stroke:#28A745,stroke-width:1px;
    classDef data fill:#FFE4B2,stroke:#E36209,stroke-width:1px;
    classDef external fill:#EDEDED,stroke:#6A737D,stroke-width:1px,stroke-dasharray: 3 3;
    classDef output fill:#E0F7FF,stroke:#0366d6,stroke-width:1px;
```
