# jerenemy/polydiff architecture

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

- Interactive diagram: https://gitdiagram.com/jerenemy/polydiff
- Repository: https://github.com/jerenemy/polydiff

## Overview

Polydiff generates fixed- or variable-size 2D polygon datasets, trains MLP/GAT/GCN DDPM denoisers, samples new polygons, and evaluates results with diagnostics. A study runner orchestrates repeatable training and sampling sweeps; pocket-conditioning and binding-affinity surrogate experiments add guidance-oriented capabilities. The graph includes the documented workflow and source-index-supported calls. Some study, guidance, and integration details are represented only at subsystem level because their implementation excerpts were incomplete.

Main entry points: [`polydiff/studies/run.py`](https://github.com/jerenemy/polydiff/blob/main/polydiff/studies/run.py) (Study runner), [`polydiff/training/train.py`](https://github.com/jerenemy/polydiff/blob/main/polydiff/training/train.py) (Diffusion training), [`polydiff/sampling/runtime.py`](https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/runtime.py) (Sampling runtime), [`polydiff/pocket_conditioning/study.py`](https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/study.py) (Pocket conditioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Polygon data"]
  node_generator["Polygon generator<br/>[gen_polygons.py]"]
  node_dataset[("Polygon datasets<br/>[polygon_dataset.py]")]
  node_diagnostics["Polygon diagnostics<br/>[diagnostics.py]"]
  node_plotting["Polygon plotting<br/>[plot_polygons.py]"]
end

subgraph group_models["Diffusion models"]
  node_diffusion["DDPM diffusion<br/>[diffusion.py]"]
  node_gat["GAT denoiser<br/>[gat.py]"]
  node_gcn["GCN denoiser<br/>[gcn.py]"]
  node_guidance_models["Guidance models<br/>[guidance_models.py]"]
end

subgraph group_execution["Training and sampling"]
  node_training["Diffusion training<br/>[train.py]"]
  node_guidance_training["Guidance training"]
  node_run_store[("Run organization<br/>[runs.py]")]
  node_sampler["Sampling entrypoint<br/>[sample.py]"]
  node_sampling_runtime["Sampling runtime<br/>[runtime.py]"]
  node_sample_guidance["Sampling guidance<br/>[guidance.py]"]
  node_restoration["Restoration metrics<br/>[restoration.py]"]
end

subgraph group_analysis["Studies and guidance"]
  node_study_runner["Study runner<br/>[run.py]"]
  node_study_runtime["Study runtime<br/>[runtime.py]"]
  node_pocket_study["Pocket conditioning<br/>[study.py]"]
  node_pocket_data[("Pocket pair data<br/>[data.py]")]
  node_pocket_geometry["Pocket geometry<br/>[geometry.py]"]
  node_pocket_surrogate["Pocket surrogate<br/>[surrogate.py]"]
end

subgraph group_affinity["Affinity surrogate"]
  node_affinity_data[("Affinity data<br/>[surrogate_data.py]")]
  node_affinity_model["Affinity models"]
  node_affinity_training["Surrogate training"]
end

node_user(("Researcher"))

node_user -->|"generates data"| node_generator
node_generator -->|"writes formats"| node_dataset
node_user -->|"starts training"| node_training
node_training -->|"loads data"| node_dataset
node_training -->|"trains model"| node_diffusion
node_diffusion -->|"builds denoiser"| node_gat
node_diffusion -->|"builds denoiser"| node_gcn
node_guidance_training -->|"loads data"| node_dataset
node_guidance_training -->|"trains guidance"| node_guidance_models
node_training -->|"creates run"| node_run_store
node_user -->|"starts sampling"| node_sampler
node_sampler -->|"runs sampling"| node_sampling_runtime
node_sampling_runtime -->|"rebuilds model"| node_diffusion
node_sampler -->|"configures guidance"| node_sample_guidance
node_sampling_runtime -->|"computes diagnostics"| node_diagnostics
node_sampling_runtime -.->|"tracks restoration"| node_restoration
node_user -->|"plots polygons"| node_plotting
node_user -->|"runs study"| node_study_runner
node_study_runner -->|"dispatches training"| node_training
node_study_runner -->|"dispatches training"| node_guidance_training
node_study_runner -->|"dispatches sampling"| node_sampler
node_study_runner -->|"uses runtime"| node_study_runtime
node_user -->|"runs conditioning"| node_pocket_study
node_pocket_study -->|"prepares pairs"| node_pocket_data
node_pocket_study -->|"uses geometry"| node_pocket_geometry
node_pocket_study -->|"uses surrogate"| node_pocket_surrogate
node_affinity_training -->|"loads data"| node_affinity_data
node_affinity_training -->|"trains model"| node_affinity_model
node_affinity_model -->|"uses data"| node_affinity_data

click node_generator "https://github.com/jerenemy/polydiff/blob/main/polydiff/data/gen_polygons.py"
click node_dataset "https://github.com/jerenemy/polydiff/blob/main/polydiff/data/polygon_dataset.py"
click node_diagnostics "https://github.com/jerenemy/polydiff/blob/main/polydiff/data/diagnostics.py"
click node_plotting "https://github.com/jerenemy/polydiff/blob/main/polydiff/data/plot_polygons.py"
click node_diffusion "https://github.com/jerenemy/polydiff/blob/main/polydiff/models/diffusion.py"
click node_gat "https://github.com/jerenemy/polydiff/blob/main/polydiff/models/gat.py"
click node_gcn "https://github.com/jerenemy/polydiff/blob/main/polydiff/models/gcn.py"
click node_guidance_models "https://github.com/jerenemy/polydiff/blob/main/polydiff/models/guidance_models.py"
click node_training "https://github.com/jerenemy/polydiff/blob/main/polydiff/training/train.py"
click node_guidance_training "https://github.com/jerenemy/polydiff/blob/main/polydiff/training/train_guidance_model.py"
click node_run_store "https://github.com/jerenemy/polydiff/blob/main/polydiff/runs.py"
click node_sampler "https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/sample.py"
click node_sampling_runtime "https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/runtime.py"
click node_sample_guidance "https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/guidance.py"
click node_restoration "https://github.com/jerenemy/polydiff/blob/main/polydiff/restoration.py"
click node_study_runner "https://github.com/jerenemy/polydiff/blob/main/polydiff/studies/run.py"
click node_study_runtime "https://github.com/jerenemy/polydiff/blob/main/polydiff/studies/runtime.py"
click node_pocket_study "https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/study.py"
click node_pocket_data "https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/data.py"
click node_pocket_geometry "https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/geometry.py"
click node_pocket_surrogate "https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/surrogate.py"
click node_affinity_data "https://github.com/jerenemy/polydiff/blob/main/predict_binding_affinity/surrogate_data.py"
click node_affinity_model "https://github.com/jerenemy/polydiff/blob/main/predict_binding_affinity/surrogate_models.py"
click node_affinity_training "https://github.com/jerenemy/polydiff/blob/main/predict_binding_affinity/train_surrogate_model.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_generator,node_dataset,node_diagnostics,node_plotting toneBlue
class node_diffusion,node_gat,node_gcn,node_guidance_models toneAmber
class node_training,node_guidance_training,node_run_store,node_sampler,node_sampling_runtime,node_sample_guidance,node_restoration toneMint
class node_study_runner,node_study_runtime,node_pocket_study,node_pocket_data,node_pocket_geometry,node_pocket_surrogate toneRose
class node_affinity_data,node_affinity_model,node_affinity_training,node_user toneIndigo
```

## Components

### Polygon data

- [Polygon generator](https://github.com/jerenemy/polydiff/blob/main/polydiff/data/gen_polygons.py): `polydiff/data/gen_polygons.py`
- [Polygon datasets](https://github.com/jerenemy/polydiff/blob/main/polydiff/data/polygon_dataset.py): `polydiff/data/polygon_dataset.py`
- [Polygon diagnostics](https://github.com/jerenemy/polydiff/blob/main/polydiff/data/diagnostics.py): `polydiff/data/diagnostics.py`
- [Polygon plotting](https://github.com/jerenemy/polydiff/blob/main/polydiff/data/plot_polygons.py): `polydiff/data/plot_polygons.py`

### Diffusion models

- [DDPM diffusion](https://github.com/jerenemy/polydiff/blob/main/polydiff/models/diffusion.py): `polydiff/models/diffusion.py`
- [GAT denoiser](https://github.com/jerenemy/polydiff/blob/main/polydiff/models/gat.py): `polydiff/models/gat.py`
- [GCN denoiser](https://github.com/jerenemy/polydiff/blob/main/polydiff/models/gcn.py): `polydiff/models/gcn.py`
- [Guidance models](https://github.com/jerenemy/polydiff/blob/main/polydiff/models/guidance_models.py): `polydiff/models/guidance_models.py`

### Training and sampling

- [Diffusion training](https://github.com/jerenemy/polydiff/blob/main/polydiff/training/train.py): `polydiff/training/train.py`
- [Guidance training](https://github.com/jerenemy/polydiff/blob/main/polydiff/training/train_guidance_model.py): `polydiff/training/train_guidance_model.py`
- [Run organization](https://github.com/jerenemy/polydiff/blob/main/polydiff/runs.py): `polydiff/runs.py`
- [Sampling entrypoint](https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/sample.py): `polydiff/sampling/sample.py`
- [Sampling runtime](https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/runtime.py): `polydiff/sampling/runtime.py`
- [Sampling guidance](https://github.com/jerenemy/polydiff/blob/main/polydiff/sampling/guidance.py): `polydiff/sampling/guidance.py`
- [Restoration metrics](https://github.com/jerenemy/polydiff/blob/main/polydiff/restoration.py): `polydiff/restoration.py`

### Studies and guidance

- [Study runner](https://github.com/jerenemy/polydiff/blob/main/polydiff/studies/run.py): `polydiff/studies/run.py`
- [Study runtime](https://github.com/jerenemy/polydiff/blob/main/polydiff/studies/runtime.py): `polydiff/studies/runtime.py`
- [Pocket conditioning](https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/study.py): `polydiff/pocket_conditioning/study.py`
- [Pocket pair data](https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/data.py): `polydiff/pocket_conditioning/data.py`
- [Pocket geometry](https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/geometry.py): `polydiff/pocket_conditioning/geometry.py`
- [Pocket surrogate](https://github.com/jerenemy/polydiff/blob/main/polydiff/pocket_conditioning/surrogate.py): `polydiff/pocket_conditioning/surrogate.py`

### Affinity surrogate

- [Affinity data](https://github.com/jerenemy/polydiff/blob/main/predict_binding_affinity/surrogate_data.py): `predict_binding_affinity/surrogate_data.py`
- [Affinity models](https://github.com/jerenemy/polydiff/blob/main/predict_binding_affinity/surrogate_models.py): `predict_binding_affinity/surrogate_models.py`
- [Surrogate training](https://github.com/jerenemy/polydiff/blob/main/predict_binding_affinity/train_surrogate_model.py): `predict_binding_affinity/train_surrogate_model.py`

### Other components

- **Researcher**

## Connections

- Researcher → Polygon generator: generates data
- Polygon generator → Polygon datasets: writes formats (evidence: `polydiff/data/gen_polygons.py`)
- Researcher → Diffusion training: starts training
- Diffusion training → Polygon datasets: loads data (evidence: `polydiff/training/train.py`)
- Diffusion training → DDPM diffusion: trains model (evidence: `polydiff/training/train.py`)
- DDPM diffusion → GAT denoiser: builds denoiser (evidence: `polydiff/models/diffusion.py`)
- DDPM diffusion → GCN denoiser: builds denoiser (evidence: `polydiff/models/diffusion.py`)
- Guidance training → Polygon datasets: loads data (evidence: `polydiff/training/train_guidance_model.py`)
- Guidance training → Guidance models: trains guidance (evidence: `polydiff/training/train_guidance_model.py`)
- Diffusion training → Run organization: creates run (evidence: `polydiff/training/train.py`)
- Researcher → Sampling entrypoint: starts sampling
- Sampling entrypoint → Sampling runtime: runs sampling (evidence: `polydiff/sampling/sample.py`)
- Sampling runtime → DDPM diffusion: rebuilds model (evidence: `polydiff/sampling/runtime.py`)
- Sampling entrypoint → Sampling guidance: configures guidance (evidence: `polydiff/sampling/sample.py`)
- Sampling runtime → Polygon diagnostics: computes diagnostics (evidence: `polydiff/sampling/runtime.py`)
- Sampling runtime → Restoration metrics: tracks restoration (evidence: `polydiff/sampling/runtime.py`)
- Researcher → Polygon plotting: plots polygons
- Researcher → Study runner: runs study
- Study runner → Diffusion training: dispatches training (evidence: `polydiff/studies/run.py`)
- Study runner → Guidance training: dispatches training (evidence: `polydiff/studies/run.py`)
- Study runner → Sampling entrypoint: dispatches sampling (evidence: `polydiff/studies/run.py`)
- Study runner → Study runtime: uses runtime (evidence: `polydiff/studies/run.py`)
- Researcher → Pocket conditioning: runs conditioning
- Pocket conditioning → Pocket pair data: prepares pairs (evidence: `polydiff/pocket_conditioning/study.py`)
- Pocket conditioning → Pocket geometry: uses geometry (evidence: `polydiff/pocket_conditioning/study.py`)
- Pocket conditioning → Pocket surrogate: uses surrogate (evidence: `polydiff/pocket_conditioning/study.py`)
- Surrogate training → Affinity data: loads data (evidence: `predict_binding_affinity/train_surrogate_model.py`)
- Surrogate training → Affinity models: trains model (evidence: `predict_binding_affinity/train_surrogate_model.py`)
- Affinity models → Affinity data: uses data (evidence: `predict_binding_affinity/surrogate_models.py`)
