# luwei0917/dynamicbind architecture

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

- Interactive diagram: https://gitdiagram.com/luwei0917/dynamicbind
- Repository: https://github.com/luwei0917/dynamicbind

## Overview

##### Project type and purpose
- Project Type: This is an open‐source scientific software toolkit with a deep equivariant generative model (DynamicBind) for predicting ligand-specific protein–ligand complex structures, plus supporting training, inference, high-throughput screening, and movie generation.
- Purpose: Starting from unbound protein structures and ligand SMILES, it (a) cleans and preprocesses inputs, (b) applies a deep equivariant generative model (built on ESM and bespoke score models) to predict binding poses and affinity scores, (c) optionally runs structural relaxation (OpenMM), and (d) outputs ranked docked complexes and animations.

##### File structure
- Top‐level scripts & entrypoints:
- train.py – model training pipeline
- run_single_protein_inference.py – inference & docking CLI
- screening.py / merge_screening_results.py – high-throughput screening
- movie_generation.py – animation generation
- inference.py / analysis.py / check_structure_violations.py / compute_lddt.py – auxiliary analysis
- Core directories:
- data/ & datasets/ – raw data files and data‐prep modules (conformer matching, embeddings, pdbbind)
- esm/ – third-party ESM library submodule for protein language models and inverse folding
- models/ – model wrappers and score networks (all_atom_score_model.py, score_model.py)
- confidence/ – modules & datasets for training a confidence‐prediction network
- utils/ – geometric, diffusion, sampling, parsing, relaxation helper routines
- Supporting files:
- environment.yml – conda environment spec
- helper_functions.py – common utility functions
- LICENSE, README.md – project metadata
- External/deployment:
- Uses external libraries: PyTorch (+ CUDA), e3nn, RDKit, PyG, OpenMM, Biopython, AmberTools.

##### README for insights
- Describes end-to-end workflows: environment setup, checkpoint download, dynamic docking, movie generation, high-throughput screening.
- Specifies I/O contracts: input protein PDB, ligand CSV SMILES, and output directories with CSVs, PDBs, SDFs, PKLs.
- Highlights dependencies and two conda environments (dynamicbind, relax).

