Ultidock

Ultidock is a high-throughput molecular docking workflow that automates ligand staging, grid preparation, AutoDock-GPU execution, and post-processing.

This document explains how to run the pipeline step by step, details the major components, and highlights the features that make Ultidock different from traditional docking scripts.

Requirements
Repository Layout
Quick Start: End-to-End Run
Command Reference
Deterministic Receptor Input Handling
Configuration Reference
Pipeline Segments & What Makes Ultidock Different
Spotlight: Grid Boxing & Cavity Finder Algorithm
Benchmarking
Working with the Example Pipelines
Troubleshooting
Citation & License

Requirements

Ultidock targets modern Linux systems. Windows and macOS users should rely on a Linux container or VM.

Hardware

Component	Requirement
CPU	x86-64 with AVX (for preprocessing and optional CPU docking)
GPU	NVIDIA CUDA or a supported OpenCL GPU for AutoDock-GPU; CPU-only Vina mode is also available.
RAM	≥ 16 GB recommended for large ligand batches
Storage	≥ 20 GB free space for ligand archives, grids, and outputs

Operating System

Ubuntu 26.04 is the documented package path below. Other modern Linux distributions need equivalent native packages and GPU runtimes.
Bash shell and coreutils available on $PATH

System Packages

On Ubuntu 26.04, install the native programs with:

sudo apt update
sudo apt install -y \
  autoconf automake build-essential clinfo cmake csh curl \
  g++-12 gcc-12 gfortran git libnetcdf-dev libtool libx11-dev \
  m4 make ocl-icd-opencl-dev openbabel openjdk-21-jre-headless \
  perl pkg-config python3 python3-pip python3-venv tar unzip wget

This installs the AutoGrid build tools (autoconf, automake, m4, perl, csh), GCC 12 used by the AutoDock-GPU build script, fpocket's C toolchain and NetCDF headers, curl for P2Rank, Java 21 for P2Rank 2.5, OpenCL build headers, and Open Babel for raw receptor .pdb conversion. It does not install a GPU driver or vendor compute runtime. On another distribution, install equivalent packages; package names and available Java versions vary.

GPU Runtimes

Before running GPU setup, install your GPU driver and compute runtime. Installing Ultidock's Python dependencies or activating a virtual environment does not install GPU drivers. A working desktop display alone does not mean CUDA or OpenCL is available. Ultidock does not install system GPU drivers.

NVIDIA/CUDA: install the NVIDIA driver and a CUDA Toolkit compatible with your GPU and the AutoDock-GPU build. See NVIDIA's official downloads. Check that nvidia-smi -L lists your GPU and nvcc --version finds the compiler.
AMD/Intel/OpenCL: install a compatible vendor or Mesa OpenCL runtime, plus the OpenCL development headers and clinfo. Check that clinfo -l lists your GPU. Number of platforms 0 means no OpenCL platform is available to that process; the ICD loader alone does not provide a GPU runtime.
Ultidock defaults to AutoDock-GPU when a GPU is detected. AutoGrid is built on first use, including CPU mode.

For AMD graphics using Mesa on Ubuntu 26.04, the Mesa OpenCL package provides Rusticl. Install it and check device visibility before running Ultidock:

sudo apt update
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev clinfo
export RUSTICL_ENABLE=radeonsi
clinfo -l

mesa-opencl-icd supplies the runtime for device discovery and execution. ocl-icd-opencl-dev supplies the OpenCL headers and linker library needed to compile AutoDock-GPU. Both are required for a fresh build; a working clinfo does not prove the development files are installed.

RUSTICL_ENABLE=radeonsi enables Mesa's AMD OpenCL devices; see the Mesa environment-variable documentation. The manual export above is useful for checking clinfo yourself. During setup, if Rusticl is present but exposes no GPU and RUSTICL_ENABLE is unset, Ultidock automatically retries with radeonsi. It keeps the setting only if a GPU appears, passes it to child processes, and saves it in docking/config.py for subsequent runs (including --skip-setup). Existing user settings are respected. This also applies to explicit --mode opencl setup. No shell profile is modified.

A Mesa/Rusticl platform name alone does not select the GPU backend: a GPU device must actually be reported. Device visibility does not by itself verify AutoDock-GPU compatibility. Containers and VMs also need GPU device and runtime access.

--mode gpu stops if no GPU is detected. Use --mode auto to permit CPU fallback, or --mode cpu to select CPU docking explicitly.

Python Environment

Ultidock requires Python 3.10+. You can use system Python and distro packages without a virtual environment or a pip installation of this checkout. On Ubuntu 26.04, install the runtime dependencies:

sudo apt install python3 python3-click python3-numpy python3-scipy \
  python3-psutil python3-pandas python3-matplotlib

From the repository root, use /usr/bin/python3 to select system Python even if your terminal currently has a virtual environment activated:

/usr/bin/python3 -m cli.ultidock --help
/usr/bin/python3 -m cli.ultidock example run quickstart
/usr/bin/python3 -m cli.molguard --help

For this source-checkout installation, replace ultidock in the commands below with /usr/bin/python3 -m cli.ultidock and molguard with /usr/bin/python3 -m cli.molguard, running from the repository root. On other distros, package versions must satisfy pyproject.toml. GPU drivers, compute runtimes and native build tools are still required independently of Python.

