How cmach508/paflow works
1. What this repository is
- PAFlow is a protein-pocket-conditioned small-molecule generation system.
- The core idea is a prior-guided flow matching model for ligand generation, paired with a learnable atom-number predictor so the model can decide how large a molecule should be for a given pocket.
2. Main execution model
- The repo is organized around a few top-level entry points in scripts/.
- Training, sampling, evaluation, and dataset preparation are all separate command-line workflows.
- Configuration is file-driven via configs/*.yml, so experiments are mostly orchestrated by scripts rather than a single monolithic app.
3. Data sources and domain objects
- The project works with protein pockets and ligands in structural formats such as PDB and SDF.
- Dataset code in datasets/ suggests support for:
- protein-ligand complex datasets,
- pairwise pocket/ligand training samples,
- PDBBind-style curated affinity data,
- general protein-ligand preprocessing wrappers.
4. Data preparation boundary
- scripts/data_preparation/ contains offline preprocessing utilities for turning raw structural data into model-ready pocket/ligand inputs.
- The scripts cover:
- extracting pockets,
- cleaning CrossDocked data,
- splitting datasets,
- converting SDF ligands to PDB,
- computing pocket volume/area.
- This is an important boundary: structural chemistry prep happens before model training or inference.
5. Core generative model
- models/en_diffusion.py, models/egnn.py, and models/uni_transformer.py indicate the generator uses geometric deep learning with equivariant components.
- models/molopt_score_model.py and models/molopt_score_model_guide.py suggest score/flow-based components with a guided variant for target-aware generation.
- The model likely operates on 3D coordinates and atom types jointly, using the protein pocket as conditioning context.
6. Guidance mechanism
- The “guide” variant is a central architectural feature: sampling can be steered by an additional signal rather than relying only on the learned generative prior.
- This is exposed directly in sampling via --pos_grad_w, which controls guidance strength.
- So the inference path is not just unconditional decoding; it combines learned molecular generation with a pocket-aware gradient signal.
7. Atom-number prediction subsystem
- scripts/train_num_predictor.py and scripts/validate_num_predictor.py train and evaluate a separate predictor for ligand atom count.
- The model implementations live under models/property_pred/.
- This subsystem is used when generating molecules for a new pocket, because the number of atoms is predicted from pocket properties such as volume and area.
8. Pocket-specific generation flow
- The README shows the practical inference pipeline:
- convert a reference ligand from SDF to PDB,
- compute pocket volume and area with external tooling,
- predict atom number,
- sample a ligand conditioned on the pocket.
- This means pocket geometry features are an explicit upstream input to the generation pipeline, not just the raw pocket structure.
9. Evaluation subsystem
- scripts/evaluate_diffusion.py drives end-to-end evaluation of generated molecules.
- utils/evaluation/ contains the metric implementations:
- atom type and atom number checks,
- bond length analysis,
- similarity,
- docking via Vina/qVina,
- chemical scoring functions such as SAS and other quality measures.
- Evaluation therefore spans both geometric validity and chemistry/affinity-oriented metrics.
10. Geometry, reconstruction, and transforms
- utils/transforms.py, utils/reconstruct.py, utils/protein_ligand.py, and related helpers form the bridge between raw structural data and model tensors.
- These utilities likely handle coordinate normalization, graph construction, atom/bond reconstruction, and conversion back to molecular structures after sampling.
11. Training and sampling orchestration
- utils/train.py, utils/warmup.py, utils/misc.py, and configuration files suggest a standard PyTorch-style training loop with optimizer scheduling and experiment utilities.
- Sampling scripts are split by use case:
- sample_flow_VP_guide.py for guided generation,
- sample_for_pocket.py for custom-pocket inference,
- sample_atom_num.py for atom-count sampling,
- sample_flow_VP.py for unguided or baseline generation.
12. External dependencies that affect architecture
- The repo depends on an external pocket-volume tool, pyKVFinder, for pocket feature extraction in custom-pocket generation.
- Docking evaluation uses Vina/qVina tooling.
- The environment is explicitly aligned with KGDiff, implying the codebase follows a similar geometric deep learning stack and dependency profile.
13. Code duplication in results/models/
- The results/models/ tree mirrors models/, which suggests saved snapshots or packaged experiment outputs rather than a separate implementation layer.
- For architecture diagrams, treat results/ as generated artifacts and experiment outputs, not a core subsystem.
14. High-level flow to diagram
- Input structural data enters through dataset loaders or pocket-specific PDB/SDF files.
- Preprocessing converts and cleans those structures into pocket-ligand training samples.
- The atom-number predictor estimates ligand size from pocket features.
- The flow-matching generative model produces 3D ligand candidates conditioned on the pocket, optionally with guidance.
- Reconstruction and evaluation utilities convert outputs back into molecules and score them with validity/chemical/docking metrics.
Main entry points: pl_data.py PL data · sample_flow_VP_guide.py Guided sample · en_diffusion.py Flow model · prop_model.py Size predictor
Components 22
Scripts
Command-line workflows for training, sampling, evaluation, and preprocessing.
- Train flow · Trains the guided flow-matching ligand generator.
scripts/train_vpflow_guide_ba.py - Guided sample · Runs pocket-conditioned sampling with guidance.
scripts/sample_flow_VP_guide.py - Pocket sample · Custom-pocket inference pipeline for ligand generation.
scripts/sample_for_pocket.py - Atom sample · Samples or predicts ligand atom counts.
scripts/sample_atom_num.py - Train size pred · Trains the atom-number predictor.
scripts/train_num_predictor.py - Validate size pred · Evaluates the atom-number predictor.
scripts/validate_num_predictor.py - Evaluate gen · Evaluates generated molecules end to end.
scripts/evaluate_diffusion.py - Prep data · Offline structural preprocessing for pockets, ligands, and dataset splits.
scripts/data_preparation
Models
Geometric generative and property-prediction model implementations.
- Flow model · Core prior-guided diffusion / flow-matching generator.
models/en_diffusion.py - Score model · Target-aware score/flow model used for guided generation.
models/molopt_score_model.py - Guide model · Guided score model variant for sampling-time steering.
models/molopt_score_model_guide.py - Geom layers · Geometric backbone components for 3D molecular modeling.
models/egnn.py - Pocket encoder · Transformer-style encoder used in the model stack.
models/uni_transformer.py - Size predictor · Atom-number predictor for pocket-conditioned ligand sizing.
models/property_pred/prop_model.py - Prop EGNN · Geometric property-prediction network used by the size predictor.
models/property_pred/prop_egnn.py
Data
Dataset loaders and pocket-ligand data interfaces.
- PL data · Protein-ligand dataset abstractions and pairwise samples.
datasets/pl_data.py - PDBBind · PDBBind-style curated protein-ligand dataset support.
datasets/pdbbind.py - Pair dataset · Pairwise pocket/ligand training dataset.
datasets/pl_pair_dataset.py
Utils
Shared transforms, reconstruction, training, and evaluation utilities.
- Transforms · Coordinate normalization, graph construction, and feature transforms.
utils/transforms.py - Reconstruct · Rebuilds molecular structures from model outputs.
utils/reconstruct.py - Metrics · Validity, similarity, bond, docking, and scoring metrics.
utils/evaluation - Train utils · Training loops, scheduling, warmup, and general helpers.
utils/train.py
Connections 23
- Train flow → Flow model: trains · Optimizes the main guided generative model.
- Train flow → Train utils: uses · Relies on shared training and warmup helpers.
- Train flow → PL data: loads · Consumes protein-ligand datasets during training.
- Guided sample → Guide model: samples · Runs guided generation with the target-aware model.
- Guided sample → Flow model: decodes · Uses the diffusion/flow generator during inference.
- Guided sample → Reconstruct: reconstructs · Converts sampled atoms and coordinates back to molecules.
- Pocket sample → Atom sample: predicts size · Uses atom-count prediction as an upstream step.
- Pocket sample → Guided sample: calls · Feeds pocket-specific inputs into guided sampling.
- Atom sample → Size predictor: uses · Runs the atom-number predictor.
- Train size pred → Size predictor: trains · Fits the atom-number prediction model.
- Train size pred → Prop EGNN: encodes · Uses geometric property-prediction components.
- Validate size pred → Size predictor: evaluates · Validates atom-number prediction quality.
- Evaluate gen → Metrics: scores · Aggregates chemistry, geometry, and docking metrics.
- Evaluate gen → Reconstruct: reconstructs · Rebuilds generated molecules before scoring.
- Prep data → PL data: prepares · Produces model-ready pocket-ligand samples.
- Prep data → Transforms: normalizes · Applies structural conversion and coordinate transforms.
- PL data → Transforms: builds · Uses transforms to create training tensors.
- PDBBind → PL data: specializes · Provides curated protein-ligand dataset support.
- Pair dataset → PL data: specializes · Implements pairwise pocket/ligand training samples.
- Flow model → Geom layers: depends on · Uses equivariant geometric layers for 3D generation.
- Flow model → Pocket encoder: conditions on · Encodes pocket context for ligand generation.
- Guide model → Score model: extends · Guided variant of the target-aware score model.
- Size predictor → Prop EGNN: depends on · Uses geometric encoders for pocket-derived features.