`deeporigin.drug_discovery.docking`¶

Not yet released

This class isn't yet available on the latest release of the deeporigin client. Use the Complex class and methods on Protein and Ligand objects.

A unified class to perform molecular docking on DeepOrigin.

Attributes¶

Number `module-attribute` ¶

Number = float | int

Classes¶

Docking ¶

Bases: Execution, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Molecular docking via the tools API (client.executions.create).

The execution request body includes sync (true = blocking, false = immediate DTO). :meth:run sets "sync": true for exactly one ligand; the server blocks until the run finishes and returns the completed execution. :meth:quote (default mode="async") and :meth:start set "sync": false (non-blocking).

:meth:start is for multiple ligands only: one create with all ligands. The call returns immediately with an execution DTO. For a single ligand, use :meth:run instead of :meth:start. Track async jobs with .sync(), from_id(), and list(). In Jupyter, use await docking.watch() or await docking.watch_async() (see :class:~deeporigin.drug_discovery.notebook_watch_mixin.NotebookWatchMixin).

Attributes:

Name	Type	Description
`protein`	`Protein`	Target protein structure.
`ligands`	`LigandSet`	Set of ligands to dock.
`pocket`	`Pocket`	Binding pocket defining the docking box.
`effort`	`int`	Docking effort level (1 = fastest, 5 = most thorough).
`name`		Execution label, set automatically from protein and ligands unless overridden.
`batch_size`	`int`	For async :meth:`start`, workflow batch size (ligands per workflow batch), a positive multiple of 4. Defaults to 16. Sent as `batchSize` on the execution create payload.

Attributes¶

batch_size `property` ¶

batch_size: int

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

effort `class-attribute` `instance-attribute` ¶

effort: int = effort

ligands `property` ¶

ligands: LigandSet

Set of ligands to dock.

name `instance-attribute` ¶

name = (
    name
    if name is not None
    else _docking_default_name(protein, ligands)
)

pocket `property` ¶

pocket: Pocket

Binding pocket defining the docking box.

protein `property` ¶

protein: Protein

Target protein structure.

tool_key `class-attribute` `instance-attribute` ¶

tool_key: str = TOOL_KEYS_AND_VERSIONS["docking"][
    "tool_key"
]

tool_version `instance-attribute` ¶

tool_version = tool_version

Functions¶

from_dto `classmethod` ¶

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

Construct a Docking instance from an execution DTO.

Rehydrates the protein, pocket, and ligands from the stored userInputs. Protein and ligand structure files are not downloaded; Protein.remote_path and each ligand's remote_path are set from the execution payload (and API metadata) so you can call :meth:~deeporigin.drug_discovery.structures.entity.Entity.download later if needed.

Parameters:

Name	Type	Description	Default
`dto`	`dict`	Execution payload (same shape as `client.executions.get`).	required
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`

Returns:

Type	Description
`Self`	A fully-hydrated Docking instance with status from the DTO.

get_poses ¶

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

Download pose SDFs from the platform and return a LigandSet.

Parameters:

Name	Type	Description	Default
`all_poses`	`bool`	If True, download all poses for each ligand. If False (default), download only the best pose per ligand.	`False`

Returns:

Type	Description
`LigandSet`	A `LigandSet` of docked poses.

Raises:

Type	Description
`ValueError`	If no execution has been started.
`DeepOriginException`	If no poses could be loaded.

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.

Tries :meth:~deeporigin.drug_discovery.structures.ligand.LigandSet.from_result first (fast metadata path, no SDF download). On failure, parses jobOutputs.poses from dto, or fetches the execution DTO via client.executions.get when dto is omitted.

To convert the result to a DataFrame::

poses = docking.get_results()
df = poses.to_dataframe()

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any] \| None`	Optional execution payload (`executions.create` / `executions.get`). Passing it avoids an extra GET when the data platform path fails but the sync response included `jobOutputs`.	`None`
`all_poses`	`bool`	When `True`, include every pose instead of only the best pose per ligand.	`False`

Returns:

Type	Description
`LigandSet`	A `LigandSet` of docked poses.

Raises:

Type	Description
`ValueError`	If :attr:`id` is unset.
`DeepOriginException`	If no poses could be loaded from the data platform or `jobOutputs`.

get_undocked_ligands ¶

get_undocked_ligands() -> LigandSet | None

Get a list of ligands that failed to dock.

Note: we cannot rely on the tool progress report to determine failed ligands, because catastrophic tool failures will not update the progress report.

Returns:

Type	Description
`LigandSet \| None`	A `LigandSet` of failed ligands, or `None` if no failed ligands yet.

run ¶

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

Execute docking synchronously (blocking).

Submits one synchronous tools execution and returns docked poses from the data platform. Requires exactly one ligand in :attr:ligands; use :meth:start for multiple ligands.

Pass quote=True (or approve_amount=0) to request a cost estimate only. In that case the platform returns a Quoted DTO, the instance is updated with estimate and status="Quoted", and None is returned.

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 the platform
`LigandSet \| None`	responds with `Quoted` status.

Raises:

Type	Description
`ValueError`	If :attr:`ligands` does not contain exactly one ligand.
`DeepOriginException`	If `effort` is outside 1–5, the execution does not succeed, or poses could not be loaded.

start ¶

start(
    *,
    quote: bool = False,
    approve_amount: int | None = None,
    **kwargs: Any
) -> None

Submit a persisted async execution. Requires at least two ligands.

For a single ligand, 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`.	`{}`

deeporigin.drug_discovery.docking¶

Attributes¶

Number module-attribute ¶

Classes¶

Docking ¶

Attributes¶

batch_size property ¶

effort class-attribute instance-attribute ¶

ligands property ¶

name instance-attribute ¶

pocket property ¶

protein property ¶

tool_key class-attribute instance-attribute ¶

tool_version instance-attribute ¶

Functions¶

from_dto classmethod ¶

get_poses ¶

get_results ¶

get_undocked_ligands ¶

run ¶

start ¶

`deeporigin.drug_discovery.docking`¶

Number `module-attribute` ¶

batch_size `property` ¶

effort `class-attribute` `instance-attribute` ¶

ligands `property` ¶

name `instance-attribute` ¶

pocket `property` ¶

protein `property` ¶

tool_key `class-attribute` `instance-attribute` ¶

tool_version `instance-attribute` ¶

from_dto `classmethod` ¶