Alternatively, use pip in a virtual environment after installing the native programs above:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Install Ultidock and its Python dependencies in one step from the repository:

python -m pip install .
python -m ultidock --help

This installs numpy, scipy, psutil, matplotlib, pandas, the ultidock workflow CLI, and the molguard deterministic I/O CLI. pandas and matplotlib are used only by the post-run analysis stage.

The distribution and public Python package are named ultidock. The molguard command and Python imports remain available as part of Ultidock. If upgrading an environment that contains the old molguard distribution, remove it first with python -m pip uninstall molguard, then run the installation above. For development, use python -m pip install -e ".[dev]" instead.

A regular installation works outside the checkout. On first workflow use, Ultidock prepares its scripts, examples, and native build sources in $XDG_DATA_HOME/ultidock (default ~/.local/share/ultidock). Configuration, compiled tools, pocket-tool downloads, and run outputs stay there; installed Python files remain untouched. Set ULTIDOCK_HOME=/path/to/workspace to choose another location. ultidock doctor prints the active workspace. Editable and direct source-checkout runs keep the existing repository layout by default; they also honor ULTIDOCK_HOME.

Python wheels do not contain machine-specific docking executables. Install AutoDock Vina with sudo apt install autodock-vina, or put vina and vina_split on PATH. Ultidock links available Vina and AutoGrid programs into the managed workspace; otherwise setup builds AutoGrid from its included source. Source-checkout runs can continue using their bundled Vina binaries. GPU drivers and native build dependencies are still installed separately from the Python package.

If you did not run the Ubuntu package command and want to prepare raw receptor .pdb files, install at least one receptor conversion backend. In a virtual environment, use Meeko; with Ubuntu system Python, install Open Babel:

python -m pip install meeko
# or: sudo apt install openbabel

Existing receptor .pdbqt files do not need Meeko/Open Babel; they are only canonicalized by molguard.

Repository Layout

ultidock/
├─ pyproject.toml            # Package manifest; defines `ultidock` and `molguard` CLIs
├─ requirements.txt          # Runtime dependencies (numpy, scipy, click, ...)
├─ requirements-dev.txt      # Development/test dependencies
├─ SETUP.md                  # Step-by-step new-user guide
├─ cli/                      # Repo-root CLI entry points
│  ├─ ultidock.py            # Workflow, benchmark, and example commands
│  └─ molguard.py            # File/receptor/grid safety commands
├─ molguard/                 # I/O hardening + validation layer
│  ├─ io/
│  │  ├─ fixedfmt.py         # Fixed-width, locale-safe float formatter
│  │  ├─ pdbqt.py            # PDBQT linter, normalizer, receptor canonicalizer
│  │  └─ receptor_prep.py    # Shared receptor prep for pipeline + benchmarks
│  ├─ grids/
│  │  └─ check.py            # AutoGrid .fld / .map sanity checker
│  ├─ cli.py                 # Compatibility shim for older imports
│  └─ tests/                 # Unit and regression tests (pytest)
├─ docking/
│  ├─ run.py                 # Main entry point for the entire pipeline
│  ├─ setup.py               # Idempotent environment + dependency setup
│  ├─ dock_v02.py            # AutoDock-GPU / AutoGrid orchestration
│  ├─ make_grids.py          # Receptor-only site finder and grid generator
│  ├─ profile_receptors.py   # Optional per-receptor sidecar profiler
│  ├─ analyse_docking_results.py
│  ├─ extract.py             # Front-end for AutoDock Vina's vina_split utility
│  ├─ clean.py               # Resets compiled binaries and outputs
│  ├─ ligands.wget           # Example ligand download manifest
│  ├─ MACRO_MOL_DIR/         # Receptors, grids, and generated sites
│  ├─ LIGANDS_DIR/           # Archived ligands and split PDBQT files
│  ├─ DOCKING_DIR/           # AutoDock-GPU/Vina output poses
│  ├─ AUTODOCK_GPU_DIR/      # Compiled AutoDock-GPU + AutoGrid binaries
│  ├─ VINA_DIR/              # AutoDock Vina binaries
│  ├─ ANALYSIS_DIR/          # Intermediate scoring/aggregation artifacts
│  └─ RESULTS_DIR/           # Final CSV/JSON summaries
├─ benchmarks/               # DUD-E download, preparation, site recovery, and docking benchmarks
├─ examples/                 # Self-contained example runners
└─ data-analyses/, results/  # Optional downstream notebooks & exports

The workflow assumes you copy receptor .pdb or .pdbqt files into docking/MACRO_MOL_DIR/ and provide a .wget manifest (or existing ligand archives) inside docking/LIGANDS_DIR/.

Quick Start: End-to-End Run

Follow this checklist whenever you want to run Ultidock from a clean workspace.

Clone the repository (or update your local copy):

git clone https://github.com/taka78/ultidock.git
cd ultidock

