Skip to content

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 -- async-only absolute binding free energy execution.

Usage::

abfe = ABFE(prepared_system=prepared_system)
abfe.quote()
abfe.start()
# Jupyter — non-blocking cell (like legacy Job.watch):
#     task = await abfe.watch()
# Jupyter — block until the job finishes:
#     await abfe.watch_async()
# Script (blocking): asyncio.run(abfe.watch_async())
abfe.sync()
results = abfe.get_results()

Classes

ABFE

Bases: Execution, QuoteMixin, AsyncExecutableMixin, NotebookWatchMixin

Absolute Binding Free Energy calculation (async-only).

Requires a PreparedSystem from system preparation before start().

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 = 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_quote_execution_dto 
get_quote_execution_dto() -> dict[str, Any]

Build the ABFE quote payload and return the tools API execution DTO.

Uses approveAmount=0 via executions.create. Parsing and state assignment are handled by :meth:~deeporigin.drug_discovery.execution_mixins.QuoteMixin._apply_quotation_dto.

Returns:

Type Description
dict[str, Any]

Raw execution dictionary from the platform.
get_results 
get_results() -> DataFrame | None

Retrieve ABFE results as a DataFrame.

Downloads the results CSV from the platform and returns a DataFrame with the binding free energy and related data.

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.

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(
    *, binding_xml_path: str, solvation_xml_path: str
) -> dict

Build the tool input parameters dict.

Parameters:

Name Type Description Default
binding_xml_path str

Remote path to the binding XML file.

 required
solvation_xml_path str

Remote path to the solvation XML file.

 required

Returns:

Type Description
dict

Parameters dict ready to be passed to the ABFE tool.