a. Main Components
1. Input Preprocessing
– Modules: clean_pdb.py, process_mols.py, parsing utilities
– Inputs: protein.pdb, ligand.csv
2. Data Preparation & Embedding
– Datasets: pdbbind, esm_embedding_preparation, conformer_matching
– ESM submodule: sequence embeddings, inverse folding encoders/decoders
3. Core Generative Model
– Score models in models/ (all-atom and coarse grained)
– Diffusion & sampling routines in utils/diffusion_utils.py, utils/sampling.py
– Confidence‐prediction network in confidence/
4. Inference & Scoring
– run_single_protein_inference.py calls inference.py → generates multiple poses → score & rank
– compute_lddt.py for per‐pose quality estimation
5. Structural Relaxation
– relax_final.py using OpenMM via utils/relax.py
6. Postprocessing & Output
– merge_screening_results.py, screening.py for HTS reports
– Movie generation pipeline: movie_generation.py uses reverseprocess pkls and relax routines
b. Interactions & Data Flow
– Protein PDB + ligand SMILES → Preprocessing → Data Preparation → Embeddings → Generative Model
– Model outputs coordinate distributions → Sampling pipeline → Pose candidates
– Candidates → Scoring (affinity & lDDT) → Ranking → Optional OpenMM Relaxation → Final PDB/SDF
– Final structures & intermediate data → Movie generation
– HTS variant runs through same flow in batch mode
c. Architectural Patterns & Design Principles
– Modular ML pipeline: clear separation of data prep, model, inference, and postprocessing
– Plug-and-play embedders: ESM code vendored under esm/ for invertible folding
– Reusable utilities following single‐responsibility (utils/)
– CLI entrypoints orchestrate the pipeline
d. Key Technologies & Frameworks
– PyTorch, PyG, e3nn for equivariant networks
– ESM library for protein language models
– RDKit & OpenMM for chemistry & relaxation
– Conda environments for dependency isolation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Store
    RawData(("Protein PDB<br/>& ligand SMILES")):::cylinder
    EmbeddingsStore(("Embeddings Store")):::cylinder
    Checkpoints(("Model Checkpoints")):::cylinder
    OutputData(("Docked Complexes<br/>& CSVs/SDFs/PKLs")):::cylinder

    %% External Dependencies
    PyTorch_e3nn>PyTorch & e3nn]:::external
    RDKit>RDKit]:::external
    OpenMM>OpenMM]:::external

    %% Preprocessing Layer
    subgraph "Data & Preprocessing"
        direction TB
        Clean["clean_pdb.py"]:::data
        ProcessMol["process_mols.py"]:::data
        Parsing["parsing.py"]:::data
    end

    %% Data Preparation & Embedding Layer
    subgraph "Data Preparation & Embedding"
        direction TB
        Conformer["conformer_matching.py"]:::data
        ESMPrep["esm_embedding_preparation.py"]:::data
        ESM2PT["esm_embeddings_to_pt.py"]:::data
        PDBBind["pdbbind.py"]:::data
        ESMSub["ESM Submodule"]:::model
    end

    %% Core Generative Model Layer
    subgraph "Core Generative Model"
        direction TB
        AllAtom["all_atom_score_model.py"]:::model
        ScoreModel["score_model.py"]:::model
        Diffusion["diffusion_utils.py"]:::model
        Sampling["sampling.py"]:::model
        ConfTrain["confidence_train.py"]:::model
        ConfData["dataset.py"]:::model
    end

    %% Inference & Scoring Layer
    subgraph "Inference & Scoring"
        direction TB
        RunSingle["run_single_protein_inference.py"]:::scoring
        InferenceMod["inference.py"]:::scoring
        ComputeLDDT["compute_lddt.py"]:::scoring
        ScoringMod["scoring.py"]:::scoring
    end

    %% Relaxation Layer
    subgraph "Structural Relaxation"
        direction TB
        RelaxFinal["relax_final.py"]:::relax
        RelaxUtil["relax.py"]:::relax
    end

    %% Postprocessing & Output Layer
    subgraph "Postprocessing & Output"
        direction TB
        Screening["screening.py"]:::relax
        Merge["merge_screening_results.py"]:::relax
        Movie["movie_generation.py"]:::relax
        SaveRev["save_reverseprocess.py"]:::relax
    end

    %% Connections
    RawData --> Clean
    Clean --> ProcessMol --> Parsing
    Parsing --> Conformer --> ESMPrep --> ESM2PT --> PDBBind --> ESMSub
    ESMSub --> EmbeddingsStore
    EmbeddingsStore --> AllAtom --> ScoreModel --> Diffusion --> Sampling
    Sampling --> Checkpoints
    Checkpoints --> RunSingle --> InferenceMod
    InferenceMod --> ScoringMod
    ScoringMod --> ComputeLDDT --> OutputData
    ScoringMod --> RelaxFinal --> RelaxUtil --> OutputData
    OutputData --> Movie
    RawData --> Screening --> Merge --> OutputData

    PyTorch_e3nn -.-> AllAtom
    PyTorch_e3nn -.-> ScoreModel
    RDKit -.-> ProcessMol
    RDKit -.-> Conformer
    OpenMM -.-> RelaxUtil

    %% Click Events
    click Clean "https://github.com/luwei0917/dynamicbind/blob/main/clean_pdb.py"
    click ProcessMol "https://github.com/luwei0917/dynamicbind/blob/main/datasets/process_mols.py"
    click Parsing "https://github.com/luwei0917/dynamicbind/blob/main/utils/parsing.py"
    click Conformer "https://github.com/luwei0917/dynamicbind/blob/main/datasets/conformer_matching.py"
    click ESMPrep "https://github.com/luwei0917/dynamicbind/blob/main/datasets/esm_embedding_preparation.py"
    click ESM2PT "https://github.com/luwei0917/dynamicbind/blob/main/datasets/esm_embeddings_to_pt.py"
    click PDBBind "https://github.com/luwei0917/dynamicbind/blob/main/datasets/pdbbind.py"
    click ESMSub "https://github.com/luwei0917/dynamicbind/tree/main/esm/"
    click AllAtom "https://github.com/luwei0917/dynamicbind/blob/main/models/all_atom_score_model.py"
    click ScoreModel "https://github.com/luwei0917/dynamicbind/blob/main/models/score_model.py"
    click Diffusion "https://github.com/luwei0917/dynamicbind/blob/main/utils/diffusion_utils.py"
    click Sampling "https://github.com/luwei0917/dynamicbind/blob/main/utils/sampling.py"
    click ConfTrain "https://github.com/luwei0917/dynamicbind/blob/main/confidence/confidence_train.py"
    click ConfData "https://github.com/luwei0917/dynamicbind/blob/main/confidence/dataset.py"
    click RunSingle "https://github.com/luwei0917/dynamicbind/blob/main/run_single_protein_inference.py"
    click InferenceMod "https://github.com/luwei0917/dynamicbind/blob/main/inference.py"
    click ComputeLDDT "https://github.com/luwei0917/dynamicbind/blob/main/compute_lddt.py"
    click ScoringMod "https://github.com/luwei0917/dynamicbind/blob/main/scoring.py"
    click RelaxFinal "https://github.com/luwei0917/dynamicbind/blob/main/relax_final.py"
    click RelaxUtil "https://github.com/luwei0917/dynamicbind/blob/main/utils/relax.py"
    click Screening "https://github.com/luwei0917/dynamicbind/blob/main/screening.py"
    click Merge "https://github.com/luwei0917/dynamicbind/blob/main/merge_screening_results.py"
    click Movie "https://github.com/luwei0917/dynamicbind/blob/main/movie_generation.py"
    click SaveRev "https://github.com/luwei0917/dynamicbind/blob/main/save_reverseprocess.py"

    %% Styles
    classDef data fill:#aed6f1,stroke:#3498db,color:#1b4f72,shape:rect
    classDef model fill:#abebc6,stroke:#27ae60,color:#145a32,shape:rect
    classDef scoring fill:#f9e79f,stroke:#d4ac0d,color:#7d6608,shape:rect
    classDef relax fill:#d7bde2,stroke:#8e44ad,color:#4a235a,shape:rect
    classDef external fill:#d5dbdb,stroke:#566573,color:#1b2631,shape:hexagon
    classDef cylinder stroke:#566573,fill:#f8f9f9,color:#1b2631,shape:cylinder
```
