GUFE Protocol API#

Alchemical transforms and their results#

class gufe.protocols.Protocol(settings: Settings)#

A protocol that implements an alchemical transformation.

Takes a Settings object customised for this protocol on init. This configures the protocol for repeated execution on (pairs of) ChemicalSystem objects.

This is an abstract base class; individual Protocol implementations should be subclasses of this class. The following methods should be implemented in any subclass:

  • _create

  • _gather

  • _default_settings

Create a new Protocol instance.

Parameters:

settings (Settings) – The full settings for this Protocol instance.

result_cls: type[ProtocolResult]#

Corresponding ProtocolResult subclass.

property settings: Settings#

The full settings for this Protocol instance.

classmethod default_settings() → Settings#

Get the default settings for this Protocol.

These can be modified and passed in as the settings for a new Protocol instance.

create(*, stateA: ChemicalSystem, stateB: ChemicalSystem, mapping: ComponentMapping | list[ComponentMapping] | None, extends: ProtocolDAGResult | None = None, name: str | None = None, transformation_key: GufeKey | None = None) → ProtocolDAG#

Prepare a ProtocolDAG with all information required for execution.

A ProtocolDAG is composed of ProtocolUnit`s, with dependencies established between them. These form a directed, acyclic graph, and each `ProtocolUnit can be executed once its dependencies have completed.

A ProtocolDAG can be passed to a Scheduler for execution on its resources. A ProtocolDAGResult can be retrieved from the Scheduler upon completion of all ProtocolUnit`s in the `ProtocolDAG.

Parameters:

  • stateA (ChemicalSystem) – The starting ChemicalSystem for the transformation.

  • stateB (ChemicalSystem) – The ending ChemicalSystem for the transformation.

  • mapping (Optional[Union[ComponentMapping, list[ComponentMapping]]]) – Mappings of e.g. atoms between a labelled component in the stateA and stateB ChemicalSystem .

  • extends (Optional[ProtocolDAGResult]) – If provided, then the ProtocolDAG produced will start from the end state of the given ProtocolDAGResult. This allows for extension from a previously-run ProtocolDAG.

  • name (Optional[str]) – A user supplied identifier for the resulting DAG

  • transformation_key (Optional[GufeKey]) – Key of the Transformation that this Protocol corresponds to, if applicable. This will be used to label the resulting ProtocolDAG, and can be used for identifying its source. This label will be passed on to the ProtocolDAGResult resulting from execution of this ProtocolDAG.

Returns:

A directed, acyclic graph that can be executed by a Scheduler.

Return type:

ProtocolDAG

gather(protocol_dag_results: Iterable[ProtocolDAGResult]) → ProtocolResult#

Gather multiple ProtocolDAGResults into a single ProtocolResult.

Parameters:

protocol_dag_results (Iterable[ProtocolDAGResult]) – The ProtocolDAGResult objects to assemble aggregate quantities from.

Returns:

Aggregated results from many ProtocolDAGResult`s from a given `Protocol.

Return type:

ProtocolResult

class gufe.protocols.ProtocolResult(**data)#

Container for all results for a single Transformation.

Contains a collection of ProtocolDAGResult instances. This is an abstract base class; individual Protocol implementations should have a corresponding subclass of ProtocolResult implemented as well.

The following methods should be implemented in any subclass: - get_estimate - get_uncertainty

property data: dict[str, Any]#

Aggregated data contents from multiple ProtocolDAGResult instances.

The structure of this data is specific to the Protocol subclass each ProtocolResult subclass corresponds to.

abstract get_estimate() → Quantity#
abstract get_uncertainty() → Quantity#

Directed acylic graphs of work#

class gufe.protocols.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

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:

Union[GufeKey, None]

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:

Optional[GufeKey]

Create a new ProtocolDAG.

Parameters:

  • protocol_units (Iterable[ProtocolUnit]) – The ProtocolUnit`s that make up this `ProtocolDAG, with dependencies included as inputs.

  • name (str) – Unique identifier for this ProtocolDAG.

class gufe.protocols.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: networkx.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:

KeyError – if either there are no results, or only failures

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

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

