Skip to content

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 use ABFEParams. RBFE uses a separate RBFEParams type with relative-FEP window defaults.

ABFE -- class to run and control absolute binding free energy calculations.

Attributes

ABFEWorkflowStep module-attribute 

ABFEWorkflowStep = Literal['system-prep', 'abfe']

Classes

ABFE

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

add_h_atoms instance-attribute 
add_h_atoms = add_h_atoms
ligand1 instance-attribute 
ligand1 = ligand if ligand is not None else ligand1
name instance-attribute 
name = name
padding instance-attribute 
padding = padding
params property writable 
params: ABFEParams

FEP calculation parameters (read-only).

prepared_system instance-attribute 
prepared_system = prepared_system
protein instance-attribute 
protein = protein
protonate_protein instance-attribute 
protonate_protein = protonate_protein
retain_waters instance-attribute 
retain_waters = retain_waters
tool_key class-attribute instance-attribute 
tool_key: str = TOOL_KEYS_AND_VERSIONS['abfe']['tool_key']
tool_version instance-attribute 
tool_version = tool_version

Methods:

from_dto 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 client.executions.get).

 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 steps is missing or unsupported.
from_id 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.
get_prepared_system 
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:PreparedSystem with paths and metadata from the result row.

Raises:

Type Description
ValueError

If no execution has been started.
DeepOriginException

If no matching system-prep results exist yet.
get_results 
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 None if not yet available.

Raises:

Type Description
ValueError

If no execution has been started.
show_convergence_time 
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" or "solvation".

 'binding'
repeat int

Repeat index from the tool results (matched to the repeat field when present, otherwise 1-based index into the analysis list). Same semantics as :meth:show_trajectory.

 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 
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" or "solvation".

 'binding'
repeat int

Repeat index from the tool results (matched to the repeat field when present, otherwise 1-based index into the analysis list). Same semantics as :meth:show_trajectory.

 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 
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']

md for the post-prep MD segment; binding or solvation for a lambda window from the corresponding leg.

 required
window int

Lambda window index (1-based). Ignored when step is md.

 1
repeat int

Repeat index from the tool results (matched to the repeat field when present, otherwise 1-based index into the analysis list).

 1

Returns:

Type Description
Any

Notebook display output from :func:deeporigin.utils.notebook.render_html.

Raises:

Type Description
ValueError

If the execution has not been started (no id).
DeepOriginException

If the job is not succeeded, results lack paths, window is invalid, or no system PDB can be resolved.