`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, QuoteMixin, 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 and sends one ligand per request; the server blocks until the run finishes and returns the completed execution. :meth:quote 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¶

app `instance-attribute` ¶

app: str | None = None

approve_amount `instance-attribute` ¶

approve_amount: int | None = None

batch_size `property` ¶

batch_size: int

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

client `instance-attribute` ¶

client: DeepOriginClient = client

completed_at `instance-attribute` ¶

completed_at: str | None = None

cost `property` ¶

cost: float | None

Actual cost in dollars, set after execution completes.

This property cannot be set manually.

created_at `instance-attribute` ¶

created_at: str | None = None

created_by `instance-attribute` ¶

created_by: str | None = None

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

effort: int = effort

estimate `property` ¶

estimate: float | None

Cost estimate in dollars, set by quote(). None until quote() is called.

This property cannot be set manually.

id `property` ¶

id: str | None

Platform execution ID when set (read-only).

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.

progress `instance-attribute` ¶

progress: dict | None = None

protein `property` ¶

protein: Protein

Target protein structure.

runtime `property` ¶

runtime: float | None

Seconds from _execution_dto["startedAt"] to completedAt or now.

When completedAt is set, uses that as the end time; otherwise uses the current UTC time. Returns None if startedAt is unknown.

session `instance-attribute` ¶

session: str | None = None

started_at `instance-attribute` ¶

started_at: str | None = None

status `instance-attribute` ¶

status: PlatformStatus | None = None

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¶

cancel ¶

cancel() -> None

Cancel a running or queued execution.

Raises:

Type	Description
`ValueError`	If the job has no execution ID.
`ValueError`	If the job is not in a cancellable state.

duplicate ¶

duplicate(
    *, client: DeepOriginClient | None = None
) -> Self

Create a fresh copy with the same configuration but no execution state.

Useful after from_id() to re-run the same calculation. The returned instance has no id, status, estimate, or cost — it is ready for quote() / start().

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	Optional API client for the new instance. Falls back to the current instance's client.	`None`

Returns:

Type	Description
`Self`	A new instance sharing the same domain-specific configuration.

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.

from_id `classmethod` ¶

from_id(
    id: str, *, client: DeepOriginClient | None = None
) -> Self

Construct a Docking instance from an existing platform execution ID.

Fetches the execution record via the API and delegates to :meth:from_dto.

Parameters:

Name	Type	Description	Default
`id`	`str`	Platform execution ID.	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 synced from
`Self`	the platform.

get_poses ¶

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

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 \| None`	A `LigandSet` of docked poses, or `None` if no pose files yet.

Raises:

Type	Description
`ValueError`	If no execution has been started.

get_results ¶

get_results(
    *, all_poses: bool = False, **kwargs
) -> DataFrame | None

Retrieve docking results as a table (no structure download).

Columns: ID, protein ID, ligand ID, pocket ID, binding energy, pose_score, best_pose.

Uses :meth:~deeporigin.drug_discovery.execution.Execution.get_results to fetch result rows for this execution. By default (all_poses=False) the query is restricted to the best pose per ligand; pass all_poses=True for every pose row.

Returns:

Type	Description
`DataFrame \| None`	A DataFrame with one row per pose record, or `None` if the API
`DataFrame \| None`	returns no pose rows yet.

Raises:

Type	Description
`ValueError`	If no execution has been started.

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.

list `classmethod` ¶

list(
    *,
    client: DeepOriginClient | None = None,
    status: list[str] | None = None
) -> list[Self]

