# 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 RestraintGroups, 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 RestraintMangaer.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 is:

>>> system.restraints.add_as_always_active(restraint)


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: 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: 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 Base class for all scalers. 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, …) ConstantPositioner(value) Always returns the supplied value. TimeRamp that always returns 1.0 This scaler is “always on” and always returns a value of 1.0”. DistProfileRestraint(system, scaler, ramp, …) 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, …) GeometricScaler(alpha_min, alpha_max, …) HyperbolicDistanceRestraint(system, scaler, …) LinearPositioner(alpha_min, alpha_max, …) Position restraints linearly within a range LinearRamp(start_time, end_time, …) TimeRamp that interpolates linearly LinearScaler(alpha_min, alpha_max[, …]) This scaler linearly interpolates between 0 and 1 from alpha_min to alpha_max. NonLinearRamp(start_time, end_time, …) TimeRamp that interpolates non-linearly NonLinearScaler(alpha_min, alpha_max, factor) NonSelectableRestraint Abstract class for non-selectable restraints. PlateauLinearScaler(alpha_min, alpha_one, …) PlateauNonLinearScaler(alpha_min, alpha_one, …) PlateauSmoothScaler(alpha_min, alpha_one, …) Base class for all positioner classes. RdcRestraint(system, scaler, ramp, …) Restraint Abstract class for all restraints. RestraintGroup(rest_list, num_active) RestraintManager(system) Base class for all resraint scaler classes. ScalerRegistry(name, bases, attrs) SelectableRestraint Abstract class for selectable restraints. SelectivelyActiveCollection(restraint_list, …) Base class for all time ramp classes. TimeRampSwitcher(first_ramp, second_ramp, …) TorsProfileRestraint(system, scaler, ramp, …) TorsionRestraint(system, scaler, ramp, …) YZCartesianRestraint(system, scaler, ramp, …) Cartesian restraint on yz coordinates only
class meld.system.restraints.AbsoluteCOMRestraint(system, scaler, ramp, group, weights, dims, force_const, position)[source]

Restraint on the distance between a group and a point in space

This class implements a restraint on the distance between the center of a group and a point in space.

The weights used to calculate the center can be specified as weights. If None, then the masses of the atoms will be used.

The dims parameter controls which dimensions are used to compute the distance. For example if dims='xyz', then the distance will be the normal distance in all three dimensions. If dims=x, then only the x-component will be considered.

Restraints are typically added using RestraintMangager.create_restraint with the 'abs_com' key:

>>> r = system.restraints.create_restraint('abs_com',
scaler=scaler, ramp=ramp,
group=group,
weights=weights,
dims=dims,
force_const=force_const,
position=position)

Parameters
• system (meld.system.System) – system object used for indexing

• scaler (Scaler or None) – scaler for force constant

• ramp (Ramp or None) – ramp for force constant

• group (list of tuple) – [(res_index, atom_name), (res_index, atom_name)…]

• weights (array_like) – Weights to use when calculating the COM. If None, then the masses will be used.

• dims (string) – combination of x, y, z that determines which dimensions are used when calculating the distance

• force_const (float) – force constant in kJ/mol/nm^2

• point (array_like) – location in space to restrain to

scaler

scaler for the force constant

Type

Scaler

ramp

ramp for the force

Type

Ramp

indices

index of atoms in group

Type

list

weights

Weights used in COM calculation. If None, then the masses will be used.

Type

array_like or None

dims

combination of xyz dimensions used for distance calculation

Type

string

force_const

force constant

Type

float

position

point in space that group is restrained to

Type

array_like

class meld.system.restraints.AlphaMapper[source]

Base class for all scalers.

class meld.system.restraints.AlwaysActiveCollection[source]
class meld.system.restraints.COMRestraint(system, scaler, ramp, group1, group2, weights1, weights2, dims, force_const, distance)[source]

Restraint on the distance between two groups along selected axes

This class implements a restraint on the distance between the center of two groups.

The weights used to calculate the center can be specified as weights1 and weights2. If these are None, then the masses of the atoms will be used.

The dims parameter controls which dimensions are used to compute the distance. For example if dims='xyz', then the distance will be the normal distance in all three dimensions. If dims='x', then only the x-component will be considered.

Restraints are typically added using RestraintMangager.create_restraint with the 'com' key:

>>> r = system.restraints.create_restraint('com', scaler, ramp=ramp,
group1=group1, group2=group2,
weights1=weights1,
weights2=weights2,
dims=dims,
force_const=force_const,
distance=distance)

Parameters
• system (meld.system.System) – system object used for indexing

• scaler (Scaler or None) – scaler for force constant

• ramp (Ramp or None) – ramp for force constant

• group1 (list of tuple) – [(res_index, atom_name), (res_index, atom_name)…]

• group2 (list of tuple) – [(res_index, atom_name), (res_index, atom_name)…]

