Ultidock v1.1.0 — First GPU-Enabled Release

This is the first release of Ultidock with full GPU acceleration via AutoDock-GPU (CUDA and OpenCL). It represents a major milestone toward high-throughput molecular docking, enabling sub-second runtimes per ligand on modern GPUs. If your CPU is limited (e.g. ≤8 cores on Ryzen 2000 series or Intel 10th gen), using GPU-Mode, even opencl, could be a good idea but if you have an okay CPU and not many GPUs, I would strongly recommend the using CPU mode.

---

Highlights

• CUDA & OpenCL support: GPU acceleration works with either backend, covering a wide range of NVIDIA and AMD hardware.
• Automatic GPU/CPU detection: setup.py identifies your platform and writes configuration into config.py seamlessly.
• Extreme throughput: On modern GPUs (tested on RTX 5070), typical docking runs complete in well under a second per ligand. In many cases I observed runtimes close to 0.5 seconds or even lower, depending on ligand size and setup.
• Multithreaded docking runner: ProcessFileThread dynamically assigns ligands to available GPUs/CPUs, parses results, and manages memory efficiently.
• Database buffering: results are batched in memory and flushed to SQLite, reducing I/O contention during parallel workloads.

Performance Notes

• Single-GPU runs are extremely efficient: the GPU finishes ligands so quickly that the main bottleneck can be CPU thread scheduling and I/O.
• Multi-GPU setups:
  • Each GPU requires only a single CPU thread to stay saturated.
  • If you have a modern CPU with many cores, scaling across GPUs is excellent.
  • If your CPU is limited (e.g. ≤8 cores on Ryzen 2000 series or Intel 10th gen), scheduling overhead may reduce efficiency.
• These CPU–GPU balance effects are based on current testing and estimation; deeper benchmarks are planned for the next releases.

Fixes & Stability

• Consistent fld/gpf generation across ligands, reducing mismatches in GPU mode.
• All paths unified under config.py, removing brittle hardcoded paths.
• Reduced crashes from missing gridfld entries during parallel jobs.

Compatibility

• Tested on NVIDIA GPUs with CUDA 12.8 and propierty driver version 580.76.05 and AMD/NVIDIA with OpenCL.
• CPU fallback path tested on Linux x86_64.
• Requires Python 3.10+

Upgrade Notes

1. Ensure you have a working CUDA or OpenCL runtime installed for your GPU vendor.
2. Run setup.py to regenerate config.py, which now includes GPU_TYPE and AUTODOCK_GPU_DIR.
3. Review the README for evolving GPU setup notes (to be expanded in v1.1.1).

Known Limitations

• Multi-GPU support is functional, but not yet fully tuned for CPU scheduling efficiency.
• Documentation for GPU setup (especially OpenCL on AMD) is still minimal.
• Some torsional edge cases may still require manual fld regeneration.

What’s Next

• Deeper multi-GPU profiling and CPU/GPU balance optimization.
• GROMACS integration for free energy estimation (MM/PBSA, umbrella sampling).
• Expanded unit tests for SQLite parser and docking consistency.
• Improved documentation for CUDA/OpenCL installation and troubleshooting.
• Fixing xml parser, I was just lazy about it.

Acknowledgements

The CCSB / AutoDock-GPU team have done an excellent job creating a highly optimized and well-engineered GPU docking engine. Their work makes it possible to reach sub-second docking per ligand on modern GPUs, and Ultidock builds on this foundation to push toward highly optimized high-throughput docking pipelines.

Quick Install (Ubuntu/Debian)

Installs build tools, OpenCL (vendor-neutral), and NVIDIA support. Safe to run line by line.

# 0) Refresh package index
sudo apt update

# 1) Build essentials & tooling
sudo apt -y install \
  build-essential gcc g++ make cmake \
  git pkg-config python3 python3-venv python3-dev

# 2) OpenCL (vendor-neutral) + CPU fallback
# - opencl-headers: headers for building OpenCL apps
# - ocl-icd-libopencl1: ICD loader (libOpenCL.so)
# - ocl-icd-opencl-dev: dev files for linking
# - clinfo: tool to list OpenCL platforms/devices
# - pocl-opencl-icd: CPU runtime (useful for testing/fallback)
sudo apt -y install \
  opencl-headers ocl-icd-libopencl1 ocl-icd-opencl-dev \
  clinfo pocl-opencl-icd

# 3) NVIDIA driver (recommended by Ubuntu)
sudo apt -y install ubuntu-drivers-common
sudo ubuntu-drivers autoinstall

# 4) Verify installs
clinfo | head -n 40       # OpenCL devices
nvidia-smi || true        # NVIDIA driver check

