`deeporigin.drug_discovery.docking`¶

Docking -- unified sync + async molecular docking execution.

Usage::

docking = Docking(protein=protein, ligands=ligands, pocket=pocket)

# sync (blocking, small sets)
poses = docking.run()

# async (persisted, large batches)
docking.quote()
docking.start()
# Jupyter — non-blocking cell (like legacy Job.watch):
#     task = await docking.watch()
# Jupyter — block until the job finishes:
#     await docking.watch_async()
# Script (blocking): asyncio.run(docking.watch_async())
docking.sync()
df = docking.get_results()
poses = docking.get_poses()

Attributes¶

Number `module-attribute` ¶

Number = float | int

Classes¶

Docking ¶

Bases: Execution, QuoteMixin, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Molecular docking supporting both sync and async execution.

Sync path (run()): uses the functions API for small ligand sets. Blocking, no execution ID, not recoverable.

Async path (start()): uses the tools API. Creates a persisted execution trackable via sync(), from_id(), and list(). In Jupyter, use await docking.watch() or await docking.watch_async() for live job HTML (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.
`name`		Execution label, set automatically from protein and ligands unless overridden.

Attributes¶

app `instance-attribute` ¶

app: str | None = None

approve_amount `instance-attribute` ¶

approve_amount: int | None = None

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

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, set after start() or by from_id()

id cannot be set manually.

ligands `property` ¶

ligands: LigandSet

Set of ligands to dock.

name `instance-attribute` ¶

name = (
    name
    if name is not None
    else _docking_default_name(
        protein=protein, ligands=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.

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 = 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() -> LigandSet | None

Download pose SDFs from the platform and return a LigandSet.

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() -> DataFrame | None

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

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

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.

list `classmethod` ¶

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

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
`JobList`	A `JobList` of matching executions.

quote ¶

quote() -> None

Request a cost estimate.

Guards against re-quoting: raises if the execution has already been quoted (status == "Quoted") or if an execution ID has been assigned.

Raises:

Type	Description
`ValueError`	If the execution has already been quoted or started.

run ¶

run() -> LigandSet

Execute docking synchronously (blocking).

Uses the functions API. Suitable for small ligand sets.

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

Submit a persisted execution to the platform.

Two valid paths depending on current status:

None: no execution exists yet — calls _start_impl to create and submit a new one.
"Quoted": a cost-approved execution already exists — calls confirm on the platform to promote it, then syncs state.

All other statuses raise immediately to prevent re-submission.

Parameters:

Name	Type	Description	Default
`**kwargs`		Forwarded to `_start_impl` (only used when status is `None`).	`{}`

Raises:

Type	Description
`ValueError`	If the current status does not permit starting.

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 ¶

client instance-attribute ¶

completed_at instance-attribute ¶

cost property ¶

created_at instance-attribute ¶

created_by instance-attribute ¶

estimate property ¶

id property ¶

ligands property ¶

name instance-attribute ¶

pocket property ¶

progress instance-attribute ¶

protein 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 ¶

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` ¶

client `instance-attribute` ¶

completed_at `instance-attribute` ¶

cost `property` ¶

created_at `instance-attribute` ¶

created_by `instance-attribute` ¶

estimate `property` ¶

id `property` ¶

ligands `property` ¶

name `instance-attribute` ¶

pocket `property` ¶

progress `instance-attribute` ¶

protein `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` ¶