• weights1 (array_like) – Weights to use when calculating the COM. If None, then the atom masses will be used.

• weights2 (array_like) – Weights to use when calculating the COM. If None, then the atom masses will be used.

• dims (string) – combination of x, y, z that determines which dimensions are used when calculating the distance

• force_const (float) – force constant in kJ/mol/nm^2

• distance (float or Positioner) – distance between groups

scaler

scaler for the force constant

Type

Scaler

ramp

ramp for the force

Type

Ramp

indices1

index of atoms in group 1

Type

list

indices2

index of atoms in group 2

Type

list

weights1

Weights to use when calculating the COM. If None, then the atom masses will be used.

Type

array_like

weights2

Weights to use when calculating the COM. If None, then the atom masses will be used.

Type

array_like

dims

combination of xyz dimensions used for distance calculation

Type

string

force_const

force constant

Type

float

positioner

controls the distance between groups

Type

Positioner

class meld.system.restraints.CartesianRestraint(system, scaler, ramp, res_index, atom_name, x, y, z, delta, force_const)[source]

Cartesian restraint on xyz coordinates

class meld.system.restraints.ConfinementRestraint(system, scaler, ramp, res_index, atom_name, radius, force_const)[source]
class meld.system.restraints.ConstantPositioner(value)[source]

Always returns the supplied value.

class meld.system.restraints.ConstantRamp[source]

TimeRamp that always returns 1.0

class meld.system.restraints.ConstantScaler[source]

This scaler is “always on” and always returns a value of 1.0”.

class meld.system.restraints.DistProfileRestraint(system, scaler, ramp, atom_1_res_index, atom_1_name, atom_2_res_index, atom_2_name, r_min, r_max, n_bins, spline_params, scale_factor)[source]
class meld.system.restraints.DistanceRestraint(system, scaler, ramp, atom_1_res_index, atom_1_name, atom_2_res_index, atom_2_name, r1, r2, r3, r4, k)[source]

Restrain the distance between two groups

The energy is zero between r2 and r3. It increases quadratically between r1 and r2 and between r3 and r4. The energy increases linearly below r1 and above r4.

Parameters
• system (meld.system.System) – system object that restraint belongs to

• scaler (Scaler or None) – A Scaler to vary the force constant with alpha. If None, then a constant 1.0 scaler will be used.

• atom_1_res_index (integer) – residue index starting from 1

• atom_1_name (string) – atom name

• atom_2_res_index (integer) – residue index starting from 1

• atom_2_name (string) – atom name

• r1 (float or Positioner) – in nanometers

• r2 (float or Positioner) – in nanometers

• r3 (float or Positioner) – in nanometers

• r4 (float or Positioner) – in nanometers

• k (float or Positioner) – in $$kJ/mol/nm^2$$

system

system object that restraint belongs to

Type

meld.system.System

scaler

A Scaler to vary the force constant with alpha. If None, then a constant 1.0 scaler will be used.

Type

Scaler or None

ramp

A ramp to vary the force constant with simulation time. If None then a constant 1.0 ramp will be used.

Type

Ramp or None

atom_index_1

atom index starting from 1

Type

int

atom_index_2

atom index starting from 1

Type

int

r1

in nanometers

Type

Positioner

r2

in nanometers

Type

Positioner

r3

in nanometers

Type

Positioner

r4

in nanometers

Type

Positioner

k

in $$kJ/mol/nm^2$$

Type

float

class meld.system.restraints.GMMDistanceRestraint(system, scaler, ramp, n_distances, n_components, atoms, weights, means, precisions)[source]

Restrain multiple distances using Gaussian mixture models

The energy has the form:

E = w1 N1 exp(-0.5 (r-u1)^T P1 (r-u1)) + w2 N2 exp(-0.5 (r-u2)^T P2 (r-u2)) + …

where:

w1, w2, … are the weights N1, N2, … are automatically calculated normalization factors r is the vector of distances for the atom pairs u1, u2, … are the mean vectors for each component P1, P2, … are the precision (inverse covariance) matrices for each component

Parameters
• system (meld.system.System) – system object that restraint belongs to

• scaler (Scaler or None) – A Scaler to vary the force constant with alpha. If None, then a constant 1.0 scaler will be used.

• n_distances (int) – number of distances involved in GMM; max 32

• n_components (int) – number of mixture components; max 32

• atoms ([(res_index, atom_name)]) – a list of (res_index, atom_name) tuples of length 2*n_distances

• weights (array-like, shape(n_components)) – The weights for the mixture components

• means (array-like, shape(n_components, n_distances)) – The means of each mixture component

• precisions (array-like, shape(n_components, n_distances, n_distances)) – The precision (i.e. inverse covariance) of each mixture component

scaler

A Scaler to vary the force constant with alpha. If None, then a constant 1.0 scaler will be used.

