class openfe.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.


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

result_cls: type[gufe.protocols.protocol.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: dict[str, gufe.mapping.componentmapping.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.

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

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

  • mapping (Optional[dict[str, 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.


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

Return type:


gather(protocol_dag_results: Iterable[ProtocolDAGResult]) ProtocolResult#

Gather multiple ProtocolDAGResults into a single ProtocolResult.


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


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

Return type: