13. Library functions — MDAnalysis.lib

MDAnalysis.lib contains code that is independent of the specific MDAnalysis framework, such as fast calculators for distances or simple logging support. Modules do not depend on other code inside MDAnalysis except in MDAnalysis.lib itself (and possibly in MDAnalysis.exceptions) and thus can be easily imported elsewhere.

13.1. Overview

MDAnalysis.lib.distances contains many high performance maths functions. Most of them have the keyword backend that allows one to either select serial (single threaded) code (backend="serial) or to use parallelized versions (e.g. backend="OpenMP" for OpenMP parallelism).

MDAnalysis.lib.transformations contains a multitude of matrix operations for manipulating coordinate data.

MDAnalysis.lib.qcprot contains a fast implementation of superposition by minimizing the RMSD.

MDAnalysis.lib.util contains various file and string utility functions whereas mathematical functions are to be found in MDAnalysis.lib.mdamath.

A number of modules are concerned with finding neighbors. MDAnalysis.lib.NeighborSearch contains high-level classes to do neighbor searches with MDAnalysis objects. MDAnalysis.lib.nsgrid contains a fast implementation of grid neighbor search whereas MDAnalysis.lib.pkdtree uses KDTrees (with periodic images) for neighbor searching. Some of the functions in MDAnalysis.lib.distances user either of these algorithms to speed up distance calculations.

13.2. List of modules

• 13.2.1. Fast distance array computation — MDAnalysis.lib.distances
• 13.2.2. Low-level modules for MDAnalysis.lib.distances
• 13.2.3. Neighbor Search wrapper for MDAnalysis — MDAnalysis.lib.NeighborSearch
• 13.2.4. Neighbor search library — MDAnalysis.lib.nsgrid
• 13.2.5. PeriodicKDTree — MDAnalysis.lib.pkdtree
• 13.2.6. Setting up logging — MDAnalysis.lib.log
• 13.2.7. Mathematical helper functions — MDAnalysis.lib.mdamath
• 13.2.8. Homogeneous Transformation Matrices and Quaternions — MDAnalysis.lib.transformations
• 13.2.9. Fast QCP RMSD structure alignment — MDAnalysis.lib.qcprot
• 13.2.10. Helper functions — MDAnalysis.lib.util
• 13.2.11. Correlations utilities — MDAnalysis.lib.correlations
• 13.2.12. Picklable read-only I/O classes — MDAnalysis.lib.picklable_file_io

13.3. Low level file formats

The modules in MDAnalysis.lib.formats contain code to access various file formats in a way that is independent from other MDAnalysis functionality (i.e., they do not use any classes from MDAnalysis.core or MDAnalysis.topology). This low-level code is used in the MDAnalysis.coordinates module but can also be re-used by other Python-based projects.

• 13.3.1. Low-level Gromacs XDR trajectory reading — MDAnalysis.lib.formats.libmdaxdr
• 13.3.2. Low level DCD trajectory reading - MDAnalysis.lib.formats.libdcd

13.4. Libmdanalysis

The __init__.pxd file in MDAnalysis.lib.libmdanalysis provides a single place to cimport MDAnalysis’ public Cython headers. This is recommended for advanced developers only.

For example, imagine we are writing a Cython extension module in MDAnalysis.lib and we would like to make a function that creates a MDAnalysis.coordinates.timestep.Timestep

from MDAnalysis.lib.libmdanalysis cimport timestep
# or we could use the relative cimport
# from .libmdanalysis cimport timestep

cdef timestep.Timestep make_timestep(int natoms):
   cdef timestep.Timestep ts = timestep.Timestep(natoms)
   return ts

Currently modules that are exposed as public Cython headers are:

• MDAnalysis.coordinates.timestep

For more details consult the source MDAnalysis.lib.libmdanalysis.__init__.pxd