AutoVina

English | 中文说明

AutoVina is a Windows-oriented research workflow that automates global receptor-ligand blind docking with AutoDock Vina. It connects input preparation, adaptive search-box generation, batch docking, score ranking, pose extraction, complex construction, and contact-residue comparison through one interactive entry point.

AutoVina is a research prototype, not a validated clinical, diagnostic, or production system. Docking predictions require domain-specific validation.

Workflow

1. Select receptor and ligand files through a file dialog.
2. Convert CIF to PDB and SDF to MOL2 when needed.
3. Clean the receptor and optionally keep selected chains.
4. Prepare receptor and ligand PDBQT files with MGLTools.
5. Estimate an adaptive ligand-sized box or accept manual box dimensions.
6. Sample centers across the receptor bounds and generate Vina configs.
7. Run AutoDock Vina jobs and rank each window by its mode-1 affinity.
8. Extract top-ranked first poses and construct receptor-ligand complexes.
9. Compare contact residues across the selected docking outputs.

Repository layout

AutoVina/
├─ main_autovina.py            # Interactive workflow entry point
├─ scripts/
│  ├─ preprocess/              # Conversion, cleaning and PDBQT preparation
│  ├─ box_config/              # Box estimation and blind-docking configs
│  ├─ docking/                 # Sequential Vina batch runner
│  └─ analysis/                # Score, pose, complex and contact analysis
├─ src/autovina/               # Reusable parsing and analysis utilities
├─ readme_require/             # Detailed Chinese user/developer notes
├─ data/                       # Local run outputs (ignored by Git)
└─ tools/                      # User-provided third-party tools (ignored by Git)

Requirements

• Windows 10 or 11
• Python 3.10 or 3.11 recommended
• AutoDock Vina
• MGLTools / AutoDockTools
• Open Babel
• openpyxl for XLSX output

Third-party binaries are intentionally excluded from this repository. See THIRD_PARTY_NOTICES.md before downloading or redistributing them.

Installation

git clone https://github.com/545liang/AutoVina.git
cd AutoVina
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Place the external tools in the following layout:

tools/
├─ vina/vina.exe
└─ mgltools/
   ├─ python.exe
   ├─ OpenBabel-2.4.1/obabel.exe
   └─ Lib/site-packages/AutoDockTools/Utilities24/
      ├─ prepare_receptor4.py
      └─ prepare_ligand4.py

The workflow was developed against AutoDock Vina 1.1.2, Open Babel 2.4.1, and an MGLTools Python 2.7.11 runtime. Other versions may require code or layout changes.

Usage

Run from the repository root:

python main_autovina.py

or double-click AutoVina.bat after Python and the external tools have been configured.

The program prompts for receptor and ligand files, optional custom parameters, and final confirmation before creating an isolated directory under data/.

Input notes

• Receptor PDB and CIF inputs are the end-to-end path currently intended for complex export.
• The preprocessing layer accepts MOL2, PDBQ, PDBQS, and PDBQT receptors, but later complex construction still requires an available receptor PDB.
• Ligand inputs may be MOL2, PDB, PDBQ, or SDF.

Main outputs

data/run_<receptor>_<ligand>/
├─ receptor/
├─ ligand/
├─ config/
├─ logs/
├─ outputs/
└─ summary/
   ├─ blind_docking_summary.csv
   ├─ top_<N>_models/
   └─ contact_comparison/

In the current implementation, top N means the N best grid-window outputs ranked by each window's mode-1 score. It is not a global ranking of every pose from every window.

Documentation and screenshots

• Chinese user guide / 中文用户说明
• Chinese developer guide / 中文开发说明
• Environment notes / 环境说明
• Screenshot assets are reserved under docs/images/.

Known limitations

• No automated test suite is included yet; current verification is based on static checks and small manual workflow runs.
• The project currently targets Windows and fixed external-tool directory conventions.
• Non-PDB/CIF receptor inputs are not guaranteed through complex export.
• Vina jobs run sequentially, although Vina may use its own internal threads.
• Generated configs contain absolute paths and are not portable after creation.
• Several scientific and packaging hardening tasks are tracked as GitHub issues.

Citation

If you use AutoVina in academic work, cite the underlying tools as appropriate:

1. Trott, O.; Olson, A. J. J. Comput. Chem. 2010, 31, 455-461. https://doi.org/10.1002/jcc.21334
2. Morris, G. M. et al. J. Comput. Chem. 2009, 30, 2785-2791. https://doi.org/10.1002/jcc.21256
3. O'Boyle, N. M. et al. J. Cheminform. 2011, 3, 33. https://doi.org/10.1186/1758-2946-3-33

License

AutoVina source code is available under the MIT License. Third-party software remains subject to its own license.

---

中文说明

AutoVina 是一个面向 Windows 的 blind docking（盲对接）科研工作流原型。它以 main_autovina.py 为统一入口，将受体/配体预处理、搜索框生成、Vina 批量对接、 分数汇总、最优构象提取、复合物构建和接触残基比较串联起来。

本项目用于科研与方法学探索，不是经过临床、诊断或生产环境验证的软件。对接结果 必须结合实验和专业知识进行验证。

主要功能

• CIF 受体自动转换为 PDB，SDF 配体自动转换为 MOL2。
• 清理非标准受体成分，并支持指定保留链。
• 根据配体尺寸生成自适应 box，或手动设置 box 尺寸。
• 在受体坐标范围内生成多个搜索中心并批量运行 Vina。
• 汇总各窗口 mode 1 分数，提取排名前 N 的第一构象。
• 输出复合物 PDB、单模型接触残基和多模型共性/差异比较表。

安装与运行

源码仓库不包含 tools/ 中的第三方程序。请按照上方目录结构自行取得并放置 AutoDock Vina、MGLTools 和 Open Babel，同时遵守各自许可证。然后运行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python main_autovina.py

详细参数、输出说明和开发结构请参阅：

• 用户说明
• 开发者说明
• 运行环境说明

当前限制

• 尚未建立自动化测试体系。
• 当前完整工作流主要面向 PDB/CIF 受体；其他受体格式在复合物导出阶段仍可能失败。
• top N 表示按每个网格窗口 mode 1 分数选出的前 N 个窗口，不是所有 pose 的全局排名。
• Vina 任务目前由批处理脚本串行调度。
• 本项目自有源码采用 MIT 许可证，第三方程序不包含在仓库和源码 Release 中。