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

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.