# forlilab/waterkit architecture

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

- Interactive diagram: https://gitdiagram.com/forlilab/waterkit
- Repository: https://github.com/forlilab/waterkit

## Overview

##### Project type and purpose
- This repository packages two mature C/C++ command-line tools (AutoDock and AutoGrid) alongside a Python library (“waterkit”) and a set of Python scripts.
- Purpose: provide an end-to-end toolkit for generating receptor/ligand grid maps (via AutoGrid), performing docking simulations (via AutoDock), and then analyzing hydration sites and water behavior through Python.

##### File structure
- Top level:
- autodocksuite-4.2.6-src/ – full source trees for AutoDock and AutoGrid (C/C++).
- data/ – precomputed parameter files and grid configuration templates.
- docs/ – Sphinx documentation.
- scripts/ – executable Python scripts that orchestrate grid creation, docking, trajectory preparation, etc.
- waterkit/ – core Python package (modules for map I/O, sampling, analysis, force‐fields, etc.).
- setup.py – Python installer entry point.
- Key patterns:
- C binaries live in their own source trees, built via Automake/Autoconf (Makefile.am, configure, etc.).
- Python layer wraps or invokes these binaries (e.g., waterkit/autodock_map.py calls AutoDock executables).
- Data/ and waterkit/data provide static assets (parameter files, water models).

##### Main components
a. User Interface Layer
- CLI scripts (scripts/*.py)
- Python package entrypoint (waterkit/waterkit.py)
b. Python Library Layer (waterkit/)
- Modules: autodock_map, autogrid, sampling, analysis, forcefield, molecule, spherical_model_map, typer, utils
- Data submodule: static water models & parameters
c. Native Executables Layer
- AutoGrid C binary (built from autodocksuite-4.2.6-src/autogrid)
- AutoDock C binary (built from autodocksuite-4.2.6-src/autodock)
d. Data Layer
- Parameter files (data/, waterkit/data)
- Grid template files (.gpf), map outputs (.map), PDBQT inputs/outputs
e. Documentation Layer
- Sphinx source (docs/) → HTML/PDF

##### Relationships & data flow
1. User invokes a script or `waterkit` CLI →
2. Python script imports waterkit modules →
3. Python wrapper builds grid definition (.gpf) →
4. Calls AutoGrid binary (subprocess) → generates map files (.map) →
5. Calls AutoDock binary to perform docking → generates trajectories (.trj, .dlg) →
6. Python sampling & analysis modules parse maps & trajectories → compute hydration metrics →
7. Results returned to user or written to disk

##### Architectural patterns & design principles
- Separation of concerns:
- Native code handles compute-intensive tasks (grid calc, docking).
- Python handles orchestration, data parsing, analysis, visualization.
- Modular packaging:
- Each Python submodule encapsulates a domain (e.g., `waterkit.analysis`, `waterkit.sampling`).
- Extensibility points:
- New analysis routines can be added under `waterkit/analysis`.
- Additional scripts or workflows in `scripts/`.

##### Technologies & frameworks
- C/C++ with Autotools (configure, Makefile.am)
- Python 3.x, setuptools (setup.py)
- Sphinx for docs
- Standard scientific stack (numpy, possibly scipy)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Installer
    setup["Installer (setup.py)"]:::installer

    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        scripts["CLI Scripts"]:::ui
        entrypoint["CLI Entrypoint\nwaterkit/waterkit.py"]:::ui
    end

    %% Python Library Layer
    subgraph "Python Core (waterkit)" 
        direction TB
        autogrid_mod["waterkit.autogrid"]:::python
        autodock_mod["waterkit.autodock_map"]:::python
        sampling_mod["waterkit.sampling"]:::python
        analysis_pkg["waterkit/analysis"]:::python
        forcefield_mod["waterkit.forcefield"]:::python
        molecule_mod["waterkit.molecule"]:::python
        spherical_mod["waterkit.spherical_model_map"]:::python
        typer_pkg["waterkit/typer"]:::python
        utils_mod["waterkit.utils"]:::python
        water_box["waterkit.water_box"]:::python
        water_mod["waterkit.water"]:::python
    end

    %% Native Executables Layer
    subgraph "Native Executables" 
        direction TB
        autogrid_bin["AutoGrid Binary (autogrid4)"]:::native
        autodock_bin["AutoDock Binary (autodock4)"]:::native
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        global_data["Global Data (data/)"]:::data
        pkg_data["Package Data\n(waterkit/data/)"]:::data
        water_models["Water Models\n(waterkit/data/water/)"]:::data
    end

    %% Documentation Layer
    subgraph "Documentation Layer"
        direction TB
        docs["Sphinx Docs (docs/)"]:::docs
    end

    %% Relationships
    setup --> scripts
    setup --> entrypoint
    scripts --> entrypoint
    scripts --> autogrid_mod
    scripts --> autodock_mod
    entrypoint --> autogrid_mod
    entrypoint --> autodock_mod
    entrypoint --> sampling_mod
    entrypoint --> analysis_pkg

    autogrid_mod --> autogrid_bin
    autodock_mod --> autodock_bin

    autogrid_bin -->|"generates .map files"| sampling_mod
    autodock_bin -->|"generates trajectories"| analysis_pkg

    pkg_data -.-> autogrid_bin
    global_data -.-> autodock_bin
    water_models -.-> water_mod

    sampling_mod --> scripts
    analysis_pkg --> scripts

    docs -.-> entrypoint

    %% Click Events
    click scripts "https://github.com/forlilab/waterkit/tree/master/scripts/"
    click entrypoint "https://github.com/forlilab/waterkit/blob/master/waterkit/waterkit.py"
    click autogrid_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/autogrid.py"
    click autodock_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/autodock_map.py"
    click sampling_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/sampling.py"
    click analysis_pkg "https://github.com/forlilab/waterkit/tree/master/waterkit/analysis/"
    click forcefield_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/forcefield.py"
    click molecule_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/molecule.py"
    click spherical_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/spherical_model_map.py"
    click typer_pkg "https://github.com/forlilab/waterkit/tree/master/waterkit/typer/"
    click utils_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/utils.py"
    click water_box "https://github.com/forlilab/waterkit/blob/master/waterkit/water_box.py"
    click water_mod "https://github.com/forlilab/waterkit/blob/master/waterkit/water.py"
    click global_data "https://github.com/forlilab/waterkit/tree/master/data/"
    click pkg_data "https://github.com/forlilab/waterkit/tree/master/waterkit/data/"
    click water_models "https://github.com/forlilab/waterkit/tree/master/waterkit/data/water/"
    click autogrid_bin "https://github.com/forlilab/waterkit/tree/master/autodocksuite-4.2.6-src/autogrid/"
    click autodock_bin "https://github.com/forlilab/waterkit/tree/master/autodocksuite-4.2.6-src/autodock/"
    click docs "https://github.com/forlilab/waterkit/tree/master/docs/"
    click setup "https://github.com/forlilab/waterkit/blob/master/setup.py"

    %% Styles
    classDef ui fill:#9f6,stroke:#333,stroke-width:1px
    classDef python fill:#6cf,stroke:#333,stroke-width:1px
    classDef native fill:#f96,stroke:#333,stroke-width:1px
    classDef data fill:#ccc,stroke:#333,stroke-width:1px
    classDef docs fill:#fc9,stroke:#333,stroke-width:1px
    classDef installer fill:#c9f,stroke:#333,stroke-width:1px
```
