molforge.docking

docking

Docking abstractions: receptor/ligand prep, pose handling, scoring.

A docking engine takes a receptor (typically a protein) and a ligand (typically a small molecule) and returns a set of plausible binding poses ranked by an engine-specific score. The interface here is intentionally narrow:

receptor + ligand -> DockingResult (list of Pose)

Concrete engines (AutoDock Vina, DiffDock, ...) inherit from :class:DockingEngine and live under :mod:molforge.wrappers.docking.

By convention, every docking engine writes its lowest-energy / top-scored pose first in :attr:DockingResult.poses, with scores sorted ascending (more negative = better, matching Vina's convention).

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.).

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.

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.