List executions of this tool type from the platform.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`
`status`	`list[str] \| None`	Optional list of statuses to filter by.	`None`

Returns:

Type	Description
`list[Self]`	Instances of this class, one per matching execution.

quote ¶

quote() -> None

Request a cost estimate.

Runs :meth:_quote_setup, :meth:_quote_impl, and :meth:_quote_finalize.

Raises:

Type	Description
`ValueError`	If the execution has already been quoted or started.
`NotImplementedError`	If :meth:`_get_quote` is not implemented.
`RuntimeError`	If the API response fails quotation validation.

run ¶

run() -> LigandSet

Execute docking: one blocking executions.create per ligand.

The platform holds the request until the run finishes and returns the final execution in the response (no client-side poll loop).

Returns:

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

show ¶

show() -> None

Display the current execution in Jupyter using the execution card HTML view.

If no platform execution ID exists yet, shows the same card with a short notice instead of raising (see :meth:~deeporigin.platform.execution_display.ExecutionDisplay.from_pending).

start ¶

start(**kwargs: Any) -> None

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

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

stop_watching ¶

stop_watching() -> None

Cancel an in-flight :meth:watch_async loop if one is running.

Safe to call when no watch is active. Does not cancel the caller's current task when invoked from inside :meth:watch_async.

sync ¶

sync() -> None

Sync status, cost, and estimate from the platform.

Raises:

Type	Description
`ValueError`	If the job has no execution ID.

watch `async` ¶

watch(*, interval: float = 5.0) -> Task

Schedule :meth:watch_async and return the :class:asyncio.Task immediately.

In Jupyter, awaiting this coroutine finishes in one event-loop turn, so the cell returns while the display keeps updating in the background (similar to legacy Job.watch()). Use this when you need to run other cells while the job runs::

task = await abfe.watch()

To block until the job finishes, use :meth:watch_async instead::

await abfe.watch_async()

Parameters:

Name	Type	Description	Default
`interval`	`float`	Seconds between polls; passed to :meth:`watch_async`.	`5.0`

Returns:

Type	Description
`Task`	The task running :meth:`watch_async`. Cancel it with
`Task`	meth:`stop_watching` or `task.cancel()`.

watch_async `async` ¶

watch_async(*, interval: float = 5.0) -> None

Poll the platform and update a Jupyter display until a terminal state.

In notebooks use top-level await abfe.watch_async(). In scripts use asyncio.run(abfe.watch_async()).

Parameters:

Name	Type	Description	Default
`interval`	`float`	Seconds between polls after a successful update.	`5.0`

Raises:

Type	Description
`ValueError`	If `id` is None, or execution data is missing when required.

deeporigin.drug_discovery.docking¶

Attributes¶

Number module-attribute ¶

Classes¶

Docking ¶

Attributes¶

app instance-attribute ¶

approve_amount instance-attribute ¶

batch_size property ¶

client instance-attribute ¶

completed_at instance-attribute ¶

cost property ¶

created_at instance-attribute ¶

created_by instance-attribute ¶

effort class-attribute instance-attribute ¶

estimate property ¶

id property ¶

ligands property ¶

name instance-attribute ¶

pocket property ¶

progress instance-attribute ¶

protein property ¶

runtime property ¶

session instance-attribute ¶

started_at instance-attribute ¶

status instance-attribute ¶

tool_key class-attribute instance-attribute ¶

tool_version instance-attribute ¶

Functions¶

cancel ¶

duplicate ¶

from_dto classmethod ¶

from_id classmethod ¶

get_poses ¶

get_results ¶

get_undocked_ligands ¶

list classmethod ¶

quote ¶

run ¶

show ¶

start ¶

stop_watching ¶

sync ¶

watch async ¶

watch_async async ¶

`deeporigin.drug_discovery.docking`¶

Number `module-attribute` ¶

app `instance-attribute` ¶

approve_amount `instance-attribute` ¶

batch_size `property` ¶

client `instance-attribute` ¶

completed_at `instance-attribute` ¶

cost `property` ¶

created_at `instance-attribute` ¶

created_by `instance-attribute` ¶

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

estimate `property` ¶

id `property` ¶

ligands `property` ¶

name `instance-attribute` ¶

pocket `property` ¶

progress `instance-attribute` ¶

protein `property` ¶

runtime `property` ¶

session `instance-attribute` ¶

started_at `instance-attribute` ¶

status `instance-attribute` ¶

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

tool_version `instance-attribute` ¶

from_dto `classmethod` ¶

from_id `classmethod` ¶

list `classmethod` ¶

watch `async` ¶

watch_async `async` ¶