# layne-huang/pmdm architecture

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

- Interactive diagram: https://gitdiagram.com/layne-huang/pmdm
- Repository: https://github.com/layne-huang/pmdm

## Overview

##### Main Components
- Data Preparation
- Pocket & ligand extraction scripts (split_pocket_ligand.py, sample_*.py)
- Configuration files (configs/*.yml, mol.yml)
- Dataset loaders and transforms (utils/data.py, utils/datasets/, utils/transforms.py)
- Model Core
- Encoders (models/encoders/*.py: attention, cftfm, egnn, gin, schnet, etc.)
- Diffusion modules (models/diffusion.py, models/epsnet/diffusion.py)
- Geometry & common utilities (models/geometry.py, models/common.py)
- Training & Inference Orchestration
- Training scripts (train.py for single GPU, train_ddp_op.py for multi-GPU/DistributedDataParallel)
- Sampling scripts (sample.py, sample_batch.py, sample_for_pdb.py, sample_frag.py, sample_linker.py)
- Evaluation & Docking
- Evaluation metrics & processing (evaluation/*.py: docking, scoring, similarity, property_cal, MM_PBSA, etc.)
- External docking tool (QuickVina2 via evaluation/env_adt.yml and prepare_receptor4.py)
- Storage & Artifacts
- Pre-trained model checkpoints (downloaded via Zenodo)
- Generated molecule outputs and intermediate files (SDF, pdbqt)
- Logging and metrics (fpscores.pkl.gz, evaluation outputs)

##### Relationships and Data Flows
- Data prep → Dataset loader: raw PDB/SDF files → utils.readers → in-memory tensors
- Config loader → training/inference scripts: YAML → hyperparameters
- Training script → Model core: forward/backward through encoder + diffusion → checkpoint writes
- Sampling script → Model core: inference pass → generated 3D coordinates → write SDF/pdb
- Generated molecules → Evaluation module → compute docking (QuickVina2) & scoring → metrics output
- CLI scripts orchestrate all steps; they import from utils, models, evaluation.

##### Architectural Patterns & Principles
- Modular decomposition: separate directories for configs, models, utils, evaluation
- Layered design:
– CLI/entry points (train.py, sample_*.py)
– Data abstraction (utils, configs)
– Model definition (models/)
– Evaluation & external integrations (evaluation/)
- Scalability: support single-GPU and distributed training (train_ddp_op.py)
- Extensibility: plug-in style encoders, flexible sampling types via command-line flags.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Service
    subgraph "Configuration Service"
        ConfigLoader["configs/dataset_config.py"]:::data
        ConfigDir["configs/"]:::data
        MolConfig["mol.yml"]:::data
    end

    %% Data Preparation
    subgraph "Data Preparation"
        PocketLigand["split_pocket_ligand.py"]:::orch
    end

    %% Dataset & Transforms
    subgraph "Dataset & Transforms"
        DataPy["utils/data.py"]:::compute
        DatasetsPy["utils/datasets.py"]:::compute
        DatasetsDir["utils/datasets/"]:::compute
        Transforms["utils/transforms.py"]:::compute
    end

    %% Model Core
    subgraph "Model Core"
        Common["models/common.py"]:::compute
        Geometry["models/geometry.py"]:::compute
        Diffusion["models/diffusion.py"]:::compute
        EpsDiff["models/epsnet/diffusion.py"]:::compute
        MDMShared["models/epsnet/MDM_pocket_coor_shared.py"]:::compute
        subgraph "Encoders"
            Attention["models/encoders/attention.py"]:::compute
            CFTFM["models/encoders/cftfm.py"]:::compute
            EdgeEnc["models/encoders/edge.py"]:::compute
            EGNN["models/encoders/egnn.py"]:::compute
            EGNNPT["models/encoders/egnn_pytorch.py"]:::compute
            GIN["models/encoders/gin.py"]:::compute
            Schnet["models/encoders/schnet.py"]:::compute
            SchnetGeo["models/encoders/schnet_geo.py"]:::compute
        end
    end

    %% Training & Distributed Training
    subgraph "Training & Distributed"
        Train["train.py"]:::orch
        TrainDDP["train_ddp_op.py"]:::orch
        TrainUtil["utils/train.py"]:::compute
        Warmup["utils/warmup.py"]:::compute
    end

    %% Inference / Sampling
    subgraph "Inference / Sampling"
        Sample["sample.py"]:::orch
        SampleBatch["sample_batch.py"]:::orch
        SamplePDB["sample_for_pdb.py"]:::orch
        SampleFrag["sample_frag.py"]:::orch
        SampleLink["sample_linker.py"]:::orch
        SampleUtil["utils/sample.py"]:::compute
    end

    %% Evaluation & Docking
    subgraph "Evaluation & Docking"
        Dock1["evaluation/docking.py"]:::external
        Dock2["evaluation/docking_2.py"]:::external
        Dock2S["evaluation/docking_2_single.py"]:::external
        PrepareQ["evaluation/prepare_qdbqt.py"]:::external
        EnvADT["evaluation/env_adt.yml"]:::data
        EvalMetrics["evaluation/evaluation_metrics.py"]:::compute
        CalSC["evaluation/cal_SC_RDKit_score.py"]:::compute
        ScoreFunc["evaluation/score_func.py"]:::compute
        Similarity["evaluation/similarity.py"]:::compute
        PropCal["evaluation/property_cal.py"]:::compute
        SASC["evaluation/sascorer.py"]:::compute
        MM_PBSA["evaluation/MM_PBSA.py"]:::compute
        Mol2SDF["evaluation/mol_2_sdf.py"]:::compute
    end

    %% Storage & Artifacts
    subgraph "Storage & Artifacts"
        SplitPT["configs/data/split_by_name.pt"]:::data
        FPScores["evaluation/fpscores.pkl.gz"]:::data
        Vina1["test_vina_crossdock.pkl"]:::data
        Vina2["test_vina_crossdock_dict.pkl"]:::data
        README["README.md"]:::data
        ModelPDF["img/model.pdf"]:::data
    end

    %% External Services & Libraries
    PyTorch["PyTorch"]:::external
    RDKit["RDKit"]:::external
    QuickVina2["QuickVina2"]:::external
    YAML["YAML Parser"]:::external

    %% Data and Control Flows
    YAML ---|parses| ConfigLoader
    ConfigLoader -->|loads| Train
    ConfigLoader -->|loads| TrainDDP
    ConfigLoader -->|loads| Sample
    ConfigLoader -->|loads| SampleBatch
    ConfigLoader -->|loads| SamplePDB
    ConfigLoader -->|loads| SampleFrag
    ConfigLoader -->|loads| SampleLink

    PocketLigand -->|produces splits| DataPy
    DataPy --> DatasetsPy
    DataPy --> DatasetsDir
    DataPy --> Transforms

    DatasetsDir -->|tensor data| Train
    DatasetsDir -->|tensor data| Sample

    Train -->|uses| Common
    Train -->|uses| Geometry
    Train -->|uses| Diffusion
    Train -->|uses| EpsDiff
    Train -->|uses| MDMShared
    Train -->|uses| Attention
    Train -->|uses| CFTFM
    Train -->|uses| EdgeEnc
    Train -->|uses| EGNN
    Train -->|uses| EGNNPT
    Train -->|uses| GIN
    Train -->|uses| Schnet
    Train -->|uses| SchnetGeo
    TrainDDP -->|same as train| Train

    Sample -->|inference| Common
    Sample -->|inference| Geometry
    Sample -->|inference| Diffusion
    Sample -->|inference| EpsDiff
    Sample -->|inference| MDMShared

    Sample -->|generates| Mol2SDF
    SampleBatch -->|generates| Mol2SDF
    SamplePDB -->|generates| Mol2SDF
    SampleFrag -->|generates| Mol2SDF
    SampleLink -->|generates| Mol2SDF

    Mol2SDF --> EvalMetrics
    EvalMetrics --> CalSC
    EvalMetrics --> ScoreFunc
    EvalMetrics --> Similarity
    EvalMetrics --> PropCal
    EvalMetrics --> SASC
    EvalMetrics --> MM_PBSA
    Mol2SDF --> Dock1
    Mol2SDF --> Dock2
    Mol2SDF --> Dock2S
    PrepareQ -->|prepares| Dock1
    EnvADT --> Dock1
    QuickVina2 --> Dock1

    Dock1 --> FPScores
    Dock2 --> FPScores
    Dock2S --> FPScores
    EvalMetrics --> FPScores

    Train --> SplitPT
    ReadME --> ModelPDF

    %% Click Events
    click ConfigLoader "https://github.com/layne-huang/pmdm/blob/main/configs/dataset_config.py"
    click ConfigDir "https://github.com/layne-huang/pmdm/tree/main/configs/"
    click MolConfig "https://github.com/layne-huang/pmdm/blob/main/mol.yml"
    click PocketLigand "https://github.com/layne-huang/pmdm/blob/main/split_pocket_ligand.py"
    click DataPy "https://github.com/layne-huang/pmdm/blob/main/utils/data.py"
    click DatasetsPy "https://github.com/layne-huang/pmdm/blob/main/utils/datasets.py"
    click DatasetsDir "https://github.com/layne-huang/pmdm/tree/main/utils/datasets/"
    click Transforms "https://github.com/layne-huang/pmdm/blob/main/utils/transforms.py"
    click Common "https://github.com/layne-huang/pmdm/blob/main/models/common.py"
    click Geometry "https://github.com/layne-huang/pmdm/blob/main/models/geometry.py"
    click Diffusion "https://github.com/layne-huang/pmdm/blob/main/models/diffusion.py"
    click EpsDiff "https://github.com/layne-huang/pmdm/blob/main/models/epsnet/diffusion.py"
    click MDMShared "https://github.com/layne-huang/pmdm/blob/main/models/epsnet/MDM_pocket_coor_shared.py"
    click Attention "https://github.com/layne-huang/pmdm/blob/main/models/encoders/attention.py"
    click CFTFM "https://github.com/layne-huang/pmdm/blob/main/models/encoders/cftfm.py"
    click EdgeEnc "https://github.com/layne-huang/pmdm/blob/main/models/encoders/edge.py"
    click EGNN "https://github.com/layne-huang/pmdm/blob/main/models/encoders/egnn.py"
    click EGNNPT "https://github.com/layne-huang/pmdm/blob/main/models/encoders/egnn_pytorch.py"
    click GIN "https://github.com/layne-huang/pmdm/blob/main/models/encoders/gin.py"
    click Schnet "https://github.com/layne-huang/pmdm/blob/main/models/encoders/schnet.py"
    click SchnetGeo "https://github.com/layne-huang/pmdm/blob/main/models/encoders/schnet_geo.py"
    click Train "https://github.com/layne-huang/pmdm/blob/main/train.py"
    click TrainDDP "https://github.com/layne-huang/pmdm/blob/main/train_ddp_op.py"
    click TrainUtil "https://github.com/layne-huang/pmdm/blob/main/utils/train.py"
    click Warmup "https://github.com/layne-huang/pmdm/blob/main/utils/warmup.py"
    click Sample "https://github.com/layne-huang/pmdm/blob/main/sample.py"
    click SampleBatch "https://github.com/layne-huang/pmdm/blob/main/sample_batch.py"
    click SamplePDB "https://github.com/layne-huang/pmdm/blob/main/sample_for_pdb.py"
    click SampleFrag "https://github.com/layne-huang/pmdm/blob/main/sample_frag.py"
    click SampleLink "https://github.com/layne-huang/pmdm/blob/main/sample_linker.py"
    click SampleUtil "https://github.com/layne-huang/pmdm/blob/main/utils/sample.py"
    click Dock1 "https://github.com/layne-huang/pmdm/blob/main/evaluation/docking.py"
    click Dock2 "https://github.com/layne-huang/pmdm/blob/main/evaluation/docking_2.py"
    click Dock2S "https://github.com/layne-huang/pmdm/blob/main/evaluation/docking_2_single.py"
    click PrepareQ "https://github.com/layne-huang/pmdm/blob/main/evaluation/prepare_qdbqt.py"
    click EnvADT "https://github.com/layne-huang/pmdm/blob/main/evaluation/env_adt.yml"
    click EvalMetrics "https://github.com/layne-huang/pmdm/blob/main/evaluation/evaluation_metrics.py"
    click CalSC "https://github.com/layne-huang/pmdm/blob/main/evaluation/cal_SC_RDKit_score.py"
    click ScoreFunc "https://github.com/layne-huang/pmdm/blob/main/evaluation/score_func.py"
    click Similarity "https://github.com/layne-huang/pmdm/blob/main/evaluation/similarity.py"
    click PropCal "https://github.com/layne-huang/pmdm/blob/main/evaluation/property_cal.py"
    click SASC "https://github.com/layne-huang/pmdm/blob/main/evaluation/sascorer.py"
    click MM_PBSA "https://github.com/layne-huang/pmdm/blob/main/evaluation/MM_PBSA.py"
    click Mol2SDF "https://github.com/layne-huang/pmdm/blob/main/evaluation/mol_2_sdf.py"
    click SplitPT "https://github.com/layne-huang/pmdm/blob/main/configs/data/split_by_name.pt"
    click FPScores "https://github.com/layne-huang/pmdm/blob/main/evaluation/fpscores.pkl.gz"
    click Vina1 "https://github.com/layne-huang/pmdm/blob/main/test_vina_crossdock.pkl"
    click Vina2 "https://github.com/layne-huang/pmdm/blob/main/test_vina_crossdock_dict.pkl"
    click README "https://github.com/layne-huang/pmdm/blob/main/README.md"
    click ModelPDF "https://github.com/layne-huang/pmdm/blob/main/img/model.pdf"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orch fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#FF6347,stroke:#333,stroke-width:1px
```
