MDAnalysis

2.10.0 · active · verified Thu Apr 16

MDAnalysis is an open-source, object-oriented toolkit for the analysis of molecular dynamics trajectories and other atomistic simulation data. It provides Python classes to represent and manipulate atomistic data, enabling users to perform various analyses from simple selections to complex calculations. The current version is 2.10.0, and new minor releases are frequent, typically on a monthly or bi-monthly cadence.

Common errors

```
AttributeError: module 'numpy' has no attribute 'float'
```
cause This error often occurs when an older version of MDAnalysis (or its dependencies) attempts to use deprecated NumPy type aliases (like `np.float`, `np.int`) with a newer NumPy version (specifically NumPy 2.0+), which removed these aliases.

fix Upgrade MDAnalysis to version 2.8.0 or newer, which includes explicit support for NumPy 2.0+. Alternatively, downgrade NumPy to a version compatible with your MDAnalysis installation, typically `pip install numpy<2.0.0`.
```
ModuleNotFoundError: No module named 'MDAnalysis'
```
cause The MDAnalysis package was not correctly installed or the Python environment where it was installed is not the one being used.

fix Ensure you have installed MDAnalysis correctly via `pip install MDAnalysis`. Verify that the Python interpreter you are running (`python` or `python3`) corresponds to the environment where MDAnalysis was installed.
```
RuntimeError: DCD reading for large (>2Gb) files is broken
```
cause Specific bug in MDAnalysis versions 2.4.0, 2.4.1, and 2.4.2 that prevented correct reading of DCD trajectory files larger than 2 gigabytes.

fix Upgrade MDAnalysis to version 2.4.3 or newer. This bug was explicitly fixed in MDAnalysis 2.4.3.

Warnings

gotcha MDAnalysis maintains compatibility with a wide range of NumPy versions (e.g., 1.26.0 up to 2.0+ for MDAnalysis 2.10.0). However, using an MDAnalysis version that is too old with a very new NumPy (especially NumPy 2.0.0+) can lead to `AttributeError` or `TypeError` related to numerical types (e.g., `np.float` not found).
Fix: Upgrade MDAnalysis to the latest version (2.8.0 or newer) to ensure full compatibility with NumPy 2.0+. If upgrading MDAnalysis is not possible, try pinning your NumPy version to a compatible range, typically `<2.0.0` for older MDAnalysis releases.
breaking The minimum supported Python version for MDAnalysis has steadily increased across major releases. For instance, MDAnalysis 2.5.0 required Python >=3.9, while MDAnalysis 2.10.0 requires Python >=3.11. Installing on an older Python environment will fail.
Fix: Ensure your Python environment meets or exceeds the minimum requirement for the desired MDAnalysis version. Check the official MDAnalysis documentation or PyPI page for the exact `requires_python` specification.
breaking Starting with MDAnalysis 2.8.0, the core library license transitioned from GPLv3+ to LGPLv3+. While this primarily affects developers and projects linking against MDAnalysis, it's a significant change for users considering redistribution or integration into proprietary software.
Fix: Review the LGPLv3+ license terms if you are developing software that links to MDAnalysis or redistributing MDAnalysis. Previous versions remain under GPLv3+.

Install

pip install MDAnalysis Install stable release

Imports

Universe
```
import MDAnalysis as mda
u = mda.Universe(...)
```
Universe is the central object for loading and manipulating simulation data.
analysis
```
from MDAnalysis.analysis import ...
```
Submodule containing various analysis tools (e.g., distances, contacts).
transformations
```
from MDAnalysis.transformations import ...
```
Submodule for modifying trajectories during loading (e.g., centering, unwrapping).

Quickstart

This quickstart demonstrates how to create a simple MDAnalysis Universe object in memory, populate it with dummy atom data, select atoms, and perform a basic calculation. In a typical workflow, you would load data from actual structure (e.g., PDB) and trajectory (e.g., XTC, DCD) files using `mda.Universe('structure.pdb', 'trajectory.xtc')`.

import MDAnalysis as mda
import numpy as np

# Create an empty Universe to demonstrate basic operations without requiring files
# In real applications, you would load structure and trajectory files (e.g., PDB, XTC).
# u = mda.Universe("path/to/structure.pdb", "path/to/trajectory.xtc")

u = mda.Universe.empty(n_atoms=4, trajectory=True)

# Add dummy atom data to the empty Universe
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[0]], universe=u, name='C'))
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[1]], universe=u, name='H'))
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[2]], universe=u, name='O'))
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[3]], universe=u, name='N'))
u.atoms.types = ['C', 'H', 'O', 'N']
u.atoms.masses = [12.01, 1.008, 15.999, 14.007]

# Set dummy positions for a single frame
u.atoms.positions = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0],
    [1.0, 1.0, 0.0]
])

print(f"Universe created with {u.atoms.n_atoms} atoms.")
print(f"First atom: {u.atoms[0].type} at {u.atoms[0].position}")

# Select atoms based on properties
carbon_atoms = u.select_atoms("type C")
print(f"\nSelected {carbon_atoms.n_atoms} carbon atom(s).")
print(f"Carbon atom position: {carbon_atoms.positions}")

# Calculate a simple property, e.g., center of mass
center_of_mass = u.atoms.center_of_mass()
print(f"\nCenter of mass of all atoms: {center_of_mass}")

view raw JSON →