GUFE Transformation API#

Alchemical network edges#

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

An edge of an alchemical network.

Connects two ChemicalSystem objects, with directionality.

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 derives 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. May also correspond to an experimental result.

property mapping: dict[str, ComponentMapping] | None#: Mapping of e.g. atoms between stateA and stateB.

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

class gufe.transformations.NonTransformation(system: ChemicalSystem, protocol: Protocol, name: str | None = None)#

Bases: Transformation

A non-alchemical edge of an alchemical network.

A “transformation” that performs no transformation at all. Technically a self-loop, or an edge with the same ChemicalSystem at either end.

Functionally used for applying a dynamics protocol to a ChemicalSystem that performs no alchemical transformation at all. This allows e.g. equilibrium MD to be performed on a ChemicalSystem as desired alongside alchemical protocols between it and and other ChemicalSystem objects.

property stateA#: The starting ChemicalSystem for the transformation.

property stateB#: The ending ChemicalSystem for the transformation.

property system: ChemicalSystem#

property protocol#

The protocol for sampling dynamics of the ChemicalSystem.

Includes all details needed to perform required simulations/calculations.

create(*, extends: ProtocolDAGResult | None = None, name: str | None = None) → ProtocolDAG#: Returns a ProtocolDAG executing this Transformation.protocol.