Skip to main content

Enabling the use of restraints in alchemical simulations

Project description


GH Actions CI codecov DOI Powered by MDAnalysis

A framework for generating restraints for MD simulations (from MD simulations).

The code currently implements a means of deriving Boresch-style restraints, with exporters for GROMACS. There is also experimental code for COM based restraints (i.e. harmonic distance or hard wall), which export to the gromacs pull code. These experimental implementations have yet to be completely tested.

In future implementations we aim to expand to other MD engines (notably OpenMM support will be coming in the near future as part of efforts to support the work done by OpenFE).

We also aim to eventually implement the following restraint types:

  • Attach Pull Restraint style restraints
  • Arbitrary multidimensional restraints (will require API overhaul)

Note: This is non-mature code, a lot is left to do and major changes will happen at any time.


Installation can either be done via PyPi or from source.

To install the latest release via PyPi do:

pip install MDRestraintsGenerator

Installing the latest development code from source can be done using the following:

git clone
cd MDRestraintsGenerator
pip install .

How to use

The code currently focuses on implementing a means of deriving Boresch restraints for GROMACS simulations. To achieve this, the following underlying methods are provided:

  1. A function to pick stable points in ligands for restraint attachment (search.find_ligand_atoms).
  2. A class for picking host restraint addition points (search.FindHostAtoms).
  3. A class for analysing a list of possible Boresch restraints over a given MD simulation and finding the most stable choice of restraint atoms (restraints.FindBoreschRestraint).

Boresch restraints are implemented under the BoreschRestraint class. When using restraints.FindBoreschRestraint, once run (using the run() method), the preffered restraint will be stored as such an object under the restraint attribute. The BoreschRestraint class offers three useful methods:

  1. The plot() function which outputs images of the distributions for the each component of the Boresch restraint (one bond, two angles, three dihedrals). In addition to the histograms, indicating both the mean and the picked frame positions, Q Q plots are also given to show how close to normality the distribution is. The latter can be useful when trying to work out if the chosen variable may occupy different binding orientations.
  2. The write() function, which writes out the ClosestRestraint.gro and files. These are based on the "picked frame", either user supplied or, in most cases, automatically obtained via the FindBoreschRestraint routine as the "frame closest to the mean across all bond/angle/dihedral distributions". This .gro file outputs the system at that frame, and the .top file contains the "intermoecular_interactions" section of a GROMACS .top file. This can then be pasted into an existing .top file to apply the restraint.
  3. The standard_state function, which currently resturns the analytical standard state correction for the restraint addition.

An example use script is provided under Documentation docstrings are provided for all functions and classes. These can be accessed by calling help(function).


A set of unit tests are provided under MDRestraintsGenerator.tests. To run these you will need to have pytest installed. The tests can be run in the following manner:

pytest -v MDRestraintsGenerator.tests


  • MDAnalysis
  • NumPy
  • SciPy
  • Matplotlib


Copyright (c) 2020, Irfan Alibay


To cite this code, please refer the following:

Project based on the Computational Molecular Science Python Cookiecutter version 1.3.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

MDRestraintsGenerator-0.2.1.tar.gz (7.6 MB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page