openmmtools.forces.RadiallySymmetricRestraintForce

class openmmtools.forces.RadiallySymmetricRestraintForce(restraint_parameters, restrained_atom_indices1, restrained_atom_indices2, controlling_parameter_name, *args, **kwargs)

Base class for radially-symmetric restraint force.

Provide facility functions to compute the standard state correction of a receptor-ligand restraint.

To create a subclass, implement the properties restrained_atom_indices1() and restrained_atom_indices2() (with their setters) that return the indices of the restrained atoms.

You will also have to implement _create_bond(), which should add the bond using the correct function/signature.

Optionally, you can implement distance_at_energy() if an analytical expression for distance(potential_energy) exists.

If you subclass this, and plan on adding additional global parameters, you need to invoke this class super().__init__ first as the controlling_parameter_name must be the first global variable.

Parameters:

restraint_parameters : OrderedDict

An ordered dictionary containing the bond parameters in the form parameter_name: parameter_value. The order is important to make sure that parameters can be retrieved from the bond force with the correct force index.

restrained_atom_indices1 : iterable of int

The indices of the first group of atoms to restrain.

restrained_atom_indices2 : iterable of int

The indices of the second group of atoms to restrain.

controlling_parameter_name : str

The name of the global parameter controlling the energy function.

*args, **kwargs

Parameters to pass to the super constructor.

Attributes:

controlling_parameter_name

str: The name of the global parameter controlling the energy function (read-only).

Methods

compute_standard_state_correction(…[, …])	Return the standard state correction of the restraint.
deserialize_xml(xml_serialization)	Shortcut to deserialize the XML representation and the restore interface.
distance_at_energy(potential_energy)	Compute the distance at which the potential energy is potential_energy.
is_restorable(openmm_object)	Check if the custom integrator or force has a restorable interface.
restore_interface(openmm_object)	Restore the original interface of an OpenMM custom force or integrator.

__init__(restraint_parameters, restrained_atom_indices1, restrained_atom_indices2, controlling_parameter_name, *args, **kwargs)

x.__init__(…) initializes x; see help(type(x)) for signature

Methods

__init__(restraint_parameters, …)	x.__init__(…) initializes x; see help(type(x)) for signature
compute_standard_state_correction(…[, …])	Return the standard state correction of the restraint.
deserialize_xml(xml_serialization)	Shortcut to deserialize the XML representation and the restore interface.
distance_at_energy(potential_energy)	Compute the distance at which the potential energy is potential_energy.
is_restorable(openmm_object)	Check if the custom integrator or force has a restorable interface.
restore_interface(openmm_object)	Restore the original interface of an OpenMM custom force or integrator.

Attributes

controlling_parameter_name	str: The name of the global parameter controlling the energy function (read-only).
restrained_atom_indices1	list: The indices of the first group of restrained atoms.
restrained_atom_indices2	list: The indices of the first group of restrained atoms.
restraint_parameters	OrderedDict: The restraint parameters in dictionary form.

compute_standard_state_correction(thermodynamic_state, square_well=False, radius_cutoff=None, energy_cutoff=None, max_volume=None)

Return the standard state correction of the restraint.

The standard state correction is computed as

• log(V_standard / V_restraint)

where V_standard is the volume at standard state concentration and V_restraint is the restraint volume. V_restraint is bounded by the volume of the periodic box.

The square_well parameter, can be used to re-compute the standard state correction when removing the bias introduced by the restraint.

Parameters:

thermodynamic_state : states.ThermodynamicState

The thermodynamic state at which to compute the standard state correction.

square_well : bool, optional

If True, this computes the standard state correction assuming the restraint to obey a square well potential. The energy cutoff is still applied to the original energy potential.

radius_cutoff : simtk.unit.Quantity, optional

The maximum distance achievable by the restraint (units compatible with nanometers). This is equivalent to placing a hard wall potential at this distance.

energy_cutoff : float, optional

The maximum potential energy achievable by the restraint in kT. This is equivalent to placing a hard wall potential at a distance such that potential_energy(distance) == energy_cutoff.

max_volume : simtk.unit.Quantity or ‘system’, optional

The volume of the periodic box (units compatible with nanometer**3). This must be provided the thermodynamic state is in NPT. If the string ‘system’ is passed, the maximum volume is computed from the system box vectors (this has no effect if the system is not periodic).

Returns:

correction : float

The unit-less standard state correction in kT at the given thermodynamic state.

Raises:

TypeError

If the thermodynamic state is in the NPT ensemble, and max_volume is not provided, or if the system is non-periodic and no cutoff is given.

controlling_parameter_name

str: The name of the global parameter controlling the energy function (read-only).

classmethod deserialize_xml(xml_serialization)

Shortcut to deserialize the XML representation and the restore interface.

Parameters:

xml_serialization : str

The XML representation of the OpenMM custom force/integrator.

Returns:

openmm_object

The deserialized OpenMM force/integrator with the original interface restored (if restorable).

distance_at_energy(potential_energy)

Compute the distance at which the potential energy is potential_energy.

Parameters:

potential_energy : simtk.unit.Quantity

The potential energy of the restraint (units of energy/mole).

Returns:

distance : simtk.unit.Quantity

The distance at which the potential energy is potential_energy (units of length).

classmethod is_restorable(openmm_object)

Check if the custom integrator or force has a restorable interface.

Parameters:

openmm_object : object

The custom integrator or force to check.

Returns:

True if the object has a restorable interface, False otherwise.

classmethod restore_interface(openmm_object)

Restore the original interface of an OpenMM custom force or integrator.

The function restore the methods of the original class that inherited from RestorableOpenMMObject. Return False if the interface could not be restored.

Parameters:

openmm_object : object

The object to restore.

Returns:

True if the original class interface could be restored, False otherwise.

restrained_atom_indices1

list: The indices of the first group of restrained atoms.

restrained_atom_indices2

list: The indices of the first group of restrained atoms.

restraint_parameters

OrderedDict: The restraint parameters in dictionary form.