# lpdi-epfl/lddm architecture

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

- Interactive diagram: https://gitdiagram.com/lpdi-epfl/lddm
- Repository: https://github.com/lpdi-epfl/lddm

## Overview

LDDM is a pocket-conditioned 3D molecular-generation system for drug design. Its basic workflow takes a protein pocket, optional ligand or fragment constraints, and a pretrained checkpoint; sampling produces molecules for de novo design, fragment growth/linking, docking, or partial docking. Advanced workflows add programmable fragment exploration and reaction-constrained synthesizable generation. Generated structures can be assessed with drug-design and 3D-geometry metrics. The graph emphasizes documented product capabilities; unsampled implementation details are represented only where the repository tree supports a subsystem, so some internal wiring is omitted.

Main entry points: [`lddm/inference/programmable_generation.py`](https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/programmable_generation.py) (Programmable generation), [`scripts/sample.py`](https://github.com/lpdi-epfl/lddm/blob/main/scripts/sample.py) (Basic sampling), [`lddm/inference/synthesizable_generation.py`](https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/synthesizable_generation.py) (Synthesizable generation), [`lddm/inference/utils.py`](https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/utils.py) (Design and docking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Runtime entry points"]
  node_basic_cli["Basic sampling<br/>[sample.py]"]
  node_programmable_cli["Programmable workflow"]
end

subgraph group_generation["Molecular generation"]
  node_basic_inference["Design and docking<br/>[utils.py]"]
  node_programmable["Programmable generation"]
  node_synthgen["Synthesizable generation"]
  node_samplers["ODE samplers<br/>[samplers.py]"]
end

subgraph group_chemistry["Chemical processing"]
  node_molecule_build["Molecule construction"]
  node_reactions["Reaction processing<br/>[reaction_utils.py]"]
end

subgraph group_evaluation["Structure evaluation"]
  node_metrics["Drug-design metrics<br/>[metrics.py]"]
  node_validity3d["3D geometry validity<br/>[validity3d.py]"]
end

subgraph group_support["Model and data"]
  node_model_runtime["LDDM model runtime<br/>[lightning.py]"]
  node_dynamics["Heterogeneous dynamics<br/>[dynamics.py]"]
  node_dataset["Molecular datasets<br/>[dataset.py]"]
  node_featurization["Molecule featurization<br/>[transforms.py]"]
end

node_user(("Researcher"))
node_inputs["Pocket and ligand inputs"]
node_checkpoint["Model checkpoint"]
node_samples["Generated molecules"]
node_reference[("Geometry reference data")]
node_basic_output["Basic SDF output"]
node_advanced_output["Advanced results"]

node_user -->|"invokes"| node_basic_cli
node_user -->|"invokes"| node_programmable_cli
node_inputs -->|"provides inputs"| node_basic_cli
node_checkpoint -->|"provides weights"| node_basic_cli
node_basic_cli -->|"runs sampling"| node_basic_inference
node_basic_inference -->|"uses model"| node_model_runtime
node_model_runtime -->|"predicts dynamics"| node_dynamics
node_basic_inference -->|"advances trajectory"| node_samplers
node_basic_inference -->|"builds molecules"| node_molecule_build
node_molecule_build -->|"writes structures"| node_basic_output
node_basic_cli -->|"writes SDF"| node_basic_output
node_programmable_cli -->|"runs workflow"| node_programmable
node_programmable -->|"uses model"| node_model_runtime
node_programmable -->|"filters candidates"| node_metrics
node_programmable -->|"writes results"| node_advanced_output
node_programmable -->|"checks geometry"| node_validity3d
node_synthgen -->|"extends exploration"| node_programmable
node_synthgen -->|"generates products"| node_reactions
node_synthgen -->|"filters candidates"| node_metrics
node_synthgen -->|"returns results"| node_advanced_output
node_validity3d -->|"reads geometry"| node_reference
node_model_runtime -->|"loads datasets"| node_dataset
node_dataset -->|"featurizes samples"| node_featurization

click node_basic_cli "https://github.com/lpdi-epfl/lddm/blob/main/scripts/sample.py"
click node_programmable_cli "https://github.com/lpdi-epfl/lddm/blob/main/scripts/generate_programmable_design.py"
click node_basic_inference "https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/utils.py"
click node_programmable "https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/programmable_generation.py"
click node_synthgen "https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/synthesizable_generation.py"
click node_samplers "https://github.com/lpdi-epfl/lddm/blob/main/lddm/model/samplers.py"
click node_model_runtime "https://github.com/lpdi-epfl/lddm/blob/main/lddm/model/lightning.py"
click node_dynamics "https://github.com/lpdi-epfl/lddm/blob/main/lddm/model/dynamics.py"
click node_dataset "https://github.com/lpdi-epfl/lddm/blob/main/lddm/data/dataset.py"
click node_featurization "https://github.com/lpdi-epfl/lddm/blob/main/lddm/data/transforms.py"
click node_molecule_build "https://github.com/lpdi-epfl/lddm/blob/main/lddm/data/molecule_builder.py"
click node_reactions "https://github.com/lpdi-epfl/lddm/blob/main/lddm/reactions/reaction_utils.py"
click node_metrics "https://github.com/lpdi-epfl/lddm/blob/main/lddm/sbdd_metrics/metrics.py"
click node_validity3d "https://github.com/lpdi-epfl/lddm/blob/main/lddm/sbdd_metrics/validity_3d/validity3d.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_basic_cli,node_programmable_cli toneBlue
class node_basic_inference,node_programmable,node_synthgen,node_samplers,node_reference toneAmber
class node_molecule_build,node_reactions toneMint
class node_metrics,node_validity3d toneRose
class node_model_runtime,node_dynamics,node_dataset,node_featurization,node_user,node_inputs,node_checkpoint,node_samples,node_basic_output,node_advanced_output toneIndigo
```

## Components

### Runtime entry points

- [Basic sampling](https://github.com/lpdi-epfl/lddm/blob/main/scripts/sample.py): `scripts/sample.py`
- [Programmable workflow](https://github.com/lpdi-epfl/lddm/blob/main/scripts/generate_programmable_design.py): `scripts/generate_programmable_design.py`

### Molecular generation

- [Design and docking](https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/utils.py): `lddm/inference/utils.py`
- [Programmable generation](https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/programmable_generation.py): `lddm/inference/programmable_generation.py`
- [Synthesizable generation](https://github.com/lpdi-epfl/lddm/blob/main/lddm/inference/synthesizable_generation.py): `lddm/inference/synthesizable_generation.py`
- [ODE samplers](https://github.com/lpdi-epfl/lddm/blob/main/lddm/model/samplers.py): `lddm/model/samplers.py`

### Chemical processing

- [Molecule construction](https://github.com/lpdi-epfl/lddm/blob/main/lddm/data/molecule_builder.py): `lddm/data/molecule_builder.py`
- [Reaction processing](https://github.com/lpdi-epfl/lddm/blob/main/lddm/reactions/reaction_utils.py): `lddm/reactions/reaction_utils.py`

### Structure evaluation

- [Drug-design metrics](https://github.com/lpdi-epfl/lddm/blob/main/lddm/sbdd_metrics/metrics.py): `lddm/sbdd_metrics/metrics.py`
- [3D geometry validity](https://github.com/lpdi-epfl/lddm/blob/main/lddm/sbdd_metrics/validity_3d/validity3d.py): `lddm/sbdd_metrics/validity_3d/validity3d.py`

### Model and data

- [LDDM model runtime](https://github.com/lpdi-epfl/lddm/blob/main/lddm/model/lightning.py): `lddm/model/lightning.py`
- [Heterogeneous dynamics](https://github.com/lpdi-epfl/lddm/blob/main/lddm/model/dynamics.py): `lddm/model/dynamics.py`
- [Molecular datasets](https://github.com/lpdi-epfl/lddm/blob/main/lddm/data/dataset.py): `lddm/data/dataset.py`
- [Molecule featurization](https://github.com/lpdi-epfl/lddm/blob/main/lddm/data/transforms.py): `lddm/data/transforms.py`

### Other components

- **Researcher**
- **Pocket and ligand inputs**
- **Model checkpoint**
- **Generated molecules**
- **Geometry reference data**
- **Basic SDF output**
- **Advanced results**

## Connections

- Researcher → Basic sampling: invokes
- Researcher → Programmable workflow: invokes
- Pocket and ligand inputs → Basic sampling: provides inputs
- Model checkpoint → Basic sampling: provides weights
- Basic sampling → Design and docking: runs sampling
- Design and docking → LDDM model runtime: uses model
- LDDM model runtime → Heterogeneous dynamics: predicts dynamics
- Design and docking → ODE samplers: advances trajectory
- Design and docking → Molecule construction: builds molecules
- Molecule construction → Basic SDF output: writes structures
- Basic sampling → Basic SDF output: writes SDF
- Programmable workflow → Programmable generation: runs workflow
- Programmable generation → LDDM model runtime: uses model
- Programmable generation → Drug-design metrics: filters candidates
- Programmable generation → Advanced results: writes results
- Programmable generation → 3D geometry validity: checks geometry
- Synthesizable generation → Programmable generation: extends exploration
- Synthesizable generation → Reaction processing: generates products
- Synthesizable generation → Drug-design metrics: filters candidates
- Synthesizable generation → Advanced results: returns results
- 3D geometry validity → Geometry reference data: reads geometry
- LDDM model runtime → Molecular datasets: loads datasets
- Molecular datasets → Molecule featurization: featurizes samples