Returns:

results – results for a given unit

Return type:

list[ProtocolUnitResult]

Raises:

KeyError – 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]

Individual units of work#

class gufe.protocols.ProtocolUnit(*, name: str | None = None, **inputs)#

A unit of work within a ProtocolDAG.

Create an instance of a ProtocolUnit.

Parameters:

  • name (str) – Custom name to give this

  • **inputs – Keyword arguments, which can include other ProtocolUnit`s on which this `ProtocolUnit is dependent. Should be either gufe objects or JSON-serializables.

property name: str | None#

Optional name for the ProtocolUnit.

property inputs: Dict[str, Any]#

Inputs to the ProtocolUnit.

Includes any ProtocolUnit instances this ProtocolUnit depends on.

property dependencies: list[ProtocolUnit]#

All units that this unit is dependent on (parents)

execute(*, context: Context, raise_error: bool = False, **inputs) → ProtocolUnitResult | ProtocolUnitFailure#

Given ProtocolUnitResult s from dependencies, execute this ProtocolUnit.

Parameters:

  • context (Context) – Execution context for this ProtocolUnit; includes e.g. shared and scratch Path s.

  • raise_error (bool) – If True, raise any errors instead of catching and returning a ProtocolUnitFailure default False

  • **inputs – Keyword arguments giving the named inputs to _execute. These can include ProtocolUnitResult objects from ProtocolUnit objects this unit is dependent on.

class gufe.protocols.ProtocolUnitResult(*, name: str | None = None, source_key: GufeKey, inputs: Dict[str, Any], outputs: Dict[str, Any], start_time: datetime.datetime | None = None, end_time: datetime.datetime | None = None)#

Successful result of a single ProtocolUnit execution.

Parameters:

  • name (Optional[str]) – Name of the ProtocolUnit that produced this ProtocolUnitResult.

  • source_key (GufeKey) – Key of the ProtocolUnit that produced this ProtocolUnitResult

  • inputs (Dict[str, Any]) – Inputs to the ProtocolUnit that produced this ProtocolUnitResult. Includes any ProtocolUnitResult`s this `ProtocolUnitResult is dependent on.

  • outputs (Dict[str, Any]) – Outputs from the ProtocolUnit._execute that generated this ProtocolUnitResult.

  • start_time (datetime.datetime) – The start and end time for executing this Unit

  • end_time (datetime.datetime) – The start and end time for executing this Unit

property name#
property source_key#
property inputs#
property outputs#
property dependencies: list[ProtocolUnitResult]#

All results that this result was dependent on

static ok() → bool#
property start_time: datetime | None#

The time execution of this Unit began

property end_time: datetime | None#

The time at which execution of this Unit finished

class gufe.protocols.ProtocolUnitFailure(*, name=None, source_key, inputs, outputs, _key=None, exception, traceback, start_time: datetime.datetime | None = None, end_time: datetime.datetime | None = None)#

Failed result of a single ProtocolUnit execution.

Parameters:

  • name (Optional[str]) – Name of the ProtocolUnit that produced this ProtocolUnitResult.

  • source_key (GufeKey) – Key of the ProtocolUnit that produced this ProtocolUnitResult

  • inputs (Dict[str, Any]) – Inputs to the ProtocolUnit that produced this ProtocolUnitResult. Includes any ProtocolUnitResult this ProtocolUnitResult was dependent on.

  • outputs (Dict[str, Any]) – Outputs from the ProtocolUnit._execute that generated this ProtocolUnitResult.

  • exception (Tuple[str, Tuple[Any, ...]]) – A tuple giving details on the exception raised during ProtocolUnit execution. The first element gives the type of exception raised; the second element is a tuple giving the exception’s args values.

  • traceback (str) – The traceback given by the exception.

property exception: Tuple[str, Tuple[Any, ...]]#
property traceback: str#
static ok() → bool#
property dependencies: list[ProtocolUnitResult]#

All results that this result was dependent on

property end_time: datetime | None#

The time at which execution of this Unit finished

property inputs#
property name#
property outputs#
property source_key#
property start_time: datetime | None#

The time execution of this Unit began