meld.system.restraints

Implements all of the restraints available in MELD.

This file implements restraints and related classes for MELD. Restraints are the primary way that “extra” forces are added into MELD simulations.

There are several important concepts: restraints, groups, collections, scalers, ramps, positioners, and the restraint manager.

Restraints

Restraints represent “extra” forces that can be added into a MELD simulation. There are many different types of restraints. Each restraint object has a variety of parameters that describe the strength of the force, the atoms involved, and so on.

There are two main types of restraints, SelectableRestraint and NonSelectableRestraint, which have substantially different behavior.

NonSelectableRestraint are “always on”. They may be scaled by scalers and ramps, but the force from each NonSelectableRestraint is independent of other restraints.

SelectableRestraint have forces and energies that depend on other SelectableRestraint. They may be combined into RestraintGroup objects, which allows for the n_active lowest energy restraints to be active at each timestep. The remaining restraints are inactive and do not contribute their forces or energy to the system for that timestep. This selectable nature allows for the implmentation of very flexible restraint strategies useful for a variety of problems in structural biology 1, 2.

The standard way to create a restraint is using their RestraintManager.create_restraint() with the appropriate restraint key:

>>> r = system.restraints.create_restraint(rest_key, params...)

Groups

SelectableRestraint must be part of a RestraintGroup. Each timestep, the restraints are sorted by energy and the num_active restraints with the lowest energy are activated for the timestep, while the rest are ignored. It is not possible to add a NonSelectableRestraint to a RestraintGroup.

RestraintGroups are created by:

>>> g = system.restraints.create_restraint(list_of_restraints, num_active)

Collections

There are two types of collection: always on, and selectively active.

Restraints that will always be active are added to a single always on collection. The standard ways to do this are:

>>> system.restraints.add_as_always_active(restraint)
>>> system.restraints.add_as_always_active_list(list_of_restraints)

Restraints or groups of restraints that will be selected are added to selectively active collections. A mix of bare SelectableRestraint or RestraintGroup objects may be added. When bare restraints are added, they are automatically placed into a group containing only that with restraint with num_active=1. The standard way to create a restraint group is:

>>> system.restraints.add_selectively_active_collection(
        list_of_restraints_and_groups, num_active)

Scalers

Each replica in a MELD simulation has a value alpha that runs from 0.0 to 1.0, inclusive. The lowest replica always has alpha=0, while the highest has alpha=1. The strength of restraints can be scaled by specifying a Scaler that maps alpha into a scaling of the force constant.

Scalers are created and added to a restraint by:

>>> scaler = system.restraints.create_scaler(scaler_key, params...)
>>> r = system.restraints.create_restraint(rest_key, scaler=scaler, params...)

Ramps

Ramps are similar to Scalers, except that they map the step of the simulation into a scaling of the force constant. They are typically used to slowly turn on forces at the start of a simulation.

Ramps are created and added to a restraint by:

>>> ramp = system.restraints.create_scaler(ramp_key, params...)
>>> r = system.restraints.create_restraint(rest_key, ramp=ramp, params...)

Note

Despite the name, ramps are created with the create_scaler() method.

Positioners

Positioners are used to control the position or distance in a restraint. They function similar to Scalers, but rather than returning a value in [0, 1], they return a value from a defined range.

Positioners are created and added to a restraint by:

>>> positioner = system.restraints.create_scaler(pos_key, params...)
>>> r = system.restraints.create_restraint(
        rest_key, param=positioner, params...)

Note

Despite the name, positioners are created with the create_scaler method.

Restraint Manager

The System object maintains a RestraintManager object, which is the primary means for interacting with restraints. Generally, restraints, groups, scalers, etc are created through the RestraintManager, rather than by direct construction.

References

1

J.L. MacCallum, A. Perez, and K.A. Dill, Determining protein structures by combining semireliable data with atomistic physical models by Bayesian inference, PNAS, 2015, 112(22), pp.6985–6990.

2

A. Perez, J.L. MacCallum, and K.A. Dill, Accelerating molecular simulations of proteins using Bayesian inference on weak information, PNAS, 2015, 112(38), pp. 11846–11851.

Classes

AbsoluteCOMRestraint(system, scaler, ramp, ...)	Restraint on the distance between a group and a point in space
AlwaysActiveCollection()	A collection of restraints that are always on
COMRestraint(system, scaler, ramp, group1, ...)	Restraint on the distance between two groups along selected axes
CartesianRestraint(system, scaler, ramp, ...)	Cartesian restraint on xyz coordinates
ConfinementRestraint(system, scaler, ramp, ...)	Confinement restraint from origin
DensityRestraint(system, scaler, ramp, atom, ...)
DistProfileRestraint(system, scaler, ramp, ...)	A spline-based distance profile restraint between two atoms
DistanceRestraint(system, scaler, ramp, ...)	Restrain the distance between two groups
GMMDistanceRestraint(system, scaler, ramp, ...)	Restrain multiple distances using Gaussian mixture models
GMMParams(n_components, n_distances, atoms, ...)
HyperbolicDistanceRestraint(system, scaler, ...)	Hyperbolic distance restraint between two atoms
NonSelectableRestraint()	Abstract class for non-selectable restraints.
RdcRestraint(system, scaler, ramp, atom1, ...)	Residual Dipolar Coupling Restraint
Restraint()	Abstract class for all restraints.
RestraintGroup(rest_list, num_active)	A group of selectable restraints
RestraintManager(system)	A class to manage restraints for a System
SelectableRestraint()	Abstract class for selectable restraints.
SelectivelyActiveCollection(restraint_list, ...)	A collection of RestraintGroup that are selectively active
TorsProfileRestraint(system, scaler, ramp, ...)	A spline-based restraint between two torsions over eight atoms
TorsionRestraint(system, scaler, ramp, ...)	A Torsion restraint between four atoms
YZCartesianRestraint(system, scaler, ramp, ...)	Cartesian restraint on yz coordinates only