Command line reference

You can run every step from the command line with pocketvina. python -m pocketvina runs the same commands. Every command has --help.

Exit codes

Code	Meaning
0	everything docked
1	usage or configuration error
2	some proteins or engine calls failed. Run the same command again to retry them
3	nothing docked

Settings in a file

You can keep the settings of pocketvina dock in a TOML file. The keys are the option names in snake_case:

# run.toml
proteins = "example/proteins"
ligands = "example/ligands.txt"
out = "results"
top_pockets = 2
box = [20, 20, 20]
seed = 42

pocketvina dock --config run.toml

Options given on the command line override the file. Relative paths are relative to the folder of the file.

Commands

pocketvina

PocketVina: GPU docking into the pockets P2Rank predicts, and the results it writes.

Exit codes: 0 ok, 1 usage or configuration error, 2 partial failure (some proteins or engine calls failed), 3 nothing docked.

Usage

pocketvina [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

-v, --verbose

Debug messages, and tracebacks of errors.

-q, --quiet

Only warnings and errors in the log.

bench

Benchmarks.

Usage

pocketvina bench [OPTIONS] COMMAND [ARGS]...

gpu

Measure docking throughput with 1, 2, 3, ... engine processes sharing one GPU (procs_per_gpu).

For each --procs value N, N engine processes start at the same time on the GPU, each docking the same --n-ligands ligands into the same pocket with the same settings (one engine call of a run with procs_per_gpu=N; --split shares the ligands out instead). A warm-up call first builds the OpenCL kernels if needed. The table is printed and written to --out.

Usage

pocketvina bench gpu [OPTIONS]

Options

--protein <protein>

Required Structure (PDB, mmCIF or PDBQT, optionally gzipped).

--ligands <ligands>

Required Ligand CSV (molecule_name,smiles); its ligands are repeated if it has fewer than --n-ligands.

--n-ligands <n_ligands>

Ligands per engine call.

Default:

100

--procs <procs>

Engine processes at the same time on the GPU, one configuration each, comma-separated.

Default:

'1,2,3'

--pocket <pocket>

Pocket (P2Rank rank).

Default:

1

--out <out>

Required Folder for bench_gpu.csv and bench_gpu.json.

--gpu <gpu_spec>

GPU (nvidia-smi index or UUID). [default: the first visible]

--center <X Y Z>

Box centre instead of P2Rank's --pocket.

--box <X Y Z>

Box size (A).

Default:

20.0, 20.0, 20.0

--thread <thread>

Engine threads.

Default:

8000

--seed <seed>

Seed of the ligand embedding and the engine.

Default:

42

--ligand-prep <ligand_prep>

Default:

'standard'

Options:

standard | legacy

--split

The processes share the --n-ligands ligands (n/N each) instead of each docking all of them.

--engine-timeout <S>

Seconds one engine call may take. [default: no limit]

--sample-interval <sample_interval>

Seconds between nvidia-smi samples.

Default:

0.5

--p2rank-model <p2rank_model>

Default:

'alphafold_conservation_hmm'

--tmp-dir <tmp_dir>

Folder for temp files.

Columns: wall_s (all processes of a configuration), ligands_per_hour (ligands docked, all processes), speedup
(ligands/hour relative to the fewest processes measured, normally 1), proc_runtime_s (mean run time of one engine
call), s_per_ligand (its time per ligand), slowdown (s_per_ligand relative to the fewest processes: how much slower
each process runs when it shares the GPU), peak_vram_mib (most GPU memory one engine used), gpu_util_mean/max (%),
gpu_mem_used_max_mib (the whole GPU). GPU columns are sampled with nvidia-smi ("-" without it).
Exit codes: 0 ok; 1 usage or input error; 2 some engine calls failed (e.g. out of GPU memory); 3 none docked.

bust

Check docked poses with PoseBusters (pip install posebusters).

Writes tables/posebusters/<protein_id>.parquet; proteins that have it already are skipped unless --overwrite.

Usage

pocketvina bust [OPTIONS]

Options

--results <results>

Required Results directory (atlas layout).

--select <select>

best: the stored best pose of each ligand; top_k: its K best modes over all pockets; per_pocket: its K best modes in each pocket.

Default:

'best'

Options:

best | top_k | per_pocket

--top-k <top_k>

K of top_k and per_pocket.

Default:

1

--config <pb_config>

PoseBusters config (dock, dock_fast, ...).

Default:

'dock'

--workers <workers>

Worker processes. [default: the CPUs available, <= 16]

--timeouts <timeouts>

Seconds per pose for each attempt, comma-separated ('none': no limit); a pose still running after the last one is a 'timeout' row.

Default:

'30,300'

--overwrite

Check proteins again that have PoseBusters results.

--protein <proteins>

Only this protein (repeatable). [default: all]

--tmp-dir <tmp_dir>

Folder for temp files.

dock

Dock ligands into the P2Rank pockets of proteins.

The options mirror PocketVinaConfig. The atlas format skips the proteins already in --out, so a stopped run resumes where it was; the effective settings are stored in its MANIFEST.json.

Usage

pocketvina dock [OPTIONS]

Options

--proteins <proteins>

Protein list file (one structure per line, relative to the list's folder), a folder of structures (*.pdb, *.ent, *.cif, *.mmcif, *.pdbqt, optionally .gz) or one structure file.

--database-path <database_path>

Database workflow (precomputed pockets), with --protein-list, instead of --proteins.

--protein-list <protein_list>

Database workflow: CSV of (database, id) rows with a header.

--ligands <ligands>

Ligand CSV: a header row, then molecule_name,smiles (.txt with the same content works too).

--out <out>

Results directory (atlas) or output folder (files).

--format <format>

Output layout: atlas (pose files and Parquet tables, resumable) or files (one PDBQT per ligand and pocket, combined_results.csv). [default: atlas]

Options:

atlas | files

--top-pockets <top_pockets>

Dock the N best-ranked pockets. [default: all]

--pockets-dir <pockets_dir>

atlas: folder of P2Rank predictions <protein>.csv (e.g. from P2RankProcessor): those proteins are docked into them without running P2Rank.

--pockets <pockets>

Dock only these pocket ranks, e.g. 10, 10-12 or 1,3,10-12 (not with --top-pockets). [default: all]

--box <X Y Z>

Docking box size (A). [default: 20 20 20]

--thread <thread>

Engine threads. [default: 8000]

--num-modes <num_modes>

Poses per ligand and pocket. [default: 20]

--energy-range <energy_range>

kcal/mol above the best pose. [default: 20]

--seed <seed>

Seed of the ligand embedding and the engine, or 'random'. [default: 42]

--ligand-prep <ligand_prep>

standard (largest fragment, seeded) or legacy (pre-v0.2, to regenerate old results). [default: standard]

Options:

standard | legacy

--ligands-per-call <ligands_per_call>

atlas: ligands per engine call, 0: all ligands of a pocket in one call. [default: --batch-size if set, else 1000]

--batch-size <batch_size>

files: ligands per batch folder and engine call (atlas: as --ligands-per-call if that is not set). [default: 10]

--gpus <gpus>

atlas: the GPU to dock on, an nvidia-smi index or UUID; 'all' or a comma-separated list for several. [default: the first visible GPU]

--procs-per-gpu <procs_per_gpu>

atlas: pockets docked at the same time on the GPU, or 'auto' (as many as its free memory holds). [default: auto]

--vram-per-proc <MIB>

GPU memory one engine needs. [default: 6600]

--engine-timeout <S>

Seconds one engine call may take. [default: no limit]

--posebusters, --no-posebusters

atlas: check the best poses with PoseBusters while docking. [default: no]

--posebusters-workers <posebusters_workers>

PoseBusters worker processes.

--tmp-dir <tmp_dir>

Folder for temp files. [default: $POCKETVINA_TMPDIR, $SLURM_TMPDIR, $TMPDIR, /tmp]

--p2rank-model <p2rank_model>

P2Rank model. [default: alphafold_conservation_hmm]

--p2rank-threads <p2rank_threads>

P2Rank threads. [default: 4]

--gzip-level <gzip_level>

atlas: pose file compression. [default: 6]

--config <RUN.TOML>

TOML file with these options (see below).

--force

atlas: replace the run definition of a results directory that holds a run with other settings or ligands.

--config run.toml: the options above as keys, in snake_case (or PocketVinaConfig field names); paths are relative to
the file's folder; flags given on the command line override it. For example:
  proteins = "proteins.txt"
  ligands = "ligands.csv"
  out = "results"
  top_pockets = 5
  box = [20, 20, 20]
  seed = 42
  procs_per_gpu = "auto"
Exit codes: 0 ok; 1 usage or configuration error; 2 some proteins or engine calls failed (rerun to retry them:
proteins done are skipped); 3 nothing docked.

export

Export poses or tables as plain files (one folder per protein).

Usage

pocketvina export [OPTIONS]

Options

--results <results>

Required Results directory (atlas layout).

--what <what>

best: the best pose per protein and ligand; all: every engine output.

Default:

'best'

Options:

best | all

--format <fmt>

sdf, pdbqt, or csv (best: best_poses.csv; all: the legacy combined_results.csv).

Default:

'sdf'

Options:

sdf | pdbqt | csv

--out <out>

Required Folder to write into.

--protein <proteins>

Only this protein (repeatable). [default: all]

import-legacy

Convert a legacy PocketVina output folder (the files format) into an atlas results directory.

Importing into a results directory that holds this import already resumes it.

Usage

pocketvina import-legacy [OPTIONS] OUTPUT_DIR

Options

--results <results>

Required Results directory to write.

--smiles <smiles>

The run's ligand CSV (molecule_name,smiles): ligand order and best-pose SDFs.

--tmp-dir <tmp_dir>

Folder for temp files.

--gzip-level <gzip_level>

Pose file compression.

Default:

6

--force

Replace another run definition in --results and import again.

Arguments

OUTPUT_DIR

Required argument

info

Summarize a results directory: settings, counts and proteins with problems.

Proteins that failed are not committed, so a results directory alone does not know them: --proteins lists the proteins of the run's list that are not done.

Usage

pocketvina info [OPTIONS]

Options

--results <results>

Required Results directory (atlas layout).

--proteins <proteins>

Protein list, folder or structure: also list its proteins that are not done (failed, or not docked yet).

--json

Print JSON.

query

Run DuckDB SQL over the results tables, or "query best": the best protein x ligand pairs.

query best: best pose per protein and ligand, best Vina score first, with ligand efficiency (and PoseBusters status when checked).

Usage

pocketvina query [OPTIONS] SQL

Options

--results <results>

Required Results directory (atlas layout).

--top <top>

query best: number of pairs.

Default:

20

--protein <proteins>

query best: only this protein (repeatable).

--csv <csv_path>

Write the rows as CSV to this file ('-': standard output) instead of printing a table.

Arguments

SQL

Required argument

Views: ligands, proteins, pockets, pocket_runs, modes, pairs, and posebusters when there are PoseBusters results.
  pocketvina query --results R "SELECT ligand_id, vina FROM pairs ORDER BY vina LIMIT 10"
  pocketvina query --results R --csv modes.csv "SELECT * FROM modes WHERE affinity < -9"
  pocketvina query best --results R --top 20

setup

Install what runs need besides the Python package (once per machine or user).

Usage

pocketvina setup [OPTIONS] COMMAND [ARGS]...

p2rank

Download P2Rank (the pocket predictor) once, and check the Java 17+ it needs.

Nothing is installed if a P2Rank is found: $P2RANK_HOME, P2Rank's prank launcher on PATH, the p2rank_2.5 folder of an older source install, or the user cache ($XDG_CACHE_HOME/pocketvina or ~/.cache/pocketvina). Otherwise P2Rank 2.5.1 (263 MiB) is downloaded from its GitHub release, checked against its pinned sha256 and unpacked so that the folder appears complete or not at all. A run without P2Rank downloads it too; this does it ahead of a run, e.g. on a login node that has internet access. Without internet access, download the release file elsewhere and pass it with --from.

Exit code 1 if P2Rank is missing (--check) or cannot be installed, or if there is no Java 17 or later.

Usage

pocketvina setup p2rank [OPTIONS]

Options

--dir <DIR>

Install into DIR/p2rank-2.5.1; runs use it once P2RANK_HOME is set to that folder. [default: the user cache, ~/.cache/pocketvina]

--from <TAR.GZ>

Unpack this p2rank_2.5.1.tar.gz (downloaded elsewhere) instead of downloading it.

--force

Install again, even if a P2Rank is found.

--check

Only show the P2Rank and Java that runs use; install nothing.

show

Write a standalone HTML page with a 3D view of a pose and print its path.

The page embeds the structures; it loads the viewer's JavaScript from a CDN when opened.

Usage

pocketvina show [OPTIONS]

Options

--results <results>

Required Results directory (atlas layout).

--protein <protein>

Required protein_id.

--ligand <ligand>

Required ligand_id, or ligand_idx (row of tables/ligands.parquet).

--pocket <pocket>

Pocket (P2Rank rank). [default: the best pose]

--mode <mode>

Mode of --pocket. [default: 1]

--out <out>

HTML file to write. [default: <protein>-<ligand>.html here]

--backend <backend>

Viewer: molstar (MolViewSpec), py3dmol, or auto (molstar if installed).

Default:

'auto'

Options:

auto | molstar | py3dmol