openmmtools.alchemy.AlchemicalState

class openmmtools.alchemy.AlchemicalState(parameters_name_suffix=None, **kwargs)[source]

Represent an alchemical state.

The alchemical parameters modify the Hamiltonian and affect the computation of the energy. Alchemical parameters that have value None are considered undefined, which means that applying this state to System and Context that have that parameter as a global variable will raise an AlchemicalStateError.

Parameters:
parameters_name_suffix : str, optional

If specified, the state will control a modified version of the global parameters with the name parameter_name + '_' + parameters_name_suffix. When this is the case, the normal parameters are not accessible.

lambda_sterics : float, optional

Scaling factor for ligand sterics (Lennard-Jones and Halgren) interactions (default is 1.0).

lambda_electrostatics : float, optional

Scaling factor for ligand charges, intrinsic Born radii, and surface area term (default is 1.0).

lambda_bonds : float, optional

Scaling factor for alchemically-softened bonds (default is 1.0).

lambda_angles : float, optional

Scaling factor for alchemically-softened angles (default is 1.0).

lambda_torsions : float, optional

Scaling factor for alchemically-softened torsions (default is 1.0).

Examples

Create an alchemically modified system.

>>> from openmmtools import testsystems
>>> factory = AbsoluteAlchemicalFactory(consistent_exceptions=False)
>>> alanine_vacuum = testsystems.AlanineDipeptideVacuum().system
>>> alchemical_region = AlchemicalRegion(alchemical_atoms=range(22))
>>> alanine_alchemical_system = factory.create_alchemical_system(reference_system=alanine_vacuum,
...                                                              alchemical_regions=alchemical_region)

Create a completely undefined alchemical state.

>>> alchemical_state = AlchemicalState()
>>> print(alchemical_state.lambda_sterics)
None
>>> alchemical_state.apply_to_system(alanine_alchemical_system)
Traceback (most recent call last):
...
AlchemicalStateError: The system parameter lambda_sterics is not defined in this state.

Create an AlchemicalState that matches the parameters defined in the System.

>>> alchemical_state = AlchemicalState.from_system(alanine_alchemical_system)
>>> alchemical_state.lambda_sterics
1.0
>>> alchemical_state.lambda_electrostatics
1.0
>>> print(alchemical_state.lambda_angles)
None

AlchemicalState implement the IComposableState interface, so it can be used with CompoundThermodynamicState. All the alchemical parameters are accessible through the compound state.

>>> from simtk import openmm, unit
>>> thermodynamic_state = states.ThermodynamicState(system=alanine_alchemical_system,
...                                                 temperature=300*unit.kelvin)
>>> compound_state = states.CompoundThermodynamicState(thermodynamic_state=thermodynamic_state,
...                                                    composable_states=[alchemical_state])
>>> compound_state.lambda_sterics
1.0

You can control the parameters in the OpenMM Context in this state by setting the state attributes.

>>> compound_state.lambda_sterics = 0.5
>>> integrator = openmm.VerletIntegrator(1.0*unit.femtosecond)
>>> context = compound_state.create_context(integrator)
>>> context.getParameter('lambda_sterics')
0.5
>>> compound_state.lambda_sterics = 1.0
>>> compound_state.apply_to_context(context)
>>> context.getParameter('lambda_sterics')
1.0

You can express the alchemical parameters as a mathematical expression involving alchemical variables. Here is an example for a two-stage function.

>>> compound_state.set_alchemical_variable('lambda', 1.0)
>>> compound_state.lambda_sterics = AlchemicalFunction('step_hm(lambda - 0.5) + 2*lambda * step_hm(0.5 - lambda)')
>>> compound_state.lambda_electrostatics = AlchemicalFunction('2*(lambda - 0.5) * step(lambda - 0.5)')
>>> for l in [0.0, 0.25, 0.5, 0.75, 1.0]:
...     compound_state.set_alchemical_variable('lambda', l)
...     print(compound_state.lambda_sterics)
0.0
0.5
1.0
1.0
1.0
Attributes:
lambda_sterics
lambda_electrostatics
lambda_bonds
lambda_angles
lambda_torsions

Methods

