# cmach508/paflow architecture

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

- Interactive diagram: https://gitdiagram.com/cmach508/paflow
- Repository: https://github.com/cmach508/paflow

## Overview

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: [`datasets/pl_data.py`](https://github.com/cmach508/paflow/blob/main/datasets/pl_data.py) (PL data), [`scripts/sample_flow_VP_guide.py`](https://github.com/cmach508/paflow/blob/main/scripts/sample_flow_VP_guide.py) (Guided sample), [`models/en_diffusion.py`](https://github.com/cmach508/paflow/blob/main/models/en_diffusion.py) (Flow model), [`models/property_pred/prop_model.py`](https://github.com/cmach508/paflow/blob/main/models/property_pred/prop_model.py) (Size predictor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_scripts["Scripts"]
  node_node_train_flow["Train flow<br/>entry script"]
  node_node_sample_flow["Guided sample<br/>entry script"]
  node_node_sample_pocket["Pocket sample<br/>entry script"]
  node_node_sample_num["Atom sample<br/>entry script<br/>[sample_atom_num.py]"]
  node_node_train_num["Train size pred<br/>entry script"]
  node_node_eval_num["Validate size pred<br/>entry script"]
  node_node_eval_diff["Evaluate gen<br/>entry script"]
  node_node_prep["Prep data<br/>preprocess suite"]
end

subgraph group_grp_models["Models"]
  node_node_diffusion(("Flow model<br/>generative model<br/>[en_diffusion.py]"))
  node_node_score(("Score model<br/>guided model"))
  node_node_score_guide(("Guide model<br/>guided variant"))
  node_node_geom(("Geom layers<br/>equivariant layers<br/>[egnn.py]"))
  node_node_encoder(("Pocket encoder<br/>transformer encoder<br/>[uni_transformer.py]"))
  node_node_prop(("Size predictor<br/>property model<br/>[prop_model.py]"))
  node_node_prop_geom(("Prop EGNN<br/>property encoder<br/>[prop_egnn.py]"))
end

subgraph group_grp_data["Data"]
  node_node_pldata["PL data<br/>dataset layer<br/>[pl_data.py]"]
  node_node_pdbbind["PDBBind<br/>dataset<br/>[pdbbind.py]"]
  node_node_plpair["Pair dataset<br/>[pl_pair_dataset.py]"]
end

subgraph group_grp_utils["Utils"]
  node_node_transforms{{"Transforms<br/>tensor bridge<br/>[transforms.py]"}}
  node_node_recon{{"Reconstruct<br/>molecule bridge<br/>[reconstruct.py]"}}
  node_node_eval_utils{{"Metrics<br/>evaluation suite"}}
  node_node_train_utils{{"Train utils<br/>training core<br/>[train.py]"}}
end

node_node_train_flow -->|"trains"| node_node_diffusion
node_node_train_flow -->|"uses"| node_node_train_utils
node_node_train_flow -->|"loads"| node_node_pldata
node_node_sample_flow -->|"samples"| node_node_score_guide
node_node_sample_flow -->|"decodes"| node_node_diffusion
node_node_sample_flow -->|"reconstructs"| node_node_recon
node_node_sample_pocket -->|"predicts size"| node_node_sample_num
node_node_sample_pocket -->|"calls"| node_node_sample_flow
node_node_sample_num -->|"uses"| node_node_prop
node_node_train_num -->|"trains"| node_node_prop
node_node_train_num -->|"encodes"| node_node_prop_geom
node_node_eval_num -->|"evaluates"| node_node_prop
node_node_eval_diff -->|"scores"| node_node_eval_utils
node_node_eval_diff -->|"reconstructs"| node_node_recon
node_node_prep -->|"prepares"| node_node_pldata
node_node_prep -->|"normalizes"| node_node_transforms
node_node_pldata -->|"builds"| node_node_transforms
node_node_pdbbind -->|"specializes"| node_node_pldata
node_node_plpair -->|"specializes"| node_node_pldata
node_node_diffusion -->|"depends on"| node_node_geom
node_node_diffusion -->|"conditions on"| node_node_encoder
node_node_score_guide -->|"extends"| node_node_score
node_node_prop -->|"depends on"| node_node_prop_geom

click node_node_train_flow "https://github.com/cmach508/paflow/blob/main/scripts/train_vpflow_guide_ba.py"
click node_node_sample_flow "https://github.com/cmach508/paflow/blob/main/scripts/sample_flow_VP_guide.py"
click node_node_sample_pocket "https://github.com/cmach508/paflow/blob/main/scripts/sample_for_pocket.py"
click node_node_sample_num "https://github.com/cmach508/paflow/blob/main/scripts/sample_atom_num.py"
click node_node_train_num "https://github.com/cmach508/paflow/blob/main/scripts/train_num_predictor.py"
click node_node_eval_num "https://github.com/cmach508/paflow/blob/main/scripts/validate_num_predictor.py"
click node_node_eval_diff "https://github.com/cmach508/paflow/blob/main/scripts/evaluate_diffusion.py"
click node_node_prep "https://github.com/cmach508/paflow/tree/main/scripts/data_preparation"
click node_node_diffusion "https://github.com/cmach508/paflow/blob/main/models/en_diffusion.py"
click node_node_score "https://github.com/cmach508/paflow/blob/main/models/molopt_score_model.py"
click node_node_score_guide "https://github.com/cmach508/paflow/blob/main/models/molopt_score_model_guide.py"
click node_node_geom "https://github.com/cmach508/paflow/blob/main/models/egnn.py"
click node_node_encoder "https://github.com/cmach508/paflow/blob/main/models/uni_transformer.py"
click node_node_prop "https://github.com/cmach508/paflow/blob/main/models/property_pred/prop_model.py"
click node_node_prop_geom "https://github.com/cmach508/paflow/blob/main/models/property_pred/prop_egnn.py"
click node_node_pldata "https://github.com/cmach508/paflow/blob/main/datasets/pl_data.py"
click node_node_pdbbind "https://github.com/cmach508/paflow/blob/main/datasets/pdbbind.py"
click node_node_plpair "https://github.com/cmach508/paflow/blob/main/datasets/pl_pair_dataset.py"
click node_node_transforms "https://github.com/cmach508/paflow/blob/main/utils/transforms.py"
click node_node_recon "https://github.com/cmach508/paflow/blob/main/utils/reconstruct.py"
click node_node_eval_utils "https://github.com/cmach508/paflow/tree/main/utils/evaluation"
click node_node_train_utils "https://github.com/cmach508/paflow/blob/main/utils/train.py"

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_node_train_flow,node_node_sample_flow,node_node_sample_pocket,node_node_sample_num,node_node_train_num,node_node_eval_num,node_node_eval_diff,node_node_prep toneBlue
class node_node_diffusion,node_node_score,node_node_score_guide,node_node_geom,node_node_encoder,node_node_prop,node_node_prop_geom toneAmber
class node_node_pldata,node_node_pdbbind,node_node_plpair toneMint
class node_node_transforms,node_node_recon,node_node_eval_utils,node_node_train_utils toneRose
```

## Components

### Scripts

Command-line workflows for training, sampling, evaluation, and preprocessing.

- [Train flow](https://github.com/cmach508/paflow/blob/main/scripts/train_vpflow_guide_ba.py): entry script · Trains the guided flow-matching ligand generator. · `scripts/train_vpflow_guide_ba.py`
- [Guided sample](https://github.com/cmach508/paflow/blob/main/scripts/sample_flow_VP_guide.py): entry script · Runs pocket-conditioned sampling with guidance. · `scripts/sample_flow_VP_guide.py`
- [Pocket sample](https://github.com/cmach508/paflow/blob/main/scripts/sample_for_pocket.py): entry script · Custom-pocket inference pipeline for ligand generation. · `scripts/sample_for_pocket.py`
- [Atom sample](https://github.com/cmach508/paflow/blob/main/scripts/sample_atom_num.py): entry script · Samples or predicts ligand atom counts. · `scripts/sample_atom_num.py`
- [Train size pred](https://github.com/cmach508/paflow/blob/main/scripts/train_num_predictor.py): entry script · Trains the atom-number predictor. · `scripts/train_num_predictor.py`
- [Validate size pred](https://github.com/cmach508/paflow/blob/main/scripts/validate_num_predictor.py): entry script · Evaluates the atom-number predictor. · `scripts/validate_num_predictor.py`
- [Evaluate gen](https://github.com/cmach508/paflow/blob/main/scripts/evaluate_diffusion.py): entry script · Evaluates generated molecules end to end. · `scripts/evaluate_diffusion.py`
- [Prep data](https://github.com/cmach508/paflow/tree/main/scripts/data_preparation): preprocess suite · Offline structural preprocessing for pockets, ligands, and dataset splits. · `scripts/data_preparation`

### Models

Geometric generative and property-prediction model implementations.

- [Flow model](https://github.com/cmach508/paflow/blob/main/models/en_diffusion.py): generative model · Core prior-guided diffusion / flow-matching generator. · `models/en_diffusion.py`
- [Score model](https://github.com/cmach508/paflow/blob/main/models/molopt_score_model.py): guided model · Target-aware score/flow model used for guided generation. · `models/molopt_score_model.py`
- [Guide model](https://github.com/cmach508/paflow/blob/main/models/molopt_score_model_guide.py): guided variant · Guided score model variant for sampling-time steering. · `models/molopt_score_model_guide.py`
- [Geom layers](https://github.com/cmach508/paflow/blob/main/models/egnn.py): equivariant layers · Geometric backbone components for 3D molecular modeling. · `models/egnn.py`
- [Pocket encoder](https://github.com/cmach508/paflow/blob/main/models/uni_transformer.py): transformer encoder · Transformer-style encoder used in the model stack. · `models/uni_transformer.py`
- [Size predictor](https://github.com/cmach508/paflow/blob/main/models/property_pred/prop_model.py): property model · Atom-number predictor for pocket-conditioned ligand sizing. · `models/property_pred/prop_model.py`
- [Prop EGNN](https://github.com/cmach508/paflow/blob/main/models/property_pred/prop_egnn.py): property encoder · 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](https://github.com/cmach508/paflow/blob/main/datasets/pl_data.py): dataset layer · Protein-ligand dataset abstractions and pairwise samples. · `datasets/pl_data.py`
- [PDBBind](https://github.com/cmach508/paflow/blob/main/datasets/pdbbind.py): dataset · PDBBind-style curated protein-ligand dataset support. · `datasets/pdbbind.py`
- [Pair dataset](https://github.com/cmach508/paflow/blob/main/datasets/pl_pair_dataset.py): dataset · Pairwise pocket/ligand training dataset. · `datasets/pl_pair_dataset.py`

### Utils

Shared transforms, reconstruction, training, and evaluation utilities.

- [Transforms](https://github.com/cmach508/paflow/blob/main/utils/transforms.py): tensor bridge · Coordinate normalization, graph construction, and feature transforms. · `utils/transforms.py`
- [Reconstruct](https://github.com/cmach508/paflow/blob/main/utils/reconstruct.py): molecule bridge · Rebuilds molecular structures from model outputs. · `utils/reconstruct.py`
- [Metrics](https://github.com/cmach508/paflow/tree/main/utils/evaluation): evaluation suite · Validity, similarity, bond, docking, and scoring metrics. · `utils/evaluation`
- [Train utils](https://github.com/cmach508/paflow/blob/main/utils/train.py): training core · Training loops, scheduling, warmup, and general helpers. · `utils/train.py`

## Connections

- 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.
