Welcome to restraintMaker’s documentation!

Logo here AutoTest

Welcome to RestraintMaker

RestraintMaker is a tool for MD-simulation restraint preparation. The package can be used to manually pick position - or distance restraints or automatically assign well-spread distance restraint over multiple molecules (e.g., used for dual-topology relative free energy (RFE) calculations). The package can be used either in a scripting mode or with a GUI-based in PyMOL(see [1]).

Introduction

Thanks to recent years’ methodological, software, and hardware improvements, RFE calculations can tackle more and more complex transformations. This development also causes a growing need for more efficient setups of such calculations, namely automatization. We aim to provide a link in the automatization chain which can easily be integrated into python workflows for RFE calculations or used with a GUI in PyMol. RestraintMaker contains a greedy approach to determine good placements of atom distance and/or position restraints based on geometric measures. It can generate distance/position restraints for RFE calculations with a dual state approach, such as TI. Further, it can be used to create distance/position restraints for multistate methods such as Replica Exchange Enveloping Distribution Sampling (RE-EDS) [3,4]. For more details on the history of distance restraints in RFE calculations, the algorithm of RestraintMaker, and an application to the calculation of relative hydration free energies you can check out:

RestraintMaker: a graph-based approach to select distance restraints in free-energy calculations with dual topology; *Ries, B.*; Rieder, S.R.*; Rhiner, C.; Hünenberger, P.H.; Riniker, S - J Comput Aided Mol Des (2022) - Open Access

Content

Development

RestraintMaker is split into two parts:

  • RestraintMaker

    This part is the core of the program. It can be executed as a standalone.

    • algorithm: restraint selecting algorithms

    • tools_RDKit: additional functions for filtering or selecting (see [2])

    • io: writing/importing outputfiles

    • utils

  • Interface PyMOL:

    Allows interfacing to PyMOL and generates the GUI-Expierence (see [1])

Installation

You can retrieve the repository from GitHub: https://github.com/rinikerlab/restraintmaker

  • Install with Anaconda

#!/usr/bash
# 1. Retrieve the repository
git clone https://github.com/rinikerlab/restraintmaker.git
cd restraintmaker

# 2. activate submodules
git submodule init
git submodule update

# 3. generate an Anaconda environment with the environment file and add the repository to its path:
conda env create --file devtools/conda-envs/dev_env.yaml -n restraintmaker
conda develop -n restraintmaker /absolute_path/to/restraintmaker

# 4. Test
conda activate restraintmaker
python examples/example_gui.py

  • Install via Pymol Plugin Manager should be possible, but not recommended right now :)

GUI Tutorial

GUI Menu

RestraintMaker adds a menu to the pymol GUI on the bottom right. This is the easiest way to interact with RestraintMaker.

pyMol

GUI Instructions

On the top left you’ll find some helpful instructions and hot keys for RestraintMaker

pyMol

Optimized Distance Restraints

Start by loading

Please follow the installation instructions above. Then, you can load the pymol GUI with an example system using

python examples/example_gui.py
pyMol

Select & Filter

By checking atoms and select in the “Selection Options” of the RestraintMaker menu, you can define which atoms are eligible to be picked for distance restraints. There are several modes to select atoms for this:

  • SingleAtomSelection: click on an atom to add it to your selection

  • AllSelection: select all atoms

  • MCSSelection: select the atoms of the maximum common substructure, as found by pymol

  • SphericalSelection: select all atoms within a sphere (see instructions on top left for tips on how to modify the sphere)

After choosing your initial selection, you can modify it by applying filters:

  • PropertyFilter: submit a pymol Atom property and value to filter

  • ElementFilter: specify one or several element types

  • RingFilter: atoms in rings

pyMol

Optimize restraints

To generate the distance restraints, there are two methods:

  • GreedyGraphOptimizer: the greedy min-max algorithm

  • BruteForceRingOptimizer: brute force approach (optimal solution, but potentially slow)

For both methods you can either use the default parameters or chose your own. Parameters are e.g. the number of restraints to choose per molecule pair.

pyMol pyMol

Export restraints to files

After generating your distance restraints, you can export them in one of the following formats:

  • Gromos_Distance_Restraints: GROMOS format

  • Gromacs_Distance_Restraints: GROMACS format

  • JSON_Distance_Restraints: JSON format which can be easily parsed and converted to the format of your choice

pyMol

Author

Benjamin Ries (@SchroederB), Salomé R. Rieder (@SalomeRonja), Clemens Rhiner (@ClemensRhiner)

Acknowledgments

The authors want to thank Carmen Esposito and Dominik Sidler for the great discussions. Project based on the Computational Molecular Science Python Cookiecutter version 1.3.

References

[1] The PyMOL Molecular Graphics System, Version 2.5 Schrödinger, LLC. (Anaconda OpenSource Version)

[2] RDKit: Cheminformatics and machine learning software (2021) - http://www.rdkit.org

[3] Christ, C. D.; van Gunsteren, W. F. - Enveloping Distribution Sampling: A Method to Calculate Free Energy Differences From a Single Simulation. J. Chem. Phys. 2007, 126, 184110. https://doi.org/10.1063/1.2730508

[4] Sidler, D.; Schwaninger, A.; Riniker, S. - Replica Exchange Enveloping Distribution Sam- pling (RE-EDS): A Robust Method to Estimate Multiple Free-Energy Differences From a Single Simulation. J. Chem. Phys. 2016, 145, 154114. https://doi.org/10.1063/1.4964781

Indices and tables