class openfe.Protocol(settings: Settings)#

A method that via an alchemical transformation estimates free energy difference

Takes a Settings object customised for this protocol on creation. 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

Parameters:

settings (Settings) – The parameters for this particular method. This will be a specialised subclass for this particular Protocol.

Note

Once the Protocol object is created, the input Settings are frozen, so should be finalised before creating the Protocol instance.

result_cls: type[gufe.protocols.protocol.ProtocolResult]#

Corresponding ProtocolResult subclass.

property settings: Settings#

A read-only view of the settings for this Protocol instance.

classmethod default_settings() → Settings#

Get the default settings for this Protocol.

These represent the current best-practices for the use of this particular method. These can be modified and passed in as the only argument for creating a new Protocol instance.

create(*, stateA: ChemicalSystem, stateB: ChemicalSystem, mapping: ComponentMapping | list[gufe.mapping.componentmapping.ComponentMapping] | 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.

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