Install the native packages and Python dependencies in Requirements. Verify the CLI with ultidock --help after a pip install, or /usr/bin/python3 -m cli.ultidock --help from the checkout.
Try the lightweight example before building the full docking toolchain:
```
ultidock example run quickstart
```
It generates a report from bundled fixtures without a GPU or Java. With source-checkout system Python, use /usr/bin/python3 -m cli.ultidock example run quickstart.
Stage inputs:
- Copy your receptor(s) to docking/MACRO_MOL_DIR/. Ultidock scans files by extension: each *.pdb is sanitized and converted to <input-stem>.pdbqt, and each *.pdbqt is only canonicalized. Generated receptor folders use the same discovered stem, matching the dock_v02.py/make_grids.py flow.
- Provide ligands via one of the following:
  - Populate docking/ligands.wget with direct links to .pdbqt.gz archives (one per line). Ultidock will download, verify, and extract them.
  - Manually place .pdbqt or .pdbqt.gz files in docking/LIGANDS_DIR/.
  - Pass --skip-wget when running setup.py/run.py to skip downloads and rely entirely on pre-populated ligand files. Keep only the ligands you intend to dock in that directory; the pipeline scans every *.pdbqt.
Run the setup + docking pipeline:
```
ultidock run --mode gpu --skip-wget
```
- With the source-checkout installation, use /usr/bin/python3 -m cli.ultidock run --mode gpu --skip-wget instead.
- Use --mode cpu if you have no GPU; this uses AutoGrid and Vina.
- Omit --skip-wget only when you intend to run the download manifest.
- Override directories as needed with --LIGANDS_DIR, --MACRO_MOL_DIR, etc. Absolute paths are recommended for scripted automation.
Monitor progress:
- Setup output reports where AutoDock-GPU and AutoGrid binaries are built or reused. The repository includes static Linux Vina binaries.
- Docking output prints the number of ligands discovered, grid preparation steps, worker launches, and database insertions.
Review results:
- Raw poses are written to docking/DOCKING_DIR/.
- Per-receptor metadata (centers, grids) lives in docking/MACRO_MOL_DIR/.
- An auto-managed SQLite database (docking/RESULTS_DIR/ultidock_results.db) is updated throughout the run for incremental result parsing and can be inspected or queried at any time.
- If pandas is installed, aggregated CSV/JSON summaries will be produced in docking/RESULTS_DIR/. Analysis CSV and Excel exports include the stored binding_site for each pose, so identical ligand/model names from different pockets remain distinguishable. Unknown sites, including those in older databases without that field, are blank. Exports retain column headers even when no poses match the filters.
Optional post-run steps:
- Run python3 docking/extract.py --help to (re)split ligand archives via AutoDock Vina's vina_split utility or prepare filtered subsets for downstream MD.
- Use the notebooks in data-analyses/ for visualization or scoring audits.

For another batch, use new input/output directories or explicitly clean the old workspace. ultidock clean -y --all deletes build products, generated maps, ligands, and results, so inspect ultidock clean --all first.

Command Reference

When a CLI command hits a common failure path, it prints a short pointer to the most relevant README section instead of burying the terminal in long guidance.

Command	Purpose
`python3 docking/run.py [options]`	Primary entry point. Validates the environment, runs setup, downloads ligands, launches docking, and triggers analysis.
`python3 docking/setup.py [options]`	Runs the setup stage only (directory creation and AutoDock-GPU/AutoGrid build checks). All CLI flags mirror `run.py`.
`python3 docking/dock_v02.py [options]`	Executes the docking stage against prepared ligands and receptors. Used internally by `run.py`.
`python3 docking/extract.py`	Wrapper around AutoDock Vina's `vina_split` for splitting ligand archives and optional filtering.
`python3 docking/clean.py -y --all`	Removes compiled binaries, cached grids, downloads, and generated configs. Run only when you want a full reset.
`python3 docking/profile_receptors.py`	Generate optional per-receptor `.config.toml` sidecars from receptor geometry.
`python3 benchmarks/cavity_recovery_benchmark.py`	Evaluate receptor-only site finding against co-crystallized ligand centers. Supports target-level `--jobs` parallelism.
`python3 benchmarks/download_dude.py`	Download DUD-E receptor, crystal ligand, active, and decoy files.
`ultidock run [options]`	Run the full docking pipeline from anywhere in the repo (no need to `cd docking/`). Forwards all flags to `docking/run.py`.
`ultidock known-site --center x,y,z [options]`	Run docking with a manual/expert site box.
`ultidock cavity [options]`	Run CaV-EMPS automatic binding-site proposal and dock against predicted sites.
`ultidock blind [options]`	Run whole-receptor/blind docking.
`ultidock report <run_dir>`	Generate Markdown/HTML reports plus PyMOL/ChimeraX helper files from a run directory.
`ultidock setup [options]`	Run the setup stage through the workflow CLI.
`ultidock clean [-y] [--all]`	Reset compiled binaries and outputs. Forwards all flags to `docking/clean.py`.
`ultidock benchmark cavity-recovery [options]`	CLI wrapper for the receptor-only site-recovery benchmark.
`ultidock benchmark download-dude [options]`	Download DUD-E receptor, crystal ligand, active, and decoy files.
`ultidock benchmark site-prediction [options]`	Download/normalize COACH420/HOLO4K, run `cav-emps\|fpocket\|p2rank`, evaluate DCC metrics, and generate reports.
`ultidock example list` / `ultidock example run <name>`	Discover and run bundled example pipelines.
`ultidock doctor`	Print tool locations and versions. Distinguishes between binaries not compiled yet (source present) and not found at all.
`molguard pdbqt check <file>`	Lint a receptor or ligand PDBQT for AutoDock column-format issues (exponent notation, missing decimals, bad atom types).
`molguard pdbqt normalize <file> -o <out>`	Rewrite all numeric columns in a ligand PDBQT through the fixed-width formatter. Torsion tree is left untouched.
`molguard receptor canonicalize <file> -o <out>`	Sort, renumber, and reformat a receptor PDBQT deterministically. Returns a SHA-256 digest for reproducibility checks.
`molguard receptor prepare <file> -o <out>`	Run the shared receptor-prep path. `.pdbqt` is canonicalized; `.pdb` is sanitized, converted, then canonicalized.
`molguard grids check <maps.fld>`	Validate AutoGrid output: checks for all-zero maps, NaN/Inf energies, missing files, and atom-type mismatches.
`molguard doctor`	Print MolGuard version and optional receptor-conversion backend availability.