CUDA Toolkit

For CUDA support, please follow NVIDIA’s official installation guide: CUDA Installation Guide for Linux (NVIDIA Docs)

Notes

• AMD/Intel GPU users should keep the vendor-neutral OpenCL stack above, but for peak performance install the vendor’s OpenCL runtime (ROCm for AMD, oneAPI for Intel).
• After installing or updating GPU drivers, a reboot is often required: sudo reboot.
• CUDA is optional — Ultidock can run via OpenCL as well.

If you run into problems, please open an issue with your config.py (scrub sensitive paths) and the command you executed. This release is a milestone — expect rapid refinements in the 1.1.x line.

Ultidock v1.0.1 (CPU-only Maintenance Release)

This release keeps the CPU-only pipeline (no GPU dependency) and focuses on safer setup, cleaner config handling, and a few quality-of-life fixes. Functionally it is equivalent to v1.0.0 for docking, but with tidier structure and fewer footguns.

---

Highlights

• Safer config import order: main loader now runs setup.py first (which writes config.py), then imports config via importlib. This avoids missing/half-written config issues.
• Single place to list scripts: scripts are gathered in one array and executed in order, improving readability and reducing path mistakes.
• Path handling via config.BASE_DIR: joins now reference config.BASE_DIR consistently to prevent relative-path surprises.
• Better setup prompts: clearer questions for docking, analysis, Vina, macro molecule, results, and (future-proofed) GPU-related directories.
• Automatic directory creation: create_directory_if_needed(...) is called for each configured path to prevent “path not found” errors on first run.
• Config writes are explicit: all selected paths are persisted to config.py in a consistent block, keeping the environment reproducible.
• Wget options hook: download helper now includes a dedicated wget_options slot (timeouts/retries, etc.) for more robust fetching.

Fixes & Robustness

• Eliminated brittle direct import of BASE_DIR from config before config existed.
• Reduced chances of executing scripts with stale paths by centralizing the join logic on config.BASE_DIR.
• Smoother first-run experience: fewer manual mkdir steps; fewer cryptic tracebacks.

Compatibility

• CPU-only: no GPU dependency required.
• CLI and data formats remain unchanged from v1.0.0 for docking runs.

Upgrade Notes

1. Fresh setup recommended: run setup.py once to regenerate config.py with the new fields.
2. Review your configured paths in config.py (especially DOCKING_DIR, ANALYSIS_DIR, VINA_DIR, MACRO_MOL_DIR, RESULTS_DIR).
3. If you have custom download flags, set/adjust wget_options in the helper.

Known Limitations

• This line intentionally omits GPU acceleration; for CUDA-enabled builds, see the v1.1.x releases.

What’s Next

• Continue polishing docs and examples for the CPU pipeline.
• GPU line (v1.1.x) evolves separately with AutoDock-GPU and upcoming GROMACS hooks.

---

If something breaks, please open an issue with your config.py (sanitize sensitive paths) and the full command you ran.

v1.0.0

Release: v1.0.0 – Stable SQLite-Backed Multithreaded Screening

This release marks the first stable and performant version of Ultidock, a fully automated molecular docking pipeline optimized for high-throughput virtual screening. It integrates AutoDock Vina with efficient, real-time SQLite data handling and parallel computation.

Key Features

• Fully integrated pipeline (setup, docking, parsing, analysis) in run.py
• Parallel docking using Python multithreading for maximum CPU utilization
• All results written directly to an SQLite database (ultidock_results.db)
• Robust and configurable filtering with SQL-powered querying
• Analysis script outputs results to .csv by default, with optional .xlsx support
• Configurable behavior and paths via a single config.py file
• Portable directory structure for reproducible runs on different systems

Test Summary

• Tested using 16-thread CPU with --cpu 2 per ligand (8 parallel ligands)
• Completed 52 ligand screenings in approximately 30–40 seconds in multiple runs
• No permission errors or manual intervention required
• Stable output, verified insertion into the SQLite database, and consistent parsing

Installation & Use

1. Clone the repository:

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

2. Run the pipeline:

   python3 docking/run.py

Exporting Results

The results will be in the docking/RESULTS/date-docking.csv file. If the file is empty, either the analysis parameters are irrelevant for your molecule or the docking attempt was unsuccessful. You should screen a wide range of ligands to account for your molecule's chemistry.

Optional (Excel):

python3 docking/analyse_docking_results.py --out results.xlsx

Version Information

• Branch: dev-beta
• Tag: v1.0.0-beta
• Status: Stable for small-to-large batch virtual screening workflows