# jssweller/drughive architecture

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

- Interactive diagram: https://gitdiagram.com/jssweller/drughive
- Repository: https://github.com/jssweller/drughive

## Overview

##### Project type and purpose
- DrugHIVE is a Python-based, command‐line-driven machine-learning pipeline (a deep hierarchical variational autoencoder) for structure‐based drug design. It ingests 3D protein–ligand data, trains a generative model, then samples or optimizes novel ligands via docking.

##### File structure
- Top‐level scripts:
- process_pdbbind_data.py, process_zinc_dataset.py – data preprocessing
- train.py – model training entry point
- generate_molecules.py – sampling new molecules
- generate_optimize.py, ff_optimize.py, dock.py – ligand optimization & docking
- Core library: drughive/
- atomgridding.py, gridutils.py – 3D grid featurization
- blocks.py, distributions.py, models.py – VAE components
- generating.py, molfitting.py, molecules.py – generative inference
- data.py, trainutils.py, lightning.py – data loaders & PyTorch Lightning integration
- visutils.py, molfiles.py – visualization & file I/O
- Config directory: YAML templates for train, generate, optimize workflows
- Data directory: example protein/ligand sets & filters
- External files: requirements.txt, setup.py

##### README for additional insights
- The README confirms use of PDBBind & ZINC datasets, RDKit/OpenBabel for chemistry, PyTorch Lightning for training, and QuickVina2 for docking. It describes four main workflows: preprocessing, training, sampling, and optimization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        PDB["PDBBind Dataset"]:::data
        ZINC["ZINC Library"]:::data
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        PP1["process_pdbbind_data.py"]:::compute
        PP2["process_zinc_dataset.py"]:::compute
        HDF5["HDF5/SDF Data Store"]:::data
    end

    %% Core Model Library
    subgraph "Core Model Library (drughive)"
        AG["AtomGridding Module"]:::compute
        GU["GridUtils Module"]:::compute
        BL["Blocks (Encoder/Decoder)"]:::compute
        DS["Distributions Module"]:::compute
        MDL["Models Module"]:::compute
        MF["Molfiles Module"]:::compute
        MOL["Molecules Module"]:::compute
        MFt["MolFitting Module"]:::compute
        GEN["Generating Module"]:::compute
        DDATA["Data Loader Module"]:::compute
        TU["TrainUtils Module"]:::compute
        LT["Lightning Integration"]:::compute
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        TrainScript["train.py"]:::compute
        TrainCfg["config/train.yml"]:::config
        CKPT["Model Checkpoint (.ckpt)"]:::data
    end

    %% Generative Inference
    subgraph "Generative Inference"
        GenScript["generate_molecules.py"]:::compute
        GenCfg["config/generate.yml"]:::config
        MolecOut["Raw Molecule Output"]:::data
    end

    %% Optimization Pipeline
    subgraph "Optimization Pipeline"
        GenOpt["generate_optimize.py"]:::compute
        FFOpt["ff_optimize.py"]:::compute
        DockScript["dock.py"]:::external
        OptCfg["config/generate_optimize.yml"]:::config
        ScoredMol["Scored/Refined Molecules"]:::data
    end

    %% Visualization & Analysis
    subgraph "Visualization & Analysis"
        VIS["VisUtils Module"]:::compute
        Plots["Plots/Images"]:::data
    end

    %% Connections
    PDB --> PP1 --> HDF5
    ZINC --> PP2 --> HDF5

    HDF5 --> DDATA
    DDATA --> TrainScript
    TrainCfg --> TrainScript
    TrainScript --> CKPT

    CKPT --> GenScript
    GenCfg --> GenScript
    GenScript --> MolecOut

    MolecOut --> GenOpt
    OptCfg --> GenOpt
    GenOpt --> DockScript --> ScoredMol
    FFOpt --> DockScript

    %% Visualization flows
    HDF5 --> VIS
    CKPT --> VIS
    MolecOut --> VIS
    ScoredMol --> VIS
    VIS --> Plots

    %% Click Events
    click PDB "https://github.com/jssweller/drughive/tree/main/data/"
    click PP1 "https://github.com/jssweller/drughive/blob/main/process_pdbbind_data.py"
    click PP2 "https://github.com/jssweller/drughive/blob/main/process_zinc_dataset.py"
    click AG "https://github.com/jssweller/drughive/blob/main/drughive/atomgridding.py"
    click GU "https://github.com/jssweller/drughive/blob/main/drughive/gridutils.py"
    click BL "https://github.com/jssweller/drughive/blob/main/drughive/blocks.py"
    click DS "https://github.com/jssweller/drughive/blob/main/drughive/distributions.py"
    click MDL "https://github.com/jssweller/drughive/blob/main/drughive/models.py"
    click MF "https://github.com/jssweller/drughive/blob/main/drughive/molfiles.py"
    click MOL "https://github.com/jssweller/drughive/blob/main/drughive/molecules.py"
    click MFt "https://github.com/jssweller/drughive/blob/main/drughive/molfitting.py"
    click GEN "https://github.com/jssweller/drughive/blob/main/drughive/generating.py"
    click DDATA "https://github.com/jssweller/drughive/blob/main/drughive/data.py"
    click TU "https://github.com/jssweller/drughive/blob/main/drughive/trainutils.py"
    click LT "https://github.com/jssweller/drughive/blob/main/drughive/lightning.py"
    click VIS "https://github.com/jssweller/drughive/blob/main/drughive/visutils.py"
    click TrainScript "https://github.com/jssweller/drughive/blob/main/train.py"
    click TrainCfg "https://github.com/jssweller/drughive/blob/main/config/train.yml"
    click GenScript "https://github.com/jssweller/drughive/blob/main/generate_molecules.py"
    click GenCfg "https://github.com/jssweller/drughive/blob/main/config/generate.yml"
    click GenOpt "https://github.com/jssweller/drughive/blob/main/generate_optimize.py"
    click FFOpt "https://github.com/jssweller/drughive/blob/main/ff_optimize.py"
    click DockScript "https://github.com/jssweller/drughive/blob/main/dock.py"
    click OptCfg "https://github.com/jssweller/drughive/blob/main/config/generate_optimize.yml"
    click setup "https://github.com/jssweller/drughive/blob/main/setup.py"
    click reqs "https://github.com/jssweller/drughive/blob/main/requirements.txt"
    click ExData "https://github.com/jssweller/drughive/tree/main/data/example_data/"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef compute fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef external fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef config fill:#EEEEEE,stroke:#616161,color:#424242;
```