GlobalParameter(parameter_name, standard_value) Descriptor for a global parameter.
apply_to_context(context) Put the Context into this AlchemicalState.
apply_to_system(system) Set the alchemical state of the system to this.
check_system_consistency(system) Check if the system is in this alchemical state.
from_system(system, *args, **kwargs) Constructor reading the state from an alchemical system.
get_alchemical_variable(variable_name) Return the value of the alchemical parameter.
get_function_variable(variable_name) Return the value of the function variable.
set_alchemical_parameters(new_value) Set all defined lambda parameters to the given value.
set_alchemical_variable(variable_name, new_value) Set the value of the alchemical variable.
set_function_variable(variable_name, new_value) Set the value of the function variable.
__init__(parameters_name_suffix=None, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__([parameters_name_suffix]) Initialize self.
apply_to_context(context) Put the Context into this AlchemicalState.
apply_to_system(system) Set the alchemical state of the system to this.
check_system_consistency(system) Check if the system is in this alchemical state.
from_system(system, *args, **kwargs) Constructor reading the state from an alchemical system.
get_alchemical_variable(variable_name) Return the value of the alchemical parameter.
get_function_variable(variable_name) Return the value of the function variable.
set_alchemical_parameters(new_value) Set all defined lambda parameters to the given value.
set_alchemical_variable(variable_name, new_value) Set the value of the alchemical variable.
set_function_variable(variable_name, new_value) Set the value of the function variable.

Attributes

AlchemicalState.lambda_angles
AlchemicalState.lambda_bonds
AlchemicalState.lambda_electrostatics
AlchemicalState.lambda_sterics
AlchemicalState.lambda_torsions
class GlobalParameter(parameter_name, standard_value, validator=None)

Descriptor for a global parameter.

Parameters:
parameter_name : str

The name of the global parameter.

standard_value : float

The value of the global parameter in the standard state. This is used to define the concept of compatible states (i.e. whether a System or Context can be transformed from a state to another).

validator : callable, optional

A function to call before setting a new value with signature validator(self, instance, new_value) -> validated_value. It is also possible to define this through the validator decorator.

Methods

validator  
apply_to_context(context)[source]

Put the Context into this AlchemicalState.

Parameters:
context : simtk.openmm.Context

The context to set.

Raises:
AlchemicalStateError

If the context does not have the required lambda global variables.

apply_to_system(system)[source]

Set the alchemical state of the system to this.

Parameters:
system : simtk.openmm.System

The system to modify.

Raises:
AlchemicalStateError

If the system does not have the required lambda global variables.

check_system_consistency(system)[source]

Check if the system is in this alchemical state.

It raises a AlchemicalStateError if the system is not consistent with the alchemical state.

Parameters:
system : simtk.openmm.System

The system to test.

Raises:
AlchemicalStateError

If the system is not consistent with this state.

classmethod from_system(system, *args, **kwargs)[source]

Constructor reading the state from an alchemical system.

Parameters:
system : simtk.openmm.System

An alchemically modified system in a defined alchemical state.

parameters_name_suffix : str, optional

If specified, the state will search for a modified version of the alchemical parameters with the name parameter_name + '_' + parameters_name_suffix.

Returns:
The AlchemicalState object representing the alchemical state of
the system.
Raises:
AlchemicalStateError

If the same parameter has different values in the system, or if the system has no lambda parameters.

get_alchemical_variable(variable_name)[source]

Return the value of the alchemical parameter.

Parameters:
variable_name : str

The name of the alchemical variable.

Returns:
variable_value : float

The value of the alchemical variable.

get_function_variable(variable_name)[source]

Return the value of the function variable.

Function variables are variables entering mathematical expressions specified with AlchemicalFunction, which can be use to enslave a lambda parameter to arbitrary variables.

Parameters:
variable_name : str

The name of the function variable.

Returns:
variable_value : float

The value of the function variable.

set_alchemical_parameters(new_value)[source]

Set all defined lambda parameters to the given value.

The undefined parameters (i.e. those being set to None) remain undefined.

Parameters:
new_value : float

The new value for all defined parameters.

set_alchemical_variable(variable_name, new_value)[source]

Set the value of the alchemical variable.

Parameters:
variable_name : str

The name of the alchemical variable.

new_value : float

The new value for the variable.

set_function_variable(variable_name, new_value)[source]

Set the value of the function variable.

Function variables are variables entering mathematical expressions specified with AlchemicalFunction, which can be use to enslave a lambda parameter to arbitrary variables.

Parameters:
variable_name : str

The name of the function variable.

new_value : float

The new value for the variable.