`deeporigin.drug_discovery.constrained_docking`¶

Constrained molecular docking via the served tools API.

Attributes¶

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.

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

USER_LOG_COLUMNS `class-attribute` ¶

USER_LOG_COLUMNS: list[str] = [
    "log_level",
    "tool_key",
    "timestamp",
    "message",
]

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

client `instance-attribute` ¶

client: DeepOriginClient = client

completed_at `instance-attribute` ¶

completed_at: str | None = None

constraint_energy `property` ¶

constraint_energy: float

Harmonic constraint energy weight sent to the tool.

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

dto `property` ¶

dto: dict[str, Any] | None

Last tools execution DTO from the platform, if any.

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

effort: int = effort

estimate `property` ¶

estimate: float | None

Cost estimate in dollars, populated when the platform returns a quotation.

Set after run(quote=True), start(quote=True), or any call with approve_amount=0. None until a quotation result is received. This property cannot be set manually.

id `property` ¶

id: str | None

Platform execution ID when set (read-only).

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.

progress `instance-attribute` ¶

progress: dict | None = None

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.

runtime `property` ¶

runtime: float | None

Seconds from DTO startedAt to completedAt or current UTC time.

Uses :attr:dto (same shape as client.executions.get). When completedAt is present, it is the end time; otherwise the end time is datetime.now(timezone.utc). Returns None if there is no DTO or startedAt is missing or empty.

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[
    "constrained_docking"
]["tool_key"]

tool_version `instance-attribute` ¶

tool_version = tool_version

Methods:¶

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.

confirm ¶

confirm() -> None

Confirm a quoted tools execution on the platform.

Requires :attr:id and status equal to "Quoted". Uses :meth:~deeporigin.platform.executions.Executions.confirm with :data:~deeporigin.utils.constants.TOOL_EXECUTION_POST_TIMEOUT_SECONDS (10 minutes) and retry=False, then applies the returned DTO via :meth:update_from_dto so status, :attr:cost, and :attr:dto reflect the platform response. For direct (blocking) tools the response is typically terminal (Completed); for async tools it may be Created or Running — call :meth:sync until the job finishes.

Raises:

Type	Description
`ValueError`	If there is no platform execution id or status is not `"Quoted"`.

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 run() / 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 ConstrainedDocking instance from an execution DTO.

from_id `classmethod` ¶

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

Construct an instance from an existing platform execution ID.

Fetches the execution DTO via client.executions.get and delegates to :meth:from_dto. Concrete subclasses override :meth:from_dto to attach domain state from userInputs.

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 partially-hydrated instance with common fields populated.

Raises:

Type	Description
`NotImplementedError`	If `cls` has no `tool_key` (bare :class:`Execution`).

from_last_run `classmethod` ¶

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

Construct an instance from the most recently created execution of this tool.

Calls client.executions.list with tool_key, order set to :data:~deeporigin.utils.constants.EXECUTION_LIST_ORDER_CREATED_DESC, and page_size=1, then delegates to :meth:from_dto. Concrete subclasses inherit this method; domain state is restored via their from_dto overrides.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`

Returns:

Type	Description
`Self`	A partially-hydrated instance for the newest execution by
`Self`	`createdAt`.

Raises:

Type	Description
`NotImplementedError`	If `cls` has no `tool_key` (bare :class:`Execution`).
`ValueError`	If no executions exist for this tool type.

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.

get_user_logs ¶

get_user_logs(
    *,
    limit: int | None = None,
    offset: int | None = None,
    select: list[str] | None = None,
    with_total_count: bool = False
) -> DataFrame | None

Search data-platform user_logs rows for this execution.

Uses :meth:deeporigin.platform.user_logs.UserLogs.search with this execution's id (tools executionId), stored as execution_id on user_logs rows — the same string passed to :meth:get_results as compute_job_id.

When no execution id is assigned yet, returns None without calling the API.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Max rows to return (forwarded to `UserLogs.search`).	`None`
`offset`	`int \| None`	Skip offset (forwarded).	`None`
`select`	`list[str] \| None`	Columns to select (forwarded).	`None`
`with_total_count`	`bool`	Request total count from the server (forwarded).	`False`

Returns:

Type	Description
`DataFrame \| None`	A DataFrame with columns `log_level`, `tool_key`, `timestamp`,
`DataFrame \| None`	and `message`. `tool_key` omits the `deeporigin.` prefix;
`DataFrame \| None`	`timestamp` is a compact humanized relative time. Returns `None`
`DataFrame \| None`	if this instance has no execution id yet or the client has no
`DataFrame \| None`	`user_logs` API.

list `classmethod` ¶

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

List executions of this tool type from the platform.

Calls client.executions.list(fetch_all_pages=True, tool_key=...), then builds instances via :meth:from_dto. Optional status filters hydrated instances by instance.status.

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 keep (membership test).	`None`

Returns:

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

Raises:

Type	Description
`NotImplementedError`	If `cls` has no `tool_key` (bare :class:`Execution`).

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 ¶

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

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`.	`{}`

stop_watching ¶

stop_watching() -> None

Cancel an in-flight watch 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 the watch loop.

sync ¶

sync() -> None

Fetch the latest tools execution from the platform and refresh fields.

