# protein-design-laboratory-pdl/vdm-motif-design architecture

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

- Interactive diagram: https://gitdiagram.com/protein-design-laboratory-pdl/vdm-motif-design
- Repository: https://github.com/protein-design-laboratory-pdl/vdm-motif-design

## Overview

#### Purpose and entry points
`vdmdesign` is a research Python package for placing van der Mer (vdM) motifs on ligand chemical groups, evaluating chemistry and clashes, then constructing compatible motif ensembles. Primary user entry points are thin module/console CLIs in `src/vdmdesign/cli/candidates.py`, `src/vdmdesign/cli/ensembles.py`, `src/vdmdesign/cli/backbone_conditioned.py`, and `src/vdmdesign/cli/audit_ensembles.py`.

#### Chemical-group specification and ligand preparation
The authoritative runtime CG catalog is `data/definitions/cg_definitions.yaml`; it supplies atom identities, graph topology, placement/alignment orders, H-bond roles, mappings, and constraints. `src/vdmdesign/specs/definitions.py` and `src/vdmdesign/specs/cg.py` turn this catalog into placement specifications and graph templates. Ligand preparation/perception in `src/vdmdesign/chemistry/ligand_preparation.py`, `src/vdmdesign/chemistry/perception.py`, and `src/vdmdesign/chemistry/ligand.py` preserves explicit PDB chemistry where possible and uses RDKit recovery paths when needed.

#### Ligand-only candidate pipeline
Ligand-only orchestration is split between `src/vdmdesign/ligand_only/candidates_workflow.py` and `src/vdmdesign/ligand_only/ensembles_workflow.py`. Candidate generation (`src/vdmdesign/candidates/generate.py`) maps requested CGs onto the prepared ligand, loads vdM data/members (`src/vdmdesign/candidates/loader.py`), aligns motifs, applies AA policy and geometric/chemical filters, and writes candidate artifacts through `src/vdmdesign/output/candidate_writer.py`.

#### Chemistry evaluation boundary
Shared chemistry is independent of workflow selection: clash calculations use `src/vdmdesign/chemistry/clash.py`; H-bond site identification and directional quality live in `src/vdmdesign/chemistry/hbond/sites.py` and `src/vdmdesign/chemistry/hbond/direction_quality.py`; aromatic interaction handling is in `src/vdmdesign/chemistry/aromatic.py`. This layer supplies filtering and ranking signals to both ligand-only and backbone-conditioned flows rather than owning search or serialization.

#### Ensemble assignment and search
`src/vdmdesign/assignment_engine/search_space.py` builds candidate slots and search state, while `src/vdmdesign/assignment_engine/compatibility.py` enforces member compatibility, clash constraints, and one-motif-per-residue rules. `src/vdmdesign/assignment_engine/ranking.py` ranks feasible assignments using H-bond quality, candidate/cluster metrics, and distances. `src/vdmdesign/ensembles/build.py` and `src/vdmdesign/ensembles/pools.py` orchestrate count-constrained ensemble construction. Torch is an optional runtime for exact search, configured by `requirements-torch.txt`.

#### Backbone-conditioned feasibility and batch flow
For backbone–ligand PDBs, `src/vdmdesign/backbone_conditioned/workflow.py` detects mapped CGs and tests vdM cluster representatives against nearby residues. `src/vdmdesign/backbone_conditioned/fit.py` applies rigid ligand-CG placement and backbone gates; `src/vdmdesign/backbone_conditioned/multi_cg.py` diagnoses compatible multi-CG rotamers. `src/vdmdesign/backbone_conditioned/ensemble_workflow.py` consumes audit provenance, restores cluster members, reapplies member-level backbone checks, then delegates feasible combinations to the ensemble search.

#### Data, outputs, and infrastructure
Runtime datasets are manifest-driven under `data/manifests/` and vdM library metadata begins at `data/vdM_library/manifest.json`; backbone-conditioned processing reads AA parquet data referenced by that library. PDB/CSV output is centralized in `src/vdmdesign/output/paths.py`, `src/vdmdesign/output/pdb_writer.py`, and `src/vdmdesign/output/ensemble_writer.py`. Outputs include prepared ligands, candidate/ensemble CSVs, standalone PDBs, backbone diagnostics, and aromatic reranking products. Core runtime is Python 3.9+ with RDKit-based chemistry; no web service or distributed infrastructure is indicated.