Researcher-Facing Run Modes

known-site: an expert/manual box baseline. You provide the center and box, and Ultidock docks against that site.
cavity: automatic CaV-EMPS mode. Ultidock proposes receptor-only site hypotheses and docks against those predicted boxes.
blind: naive whole-receptor baseline. Ultidock builds a broad receptor box without a site hypothesis.
benchmark: reproducible evaluation workflows for DUD-E, COACH420, HOLO4K, and method comparisons.

Key `run.py` Flags

Flag	Description
`--mode {auto,gpu,cuda,opencl,cpu}`	`auto` permits CPU fallback; `gpu` requires a detected NVIDIA/OpenCL GPU. `cuda`, `opencl`, and `cpu` select a backend explicitly. Automatic OpenCL detection requires `clinfo`.
`--skip-setup`	Assume setup has already been run and use the existing config.
`--LIGANDS_DIR PATH`	Override ligand staging directory.
`--MACRO_MOL_DIR PATH`	Override receptor directory.
`--AUTODOCK_GPU_DIR PATH`	Override AutoDock-GPU build/install directory.
`--VINA_DIR PATH`	Override AutoDock Vina install directory.
`--RESULTS_DIR PATH`, `--ANALYSIS_DIR PATH`, `--DOCKING_DIR PATH`	Customize other pipeline locations.
`--wget FILE`	Use a custom `.wget` manifest for ligand downloads.
`--skip-wget`	Skip executing `wget` commands even if a manifest is present.
`--skip-profile`	Preserve existing per-receptor `.config.toml` sidecars and skip automatic profiling.
`--receptor-prep-mode {auto,off}`	Enable or disable shared receptor preparation/canonicalization.
`--receptor-prepare-command TEMPLATE`	Override the receptor conversion command. Use `{input}`, `{output}`, and optionally `{seed}`.
`--force-receptor-prep`	Regenerate prepared receptor `.pdbqt` outputs even if sibling outputs already exist.

All flags are optional; defaults point to directories within docking/.

Deterministic Receptor Input Handling

Ultidock does not require receptors to use a fixed filename such as receptor.pdb or gpcr_beta.pdbqt. The pipeline scans MACRO_MOL_DIR by file extension and treats the discovered filename stem as the receptor identity used for generated receptor files, site folders, grid caches, and downstream result names.

The shared receptor-prep path lives in molguard.io.receptor_prep and is used by both regular pipeline runs and benchmark scripts:

*.pdbqt inputs are not reconverted. They are canonicalized through molguard so atom ordering, numbering, fixed-width numeric fields, and the resulting SHA-256 digest are deterministic.
*.pdb inputs are sanitized for receptor-conversion tools, converted to <input-stem>.pdbqt, then canonicalized through the same PDBQT path.
Multiple receptor files can live in MACRO_MOL_DIR; each receptor keeps its own discovered stem. If both raw and prepared forms exist for the same stem, the existing .pdbqt is preferred unless receptor prep is forced.
Drastic rescue actions, such as deleting residues after a Meeko excess-bond failure, print a loud warning because they change the receptor model and must be reported with benchmark or docking results.

This structure keeps the benchmark and production pipeline scientifically aligned: receptor preparation is not a special benchmark-only script, and a researcher can use normal receptor filenames without manually renaming files to match Ultidock internals.

Configuration Reference

Running python3 docking/run.py or python3 docking/setup.py writes a fully resolved configuration to docking/config.py. The file records the exact directories, binaries, and grid parameters that Ultidock will reuse on the next invocation. Edit the file directly (or pass CLI overrides) to fine-tune a run.

Directory Layout Variables

Variable	Meaning
`LIGANDS_DIR`	Absolute path where ligand archives and split PDBQT files are staged.
`DOCKING_DIR`	Output directory for AutoDock-GPU / Vina poses and logs.
`ANALYSIS_DIR`	Workspace for intermediate scoring, per-ligand summaries, and temporary exports.
`VINA_DIR`	Location of the AutoDock Vina binaries used for ligand splitting or CPU docking.
`AUTODOCK_GPU_DIR`	Location of the AutoDock-GPU and AutoGrid toolchains compiled during setup.
`MACRO_MOL_DIR`	Root folder for receptor structures, generated grids, and per-site artifacts.
`RESULTS_DIR`	Destination for final CSV/JSON exports and the SQLite results database.
`DB_PATH`	Full path to the SQLite database (`ultidock_results.db`) that receives live docking updates.

