`deeporigin.drug_discovery.abfe`¶

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.

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

Classes¶

ABFE ¶

Bases: Execution, QuoteMixin, AsyncExecutableMixin, NotebookWatchMixin

Absolute Binding Free Energy calculation (async-only).

Requires a PreparedSystem from system preparation before start(). After success, :meth:show_trajectory can download trajectory and structure files and open a Mol* viewer in Jupyter (or marimo), and :meth:show_overlap_matrix / :meth:show_convergence_time can display binding or solvation diagnostic PNGs from the ABFE result row for this execution.

Attributes:

Name	Type	Description
`prepared_system`		Prepared system containing binding and solvation XML paths.
`name`		Execution label, set from platform entities when IDs are present unless overridden.

Attributes¶

name `instance-attribute` ¶

name = (
    name
    if name is not None
    else _abfe_default_name(
        prepared_system=prepared_system, client=client
    )
)

params `property` `writable` ¶

params: ABFEParams

ABFE calculation parameters (read-only).

prepared_system `instance-attribute` ¶

prepared_system = prepared_system

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

tool_key: str = TOOL_KEYS_AND_VERSIONS['abfe']['tool_key']

tool_version `instance-attribute` ¶

tool_version = tool_version

Functions¶

from_dto `classmethod` ¶

from_dto(
    dto: dict, *, client: DeepOriginClient | None = None
) -> Self

Construct an ABFE instance from an execution DTO.

Rehydrates prepared_system and _params from the stored userInputs and metadata.

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 ABFE instance with status from the DTO.

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_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 record's data payload. 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.

ABFEParams `dataclass` ¶

ABFE calculation parameters.

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.

Attributes¶

annihilate `class-attribute` `instance-attribute` ¶

annihilate: bool = True

binding_n_windows `class-attribute` `instance-attribute` ¶

binding_n_windows: int = 48

binding_npt_reduce_restraints_ns `class-attribute` `instance-attribute` ¶

binding_npt_reduce_restraints_ns: float = 2.0

binding_nvt_heating_ns `class-attribute` `instance-attribute` ¶

binding_nvt_heating_ns: float = 1.0

binding_steps `class-attribute` `instance-attribute` ¶

binding_steps: int = 1250000

cutoff `class-attribute` `instance-attribute` ¶

cutoff: float = 0.9

dt `class-attribute` `instance-attribute` ¶

dt: float = 0.004

repeats `class-attribute` `instance-attribute` ¶

repeats: int = 1

replex_period_ps `class-attribute` `instance-attribute` ¶

replex_period_ps: float = 2.5

solvation_n_windows `class-attribute` `instance-attribute` ¶

solvation_n_windows: int = 32

solvation_npt_reduce_restraints_ns `class-attribute` `instance-attribute` ¶

solvation_npt_reduce_restraints_ns: float = 0.2

solvation_nvt_heating_ns `class-attribute` `instance-attribute` ¶

solvation_nvt_heating_ns: float = 0.1

solvation_steps `class-attribute` `instance-attribute` ¶

solvation_steps: int = 500000

temperature `class-attribute` `instance-attribute` ¶

temperature: float = 298.15

test_run `class-attribute` `instance-attribute` ¶

test_run: int = 0

Functions¶

to_dict ¶

to_dict(*, prepared_system: PreparedSystem) -> dict

Build the tool input parameters dict.

Parameters:

Name	Type	Description	Default
`prepared_system`	`PreparedSystem`	Prepared system with XML paths and entity IDs (same shape as system-prep `system` output).	required

Returns:

Type	Description
`dict`	Parameters dict ready to be passed to the ABFE tool.

deeporigin.drug_discovery.abfe¶

Classes¶

ABFE ¶

Attributes¶

name instance-attribute ¶

params property writable ¶

prepared_system instance-attribute ¶

tool_key class-attribute instance-attribute ¶

tool_version instance-attribute ¶

Functions¶

from_dto classmethod ¶

from_id classmethod ¶

get_results ¶

show_convergence_time ¶

show_overlap_matrix ¶

show_trajectory ¶

ABFEParams dataclass ¶

Attributes¶

annihilate class-attribute instance-attribute ¶

binding_n_windows class-attribute instance-attribute ¶

binding_npt_reduce_restraints_ns class-attribute instance-attribute ¶

binding_nvt_heating_ns class-attribute instance-attribute ¶

binding_steps class-attribute instance-attribute ¶

cutoff class-attribute instance-attribute ¶

dt class-attribute instance-attribute ¶

repeats class-attribute instance-attribute ¶

replex_period_ps class-attribute instance-attribute ¶

solvation_n_windows class-attribute instance-attribute ¶

solvation_npt_reduce_restraints_ns class-attribute instance-attribute ¶

solvation_nvt_heating_ns class-attribute instance-attribute ¶

solvation_steps class-attribute instance-attribute ¶

temperature class-attribute instance-attribute ¶

test_run class-attribute instance-attribute ¶

Functions¶

to_dict ¶

`deeporigin.drug_discovery.abfe`¶

name `instance-attribute` ¶

params `property` `writable` ¶

prepared_system `instance-attribute` ¶

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

tool_version `instance-attribute` ¶

from_dto `classmethod` ¶

from_id `classmethod` ¶

ABFEParams `dataclass` ¶

annihilate `class-attribute` `instance-attribute` ¶

binding_n_windows `class-attribute` `instance-attribute` ¶

binding_npt_reduce_restraints_ns `class-attribute` `instance-attribute` ¶

binding_nvt_heating_ns `class-attribute` `instance-attribute` ¶

binding_steps `class-attribute` `instance-attribute` ¶

cutoff `class-attribute` `instance-attribute` ¶

dt `class-attribute` `instance-attribute` ¶

repeats `class-attribute` `instance-attribute` ¶

replex_period_ps `class-attribute` `instance-attribute` ¶

solvation_n_windows `class-attribute` `instance-attribute` ¶

solvation_npt_reduce_restraints_ns `class-attribute` `instance-attribute` ¶

solvation_nvt_heating_ns `class-attribute` `instance-attribute` ¶

solvation_steps `class-attribute` `instance-attribute` ¶

temperature `class-attribute` `instance-attribute` ¶

test_run `class-attribute` `instance-attribute` ¶