Main entry points: [`src/vdmdesign/candidates/generate.py`](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/candidates/generate.py) (Candidate generation), [`src/vdmdesign/cli/candidates.py`](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/cli/candidates.py) (CLI modules), [`src/vdmdesign/assignment_engine/compatibility.py`](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/compatibility.py) (Compatibility rules), [`src/vdmdesign/backbone_conditioned/ensemble_workflow.py`](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/ensemble_workflow.py) (Backbone ensemble flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_cli["CLI modules<br/>Python CLI<br/>[candidates.py]"]
end

subgraph group_specs["Specifications &amp; Chemistry"]
  node_cg_catalog["CG catalog<br/>YAML catalog"]
  node_cg_specs["CG specifications<br/>Python specs<br/>[definitions.py]"]
  node_ligand_prep["Ligand preparation<br/>Chemistry"]
  node_chemistry["Chemistry evaluation<br/>Chemistry layer<br/>[clash.py]"]
end

subgraph group_ligand["Ligand-only Pipeline"]
  node_candidate_workflow["Candidate workflow"]
  node_candidate_generation["Candidate generation<br/>Candidate engine<br/>[generate.py]"]
  node_vdm_loader["vdM loader<br/>Data loader<br/>[loader.py]"]
  node_ensemble_workflow["Ensemble workflow"]
end

subgraph group_ensemble["Ensemble Search"]
  node_search_space["Search space<br/>Assignment engine<br/>[search_space.py]"]
  node_compatibility["Compatibility rules<br/>Assignment engine<br/>[compatibility.py]"]
  node_ranking["Assignment ranking<br/>Assignment engine<br/>[ranking.py]"]
  node_ensemble_builder["Ensemble builder<br/>Ensemble engine<br/>[build.py]"]
end

subgraph group_backbone["Backbone-conditioned Flow"]
  node_backbone_workflow["Backbone feasibility<br/>Workflow<br/>[workflow.py]"]
  node_backbone_fit["Backbone fit gates<br/>Feasibility engine<br/>[fit.py]"]
  node_multi_cg["Multi-CG diagnostics<br/>Rotamer analysis<br/>[multi_cg.py]"]
  node_backbone_ensemble["Backbone ensemble flow<br/>Workflow"]
end

subgraph group_dataout["Data &amp; Outputs"]
  node_runtime_data[("Runtime datasets<br/>Manifest-driven data<br/>[manifest.json]")]
  node_output["Output writers<br/>Serialization<br/>[ensemble_writer.py]"]
end

node_cli -->|"runs"| node_candidate_workflow
node_cli -->|"runs"| node_ensemble_workflow
node_cli -->|"runs"| node_backbone_workflow
node_cli -->|"runs"| node_backbone_ensemble
node_cg_catalog -->|"defines"| node_cg_specs
node_cg_specs -->|"placement specs"| node_candidate_generation
node_ligand_prep -->|"prepared ligand"| node_candidate_generation
node_candidate_workflow -->|"orchestrates"| node_candidate_generation
node_vdm_loader -->|"vdM members"| node_candidate_generation
node_runtime_data -->|"library data"| node_vdm_loader
node_chemistry -->|"filter signals"| node_candidate_generation
node_candidate_generation -->|"candidate artifacts"| node_output
node_ensemble_workflow -->|"orchestrates"| node_ensemble_builder
node_candidate_generation -->|"candidates"| node_search_space
node_search_space -->|"candidate slots"| node_compatibility
node_chemistry -->|"clash and interaction signals"| node_compatibility
node_compatibility -->|"feasible assignments"| node_ranking
node_ranking -->|"ranked assignments"| node_ensemble_builder
node_ensemble_builder -->|"ensemble artifacts"| node_output
node_backbone_workflow -->|"tests representatives"| node_backbone_fit
node_backbone_fit -->|"feasible placements"| node_multi_cg
node_runtime_data -->|"AA parquet"| node_backbone_workflow
node_backbone_ensemble -->|"feasible combinations"| node_compatibility
node_backbone_ensemble -->|"diagnostics and ensembles"| node_output

click node_cli "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/cli/candidates.py"
click node_cg_catalog "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/data/definitions/cg_definitions.yaml"
click node_cg_specs "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/specs/definitions.py"
click node_ligand_prep "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/chemistry/ligand_preparation.py"
click node_chemistry "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/chemistry/clash.py"
click node_candidate_workflow "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/ligand_only/candidates_workflow.py"
click node_candidate_generation "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/candidates/generate.py"
click node_vdm_loader "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/candidates/loader.py"
click node_ensemble_workflow "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/ligand_only/ensembles_workflow.py"
click node_search_space "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/search_space.py"
click node_compatibility "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/compatibility.py"
click node_ranking "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/ranking.py"
click node_ensemble_builder "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/ensembles/build.py"
click node_backbone_workflow "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/workflow.py"
click node_backbone_fit "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/fit.py"
click node_multi_cg "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/multi_cg.py"
click node_backbone_ensemble "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/ensemble_workflow.py"
click node_runtime_data "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/data/vdM_library/manifest.json"
click node_output "https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/output/ensemble_writer.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_cli toneBlue
class node_cg_catalog,node_cg_specs,node_ligand_prep,node_chemistry toneAmber
class node_candidate_workflow,node_candidate_generation,node_vdm_loader,node_ensemble_workflow toneMint
class node_search_space,node_compatibility,node_ranking,node_ensemble_builder toneRose
class node_backbone_workflow,node_backbone_fit,node_multi_cg,node_backbone_ensemble toneIndigo
class node_runtime_data,node_output toneTeal
```

## Components

### Entry Points

- [CLI modules](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/cli/candidates.py): Python CLI · Candidate, ensemble, backbone, and audit commands. · `src/vdmdesign/cli/candidates.py`

### Specifications & Chemistry

- [CG catalog](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/data/definitions/cg_definitions.yaml): YAML catalog · Authoritative chemical-group definitions. · `data/definitions/cg_definitions.yaml`
- [CG specifications](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/specs/definitions.py): Python specs · Builds placement specifications and graph templates. · `src/vdmdesign/specs/definitions.py`
- [Ligand preparation](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/chemistry/ligand_preparation.py): Chemistry · Preserves PDB chemistry with RDKit recovery when required. · `src/vdmdesign/chemistry/ligand_preparation.py`
- [Chemistry evaluation](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/chemistry/clash.py): Chemistry layer · Clash, H-bond, and aromatic signals shared by both workflows. · `src/vdmdesign/chemistry/clash.py`

### Ligand-only Pipeline

- [Candidate workflow](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/ligand_only/candidates_workflow.py): Workflow · Orchestrates ligand-only candidate generation. · `src/vdmdesign/ligand_only/candidates_workflow.py`
- [Candidate generation](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/candidates/generate.py): Candidate engine · Maps CGs, aligns vdMs, and applies geometric and chemical filters. · `src/vdmdesign/candidates/generate.py`
- [vdM loader](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/candidates/loader.py): Data loader · Loads vdM metadata and members. · `src/vdmdesign/candidates/loader.py`
- [Ensemble workflow](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/ligand_only/ensembles_workflow.py): Workflow · Orchestrates ligand-only ensemble construction. · `src/vdmdesign/ligand_only/ensembles_workflow.py`

### Ensemble Search

- [Search space](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/search_space.py): Assignment engine · Builds candidate slots and search state. · `src/vdmdesign/assignment_engine/search_space.py`
- [Compatibility rules](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/compatibility.py): Assignment engine · Enforces clashes, member compatibility, and residue uniqueness. · `src/vdmdesign/assignment_engine/compatibility.py`
- [Assignment ranking](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/assignment_engine/ranking.py): Assignment engine · Ranks feasible assignments using chemistry and candidate metrics. · `src/vdmdesign/assignment_engine/ranking.py`
- [Ensemble builder](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/ensembles/build.py): Ensemble engine · Constructs count-constrained ensembles; optional Torch exact search. · `src/vdmdesign/ensembles/build.py`

### Backbone-conditioned Flow

- [Backbone feasibility](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/workflow.py): Workflow · Finds mapped CGs and tests representatives against nearby residues. · `src/vdmdesign/backbone_conditioned/workflow.py`
- [Backbone fit gates](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/fit.py): Feasibility engine · Applies rigid placement and backbone gates. · `src/vdmdesign/backbone_conditioned/fit.py`
- [Multi-CG diagnostics](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/multi_cg.py): Rotamer analysis · Diagnoses compatible multi-CG rotamers. · `src/vdmdesign/backbone_conditioned/multi_cg.py`
- [Backbone ensemble flow](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/backbone_conditioned/ensemble_workflow.py): Workflow · Restores members, reapplies checks, and delegates search. · `src/vdmdesign/backbone_conditioned/ensemble_workflow.py`

### Data & Outputs

- [Runtime datasets](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/data/vdM_library/manifest.json): Manifest-driven data · vdM library metadata and referenced AA parquet data. · `data/vdM_library/manifest.json`
- [Output writers](https://github.com/protein-design-laboratory-pdl/vdm-motif-design/blob/main/src/vdmdesign/output/ensemble_writer.py): Serialization · Centralized PDB, CSV, diagnostic, and reranking output. · `src/vdmdesign/output/ensemble_writer.py`

## Connections

- CLI modules → Candidate workflow: runs
- CLI modules → Ensemble workflow: runs
- CLI modules → Backbone feasibility: runs
- CLI modules → Backbone ensemble flow: runs
- CG catalog → CG specifications: defines
- CG specifications → Candidate generation: placement specs
- Ligand preparation → Candidate generation: prepared ligand
- Candidate workflow → Candidate generation: orchestrates
- vdM loader → Candidate generation: vdM members
- Runtime datasets → vdM loader: library data
- Chemistry evaluation → Candidate generation: filter signals
- Candidate generation → Output writers: candidate artifacts
- Ensemble workflow → Ensemble builder: orchestrates
- Candidate generation → Search space: candidates
- Search space → Compatibility rules: candidate slots
- Chemistry evaluation → Compatibility rules: clash and interaction signals
- Compatibility rules → Assignment ranking: feasible assignments
- Assignment ranking → Ensemble builder: ranked assignments
- Ensemble builder → Output writers: ensemble artifacts
- Backbone feasibility → Backbone fit gates: tests representatives
- Backbone fit gates → Multi-CG diagnostics: feasible placements
- Runtime datasets → Backbone feasibility: AA parquet
- Backbone ensemble flow → Compatibility rules: feasible combinations
- Backbone ensemble flow → Output writers: diagnostics and ensembles