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]

ProtocolUnitResults 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 ProtocolUnits.

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 ProtocolUnitResult for a given ProtocolUnit, if it exists.

Returns:

success – the successful ProtocolUnitResult for this ProtocolUnit

Return type:

ProtocolUnitResult

Raises:

  • MissingUnitResultError: – if there are no results for that ProtocolUnit

  • ProtocolUnitFailureError: – if there are only failures for that ProtocolUnit

unit_to_all_results(protocol_unit: ProtocolUnit) → list[ProtocolUnitResult]

Return all ProtocolUnitResults (success and failure) for a given ProtocolUnit.

Returns:

results – ProtocolUnitResults for the given ProtocolUnit

Return type:

list[ProtocolUnitResult]

Raises:

MissingUnitResultError – if no ProtocolUnitResults present for the given ProtocolUnit

result_to_unit(protocol_unit_result: ProtocolUnitResult) → ProtocolUnit

Return the ProtocolUnit corresponding to the given ProtocolUnitResult.

Returns:

the ProtocolUnit corresponding to the given ProtocolUnitResult

Return type:

ProtocolUnit

Raises:

MissingUnitResultError – if the given ProtocolUnitResult isn’t present

ok() → bool

Check if this ProtocolDAGResult succeeded or failed.

Returns True if there is at least one successful ProtocolUnitResult for each ProtocolUnit, and False otherwise.

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]

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.

property graph: DiGraph

DAG of ProtocolUnit nodes with edges denoting dependencies.

property name: str | None

Optional identifier.

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.

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.

Properties

namestr

Optional identifier for this ProtocolDAGResult.

protocol_unitslist[ProtocolUnit]

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

graphnx.DiGraph

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

Create a new ProtocolDAG`

param protocol_units:

The ProtocolUnit s that make up this ProtocolDAG, with dependencies included as inputs.

type protocol_units:

Iterable[ProtocolUnit]

param transformation_key:

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.

type transformation_key:

Optional[GufeKey]

param extends_key:

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.

type extends_key:

Optional[GufeKey]

param name:

Unique identifier for this ProtocolDAG.

type name:

str

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.

property graph: DiGraph

DAG of ProtocolUnit nodes with edges denoting dependencies.

property name: str | None

Optional identifier.

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.

gufe.protocols.protocoldag.execute_DAG(protocoldag: ProtocolDAG, *, shared_basedir: Path, scratch_basedir: Path, cache_basedir: Path | None = None, stderr_basedir: Path | None = None, stdout_basedir: Path | None = None, keep_shared: bool = False, keep_scratch: bool = False, keep_cache: 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.

  • cache_basedir (Path | None = None) – Filesystem path to use for ProtocolUnitResult caching during execution. If None (default), results will not be cached and it will not be able to resume DAG execution from the last successfully finished ProtocolUnit.

  • stderr_basedir (Path | None) – Filesystem path to use for ProtocolUnit stderr archiving.

  • stdout_basedir (Path | None) – Filesystem path to use for ProtocolUnit stdout archiving.

  • 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.

  • keep_cache (bool) – If True, don’t remove the cache directory which contains the serialized ProtocolUnitResult for all executed ProtocolUnit/s.

  • 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

Raises:

ProtocolDAGExecutionError – If the ProtocolDAG cannot be executed due to an invalid cache state.