GUFE Transformation API

Alchemical network edges

class gufe.transformations.Transformation(stateA: ChemicalSystem, stateB: ChemicalSystem, protocol: Protocol, mapping: ComponentMapping | list[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: ComponentMapping | list[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

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.

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.

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

classmethod load(file)

Create a Transformation from a JSON file.

Parameters:

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

property mapping: ComponentMapping | list[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.

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.

Alchemical Networks

class gufe.network.AlchemicalNetwork(edges: Iterable[Transformation] | None = None, nodes: Iterable[ChemicalSystem] | None = None, name: str | None = None)

A network with all the information needed for a simulation campaign.

Nodes are ChemicalSystem instances and edges are Transformation instances.

property graph

property edges: frozenset[Transformation]

Network edges as a frozenset of Transformation instances.

property nodes: frozenset[ChemicalSystem]

Network nodes as a frozenset of ChemicalSystem instances.

property name: str | None

Optional identifier for the network.

to_graphml() → str

classmethod from_graphml(str)