Runtime Controls

Variable	Description
`GPU_TYPE`	Which accelerator build to prepare (`CPU`, `CUDA`, or `OCL`). In CPU mode AutoGrid is built and bundled Vina binaries are used.
`NUMWI`	Number of AutoDock-GPU work items queued per ligand batch. Increase to better saturate large GPUs; reduce on memory-constrained devices.
`AUTO_GRID_BIN`	Resolved path to the `autogrid4` binary. Adjust if you provide a prebuilt AutoGrid installation.
`GRID_MODE`	Strategy for identifying grid centers: `ligand`, `residues`, `centers` (hotspot-driven default), or `blind` (whole-protein).
`SITE_POLICY`	Automatic site-family policy: `receptor_search`, `exhaustive_search`, `internal`, `surface`, or `hybrid`.
`GRID_SPACING`	Ångström spacing between grid points. Smaller values yield finer resolution at the cost of longer AutoGrid runtimes.
`GRID_MARGIN`	Extra Ångström padding applied to each hotspot-derived grid to ensure the box fully encloses the binding site.
`GRID_CAP`	Maximum Å-length per axis when running in blind mode to prevent runaway grid sizes.
`CENTERS_TSV`	Optional path to a precomputed `centers.tsv`. Leave as `None` to let Ultidock regenerate hotspot centers automatically.
`REF_LIGAND_PDB`	Reference ligand file used when `GRID_MODE="ligand"` to seed the search box from a co-crystal pose.
`RECEPTOR_PREP_MODE`	`auto` prepares/canonicalizes receptor inputs in `MACRO_MOL_DIR`; `off` leaves files untouched.
`RECEPTOR_PREP_COMMAND`	Optional receptor conversion command template for `.pdb`/`.mol2` inputs.
`RECEPTOR_PREP_SEED`	Seed forwarded to external receptor-conversion commands.
`RECEPTOR_PREP_FORCE`	Regenerate converted receptor outputs when `True`.

Grid Boxing & Cavity Finder Dials

These parameters feed the hotspot detection routine acknowledged in the Spotlight section.

Variable	Description
`HOTSPOT_NMS_MINSEP_A`	Minimum Å separation between detected hotspots when applying non-maximum suppression. The effective value is clamped relative to box size.
`R_MIN_CAVITY_A`	Minimum inscribed sphere radius (Å) required for a cavity to be considered viable. `None` enables adaptive receptor-specific estimation.
`ADAPTIVE_R_MIN_*`	Parameters controlling receptor-specific EDT threshold estimation and clamping.
`MAPS_POCKET_MAX_A`	Upper EDT shell bound used by map-driven surface pocket detection.
`HOTSPOT_NMS_BOX_FRACTION`, `HOTSPOT_NMS_MIN_A`, `HOTSPOT_NMS_MAX_A`	Bounds used to clamp inter-site separation from the requested docking-box side length.
`SURFACE_SHELL__MIN_A` / `SURFACE_SHELL__MAX_A`	Inner/outer Å bounds for the surface shell used to classify near-surface voxels.
`SURFACE_NMS_MINSEP_A`	Å separation floor when evaluating surface cavities. Larger values merge nearby openings.
`MAX_CENTER_DIST_A`	Å-distance threshold from the protein surface for accepting automatically detected centers.
`CONTACT_SHELL_A`	Thickness of the contact shell counted when evaluating pocket accessibility.
`HOTSPOT_BOX_ANGLE`	Minimum side length (Å) for the automatically generated search box, ensuring consistent grid volumes even for narrow cavities.
`MIN_SURFACE_FRAC`	Minimum fraction of grid voxels that must belong to the surface shell for a box to qualify as a surface pocket.
`AUTOSITES`	Target number of hotspots (grid boxes) to generate per receptor when running in automatic centers mode.

Tweak these parameters only when you need to bias the hotspot finder—for example, tightening MIN_SURFACE_FRAC to focus on buried cavities or lowering AUTOSITES to restrict the number of generated docking boxes.

Pipeline Segments & What Makes Ultidock Different

Ultidock is organized into four primary segments. Each segment has been engineered for reliability and reproducibility compared to ad-hoc docking scripts.

