Usage

The usage of MDTools is really simple. Just select the script you want to execute and run it. All (documented) scripts are listed in the Scripts section.

Location of the scripts 

If you have installed MDTools into its own virtual Python environment (recommended), all MDTools scripts should have been installed to path/to/virtual/environment/bin/. If you have installed MDTools without using a virtual environment, all scripts should have been installed to ${HOME}/.local/bin/ (on Linux systems). Usually, these directories are part of your PATH, so that you can simply run the scripts by typing their name, e.g.

contact_hist.py --help

If you get a “command-not-found” error, you probably have to add the bin/ directory to your PATH. On Linux systems, this can e.g. be done by adding export PATH="${PATH}:absolute/path/to/bin/" to your ${HOME}/.bashrc file.

Alternatively, you can always run the scripts by calling:

python3 path/to/script.py

If you have installed MDTools using a virtual environment, you must first activate the virtual environment with source path/to/virtual/environment/bin/activate or you have to replace python3 by path/to/virtual/environment/bin/python3.

Examples 

Todo

Give one or more examples how to use the scripts.

Compressed files 

All MDTools scripts support reading or writing compressed files of the following formats:

gzip (.gz)

bzip2 (.bz2)

XZ/LZMA2 (.xz)

LZMA (.lzma)

One exception is that discrete trajectories cannot be saved as gzip-compressed .npz archives. See mdtools.file_handler.save_dtrj().

Generally, the file format is determined from the file name extension. When reading files and the format could not be determined from the extension, the format is determined from the file signature. If the file format cannot be determined, it is assumed that the file is uncompressed.

Plots 

Scripts that create plots are optimized for writing PDF files. Other output formats may work, too, but are not guaranteed to work. When a script saves multiple plots to the same file, PDF is the only supported file format.

You can convert PDF pages to many other image formats for instance with pdftoppm.

Unbuffered output 

All scripts usually stream some run time information to standard output. In environments that buffer the output stream, this run time information might show up only after a long delay (to be more precise: after the buffer size is reached). To force unbuffered output, call Python with the -u (unbuffered) option:

python3 -u path/to/script.py

Optimized mode 

Usually, we do consistency checks via assert statements. For instance, if a function returns a probability, we check whether the return value lies within the interval [0, 1] before returning it. You can turn off these checks by calling Python with the -O (optimized) option:

python3 -O path/to/script.py

However, the checks are usually not computationally expensive and you will probably not notice any difference. Therefore, we don’t recommend using the -O option.

Note

Currently, most of the checks are wrapped in if debug: do check conditions (see Debug mode), even if the check is computationally cheap. However, when writing new code or refactoring old one, we will use assert statements for computationally cheap checks.

Debug mode 

Consistency checks that might indeed become computationally demanding (e.g. because they are computationally heavy per se or because they scale badly with system size), are wrapped in if debug: do check conditions rather than in assert statements. By default, the value of debug is set to False. If you get weird results or errors from a script and the script offers a debug option, we advise you to run the script in debug mode and see if warnings or errors are raised. These might help you to identify bad user input, parameter settings or bugs. If you spot a bug, please open a new Issue on GitHub.

Differences to the terminology of MDAnalysis 

Because MDTools is build on MDAnalysis, we use basically the same terminology as MDAnalysis. However, some terms are used differently. Here is a list of terms whose meaning is different in MDTools compared to MDAnalysis:

unwrap 

Meaning in MDAnalysis:

Move atoms in such a way that chemical bonds are not split across periodic boundaries of the simulation box (see e.g. MDAnalysis.core.groups.AtomGroup.unwrap()).

In MDTools this operation is called “make whole”, because you fix molecules that are broken across periodic boundaries.

Meaning in MDTools:

Get the real-space positions of all atoms. In other words, unfold a wrapped trajectory, where all atoms lie within the primary unit cell, and get the positions of all atoms like they were if they had not been put back into the primary unit cell when they have crossed a periodic boundary.

Real-space positions are e.g. needed when calculating the MSD.

Usually, it makes only sense to unwrap a trajectory starting from the very first frame, because the unwrapped trajectory is (re-)constructed by summing up the displacements from frame to frame and adding these displacements to the initial configuration. See e.g. Bülow et al., J. Chem. Phys., 2020, 153, 021101.