class openfe.Transformation(stateA: ChemicalSystem, stateB: ChemicalSystem, protocol: Protocol, mapping: ComponentMapping | list[gufe.mapping.componentmapping.ComponentMapping] | dict[str, gufe.mapping.componentmapping.ComponentMapping] | None = None, name: str | None = None)#

Two chemical states with a method for estimating free energy difference

Connects two ChemicalSystem objects, with directionality, and relates this to a Protocol which will provide an estimate of the free energy difference of moving between these systems. Used as an edge of an AlchemicalNetwork.

Parameters:

  • stateA (ChemicalSystem) – The start (A) and end (B) states of the transformation

  • stateB (ChemicalSystem) – The start (A) and end (B) states of the transformation

  • protocol (Protocol) – The method used to estimate the free energy difference between states A and B

  • mapping (Optional[Union[ComponentMapping, list[ComponentMapping]]]) – the details of any transformations between Component s of the two states

  • name (str, optional) – a human-readable tag for this transformation

property stateA: ChemicalSystem#

The starting ChemicalSystem for the transformation.

property stateB: ChemicalSystem#

The ending ChemicalSystem for the transformation.

property protocol: Protocol#

The protocol used to perform the transformation.

This protocol estimates the free energy differences between stateA and stateB ChemicalSystem objects. It includes all details needed to perform required simulations/calculations and encodes the alchemical pathway used.

property mapping: ComponentMapping | list[gufe.mapping.componentmapping.ComponentMapping] | None#

The mappings relevant for this Transformation

property name: str | None#

Optional identifier for the transformation; used as part of its hash.

Set this to a unique value if adding multiple, otherwise identical transformations to the same AlchemicalNetwork to avoid deduplication.

create(*, extends: ProtocolDAGResult | None = None, name: str | None = None) → ProtocolDAG#

Returns a ProtocolDAG executing this Transformation.protocol.

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

Gather multiple ProtocolDAGResult into a single ProtocolResult.

Parameters:

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

Returns:

Aggregated results from many ProtocolDAGResult objects, all from a given Protocol.

Return type:

ProtocolResult

dump(file)#

Dump this Transformation to a JSON file.

Note that this is not space-efficient: for example, any Component which is used in both ChemicalSystem objects will be represented twice in the JSON output.

Parameters:

file (Union[PathLike, FileLike]) – a pathlike of filelike to save this transformation to.

classmethod load(file)#

Create a Transformation from a JSON file.

Parameters:

file (Union[PathLike, FileLike]) – a pathlike or filelike to read this transformation from