Setup (setup.py)
- Idempotently creates the full directory tree (LIGANDS, MACRO_MOL, DOCKING, RESULTS, etc.).
- Detects GPU availability and compiles AutoDock-GPU/AutoGrid with the correct compute capabilities.
- Runs shared receptor preparation through molguard: existing .pdbqt receptors are canonicalized, while raw .pdb receptors are sanitized, converted, and then canonicalized.
- Respects explicit CLI paths so scripted runs can reuse shared toolchains.
Ligand Preparation
- ligands.wget entries are executed with robust retry logic and optional HTTPS upgrades (HSTS aware) unless --skip-wget is specified, in which case pre-seeded ligand archives are used as-is.
- extract.py orchestrates AutoDock Vina's vina_split to extract, split, and stage ligands with deterministic filenames so downstream consumers can glob without guessing naming schemes.
Docking (dock_v02.py)
- Per-receptor grid caching eliminates redundant AutoGrid runs even when the pipeline is restarted.
- Site folders are named from the discovered receptor stem; site IDs such as S1 and S2 are output identifiers only, not quality labels.
- Semaphore-guarded worker pool maintains one AutoDock-GPU process per GPU while CPU preparation remains concurrent.
- Metadata (grid centers, hotspots, cavity statistics) is persisted for MD seeding and reproducibility.
I/O Hardening (molguard)
- Fixed-width float formatter (fixedfmt.py) ensures every number written to AutoGrid/AutoDock files respects the Fortran-style column widths those tools parse — no exponent notation, no missing decimals, no locale drift.
- PDBQT linter and normalizer catches column-format bugs before they reach AutoGrid, with fail-slow error collection and a regression test suite.
- Shared receptor preparation produces deterministic receptor PDBQT files and prints loud warnings for drastic rescue actions, such as deleting residues after a Meeko excess-bond failure.
- Grid map checker validates AutoGrid output immediately after each run: all-zero maps, NaN/Inf energies, and missing files are caught with actionable error messages pointing to the .glg log.
Analysis (analyse_docking_results.py)
- Optional stage that aggregates top poses, binding energies, and summary statistics. If pandas is unavailable the pipeline logs a warning and continues so production runs are never blocked by optional tooling.
- Results are parsed directly from the automatically maintained SQLite database so reruns can resume and analytics scripts can attach without bespoke exports.

Single-command automation: run.py orchestrates everything from toolchain compilation to final scoring, eliminating manual multi-step checklists.
Directory-first design: explicit, user-configurable directories keep receptors, ligands, grids, and results isolated and reproducible.
Deterministic I/O: the molguard layer guarantees that the same input always produces byte-identical PDBQT and grid files regardless of machine or locale, enabling reliable comparative studies.
Example-driven: the examples/ directory demonstrates full CPU and GPU runs, including workspace reset, staging, and pipeline invocation.
Resilient defaults: built-in fallbacks for missing optional dependencies (e.g., pandas, wget SSL issues) keep long batches running with informative warnings.
Database-native: every docking job streams its status into the SQLite results store, enabling instant post-processing without manual log parsing.
Future-ready: the branch maintains alignment with planned GROMACS integration by preserving metadata required for MD restarts and analysis.

Spotlight: Grid Boxing & Cavity Finder Algorithm

Ultidock's automatic site finder is formally named CaV-EMPS: Cavity detection via Electrostatic Map Pocket Scoring. Its goal is to approximate the binding-site center that a researcher might otherwise take from a co-crystal ligand, using only receptor-derived information. In practical screening work, that co-crystallized ligand and its centroid are often not available, so Ultidock does not require a known crystal center before docking.

The finder is implemented in docking/make_grids.py and orchestrated by docking/dock_v02.py. It analyzes receptor geometry and receptor-derived AutoGrid signals to propose a compact set of likely docking boxes. In benchmarks, the crystal ligand center is used only after site generation as an external recovery reference, not as an input to CaV-EMPS. CaV-EMPS ranking scores are used to order site hypotheses; they are not binding affinity estimates.

The default receptor_search policy combines complementary receptor-derived signals:

Internal geometry: receptor atoms are rasterized onto the AutoGrid lattice, and an Euclidean distance transform identifies enclosed cavities and channels.
Surface/map favorability: favorable AutoGrid interaction maps are clipped to physically useful negative values, smoothed over a ligand-sized region, and masked to receptor-proximal pocket shells. This avoids selecting a single favorable surface voxel as if it were a pocket center.
Hybrid portfolio assembly: internal, surface, and consensus candidates are de-duplicated by Å-scale non-maximum suppression and written as docking boxes.

Adaptive clamping is used in two places. First, the cavity radius threshold can be inferred from each receptor's own EDT peak distribution instead of forcing a single global value. Second, inter-site separation is clamped relative to the docking-box side length so the generated boxes are distinct but not needlessly sparse.

Site IDs (S1, S2, etc.) are only output identifiers. They are not scores, priorities, or quality labels. Downstream evaluation should use distance or docking metrics over all generated sites rather than interpreting S1 as the "best" site.

Benchmarking

Benchmark scripts live in benchmarks/. The repository tracks the scripts, but downloaded DUD-E datasets and generated benchmark outputs are ignored by Git and should remain local.

Download DUD-E Targets

Download receptor, crystal ligand, active, and decoy files for selected targets:

ultidock benchmark download-dude \
  --targets ace,bace1,braf,cdk2,cxcr4,drd3,egfr,esr1,gcr,hdac2,hivpr,pde5a,pparg,src,vgfr2 \
  --dataset-root benchmarks/datasets

Receptor Site-Recovery Benchmark

Evaluate whether the receptor-only site finder recovers the experimentally observed co-crystal pocket neighborhood:

ultidock benchmark cavity-recovery \
  --dataset-root benchmarks/datasets \
  --targets ace,bace1,braf,cdk2,cxcr4,drd3,egfr,esr1,gcr,hdac2,hivpr,pde5a,pparg,src,vgfr2 \
  --autosites 6 \
  --site-policy receptor_search \
  --jobs 4 \
  --force \
  --output-dir benchmarks/results/cavity_recovery

The benchmark records both the legacy distance from each generated site center to the centroid of the co-crystallized ligand and the paper-facing DCC distance to the closest ligand atom. The ligand geometry is an external reference for the experimentally observed bound pose; it is not used during site generation.

Important output files:

summary.csv: target-level closest-site, DCC, and Top-k success flags
sites.csv: per-site centroid distances, DCC distances, and ranking metadata
predictions.tsv: normalized cav-emps predictions for shared evaluators
per-target centers.tsv: the generated docking boxes used for evaluation

By default, benchmark runs use a compact artifact layout: large AutoGrid maps and scratch files are written to temporary work directories and removed after the small evaluation files are written. Add --keep-artifacts when debugging a target and you want to preserve per-target maps/ files; use --work-root to put scratch work on a larger disk.

COACH420/HOLO4K Site-Prediction Benchmark

Run the paper-facing site-prediction benchmark in one pass:

ultidock benchmark site-prediction \
  --datasets coach420,holo4k \
  --methods cav-emps,fpocket,p2rank \
  --jobs 4 \
  --output-dir benchmarks/results/site_prediction/coach_holo_$(date +%Y%m%d_%H%M)

The command downloads rdk/p2rank-datasets when needed, normalizes receptors and ligand labels, runs each selected method, evaluates DCC Top-n/Top-(n+2), and writes Markdown/HTML reports under the output directory.

The site-prediction benchmark follows the same compact default for CaV-EMPS AutoGrid maps. Pass --keep-artifacts only for debugging, or --work-root /path/to/scratch when temporary files should live on a larger drive.

Reports and Visualization

Ultidock run directories can be turned into researcher-facing artifacts:

ultidock report path/to/run_dir

The report generator writes report.md, report.html, cavity_centers.pdb, cavemps_sites.pml, site_boxes.pml, top_poses.pml, cavemps_sites.cxc, and cavity_centers.bild when site coordinates are available. These files are intended for quick inspection in PyMOL or ChimeraX and for recording the command, configuration, software version, and CaV-EMPS site ranking used for a run.

Docking/Enrichment Benchmarks

benchmarks/dude_docking_benchmark.py and benchmarks/run_full_dude_benchmark.py run full active/decoy docking arms and collect virtual-screening metrics such as ROC-AUC, EF1, EF5, BEDROC, and logAUC. These runs are much more expensive than the cavity-recovery benchmark and should be treated as final validation runs rather than quick smoke tests.

Working with the Example Pipelines

Start with the lightweight quickstart to verify the researcher-facing artifact flow:

ultidock example run quickstart

It writes input/receptor.pdb, input/reference_ligand.mol2, run_config.yaml, sites.tsv, predictions.tsv, top_hits.csv, results.sqlite, report.md, report.html, and PyMOL/ChimeraX helper files.

Two curated docking examples (gabaa-benzos and sert-escitalopram) showcase the fuller docking workflow. The separate gabaa-8dd2-cav-emps example runs a preregistered blind site-recovery case study against five withheld GABA/zolpidem sites, including the controlled CaV-EMPS ablations and fpocket/P2Rank comparison. Each full example runner follows a documented researcher workflow:

ultidock example list
ultidock example run sert-escitalopram
ultidock example run sert-escitalopram p2rank
ultidock example run sert-escitalopram fpocket
ultidock example run sert-escitalopram p2rank --mode cpu  # no GPU runtime
ultidock example run gabaa-8dd2-cav-emps --dry-run

The SERT example uses CaV-EMPS by default. Pass p2rank or fpocket after the example name to select that pocket finder. The chosen method generates fresh sites from the staged SERT receptor before docking.

Each full docking example prints its own directory under examples/<name>/workspace/<timestamp>/. Inputs, grids, and results for that run stay there; installed AutoDock and Vina binaries are reused. The example passes --skip-wget, so it docks only its bundled ligands. A new run gets a new workspace, and completed workspaces remain available for inspection.

P2Rank 2.5 requires Java 17–23. Java 25 can fail with Unsupported class file major version 69 while loading P2Rank's Groovy configuration. On Ubuntu, install a compatible runtime with sudo apt install openjdk-21-jre-headless. The bundled external/bin/prank launcher uses /usr/lib/jvm/java-21-openjdk-amd64 automatically when JAVA_HOME is unset. If JAVA_HOME points to an incompatible Java version, set it to the Java 21 directory before running ultidock ... p2rank.

What the helper (examples/common.py) does:

Creates a new example workspace without removing previous runs.
Copies that example's receptor and ligands into the new workspace.
Predicts sites with the selected method, when p2rank or fpocket is given.
Runs the full pipeline with explicit input/output paths and no ligand download.

P2Rank or fpocket can propose several sites. AutoGrid then builds maps for each site sequentially; [autogrid] prepared N site grids means that stage finished. Docking work grows with the number of ligands times the number of sites.

Use these scripts as blueprints for your own automation or CI workflows.

Troubleshooting

ultidock: command not found or make install has no target
- From the repository root, run python3 -m venv .venv, source .venv/bin/activate, then python -m pip install -e .. Activate .venv in each new shell. The repository root has no Makefile; the ultidock command is installed by pip. The system-Python alternative is in Python Environment.
P2Rank reports Unsupported class file major version 69
- The pinned P2Rank 2.5 supports Java 17–23. Install openjdk-21-jre-headless on Ubuntu and unset an incompatible JAVA_HOME, or set JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64.
fpocket stops compiling at src/fparams.c with strcpy pointer errors
- Use bash scripts/install_pocket_tools.sh fpocket from this checkout. The installer corrects the fpocket 4.2.3 source before compiling it. If you built an older checkout, update it and rerun that command.
An example discovers more ligands than it bundled
- Run the updated example command so it creates a new isolated workspace. For a manual run, inspect docking/LIGANDS_DIR/: every *.pdbqt there is selected for docking. Use a dedicated --LIGANDS_DIR for each batch.
AutoGrid prints S1, S2, ... and seems to pause
- It builds a separate map set for each predicted site, one at a time. Check the current site's grid.glg in the printed directory. Docking begins after [autogrid] prepared N site grids.
Build fails with CL/opencl.h: No such file or directory
- Install ocl-icd-opencl-dev on Debian/Ubuntu, then rerun setup. This provides the headers and linker library; installing only the OpenCL runtime is insufficient. For custom SDKs, check GPU_INCLUDE_PATH and GPU_LIBRARY_PATH.
GPU not detected, or clinfo reports zero platforms
- Follow GPU Runtimes to install and verify the system driver and compute runtime. Check from the same terminal or container that runs Ultidock; activating a Python virtual environment does not supply a GPU runtime.
SSL errors while downloading ligands
- Corporate firewalls or strict TLS inspection can block files.docking.org. Download the required archives manually and place them in docking/LIGANDS_DIR/ before running the pipeline.
AutoDock-GPU compilation failures
- For CUDA, check nvcc --version, the driver, and gcc-12/g++-12. For OpenCL, check clinfo -l, ocl-icd-opencl-dev, and the vendor runtime. Run ultidock doctor and retry setup after fixing the missing dependency.
ultidock doctor shows [WARN] not compiled for AutoGrid or AutoDock-GPU
- The source tree is present but the binaries have not been built yet. Run ultidock setup --mode gpu --skip-wget (or --mode cpu without a GPU) to compile them. After a successful build, doctor will report [OK] with the resolved binary path.
molguard pdbqt check reports NO_DECIMAL or EXPONENT errors
- These indicate the PDBQT file was written by a tool that does not respect AutoDock column widths (e.g., some OpenBabel versions or AMBER converters). Run molguard pdbqt normalize <file> -o <fixed.pdbqt> to reformat the numeric columns before docking.
Optional analysis skipped
- If you see ModuleNotFoundError: pandas, install it with pip install pandas and re-run the analysis stage: python3 docking/analyse_docking_results.py.
Out-of-disk-space errors
- Ligand archives can be large. Clean up with python3 docking/clean.py -y or remove unused files from docking/LIGANDS_DIR/ and docking/DOCKING_DIR/.

Citation & License

If you use Ultidock in research, use the version-specific Zenodo DOI when available. The release author, title, version, and repository metadata are in CITATION.cff.

Ultidock is released under the MIT License. When applicable, please also cite:

Trott, O., & Olson, A. J. (2010). AutoDock Vina: Improving the speed and accuracy of docking with a new scoring function, efficient optimization, and multithreading. Journal of Computational Chemistry, 31(2), 455–461.
Santos-Martins, D., et al. (2021). Accelerating AutoDock4 with GPUs and Gradient-Based Local Search. Journal of Chemical Theory and Computation, 17(2), 1060-1073.

If you find Ultidock useful, please star the repository and consider sharing your improvements via pull requests.

Navigation Menu

Repository files navigation

Ultidock

Table of Contents

Requirements

Hardware

Operating System

System Packages

GPU Runtimes

Python Environment

Repository Layout

Quick Start: End-to-End Run

Command Reference

Researcher-Facing Run Modes

Key `run.py` Flags

Deterministic Receptor Input Handling

Configuration Reference

Directory Layout Variables

Runtime Controls

Grid Boxing & Cavity Finder Dials

Pipeline Segments & What Makes Ultidock Different

Spotlight: Grid Boxing & Cavity Finder Algorithm

Benchmarking

Download DUD-E Targets

Receptor Site-Recovery Benchmark

COACH420/HOLO4K Site-Prediction Benchmark

Reports and Visualization

Docking/Enrichment Benchmarks

Working with the Example Pipelines

Troubleshooting

Citation & License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
benchmarks		benchmarks
cli		cli
data-analyses		data-analyses
docking		docking
docs		docs
examples		examples
molguard		molguard
scripts		scripts
ultidock		ultidock
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
test_dude_benchmark_helpers.py		test_dude_benchmark_helpers.py
traffic-badge.json		traffic-badge.json

Latest commit

History

Folders and files

Repository files navigation

Ultidock

Table of Contents

Requirements

Hardware

Operating System

System Packages

GPU Runtimes

Python Environment

Repository Layout

Quick Start: End-to-End Run

Command Reference

Researcher-Facing Run Modes

Key run.py Flags

Deterministic Receptor Input Handling

Configuration Reference

Directory Layout Variables

Runtime Controls

Grid Boxing & Cavity Finder Dials

Pipeline Segments & What Makes Ultidock Different

Spotlight: Grid Boxing & Cavity Finder Algorithm

Benchmarking

Download DUD-E Targets

Receptor Site-Recovery Benchmark

COACH420/HOLO4K Site-Prediction Benchmark

Reports and Visualization

Docking/Enrichment Benchmarks

Working with the Example Pipelines

Troubleshooting

Citation & License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Key `run.py` Flags