molforge.wrappers.docking¶

docking ¶

Docking-engine wrappers.

Concrete engines

:class:Vina — implemented (AutoDock Vina; small-molecule docking)
:class:DiffDock — implemented (diffusion-based blind docking)
:class:Gnina — implemented (CNN-rescored Vina; learned scoring)

Shared

:class:DockingEngine — abstract base for the engine contract
:class:DockingEngineNotInstalledError — raised when heavy dependencies (the vina PyPI package, the gnina binary) aren't installed.

All engines write poses sorted best-first into :attr:DockingResult.poses.

DockingEngine ¶

Bases: ABC

Abstract base for receptor-ligand docking engines.

Subclasses must implement :meth:dock. They should also handle their own receptor and ligand preparation (charge assignment, conversion to engine-specific formats) inside :meth:dock rather than exposing that complexity to users — that's the whole point of having a wrapper.

Attributes:

Name	Type	Description
`name`	`str`	Human-readable engine name (set by subclasses).

dock `abstractmethod` ¶

dock(
    receptor: Protein, ligand: object, **kwargs: object
) -> DockingResult

Dock ligand against receptor.

Parameters:

Name	Type	Description	Default
`receptor`	`Protein`	The receptor structure.	required
`ligand`	`object`	The ligand. Type is engine-dependent — typically a path to an SDF/MOL2, a SMILES string, or a :class:`Protein` (with ligand atoms).	required
`**kwargs`	`object`	Engine-specific options.	`{}`

Returns:

Name	Type	Description
`A`	`DockingResult`	class:`DockingResult` with poses sorted best-first.

DockingEngineNotInstalledError ¶

Bases: ImportError

Raised when a docking engine's heavy dependencies aren't installed.

The message points at the relevant pip install extras so users can fix it without grepping the docs.

DockingResult `dataclass` ¶

DockingResult(
    poses: list[Pose] = list(),
    receptor: Protein | None = None,
    engine: str = "",
    metadata: dict[str, object] = dict(),
)

Collection of poses returned by a docking engine.

Attributes:

Name	Type	Description
`poses`	`list[Pose]`	List of :class:`Pose` objects, sorted best-first (lowest score first).
`receptor`	`Protein \| None`	The receptor structure that was docked against.
`engine`	`str`	Engine name (`"Vina"`, `"DiffDock"`, etc.).
`metadata`	`dict[str, object]`	Engine-specific run metadata (search box, exhaustiveness, walltime, etc.).

best `property` ¶

best: Pose

The top-scoring pose. Raises IndexError if empty.

top_n ¶

top_n(n: int) -> list[Pose]

Return the n best-scoring poses.

Pose `dataclass` ¶

Pose(
    ligand: Protein,
    score: float,
    rank: int = 0,
    rmsd_lb: float | None = None,
    rmsd_ub: float | None = None,
    metadata: dict[str, object] = dict(),
)

A single docked ligand pose.

Attributes:

Name	Type	Description
`ligand`	`Protein`	The ligand structure for this pose as a :class:`Protein` (with `entity_type == "ligand"` atoms; small-molecule chemistry-aware features like bond orders are out of scope for the core data model — pose comparison and ranking only need coordinates and energy).
`score`	`float`	Engine-specific scalar score. Convention: lower = better (e.g. Vina returns kcal/mol affinity estimates as negative numbers).
`rank`	`int`	0-indexed rank within the result (0 = best).
`rmsd_lb`	`float \| None`	Vina-style "RMSD lower bound" between this pose and the best pose, if reported by the engine.
`rmsd_ub`	`float \| None`	Vina-style "RMSD upper bound" between this pose and the best pose, if reported.
`metadata`	`dict[str, object]`	Engine-specific extras (component-energy breakdown, confidence scores, etc.).

DiffDock ¶

DiffDock(
    *,
    repo_dir: str | PathLike[str] | None = None,
    python_executable: str | None = None,
    samples_per_complex: int = 10,
    inference_steps: int = 20,
    batch_size: int = 10,
)

Bases: DockingEngine

Wrapper around DiffDock (diffusion-based blind docking).

Parameters:

Name	Type	Description	Default
`repo_dir`	`str \| PathLike[str] \| None`	Path to a cloned `gcorso/DiffDock` repository. If `None`, the wrapper reads `$DIFFDOCK_HOME`. Resolution is lazy — construction never touches the filesystem, so a `DiffDock()` instance is cheap to create in code paths that may never call :meth:`dock`.	`None`
`python_executable`	`str \| None`	Python interpreter used to run DiffDock's `inference` module. Defaults to `sys.executable`; override when DiffDock's dependencies live in a separate environment.	`None`
`samples_per_complex`	`int`	Number of poses DiffDock samples (and the cap on how many ranked poses are returned). DiffDock's default is 10.	`10`
`inference_steps`	`int`	Reverse-diffusion steps. DiffDock's default is 20; more steps cost runtime roughly linearly.	`20`
`batch_size`	`int`	Sampling batch size passed through to DiffDock.	`10`

Example

from molforge.wrappers.docking import DiffDock import molforge as mf

receptor = mf.load("receptor.pdb") result = DiffDock().dock( ... receptor=receptor, ... ligand="CC(=O)Oc1ccccc1C(=O)O", # aspirin SMILES ... ) best = result.best best.metadata["confidence"] # DiffDock confidence score 0.74

dock ¶

dock(
    receptor: Protein | str | PathLike[str],
    ligand: str | PathLike[str],
    *,
    timeout: float | None = None,
    **_kwargs: object,
) -> DockingResult

Dock ligand against receptor with DiffDock.

Parameters:

Name	Type	Description	Default
`receptor`	`Protein \| str \| PathLike[str]`	A :class:`Protein` or a path to a PDB file.	required
`ligand`	`str \| PathLike[str]`	Either a SMILES string or a path to an `.sdf` / `.mol` / `.mol2` file. A value that exists as a file is treated as a path; otherwise it is treated as SMILES.	required
`timeout`	`float \| None`	Optional subprocess timeout in seconds.	`None`
`**_kwargs`	`object`	Reserved for future DiffDock options.	`{}`

Returns:

Name	Type	Description
`A`	`DockingResult`	class:`DockingResult` whose poses are sorted best-first.
	`DockingResult`	DiffDock reports a confidence (higher = better); each
	`DockingResult`	class:`Pose` keeps the raw value in
	`DockingResult`	`metadata["confidence"]` and sets `score` to its
	`DockingResult`	negation, so `score` ascending is best-first — matching
	`DockingResult`	the convention used by :class:`Vina`.

Raises:

Type	Description
`DockingEngineNotInstalledError`	If the DiffDock repo cannot be located.
`RuntimeError`	If the DiffDock subprocess fails or produces no output.

Gnina ¶

Gnina(
    *,
    gnina_executable: str = "gnina",
    cnn_scoring: str = "rescore",
    cnn: str | None = None,
    sort_order: str = "CNNscore",
    scoring: str = "vina",
    seed: int | None = None,
    cpu: int = 0,
    timeout: float = 600.0,
    verbose: bool = False,
)

Bases: DockingEngine

Wrapper around the gnina docking binary.

Parameters:

Name	Type	Description	Default
`gnina_executable`	`str`	Name or absolute path of the `gnina` binary. Defaults to `"gnina"` (expected on `$PATH`). Lazy resolution: construction never touches the filesystem.	`'gnina'`
`cnn_scoring`	`str`	When and how the CNN scoring function is used. One of `"none"`, `"rescore"` (default), `"refinement"`, `"all"`. See module docstring for the trade-offs.	`'rescore'`
`cnn`	`str \| None`	CNN model name (passed as `--cnn`). `None` uses gnina's default. Examples: `"crossdock_default2018"`, `"dense_default2018"`, `"general_default2018_ensemble"`.	`None`
`sort_order`	`str`	How to rank the returned poses. One of `"CNNscore"` (default), `"CNNaffinity"`, `"Energy"`. The first pose in the returned `DockingResult.poses` list is the best by this criterion.	`'CNNscore'`
`scoring`	`str`	Empirical scoring function for the Vina-style search. `"vina"` (default) or `"vinardo"`.	`'vina'`
`seed`	`int \| None`	Random seed for reproducibility. `None` = engine default (non-reproducible).	`None`
`cpu`	`int`	Number of CPU threads. `0` = let gnina decide.	`0`
`timeout`	`float`	Subprocess timeout in seconds. Defaults to a generous 600s — gnina with CNN rescore can take a couple minutes on big systems; pass a larger timeout for `cnn_scoring="refinement"` or `"all"`.	`600.0`
`verbose`	`bool`	When True, gnina's stdout/stderr streams to the console instead of being captured. Useful for debugging.	`False`

dock ¶

dock(
    receptor: Protein | str | PathLike[str],
    ligand: Protein | str | PathLike[str],
    *,
    center: tuple[float, float, float],
    box_size: tuple[float, float, float] = (
        20.0,
        20.0,
        20.0,
    ),
    exhaustiveness: int = 8,
    n_poses: int = 9,
    min_rmsd: float = 1.0,
    **_kwargs: object,
) -> DockingResult

Dock ligand against receptor using gnina.

Parameters:

Name	Type	Description	Default
`receptor`	`Protein \| str \| PathLike[str]`	A :class:`Protein` or a path to a structure file (`.pdb` / `.pdbqt` / `.mol2`). gnina handles format detection internally; molforge writes a temp PDB when given a Protein.	required
`ligand`	`Protein \| str \| PathLike[str]`	A :class:`Protein` (with ligand atoms) or a path to a ligand file (`.sdf` / `.mol` / `.mol2` / `.pdb` / `.pdbqt`). For SMILES input, prepare the ligand to SDF first via :func:`molforge.wrappers.docking.prepare_ligand`.	required
`center`	`tuple[float, float, float]`	`(x, y, z)` centre of the search box in Å.	required
`box_size`	`tuple[float, float, float]`	`(x, y, z)` extent of the search box in Å.	`(20.0, 20.0, 20.0)`
`exhaustiveness`	`int`	gnina's `--exhaustiveness` (search effort; higher = slower + more thorough). Default 8 (gnina default).	`8`
`n_poses`	`int`	Maximum number of poses to return.	`9`
`min_rmsd`	`float`	Minimum RMSD between poses to keep both (gnina's `--min_rmsd_filter`).	`1.0`

Returns:

Name	Type	Description
`A`	`DockingResult`	class:`DockingResult` whose `poses` are sorted
	`DockingResult`	best-first by the configured `sort_order` (CNNscore
	`DockingResult`	by default).

Raises:

Type	Description
`DockingEngineNotInstalledError`	If `gnina` isn't on `$PATH`.
`RuntimeError`	If gnina exits non-zero or fails to produce parseable output.

Vina ¶

Vina(
    *,
    scoring: str = "vina",
    seed: int | None = None,
    cpu: int = 0,
    verbosity: int = 0,
)

Bases: DockingEngine

Wrapper around AutoDock Vina.

Parameters:

Name	Type	Description	Default
`scoring`	`str`	Scoring function name. `"vina"` (default) or `"vinardo"`.	`'vina'`
`seed`	`int \| None`	Random seed for reproducibility. `None` = engine default.	`None`
`cpu`	`int`	Number of CPU threads to use. `0` = all available.	`0`
`verbosity`	`int`	Vina's internal verbosity (0 = silent, 1 = some, 2 = verbose).	`0`

Example

from molforge.wrappers.docking import Vina import molforge as mf

receptor = mf.load("receptor_prepared.pdbqt") result = Vina().dock( ... receptor=receptor, ... ligand="ligand.pdbqt", ... center=(10.0, 5.0, -2.0), ... box_size=(20.0, 20.0, 20.0), ... exhaustiveness=8, ... n_poses=9, ... ) best = result.best best.score # Vina affinity in kcal/mol -8.4

dock ¶

dock(
    receptor: Protein | str | PathLike[str],
    ligand: Protein | str | PathLike[str],
    *,
    center: tuple[float, float, float],
    box_size: tuple[float, float, float] = (
        20.0,
        20.0,
        20.0,
    ),
    exhaustiveness: int = 8,
    n_poses: int = 9,
    energy_range: float = 3.0,
    min_rmsd: float = 1.0,
    **_kwargs: object,
) -> DockingResult

Dock ligand against receptor using Vina.

Parameters:

Name	Type	Description	Default
`receptor`	`Protein \| str \| PathLike[str]`	A :class:`Protein`, a path to a PDB / mmCIF file (prepared automatically with meeko), or a path to an already-prepared `.pdbqt` file (used as-is).	required
`ligand`	`Protein \| str \| PathLike[str]`	A :class:`Protein` (with ligand atoms) or a path to a `.sdf` / `.mol` / `.mol2` / `.pdb` / `.pdbqt` file. For SMILES input, use :func:`molforge.wrappers.docking.prepare_ligand` directly with `from_smiles=True` before calling `dock`.	required
`center`	`tuple[float, float, float]`	`(x, y, z)` center of the search box in Å. This is the most important parameter — get it wrong and you'll dock to nothing.	required
`box_size`	`tuple[float, float, float]`	`(dx, dy, dz)` size of the search box in Å. 20-25 Å per side covers a typical pocket.	`(20.0, 20.0, 20.0)`
`exhaustiveness`	`int`	Sampling intensity. Vina default is 8; use 16 or 32 for more thorough searches. Linear in runtime.	`8`
`n_poses`	`int`	Maximum number of poses to return.	`9`
`energy_range`	`float`	Maximum energy difference (kcal/mol) between best and worst returned pose.	`3.0`
`min_rmsd`	`float`	Minimum RMSD between distinct poses.	`1.0`
`**_kwargs`	`object`	Reserved for future Vina options.	`{}`

Returns:

Name	Type	Description
`A`	`DockingResult`	class:`DockingResult` with poses sorted best (most negative
	`DockingResult`	affinity) first. Each :class:`Pose` has `score` in kcal/mol
	`DockingResult`	and `rmsd_lb` / `rmsd_ub` populated relative to the best pose.

Raises:

Type	Description
`DockingEngineNotInstalledError`	If `vina` is not installed.

is_pdbqt_path ¶

is_pdbqt_path(value: object) -> bool

True iff value is a path string pointing to a .pdbqt file.

prepare_ligand ¶

prepare_ligand(
    ligand: str | PathLike[str],
    out_path: str | PathLike[str],
    *,
    from_smiles: bool = False,
    add_hydrogens: bool = True,
    generate_3d: bool = True,
) -> Path

Prepare a ligand for AutoDock Vina, writing a PDBQT to out_path.

Parameters:

Name	Type	Description	Default
`ligand`	`str \| PathLike[str]`	One of: A path to an already-prepared `.pdbqt` file (copied as-is). A path to an `.sdf` / `.mol` / `.mol2` / `.pdb` file. A SMILES string (if `from_smiles=True`).	required
`out_path`	`str \| PathLike[str]`	Destination path for the PDBQT file.	required
`from_smiles`	`bool`	Treat `ligand` as a SMILES string rather than a path.	`False`
`add_hydrogens`	`bool`	Add explicit hydrogens (needed by Vina).	`True`
`generate_3d`	`bool`	Generate a 3-D conformer via RDKit's ETKDG.	`True`

Returns:

Type	Description
`Path`	The path the PDBQT was written to.

Raises:

Type	Description
`DockingEngineNotInstalledError`	If `meeko` or `rdkit` is missing.

prepare_receptor ¶

prepare_receptor(
    receptor: Protein | str | PathLike[str],
    out_path: str | PathLike[str],
    *,
    rigid_only: bool = True,
) -> Path

Prepare a receptor for AutoDock Vina, writing a PDBQT to out_path.

Parameters:

Name	Type	Description	Default
`receptor`	`Protein \| str \| PathLike[str]`	A :class:`molforge.core.Protein`, a path to a PDB / mmCIF file, or a path to an already-prepared PDBQT (in which case we copy it to `out_path` and return).	required
`out_path`	`str \| PathLike[str]`	Destination path for the PDBQT file.	required
`rigid_only`	`bool`	If True (default), treat the entire receptor as rigid (the usual case). Set False if you've added side-chain flexibility annotations upstream.	`True`

Returns:

Type	Description
`Path`	The path the PDBQT was written to.

Raises:

Type	Description
`DockingEngineNotInstalledError`	If `meeko` isn't installed.

molforge.wrappers.docking¶

docking ¶

DockingEngine ¶

dock abstractmethod ¶

DockingEngineNotInstalledError ¶

DockingResult dataclass ¶

best property ¶

top_n ¶

Pose dataclass ¶

DiffDock ¶

dock ¶

Gnina ¶

dock ¶

Vina ¶

dock ¶

is_pdbqt_path ¶

prepare_ligand ¶

prepare_receptor ¶

dock `abstractmethod` ¶

DockingResult `dataclass` ¶

best `property` ¶

Pose `dataclass` ¶