qtools

Description

qtools is a toolset comprised of a Python library Qpyl and a set of command-line tools, for use with the molecular dynamics simulation package Q. This open-source project was created by Miha Purg (currently at Uppsala University) in order to provide Q-users with a set of well-tested tools for automating repetitive and/or tedious tasks, debugging simulations, and analysing results. The author strives to achieve a good balance between the level of user-control over Q (i.e., relatively low abstraction level) and the ease-of-use provided by qtools.

Disclaimer: qtools is not affiliated with Q nor should it be considered an official toolset for Q.

Functionality

• Python wrapper for Q
• Parameter conversions (FFLD OPLS, Amber/GAFF)
• Input generation for molecular dynamics/free energy perturbation/umbrella sampling (MD/FEP/US) simulations
• FEP-file generation for empirical valence bond (EVB) simulations
• EVB mapping and automatic fitting of off-diagonal and gas-shift parameters
• Linear response approximation (LRA) calculations (including group contributions)
• Output parsing and analysis of MD, FEP, and EVB
• Support for Q6 (quantum classical path and group exclusion calculations)
• Graphical tool for visualizing results and debugging simulations:
  • Free-energy profiles & sampling distributions
  • LRA and reorganization free-energy breakdown
  • LRA group contributions
  • Energy breakdown (vdW, electrostatics, ...)

Requirements

• Python 3.4+
• Q (see the Q6 github page).
• matplotlib is required for q_plot.py, a non-essential utility used mostly for troubleshooting simulations.

Installation (Linux, OSX)

Clone the repository:

mkdir -p ~/bin && cd ~/bin
git clone https://github.com/mpurg/qtools

If using Bash, add this line to your ~/.bashrc:

source $HOME/bin/qtools/qtools_init.sh

Reload .bashrc and run the CLI config script:

source ~/.bashrc
qscripts_config.py

This script looks for Q executables in your PATH and creates a default settings-file $QTOOLS_HOME/qscripts.cfg.
If the executables are not found the settings file should be modified manually.

Documentation

The starting point should be the docs/tutorials folder. It contains working examples of how you can use the command line tools to prepare, simulate and analyse a simple SN2 reaction with EVB. Additionally, a recently published chapter in the serial Methods in Enzymology provides step-by-step instructions for performing EVB simulations on a real enzymatic system with qtools. Manuscript available here (paywalled).

For those inclined on using the Python API directly, jupyter-notebook examples calling the Qpyl API can be found in docs/examples. The API reference can be found in docs/api/html. Additionally, the tests, and the command-line interface (qscripts-cli) can be useful to explore the API.

Testing

Automated Testing is performed on Travis-CI, with pytest for Qpyl (code coverage). and simple regression tests for CLI tools. To run the tests locally make sure you have pytest and pytest-cov installed, then type:

export QBIN_DIR=$HOME/apps/Q6/bin   # absolute path to your local Q-binary folder (optional)
cd tests
./run_tests.sh

If QBIN_DIR is not set, pre-compiled Q binaries will be downloaded from Github.

Citations

To acknowledge the use of qtools in scientific publications, please specify the version and the DOI of the latest release:

Example:
...analysis was performed with qtools v0.7.0 (DOI: 10.5281/zenodo.842003).

Bugs, feature requests, and contributions

Submit issues and feature requests to Github (https://github.com/mpurg/qtools/issues).
To contribute create a pull request.

Author

Miha Purg ([email protected])

Contributors

Paul Bauer Florian van der Ent