gufe.protocols.protocoldag¶

Functions

execute_DAG(protocoldag, *, shared_basedir, ...)

Locally execute a full ProtocolDAG in serial and in-process.

Classes

`DAGMixin`()
`ProtocolDAG`(*, protocol_units, ...[, ...])	An executable directed acyclic graph (DAG) of `ProtocolUnit` objects.
`ProtocolDAGResult`(*, protocol_units, ...[, ...])	Result for a single execution of an entire `ProtocolDAG`.

class gufe.protocols.protocoldag.DAGMixin¶

property name: str | None¶: Optional identifier.

property graph: DiGraph¶: DAG of ProtocolUnit nodes with edges denoting dependencies.

property protocol_units: list[ProtocolUnit]¶

List of ProtocolUnit s given in DAG-dependency order.

DAG-dependency order guarantees that any task is listed after all of its dependencies.

property transformation_key: GufeKey | None¶

The GufeKey of the Transformation this object performs.

If None, then this object was not created from a Transformation. This may be the case when creating a ProtocolDAG from a Protocol directly, without use of a Transformation object.

This functions as a label, indicating where this object came from.

property extends_key: GufeKey | None¶

The GufeKey of the ProtocolDAGResult this object extends.

If None, then this object does not extend from a result at all.

This functions as a label, indicating where this object came from. It can be used to reconstruct the set of extension relationships between a collection of ProtocolDAGs.

class gufe.protocols.protocoldag.ProtocolDAGResult(*, protocol_units: list[ProtocolUnit], protocol_unit_results: list[ProtocolUnitResult], transformation_key: GufeKey | None, extends_key: GufeKey | None = None, name: str | None = None)¶

Result for a single execution of an entire ProtocolDAG.

There may be many of these for a given Transformation. Data elements from these objects are combined by Protocol.gather into a ProtocolResult.

property result_graph: DiGraph¶

DAG of ProtocolUnitResult nodes with edges denoting dependencies.

Each edge is directed from a task towards its dependencies; for example, an edge between a production run and its equilibration would point towards the equilibration unit.

property protocol_unit_results: list[ProtocolUnitResult]¶

ProtocolUnitResult`s for each `ProtocolUnit used to compute this object.

Results are given in DAG-dependency order. In this order, tasks are always listed after their dependencies.

property protocol_unit_failures: list[ProtocolUnitFailure]¶: A list of all failed units.

Note

These are returned in DAG order, with tasks listed after their dependencies.

property protocol_unit_successes: list[ProtocolUnitResult]¶: A list of only successful ProtocolUnit results.

Note

These are returned in DAG order, with tasks listed after their dependencies.

unit_to_result(protocol_unit: ProtocolUnit) → ProtocolUnitResult¶

Return the successful result for a given Unit.

Returns:

success – the successful result for this Unit

Return type:

ProtocolUnitResult

Raises:

MissingUnitResultError: – if there are no results for that protocol unit
ProtocolUnitFailureError: – if there are only failures for that protocol unit

unit_to_all_results(protocol_unit: ProtocolUnit) → list[ProtocolUnitResult]¶

Return all results (success and failure) for a given Unit.

Returns:: results – results for a given unit
Return type:: list[ProtocolUnitResult]
Raises:: MissingUnitResultError – if no results present for a given unit

result_to_unit(protocol_unit_result: ProtocolUnitResult) → ProtocolUnit¶

ok() → bool¶

property terminal_protocol_unit_results: list[ProtocolUnitResult]¶

Get ProtocolUnitResults that terminate the DAG.

Returns:: All ProtocolUnitResults which do not have a ProtocolUnitResult that follows on (depends) on them.
Return type:: list[ProtocolUnitResult]

class gufe.protocols.protocoldag.ProtocolDAG(*, protocol_units: list[ProtocolUnit], transformation_key: GufeKey | None, extends_key: GufeKey | None = None, name: str | None = None)¶

An executable directed acyclic graph (DAG) of ProtocolUnit objects.

A ProtocolDAG is composed of ProtocolUnit objects as well as how they depend on each other. A single ProtocolDAG execution should yield sufficient information to calculate a free energy difference (though perhaps not converged) between two ChemicalSystem objects.

A ProtocolDAG yields a ProtocolDAGResult when executed.

name¶

Optional identifier for this ProtocolDAGResult.

Type:: str

protocol_units¶

ProtocolUnit`s (given in DAG-dependency order) used to compute this `ProtocolDAGResult. Tasks are always listed after their dependencies.

Type:: list[ProtocolUnit]

graph¶

Graph of ProtocolUnit`s as nodes, with directed edges to each `ProtocolUnit’s dependencies.

Type:: nx.DiGraph

Create a new ProtocolDAG

Parameters:

protocol_units (Iterable[ProtocolUnit]) – The ProtocolUnit s that make up this ProtocolDAG, with dependencies included as inputs.
transformation_key (Optional[GufeKey]) – Key of the Transformation that this ProtocolDAG corresponds to, if applicable. This functions as a label for identifying the source of this ProtocolDAG. This label will be passed on to the ProtocolDAGResult resulting from execution of this ProtocolDAG.
extends_key (Optional[GufeKey]) – Key of the ProtocolDAGResult that this ProtocolDAG extends from. This functions as a label for identifying the source of this ProtocolDAG. This label will be passed on to the ProtocolDAGResult resulting from execution of this ProtocolDAG.
name (str) – Unique identifier for this ProtocolDAG.

gufe.protocols.protocoldag.execute_DAG(protocoldag: ProtocolDAG, *, shared_basedir: Path, scratch_basedir: Path, keep_shared: bool = False, keep_scratch: bool = False, raise_error: bool = True, n_retries: int = 0) → ProtocolDAGResult¶

Locally execute a full ProtocolDAG in serial and in-process.

Parameters:

protocoldag (ProtocolDAG) – The :class:ProtocolDAG to execute.
shared_basedir (Path) – Filesystem path to use for shared space that persists across whole DAG execution. Used by a ProtocolUnit to pass file contents to dependent class:ProtocolUnit instances.
scratch_basedir (Path) – Filesystem path to use for ProtocolUnit scratch space.
keep_shared (bool) – If True, don’t remove shared directories for ProtocolUnit`s after the `ProtocolDAG is executed.
keep_scratch (bool) – If True, don’t remove scratch directories for a ProtocolUnit after it is executed.
raise_error (bool) – If True, raise an exception if a ProtocolUnit fails, default True if False, any exceptions will be stored as ProtocolUnitFailure objects inside the returned ProtocolDAGResult
n_retries (int) – the number of times to attempt, default 0, i.e. try once and only once

Returns:

The result of executing the ProtocolDAG.

Return type:

ProtocolDAGResult