Welcome to the documentation of




Jul 07, 2021

Test status Documentation Status License GPLv3 Made with Python Made with Sphinx Powered by MDAnalysis


MDTools is a collection of ready-to-use Python scripts to prepare and analyze molecular dynamics (MD) simulations.

The main feature of this package is not the package itself, but the Python Scripts shipped along with this package in the scripts/ directory. These Python scripts are fully functional and directly executable (provided you have installed Python) without the need to go into the source code.

The idea is to provide you with a collection of scripts to prepare and analyze MD simulations similar to the command-line tools shipped along with Gromacs. For instance, the script scripts/dynamics/msd_serial.py can be used to calculate the mean square displacement of a given selection (i.e. a user-defined group of atoms). Since MDTools is based on MDAnalysis, you are not limited to Gromacs trajectories but you can read and analyze a variety of different trajectory and topology formats. You also benefit from MDAnalysis’ rich selection syntax.

For you there is no need to interact with the MDTools package directly. You can simply run the scripts and do not need to care about what is happening in the background (although of course you can). Simply install the package, run the scripts and be happy ;). You only need to interact with the MDTools package directly, when

  • You want to make changes to the scripts;

  • You write your own scripts and want to use functions, classes or other objects defined in the MDTools package;

  • You want to contribute to this package.

MDTools is written in pure Python and is mainly based on the Python packages MDAnalysis, NumPy, SciPy and matplotlib. The scripts on Markov modeling are based on PyEMMA.


This project is at the beginning. At the moment it is mainly intended for my personal use and will evolve according to my personal needs. However, everybody is welcome to use it and to contribute to it and to write scripts for his/her own purposes. As mentioned above, the aim of this project is to build up a collection of generic Python scripts to prepare and analyze MD simulations. If you want to contribute, please read the Developer’s guide.


The scripts and functions are not (extensively) tested! The only test cases we have so far are the examples from the Examples sections of the docstrings, which are verified using doctest. The plan is to implement extensive unittests using pytest, but so far we did not had the time for this. Implementing unittest would thus be great way for you to contribute to this project and it would be highly appreciated.

Getting started

Installation instructions are given in the Installation section. The basic usage of the scripts is described in the Usage section.


If you want to contribute to the project, please read the Developer’s guide.

Source code

Source code is available from https://github.com/andthum/mdtools under the GNU General Public License, version 3. You can download or clone the repository with Git:

git clone https://github.com/andthum/mdtools


MDTools is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

MDTools is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.