Calls client.executions.get for :attr:id and applies the response with :meth:update_from_dto. Use when the job may have changed outside this process (for example after submission from the web UI), to poll lifecycle state, or to refresh an instance built from an older DTO. Available on sync-only and async execution types alike.

If executions.get returns a falsy value, this instance is left unchanged.

Raises:

Type	Description
`ValueError`	If this instance has no execution id yet.
`NotImplementedError`	If `type(self).tool_key` is empty (bare :class:`Execution`).
`ValueError`	If the returned DTO `tool.key` does not match this class (see :meth:`update_from_dto`).

update_from_dto ¶

update_from_dto(dto: dict[str, Any]) -> None

Apply tools execution fields from dto onto this instance.

Updates id, pricing, lifecycle fields, and _dto the same way as :meth:from_dto for a newly created instance. Use after a live executions.create / sync() response to refresh state without constructing a new object (domain inputs on self are unchanged).

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any]`	Execution payload (same shape as `client.executions.get`).	required

Raises:

Type	Description
`NotImplementedError`	If `type(self)` has no `tool_key` (bare :class:`Execution`).
`ValueError`	If the DTO `tool.key` does not match `tool_key`.

wait ¶

wait(
    *,
    poll_interval: float = 5.0,
    timeout: float | None = None
) -> dict[str, Any] | None

Block until this execution reaches a terminal state.

Parameters:

Name	Type	Description	Default
`poll_interval`	`float`	Seconds to sleep between polling cycles.	`5.0`
`timeout`	`float \| None`	Maximum total seconds to wait. If `None`, waits indefinitely.	`None`

Returns:

Type	Description
`dict[str, Any] \| None`	The latest execution DTO, or `None` if the platform returned no DTO.

Raises:

Type	Description
`ValueError`	If this instance has no execution id yet.
`TimeoutError`	If `timeout` elapses before the execution terminates.

watch `async` ¶

watch(
    *, interval: float = 5.0, blocking: bool = False
) -> Task | None

Start live notebook updates; optionally block until the job finishes.

By default, awaiting this coroutine finishes in one event-loop turn, so the cell returns while the display keeps updating in the background. Use this when you need to run other cells while the job runs::

task = await abfe.watch()

Set blocking=True or export JOB_WATCH_BLOCK=1 (truthy values: 1, true, yes, on) to run the poll loop inline so the cell does not return until a terminal state — useful for nbconvert --execute and doc CI (see :data:~deeporigin.utils.constants.JOB_WATCH_BLOCK_ENV)::

await abfe.watch(blocking=True)
# or: export JOB_WATCH_BLOCK=1

Parameters:

Name	Type	Description	Default
`interval`	`float`	Seconds between polls.	`5.0`
`blocking`	`bool`	When True, await the watch loop instead of returning a background task. Also blocks when `JOB_WATCH_BLOCK` is truthy.	`False`

Returns:

Type	Description
`Task \| None`	The background task when not blocking; `None` when blocking.
`Task \| None`	Cancel a background watch with :meth:`stop_watching` or `task.cancel()`.

deeporigin.drug_discovery.constrained_docking¶

Attributes¶

Classes¶

ConstrainedDocking ¶

Attributes¶

USER_LOG_COLUMNS class-attribute ¶

app instance-attribute ¶

approve_amount instance-attribute ¶

batch_size property ¶

client instance-attribute ¶

completed_at instance-attribute ¶

constraint_energy property ¶

cost property ¶

created_at instance-attribute ¶

created_by instance-attribute ¶

dto property ¶

effort class-attribute instance-attribute ¶

estimate property ¶

id property ¶

ligand property ¶

ligands property ¶

mcs_smarts property ¶

mcs_smiles property ¶

name instance-attribute ¶

pocket property ¶

progress instance-attribute ¶

protein property ¶

reference_ligand property ¶

reference_pose property ¶

runtime property ¶

session instance-attribute ¶

started_at instance-attribute ¶

status instance-attribute ¶

tool_key class-attribute instance-attribute ¶

tool_version instance-attribute ¶

Methods:¶

cancel ¶

confirm ¶

duplicate ¶

from_dto classmethod ¶

from_id classmethod ¶

from_last_run classmethod ¶

get_poses ¶

get_reference_pose ¶

get_results ¶

get_user_logs ¶

list classmethod ¶

run ¶

show ¶

show_box ¶

start ¶

stop_watching ¶

sync ¶

update_from_dto ¶

wait ¶

watch async ¶

Functions:¶

`deeporigin.drug_discovery.constrained_docking`¶

USER_LOG_COLUMNS `class-attribute` ¶

app `instance-attribute` ¶

approve_amount `instance-attribute` ¶

batch_size `property` ¶

client `instance-attribute` ¶

completed_at `instance-attribute` ¶

constraint_energy `property` ¶

cost `property` ¶

created_at `instance-attribute` ¶

created_by `instance-attribute` ¶

dto `property` ¶

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

estimate `property` ¶

id `property` ¶

ligand `property` ¶

ligands `property` ¶

mcs_smarts `property` ¶

mcs_smiles `property` ¶

name `instance-attribute` ¶

pocket `property` ¶

progress `instance-attribute` ¶

protein `property` ¶

reference_ligand `property` ¶

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

from_last_run `classmethod` ¶

list `classmethod` ¶

watch `async` ¶