deeporigin.drug_discovery.abfe¶
ABFE drives platform tool deeporigin.abfe-end-to-end. Constructor inputs infer workflow
steps the same way as RBFE: protein + ligand runs
["system-prep", "abfe"]; prepared_system runs ["abfe"] only. FEP
simulation settings are shared with RBFE via ABFEParams
(also exported as RBFEParams from rbfe).
ABFE -- class to run and control absolute binding free energy calculations.
Attributes¶
Classes¶
Bases: Execution, AsyncExecutableMixin, NotebookWatchMixin
ABFE workflow (deeporigin.abfe-end-to-end).
Platform steps are inferred from constructor inputs (see :meth:_post_init):
["system-prep", "abfe"]:protein+ligand/ligand1["abfe"]:prepared_system
Attributes:
| Name | Type | Description |
|---|---|---|
steps |
Ordered workflow steps forwarded to the platform tool. |
|
name |
Optional execution label (auto-generated for combined mode). |
Attributes¶
class-attribute
¶
USER_LOG_COLUMNS: list[str] = [
"log_level",
"tool_key",
"timestamp",
"message",
]
property
¶
cost: float | None
Actual cost in dollars, set after execution completes.
This property cannot be set manually.
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.
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.
class-attribute
instance-attribute
¶
tool_key: str = TOOL_KEYS_AND_VERSIONS['abfe']['tool_key']
Methods:¶
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() -> 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
|
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. |
classmethod
¶
from_dto(
dto: dict[str, Any],
*,
client: DeepOriginClient | None = None
) -> Self
Construct an ABFE instance from an execution DTO.
Rehydrates steps, prep inputs, prepared_system, and _params from
stored userInputs (falling back to inputs for older payloads).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dto
|
dict[str, Any]
|
Execution payload (same shape as |
required |
client
|
DeepOriginClient | None
|
Optional API client. Uses the default if not provided. |
None
|
Returns:
| Type | Description |
|---|---|
Self
|
A fully-hydrated ABFE instance with status from the DTO. |
Raises:
| Type | Description |
|---|---|
ValueError
|
When |
classmethod
¶
from_id(
id: str, *, client: DeepOriginClient | None = None
) -> Self
Construct an ABFE 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 ABFE instance with status synced from the platform. |
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
|
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If |
ValueError
|
If no executions exist for this tool type. |
get_prepared_system(
*, ligand1_id: str | None = None
) -> PreparedSystem
Load a :class:PreparedSystem from system-prep results for this execution.
Fetches prepared-system rows scoped to this ABFE execution via
:meth:~deeporigin.drug_discovery.structures.prepared_system.PreparedSystem.from_result.
When multiple rows match, returns the first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ligand1_id
|
str | None
|
Optional ligand ID to filter by. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
PreparedSystem
|
class: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no execution has been started. |
DeepOriginException
|
If no matching system-prep results exist yet. |
get_results(**_kwargs: Any) -> DataFrame | None
Retrieve ABFE results as a DataFrame.
Uses :meth:~deeporigin.drug_discovery.execution.Execution.get_results
(results for this execution by id), then builds a one-row table from the
first deeporigin.abfe-end-to-end record's data payload. System-prep rows
from combined runs are excluded. Keyword arguments are accepted for
signature compatibility with the base class but are not forwarded.
Returns:
| Type | Description |
|---|---|
DataFrame | None
|
A DataFrame with ABFE results, or |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no execution has been started. |
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 |
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 |
DataFrame | None
|
and |
DataFrame | None
|
|
DataFrame | None
|
if this instance has no execution id yet or the client has no |
DataFrame | None
|
|
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 |
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_convergence_time(
*,
run: Literal["binding", "solvation"] = "binding",
repeat: int = 1
) -> None
Display the time-convergence PNG for this execution in Jupyter.
Reads the first data-platform result row for this job (same payload as
client.results.get(compute_job_id=abfe.id)), takes convergence_plot
from binding_analysis or solvation_analysis for the chosen
repeat, downloads via :meth:deeporigin.platform.files.Files.download,
and renders with :class:IPython.display.Image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run
|
Literal['binding', 'solvation']
|
Which leg of the calculation to show: |
'binding'
|
repeat
|
int
|
Repeat index from the tool results (matched to the
|
1
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the execution has no platform id yet. |
DeepOriginException
|
If the run is not complete, results are missing, or no convergence plot path is present for the chosen leg. |
show_overlap_matrix(
*,
run: Literal["binding", "solvation"] = "binding",
repeat: int = 1
) -> None
Display the overlap-matrix PNG for this execution in Jupyter.
Reads the first data-platform result row for this job (same payload as
client.results.get(compute_job_id=abfe.id)), takes
overlap_matrix_plot from binding_analysis or
solvation_analysis for the chosen repeat, downloads via
:meth:deeporigin.platform.files.Files.download, and renders with
:class:IPython.display.Image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run
|
Literal['binding', 'solvation']
|
Which leg of the calculation to show: |
'binding'
|
repeat
|
int
|
Repeat index from the tool results (matched to the
|
1
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the execution has no platform id yet. |
DeepOriginException
|
If the run is not complete, results are missing, or no overlap-matrix plot path is present for the chosen leg. |
show_trajectory(
*,
step: Literal["md", "binding", "solvation"],
window: int = 1,
repeat: int = 1
) -> Any
Visualize an ABFE trajectory in a notebook using Mol*.
Trajectory remote paths are read from this execution's data-platform
results (same payload as client.results.get(compute_job_id=abfe.id)):
for binding or solvation, the per-window
solute_trajectory_20ps.xtc paths under binding_analysis /
solvation_analysis. For md, the equilibration/production MD path
under tool-runs/<id>/protein/ligand/simple_md/... is derived from
those paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
step
|
Literal['md', 'binding', 'solvation']
|
|
required |
window
|
int
|
Lambda window index (1-based). Ignored when |
1
|
repeat
|
int
|
Repeat index from the tool results (matched to the
|
1
|
Returns:
| Type | Description |
|---|---|
Any
|
Notebook display output from :func: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the execution has not been started (no id). |
DeepOriginException
|
If the job is not succeeded, results lack paths,
|
start(
*,
quote: bool = False,
approve_amount: int | None = None,
**kwargs
) -> None
Submit a persisted async execution to the platform.
Only valid when status is None (no execution exists yet).
All other statuses raise immediately to prevent re-submission.
Pass quote=True or approve_amount=0 to request a cost estimate
without running. If the platform returns a Quoted DTO the instance
is left in that state — call :meth:~deeporigin.drug_discovery.execution.Execution.confirm
explicitly to proceed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
quote
|
bool
|
Shorthand for |
False
|
approve_amount
|
int | None
|
Spend cap passed to the platform as |
None
|
**kwargs
|
Forwarded verbatim to |
{}
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the current status is not |
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() -> 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 |
ValueError
|
If the returned 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 |
required |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If |
ValueError
|
If the DTO |
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
|
Returns:
| Type | Description |
|---|---|
dict[str, Any] | None
|
The latest execution DTO, or |
Raises:
| Type | Description |
|---|---|
ValueError
|
If this instance has no execution id yet. |
TimeoutError
|
If |
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 |
False
|
Returns:
| Type | Description |
|---|---|
Task | None
|
The background task when not blocking; |
Task | None
|
Cancel a background watch with :meth: |
dataclass
¶
FEP calculation parameters shared by ABFE and RBFE.
Attributes:
| Name | Type | Description |
|---|---|---|
annihilate |
bool
|
Whether to annihilate the ligand. |
dt |
float
|
Time step in ps. Used for both emeq_md_options and prod_md_options. |
temperature |
float
|
Temperature in K. Used for both emeq_md_options and prod_md_options. |
cutoff |
float
|
Cutoff distance in nm. Used for both emeq_md_options and prod_md_options. |
repeats |
int
|
Number of repeats. |
replex_period_ps |
float
|
Replica exchange period in ps. |
test_run |
int
|
Test run flag. |
binding_n_windows |
int
|
Number of windows for binding calculation. |
binding_npt_reduce_restraints_ns |
float
|
NPT reduce restraints time in ns for binding. |
binding_nvt_heating_ns |
float
|
NVT heating time in ns for binding. |
binding_steps |
int
|
Number of steps for binding calculation. |
solvation_n_windows |
int
|
Number of windows for solvation calculation. |
solvation_npt_reduce_restraints_ns |
float
|
NPT reduce restraints time in ns for solvation. |
solvation_nvt_heating_ns |
float
|
NVT heating time in ns for solvation. |
solvation_steps |
int
|
Number of steps for solvation calculation. |