Home

MELD OpenMM Plugin

This plugin is primarily intended to support MELD, which is a tool for integrative structural biology. However, it is possible to use the restraints provided in this plugin without using the full MELD package.

The full MELD package and the restraints in this plugin are described more fully in this paper.

Basic Concepts

The restraints in this plugin depend on three basic concepts:

1. Restraints: these couple an energy term to geometric features of the structures, e.g. distances between atom pairs.
2. Groups: these combine multiple restraints into a single collective restraint. Only a user-specified number of restraints within each group will be enforced, while the remainder are ignored (see below).
3. Collections: these are similar to groups, except that collections aggregate together multiple groups into a single collective energy term (see below).

Each restraint must belong to exactly one group. Each group must belong to exactly one collection.

Restraints

MELD features a variety of different restraint types, including harmonic distance restraints, spline-based distance restraints, hyperbolic distance restraints, harmonic torsion restraints, and spline-based phi/psi torsion pair restraints.

Each restraint requires the specification of the atoms involved and a variety of parameters that describe how the energy varies with the geometry.

All of the methods that create restraints will return the restraint index, which is later used to combine restraints into groups.

Groups

Groups serve to combine restraints into multi-body collective restraints. The key feature of a group is that only a user selectable number of restraints, n_active, within the group are active. Only the active restraints contribute their forces and energies to the system. Each tilmestep, the energy and forces for each component restraint of a group are evaluated. The restraints are then sorted by energy. The n_active lowest energy restraints are activated and contribute their forces and energies to the system.

The use of groups allows us to treat ambiguous data, where there are several geometric features that could account for the data. In this case, we combine all of the individual restraints into a group and set n_active=1. This has a similar effect to the "r^-6" restraints that are commonly used in NMR.

Groups are also useful when a collection of data has false positives. In this case, all of the individual restraints are combined into a group, with n_active set to the expected number of true positive signals in the data.

Every restraint must be part of a group, which could be a singleton group containing only that restraint with n_active=1.

When a group is created, the function returns the group index, which is used when creating collections.

Collections

Collections are conceptually similar to groups, except they act at a higher level by combining groups rather than restraints. They provide an extra level of functionality that allows one to further "sculpt" the energy landscape.

Each group must be part of a collection.

A simple example

import meldplugin as mp

meldforce = mp.MeldForce()

# add a few distance restraints
# energy is linear < r1 or > r4
# energy is quadratic between r1 and r2, and r3 and r4
# energy is zero between r2 and r3
r1 = mf.addDistanceRestraint(0,  # zero-based index of atom 1
                             1,  # zero-based index of atom 2
                             0,  # r1 in nm
                             0.1,  # r2 in nm
                             0.1,  # r3 in nm
                             999.,   # r4 in nm
                             1000.0  # force constant in kJ / mol / nm^2
                            )
r2 = mf.addDistanceRestraint(1, 2, 0, 0.1, 0.1, 999., 1000.0)
r3 = mf.addDistanceRestraint(2, 3, 0, 0.1, 0.1, 999., 1000.0)

# now add a group, that enforces the currently-lowest-energy restraint of the three
g1 = mf.addGroup([r1, r2, r3],  # list of restraints
                 1  # n_active
                 )

# now add a collection containing just that restraint
mf.addCollection([g1],  # list of groups
                 1  # n_active
                )

# now add the MeldForce to the system
system.addForce(mf)