gufe.transformations.transformation¶

Classes

`NonTransformation`(system, protocol[, name, ...])	A non-alchemical edge of an alchemical network.
`Transformation`(stateA, stateB, protocol[, ...])	Two chemical states with a method for estimating the free energy difference between them.
`TransformationBase`(protocol[, name])	Transformation base class.

class gufe.transformations.transformation.TransformationBase(protocol: Protocol, name: str | None = None)¶

Transformation base class.

Parameters:

protocol (Protocol) – The sampling method to use for the transformation.
name (str, optional) – A human-readable name 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.

abstract property stateA: ChemicalSystem¶: The starting ChemicalSystem for the transformation.

abstract property stateB: ChemicalSystem¶: The ending ChemicalSystem for the transformation.

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

property protocol: Protocol¶

The Protocol used to perform the transformation.

The 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 or non-alchemical pathway used.

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

Gather multiple ProtocolDAGResult s 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.transformation.Transformation(stateA: ChemicalSystem, stateB: ChemicalSystem, protocol: Protocol, mapping: ComponentMapping | list[ComponentMapping] | dict[str, ComponentMapping] | None = None, name: str | None = None, validate: bool = False)¶

Two chemical states with a method for estimating the free energy difference between them.

Connects two ChemicalSystem objects, with directionality, and relates these to a Protocol which will provide an estimate of the free energy difference 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 name for this transformation.
validate (bool, optional) – Whether or not to validate the inputs to be provided to the Protocol.

See also

Protocol.validate()

property stateA: ChemicalSystem¶: The starting ChemicalSystem for the transformation.

property stateB: ChemicalSystem¶: The ending ChemicalSystem for the transformation.

property mapping: ComponentMapping | list[ComponentMapping] | None¶: The mappings relevant for this Transformation

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

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 s 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 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 protocol: Protocol¶

The Protocol used to perform the transformation.

class gufe.transformations.transformation.NonTransformation(system: ChemicalSystem, protocol: Protocol, name: str | None = None, validate: bool = False)¶

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.

Parameters:

system (ChemicalSystem) – The system to be sampled, acting as both the starting and end state of the NonTransformation.
protocol (Protocol) – The sampling method to use on the system
name (str, optional) – A human-readable name for this transformation.
validate (bool, optional) – Whether or not to validate the inputs to be provided to the Protocol.

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 s 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 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 protocol: Protocol¶

The Protocol used to perform the transformation.

property stateA: ChemicalSystem¶

The ChemicalSystem this NonTransformation samples.

Synonymous with system attribute and identical to stateB.

property stateB: ChemicalSystem¶

The ChemicalSystem this NonTransformation samples.

Synonymous with system attribute and identical to stateA.

property system: ChemicalSystem¶: The ChemicalSystem this “transformation” samples.

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