Skip to content

deeporigin.drug_discovery.constrained_docking

Constrained molecular docking via the served tools API.

Classes

ConstrainedDocking

Bases: Execution, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Harmonic constrained docking via deeporigin.constrained-docking.

Dock test ligands using harmonic constraints derived server-side from a reference ligand pose via MCS alignment. Callers supply reference_ligand (scaffold identity) and reference_pose (3D coordinates); the platform derives per-atom constraints for each test ligand. Test ligands may be SMILES-only (no structure file) when lig.smiles is set; the server embeds an ephemeral 3D structure for MCS.

:meth:run sets inputs.sync=true for exactly one test ligand (blocking). :meth:start sets inputs.sync=false for two or more test ligands (async workflow). Track async jobs with .sync(), .wait(), or await watch().

Attributes:

Name Type Description
protein Protein

Target protein structure.
ligands LigandSet

Test ligands to constrain-dock.
pocket Pocket

Binding pocket defining the docking box.
reference_ligand Ligand

Template ligand identity for MCS constraint derivation.
reference_pose Ligand

Required 3D reference pose SDF used for constraints.
constraint_energy float

Harmonic constraint weight sent to the tool.
effort int

Docking effort level (1 = fastest, 5 = most thorough).
name

Execution label, set automatically unless overridden.
batch_size int

Workflow batch size for async :meth:start (default 8).

Attributes

batch_size property 
batch_size: int

Workflow batch size for async :meth:start (default 8).

constraint_energy property 
constraint_energy: float

Harmonic constraint energy weight sent to the tool.

effort class-attribute instance-attribute 
effort: int = effort
ligand property 
ligand: Ligand

Single test ligand when exactly one was provided.

ligands property 
ligands: LigandSet

Test ligands to constrain-dock.

mcs_smarts property 
mcs_smarts: str | None

Optional SMARTS override for the common scaffold.

mcs_smiles property 
mcs_smiles: str | None

Optional SMILES override for the common scaffold.

name instance-attribute 
name = (
    name
    if name is not None
    else _constrained_docking_default_name(protein, ligands)
)
pocket property 
pocket: Pocket

Binding pocket defining the docking box.

protein property 
protein: Protein

Target protein structure.

reference_ligand property 
reference_ligand: Ligand

Reference/template ligand used for MCS constraint derivation.

reference_pose property 
reference_pose: Ligand

Required 3D reference pose submitted to the tool.

tool_key class-attribute instance-attribute 
tool_key: str = TOOL_KEYS_AND_VERSIONS[
    "constrained_docking"
]["tool_key"]
tool_version instance-attribute 
tool_version = tool_version

Methods:

from_dto classmethod 
from_dto(
    dto: dict, *, client: DeepOriginClient | None = None
) -> Self

Construct a ConstrainedDocking instance from an execution DTO.

get_poses 
get_poses(*, all_poses: bool = False) -> LigandSet

Download pose SDFs from the platform and return a LigandSet.

get_reference_pose 
get_reference_pose(
    dto: dict[str, Any] | None = None,
) -> Ligand

Load the reference pose reported by this execution.

Parameters:

Name Type Description Default
dto dict[str, Any] | None

Optional execution payload to avoid an extra GET.

 None

Returns:

Type Description
Ligand

The reference pose as a :class:Ligand.
get_results 
get_results(
    dto: dict[str, Any] | None = None,
    *,
    all_poses: bool = False
) -> LigandSet

Load docked poses for this execution from the data platform or jobOutputs.

run 
run(
    *,
    quote: bool = False,
    approve_amount: int | None = None
) -> LigandSet | None

Execute constrained docking synchronously (blocking).

Parameters:

Name Type Description Default
quote bool

Shorthand for approve_amount=0.

 False
approve_amount int | None

Spend cap forwarded to the platform as approveAmount.

 None

Returns:

Type Description
LigandSet | None

A LigandSet of docked poses, or None when quoted.

Raises:

Type Description
DeepOriginException

If the execution does not succeed or poses could not be loaded.
show_box 
show_box(
    *,
    poses: Ligand | LigandSet | list[Ligand] | None = None
)

Visualize the protein with the docking search box in a Jupyter notebook.

When poses is provided, docked ligands are overlaid with the wireframe search box (visualizeDockedLigands + renderBoundingBox).

Parameters:

Name Type Description Default
poses Ligand | LigandSet | list[Ligand] | None

Optional docked pose(s) to overlay with the search box. Accepts a single :class:Ligand, a :class:LigandSet, or a list of ligands.

 None

Returns:

Type Description

Result of :func:~deeporigin.utils.notebook.render_html for the Mol*

viewer (None after Jupyter display, or a marimo mo.Html wrapper).

Raises:

Type Description
DeepOriginException

If the protein structure cannot be loaded locally.
ValueError

If poses is an empty collection.
start 
start(
    *,
    quote: bool = False,
    approve_amount: int | None = None,
    **kwargs: Any
) -> None

Submit a persisted async execution.

Requires at least two test ligands unless quote=True (cost estimate only), in which case a single test ligand is allowed.

For a single-ligand docking run, use :meth:run instead.

Parameters:

Name Type Description Default
quote bool

Shorthand for approve_amount=0.

 False
approve_amount int | None

Spend cap forwarded to the platform.

 None
**kwargs Any

Forwarded to _start_impl.

 {}