Usage Guide¶

There are two major stages which can run separately or simultaneously: ligand preparation and their docking.

Database Initialization / Ligand Preparation¶

EasyDock uses an SQLite database to store all inputs, parameters, and results. Once initialized, the database preserves all settings for reproducibility.

Basic Initialization¶

Create a database with molecule validation:

easydock -i input.smi -o output.db -c 4

Parameters:
- -i: Input SMILES file
- -o: Output database file
- -c: Number of CPU cores

This performs:
- Salt removal
- Generation of one stereoisomer if there are some undefined chiral centers or double bonds (reproducible generation)
- Conversion to 3D structures (or uses existing coordinates if 3D SDF input)

Stereoisomer Enumeration¶

Enumerate up to 4 stereoisomers for undefined chiral centers and double bonds:

easydock -i input.smi -o output.db -c 4 -s 4

Maximum runtime of stereoisomer enumeration is limited to 300 seconds per molecule. This avoids excessively long generation for some structures. In those cases it is recommended to enumerate stereoisomers before supplying these molecules to EasyDock.

Protonation Options¶

Using MolGpKa:

easydock -i input.smi -o output.db -c 4 --protonation molgpka

Using MolGpKa with post-processing SMARTS fixes (corrects common mis-protonations):

easydock -i input.smi -o output.db -c 4 --protonation molgpka_fix

Using pre-built Uni-pKa container:

easydock -i input.smi -o output.db -c 4 --protonation /path/to/unipka.sif

Using Chemaxon (requires license):

easydock -i input.smi -o output.db -c 4 --protonation chemaxon

Custom pH

easydock -i input.smi -o output.db -c 4 --protonation molgpka --pH 12

No protonation (use input states):

easydock -i input.smi -o output.db -c 4

Molecular Docking¶

Vina Docking¶

Complete pipeline (initialization + docking):

easydock -i input.smi -o output.db --program vina --config config.yml -c 4 --sdf

Using pre-initialized database:

easydock -o output.db --program vina --config config.yml -c 4 --sdf

Vina Configuration (config.yml):

protein: /path/to/protein.pdbqt
protein_setup: /path/to/grid.txt
exhaustiveness: 8
seed: 0
n_poses: 5
ncpu: 5

Grid Box Definition (grid.txt):

center_x = 10.0
center_y = 15.0
center_z = 20.0
size_x = 25.0
size_y = 25.0
size_z = 25.0

Gnina Docking¶

easydock -i input.smi -o output.db --program gnina --config config.yml -c 4 --sdf

Gnina Configuration:

script_file: /path/to/gnina
protein: /path/to/protein.pdbqt
protein_setup: /path/to/grid.txt
exhaustiveness: 8
scoring: default
cnn_scoring: rescore
cnn: dense_ensemble
n_poses: 10
addH: False
ncpu: 1
seed: 0

Smina Docking¶

Use Gnina program with Smina-specific configuration:

script_file: /path/to/gnina
protein: /path/to/protein.pdbqt
protein_setup: /path/to/grid.txt
exhaustiveness: 8
scoring: vinardo
cnn_scoring: None
cnn: dense_ensemble
n_poses: 10
addH: False
ncpu: 1
seed: 0

Vina-GPU Family¶

For Vina-GPU, QVina2-GPU, or QVinaW-GPU:

easydock -i input.smi -o output.db --program vina-gpu --config config.yml --sdf

Configuration:

script_file: /path/to/AutoDock-Vina-GPU-2-1 --opencl_binary_path /path/to/opencl/
protein: /path/to/protein.pdbqt
protein_setup: /path/to/grid.txt
n_poses: 3
thread: 8000  # Optional, default is 8000

QVina2 / QVina-W¶

easydock -i input.smi -o output.db --program qvina --config config.yml --sdf

Configuration:

script_file: /path/to/qvina2  # or /path/to/qvinaw
protein: /path/to/protein.pdbqt
protein_setup: /path/to/grid.txt
exhaustiveness: 8
n_poses: 3
ncpu: 2
seed: 0

Server-Based Docking¶

--program server enables docking through a long-running server process. The server is started once per worker and handles multiple molecules without restarting. This mode supports containerized docking programs such as CarsiDock and GPU-accelerated Vina variants.

easydock -i input.smi -o output.db --program server --config config.yml -c 4 --sdf

The config file has three kinds of keys:

• Control keys (script_file, score_mode, startup_timeout, etc.) — read by EasyDock itself and placed at the top level.
• init_server: — parameters forwarded verbatim to the server's init command (receptor files, pocket definition, program-specific settings).
• info_server: — optional overrides for the server's default INFO values such as batch_size. The server exposes these defaults via its info command; this section lets you change them without modifying the server.

The ligand input/output formats (ligand_in_format, ligand_out_format) are auto-detected from the server's info command and do not need to be set manually.

CarsiDock¶

CarsiDock is a deep-learning docking program. It accepts SMILES input and uses RTMScore for pose ranking (higher score = better). A pre-built Apptainer container is available (see Installation).

script_file: /path/to/carsidock.sif
score_mode: max   # RTMScore: higher score is better

init_server:
  protein: /path/to/protein.pdb
  reflig: /path/to/reference_ligand.sdf
  num_conformer: 5

• protein: protein PDB file (defines the binding site)
• reflig: reference ligand that defines the binding pocket
• num_conformer: number of conformers to generate per ligand (default: 5)

To limit the number of molecules docked per server request (e.g. for memory reasons), override batch_size via info_server:

script_file: /path/to/carsidock.sif
score_mode: max

init_server:
  protein: /path/to/protein.pdb
  reflig: /path/to/reference_ligand.sdf
  num_conformer: 5

info_server:
  batch_size: 5

SurfDock¶

SurfDock is a surface-aware deep-learning docking program. It accepts SMILES input and ranks poses by screen confidence (higher score = better). A pre-built Apptainer container is available (see Installation).

script_file: /path/to/surfdock.sif

init_server:
  protein: /path/to/protein.pdb
  reflig: /path/to/reference_ligand.sdf
  num_save_poses: 10        # number of poses to save per ligand (default: 10)
  device: gpu               # gpu or cpu (default: gpu)
  tmpdir: /path/to/tmp/dir  # (optional), where to store temporary files
  keep_tmpdir: true         # (default: false), whether to keep temp file (useful for debug)

Vina-GPU Server¶

The Vina-GPU server bundles GPU and CPU Vina variants in a single container. It accepts PDBQT input and output and uses Vina scoring (lower = better).

script_file: /path/to/vinagpu.sif

init_server:
  protein: /path/to/protein.pdbqt
  protein_setup: /path/to/grid.txt
  program: vina-gpu
  n_poses: 9
  thread: 8000
  seed: 0

Generic Docking¶

--program generic runs any external docking binary or Python script driven purely by a YAML config — no code changes required. Useful for docking programs that EasyDock does not ship a dedicated module for.

easydock -i input.smi -o output.db --program generic --config config.yml -c 4 --sdf

See Generic Docking for the full config format and I/O conventions.

Resuming Interrupted Calculations¶

Simply run the same command or provide just the database:

easydock -o output.db

EasyDock will continue from where it stopped, using settings stored in the database.

Output Options¶

Generate SDF File¶

Add --sdf flag to create an SDF file with top poses after docking will be finished:

easydock -o output.db --program vina --config config.yml -c 4 --sdf

This creates output.sdf with the best scoring pose for each molecule.