Type

Scaler or None

ramp

A ramp to vary the force constant with simulation time. If None then a constant 1.0 ramp will be used.

Type

Ramp or None

n_distances

number of distances involved in restraint

Type

int

n_components

number of mixture components

Type

int

atoms

a list of atom indices of length 2*n_distances

Type

[int]

weights

The weights for the mixture components

Type

array-like, shape(n_components)

means

The means of each mixture component, in nm

Type

array-like, shape(n_components, n_distances)

precisions

The precision (i.e. inverse covariance) of each mixture component, in nm^(-2)

Type

array-like, shape(n_components, n_distances, n_distances)

classmethod from_params(system, scaler, ramp, params)[source]

Create a GMMDistanceRestraint from a GMMParams object.

class meld.system.restraints.GMMParams(n_components, n_distances, atoms, weights, means, precisions)
atoms

Alias for field number 2

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

means

Alias for field number 4

n_components

Alias for field number 0

n_distances

Alias for field number 1

precisions

Alias for field number 5

weights

Alias for field number 3

class meld.system.restraints.GeometricScaler(alpha_min, alpha_max, strength_at_alpha_min, strength_at_alpha_max)[source]
class meld.system.restraints.HyperbolicDistanceRestraint(system, scaler, ramp, atom_1_res_index, atom_1_name, atom_2_res_index, atom_2_name, r1, r2, r3, r4, k, asymptote)[source]
class meld.system.restraints.LinearPositioner(alpha_min, alpha_max, pos_min, pos_max)[source]

Position restraints linearly within a range

class meld.system.restraints.LinearRamp(start_time, end_time, start_weight, end_weight)[source]

TimeRamp that interpolates linearly

class meld.system.restraints.LinearScaler(alpha_min, alpha_max, strength_at_alpha_min=1.0, strength_at_alpha_max=0.0)[source]

This scaler linearly interpolates between 0 and 1 from alpha_min to alpha_max.

class meld.system.restraints.NonLinearRamp(start_time, end_time, start_weight, end_weight, factor)[source]

TimeRamp that interpolates non-linearly

class meld.system.restraints.NonLinearScaler(alpha_min, alpha_max, factor, strength_at_alpha_min=1.0, strength_at_alpha_max=0.0)[source]
class meld.system.restraints.NonSelectableRestraint[source]

Abstract class for non-selectable restraints.

class meld.system.restraints.PlateauLinearScaler(alpha_min, alpha_one, alpha_two, alpha_max, strength_at_alpha_min=1.0, strength_at_alpha_max=0.0)[source]
class meld.system.restraints.PlateauNonLinearScaler(alpha_min, alpha_one, alpha_two, alpha_max, factor, strength_at_alpha_min=1.0, strength_at_alpha_max=0.0)[source]
class meld.system.restraints.PlateauSmoothScaler(alpha_min, alpha_one, alpha_two, alpha_max, strength_at_alpha_min=1.0, strength_at_alpha_max=0.0)[source]
class meld.system.restraints.Positioner[source]

Base class for all positioner classes.

class meld.system.restraints.RdcRestraint(system, scaler, ramp, atom_1_res_index, atom_1_name, atom_2_res_index, atom_2_name, kappa, d_obs, tolerance, force_const, quadratic_cut, weight, expt_index, patcher)[source]
class meld.system.restraints.Restraint[source]

Abstract class for all restraints.

class meld.system.restraints.RestraintManager(system)[source]
class meld.system.restraints.RestraintScaler[source]

Base class for all resraint scaler classes.

class meld.system.restraints.SelectableRestraint[source]

Abstract class for selectable restraints.

class meld.system.restraints.SelectivelyActiveCollection(restraint_list, num_active)[source]
class meld.system.restraints.TimeRamp[source]

Base class for all time ramp classes.

class meld.system.restraints.TimeRampSwitcher(first_ramp, second_ramp, switching_time)[source]
class meld.system.restraints.TorsProfileRestraint(system, scaler, ramp, atom_1_res_index, atom_1_name, atom_2_res_index, atom_2_name, atom_3_res_index, atom_3_name, atom_4_res_index, atom_4_name, atom_5_res_index, atom_5_name, atom_6_res_index, atom_6_name, atom_7_res_index, atom_7_name, atom_8_res_index, atom_8_name, n_bins, spline_params, scale_factor)[source]
class meld.system.restraints.TorsionRestraint(system, scaler, ramp, atom_1_res_index, atom_1_name, atom_2_res_index, atom_2_name, atom_3_res_index, atom_3_name, atom_4_res_index, atom_4_name, phi, delta_phi, k)[source]
class meld.system.restraints.YZCartesianRestraint(system, scaler, ramp, res_index, atom_name, y, z, delta, force_const)[source]

Cartesian restraint on yz coordinates only