Docking Plugin¶

Package: caddforge-docking

Public source tag

This page describes caddforge-docking 0.7.0, tagged as v0.7.0. Published on PyPI; see the version matrix.

The docking plugin provides docking and rescoring workflows through the standard CADDForge workflow/job interface.

Install optional GUI support with:

python -m pip install "caddforge-docking[gui]"

Requirements and example status¶

The example library provides downloadable configuration templates for every workflow on this page, plus a shared Python runner. File paths refer to inputs you must prepare; these are not bundled research datasets. Schema validation does not establish scientific validity or engine availability. See the version matrix for release tags and publication status.

`unidock`¶

Runs GPU-accelerated docking with Uni-Dock.

CLI:

caddforge run docking unidock --config unidock.yaml

YAML:

receptor_path: data/protein.pdbqt
ligand_multisdf_path: data/ligands.sdf
center_x: 0.0
center_y: 0.0
center_z: 0.0
size_x: 20
size_y: 20
size_z: 20
search_mode: fast
exhaustiveness: 384
batch_size: 50000

Python:

from caddforge.core.execution import load_result_for_job, submit_workflow
from caddforge.plugins import get_tool

spec = get_tool("docking", "unidock")
cfg = spec.config_cls(
    receptor_path="data/protein.pdbqt",
    ligand_multisdf_path="data/ligands.sdf",
    center_x=0.0,
    center_y=0.0,
    center_z=0.0,
    size_x=20.0,
    size_y=20.0,
    size_z=20.0,
    backend="local",
)
workflow = spec.workflow_cls(cfg)
job = submit_workflow(
    workflow, cfg, backend_name=cfg.backend,
    input_ports=tuple(getattr(spec.plugin, "input_ports", ())),
)
result = load_result_for_job(job)
if result is not None:
    print(result.paths["best_scores_csv"])

Outputs to inspect: results/docked_out/, results/best_scores.csv, results/result_record.json.

exhaustiveness defaults to 384 in this release. Set it explicitly when reproducing runs made with an earlier default.

`idockya`¶

Runs docking with OpenChemLib iDockYa through pyocl, provided by pyocl-idor>=0.8.3. Java 21 or newer is required; configure JAVA_HOME accordingly.

CLI:

caddforge run docking idockya --config idockya.yaml

YAML:

receptor_path: data/receptor.sdf
native_ligand_path: data/native_ligand.sdf
ligand_path: data/ligands.sdf
output_format: sdf
output_dir_name: docked_out
num_workers: 0
max_inflight_tasks: 0

Python:

from caddforge.core.execution import load_result_for_job, submit_workflow
from caddforge.plugins import get_tool

spec = get_tool("docking", "idockya")
cfg = spec.config_cls(
    receptor_path="data/receptor.sdf",
    native_ligand_path="data/native_ligand.sdf",
    ligand_path="data/ligands.sdf",
    output_format="sdf",
    backend="local",
)
workflow = spec.workflow_cls(cfg)
job = submit_workflow(
    workflow, cfg, backend_name=cfg.backend,
    input_ports=tuple(getattr(spec.plugin, "input_ports", ())),
)
result = load_result_for_job(job)
if result is not None:
    print(result.metrics)

Outputs to inspect: results/docked_out/, results/best_scores.csv, results/result_record.json.

`gnina`¶

Runs docking or rescoring with the gnina executable.

CLI:

caddforge run docking gnina --config gnina.yaml

YAML:

receptor_path: data/protein.pdb
ligand_path: data/ligands.sdf
autobox_ligand_path: data/reference_ligand.sdf
flexres:
  - A:194
  - A:244
  - A:252
scoring: dkoes_fast
cnn_scoring: rescore
no_gpu: true
output_format: sdf

Python:

from caddforge.core.execution import load_result_for_job, submit_workflow
from caddforge.plugins import get_tool

spec = get_tool("docking", "gnina")
cfg = spec.config_cls(
    receptor_path="data/protein.pdb",
    ligand_path="data/ligands.sdf",
    autobox_ligand_path="data/reference_ligand.sdf",
    flexres=["A:194", "A:244", "A:252"],
    no_gpu=True,
    backend="local",
)
workflow = spec.workflow_cls(cfg)
job = submit_workflow(
    workflow, cfg, backend_name=cfg.backend,
    input_ports=tuple(getattr(spec.plugin, "input_ports", ())),
)
result = load_result_for_job(job)
if result is not None:
    print(result.paths["best_scores_csv"])

Outputs to inspect: results/docked_out/, results/gnina_logs/, results/best_scores.csv, results/result_record.json.

Flexible docking also writes raw gnina flex receptor outputs when write_flex_receptor_output is enabled. By default, gnina additionally writes one full protein-ligand complex PDB, one protein-only PDB, and one ligand-only SDF per generated pose under results/flexible_complexes/. These artifacts preserve protein and ligand hydrogen presence from the input receptor and ligand records. Ligand bond orders and formal charges are copied from the input ligand; PDB complexes emit ligand bond orders as CONECT records, but downstream support for interpreting those bond orders is reader-dependent. Use a PDB receptor for this mode, or set write_flexible_complexes: false to keep only the raw gnina outputs.

Pipeline output aliases include scores, poses, flexible_complexes_manifest, flexible_complexes, flexible_proteins, and flexible_ligand_poses. The flexible artifact aliases are optional and are emitted only when flexible complex generation produces them.

On Slurm, GNINA stages static inputs once in node-local scratch, synchronizes live text logs, and publishes completed ligand artifacts asynchronously. log_sync_interval_seconds and result_sync_interval_seconds control those retry intervals. A temporary shared-filesystem outage does not interrupt docking, but the workflow does not report success if required artifacts remain unpublished after the final retry.

Compressed inputs¶

Declared receptor, ligand, and reference inputs may use a trailing .gz; CADDForge expands them in runtime scratch. UniDock indexes can reference .sdf.gz ligands.

Docking Plugin¶

Requirements and example status¶

unidock¶

idockya¶

gnina¶

Compressed inputs¶

`unidock`¶

`idockya`¶

`gnina`¶