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.