How facebookresearch/adjoint_sampling works
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