AutoDock Vina Docking

What this workflow does

This workflow takes a receptor in PDB format and a ligand library. The library is a SMILES file or a 3D SDF file. The workflow prepares every input into the PDBQT format that AutoDock Vina needs. It then docks each ligand into a defined search box. It returns ranked binding energy tables in CSV format.

The Vina scoring function is empirical. It is fast enough to screen a library on a CPU. This makes AutoDock Vina a cheap first pass. You run it before an expensive free-energy method or an ML affinity model.

The prep stage uses OpenBabel for the receptor and Meeko for the ligands. OpenBabel adds hydrogens at pH 7.4. It also processes truncated crystal structures correctly. Meeko assigns the correct small-molecule atom types and torsions. RDKit embeds each SMILES to 3D first with ETKDG and MMFF.

The compute problem

A docking screen has three stages with different hardware needs.

The prep stage reads the receptor and the ligand file. It writes the PDBQT set and the box definition. This stage needs one CPU and a few seconds.

The dock stage runs AutoDock Vina once per ligand. This stage is the expensive one. It scales with the library size, the exhaustiveness value, and the number of poses. A large library needs many CPU cores.

The summary stage parses the affinities from the pose files. It writes two CSV tables. This stage needs one CPU and a few seconds.

Most tools force all three stages onto one machine. You then hold a large CPU node while the two light stages run. You also copy the archives between machines by hand. Each copy is a chance to lose a file or to run a stage on stale input.

The dependency set is a second problem. The vina package on PyPI has no macOS arm64 wheel. It builds from source and needs Boost. The conda-forge build ships Python bindings for osx-arm64, osx-64, linux-64, and linux-aarch64.

How Horus solves it

Horus assigns an executor to each stage. The prep and summary stages run on your local CPU. The dock stage runs where you want it. You point it at a bigger CPU box, an HPC scheduler, or the same laptop.

Horus builds the per-stage environment from conda-forge. The prep environment holds Meeko, OpenBabel, and RDKit. The dock environment holds AutoDock Vina. The two environments stay separate, so a version conflict cannot happen.

To move the dock stage to another machine, change the executor: field. The runtime.command string does not change. This is the portability rule across all Horus workflows. The same YAML file runs on a laptop and on a cluster.

Horus moves the data across each boundary for you. It sends the input archive to the dock host and brings the pose archive back. You write no copy commands.

The alternative costs you time and money. You either pin the whole screen to one node and pay for idle cores, or you maintain a second script per host. Both options break when the host changes.

A ligand that fails to dock is logged and skipped. Horus records it in the archive manifest.json. One bad structure never sinks the screen.

Pipeline

prep (local, CPU)        receptor.pdb + ligands.smi ──► vina_inputs.tar.gz
   │  OpenBabel → receptor.pdbqt, Meeko → ligands/*.pdbqt, box.json
dock (CPU, Vina)         AutoDock Vina per ligand   ──► docking_out.tar.gz
   │  best poses + REMARK VINA RESULT affinities
summary (local, CPU)     parse affinities           ──► summary.csv + poses.csv

Inputs and outputs

Inputs

• receptor.pdb: the target protein. The workflow adds hydrogens at pH 7.4. The bundled example is chain A of 1IEP, the Abl kinase.
• ligands.smi: one SMILES [name] per line. The name field becomes the table identifier. You can point --ligands at a 3D .sdf file instead. The workflow detects the type from the extension.

Outputs land in results/:

• vina_inputs.tar.gz: the prepared PDBQT set and the box definition.
• docking_out.tar.gz: the raw pose files.
• summary.csv: one row per ligand, ranked best first: rank, ligand best_affinity_kcal_mol, mean_affinity_kcal_mol, num_poses.
• poses.csv: one row per pose: ligand, pose, affinity_kcal_mol, rmsd_lb rmsd_ub.

A lower affinity value means stronger predicted binding.

Run the workflow

The prep and dock stages build conda environments from conda-forge. A conda family tool must be on your PATH. The workflow.yaml file defaults to conda. Set it to mamba or micromamba in the prep and dock executors if that is what you have.

Install the horus-runtime and the plugins one time:

uv sync

If you do not have uv, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

You can also install the packages with pip:

pip install horus-runtime horus-environments

Then run the workflow:

horus run workflow.yaml

To set the search box, edit the args: of the prep stage. Set --center X Y Z and --size X Y Z in ångström. The example uses the 1IEP ATP pocket at 15.190 53.903 16.917. You can pass --ref-ligand <file> to center the box on a bound reference ligand. You can omit --center for blind docking over the whole receptor. Use a large --size in that case.

To set the search effort, edit the args: of the dock stage. The --exhaustiveness value defaults to 16. A higher value is more thorough and slower. The --n-poses value defaults to 9. The --cpu value defaults to 0, which means autodetect.

References

• AutoDock Vina on GitHub
• AutoDock Vina documentation
• AutoDock Vina 1.2.0 paper
• Meeko
• OpenBabel