MDTraj

Common errors

• MemoryError: Unable to allocate ... / numpy.core._exceptions._ArrayMemoryError: Unable to allocate ...

  cause Attempting to load a trajectory that is too large to fit into available RAM.
  fix For large trajectories, use `md.iterload()` to process frames iteratively, or `md.load(..., stride=N)` to load only a subset of frames, or `md.load(..., atom_indices=...)` to load a subset of atoms.

• AttributeError: 'Trajectory' object has no attribute 'x'

  cause Users accustomed to other MD libraries might expect direct access to coordinates via `traj.x`, `traj.y`, `traj.z`.
  fix MDTraj stores coordinates in `traj.xyz` as a NumPy array of shape (n_frames, n_atoms, 3). Access the full coordinate array via `traj.xyz`.

• TypeError: expected an input topology

  cause Some MDTraj functions require a complete `Topology` object that defines bonds, angles, and dihedrals, not just atomic coordinates. This often occurs when loading simple PDBs without explicit bond records or using a trajectory without a complete topology.
  fix Ensure your trajectory has a complete topology. Load from a format that contains bond information (e.g., Amber topology files, GROMACS topologies, or more complex PDBs), or use `traj.guess_bonds()` to infer bond connectivity after loading.

• ValueError: No atoms selected by '...' (where '...' is your selection string)

  cause The atom selection string provided to `traj.topology.select()` or similar functions did not match any atoms in the trajectory's topology. This can be due to typos, incorrect atom/residue names, or misunderstanding the selection syntax.
  fix Double-check the selection string against the MDTraj documentation's 'Atom Selection' guide. Verify atom and residue names present in your topology by printing `traj.topology` or iterating through `traj.topology.atoms`.

Warnings

• gotcha MDTraj uses nanometers (nm) for length and picoseconds (ps) for time as its internal default units. Many other MD packages or traditional practices use Angstroms (Å) or different time units, which can lead to unit conversion errors if not explicitly handled.
  Fix: Always be aware of the units used by MDTraj functions. Convert units explicitly when interacting with other software, e.g., multiply Å by 0.1 to get nm, or divide nm by 0.1 to get Å.
• gotcha MDTraj's atom selection syntax, while powerful, is unique and not identical to selection languages in other MD programs (e.g., VMD, Amber). Misunderstanding the syntax is a frequent source of incorrect selections or empty results.
  Fix: Consult the MDTraj documentation's 'Atom Selection' guide (mdtraj.org/latest/atom_selection.html). Test selections on small topologies or use `traj.atom_slice(traj.topology.select('...'))` to inspect results.
• gotcha Loading very large trajectories (many frames, many atoms) entirely into memory using `md.load()` can quickly exhaust available RAM, leading to `MemoryError`.
  Fix: For large files, use `md.iterload()` to iterate over frames without loading the entire trajectory at once. Alternatively, use `md.load(..., stride=N)` to load only a subset of frames, or `md.load(..., atom_indices=atom_selection)` to load a subset of atoms.
• breaking Specific file formats (e.g., HDF5, NetCDF, DCD) rely on external Python packages (like `h5py`, `netCDF4`). Updates to these underlying packages or `mdtraj` itself can sometimes introduce breaking changes or require specific versions for proper functionality.
  Fix: If encountering read/write errors for specific formats, ensure `mdtraj` and its relevant dependencies (e.g., `pip install h5py netCDF4`) are up-to-date and compatible. Consult `mdtraj`'s release notes for specific version requirements.

Install

• pip install mdtraj Install stable release

Imports

• mdtraj

  import mdtraj as md

  The convention is to import mdtraj as 'md'.
• Trajectory

  import mdtraj as md
  traj = md.Trajectory(...)

Quickstart

This quickstart demonstrates loading a minimal PDB file into an MDTraj Trajectory object, inspecting its basic properties, and performing a simple distance calculation. It cleans up the temporary file afterward.

import mdtraj as md
import os

# Create a minimal PDB file for demonstration
pdb_content = """
ATOM      1  N   ALA A   1       1.000   2.000   3.000  1.00 10.00           N
ATOM      2  CA  ALA A   1       2.000   2.000   3.000  1.00 10.00           C
ATOM      3  C   ALA A   1       3.000   2.000   3.000  1.00 10.00           C
TER
"""
pdb_filename = "minimal.pdb"
with open(pdb_filename, "w") as f:
    f.write(pdb_content)

# Load a trajectory
traj = md.load(pdb_filename)

print(f"Trajectory loaded: {traj.n_frames} frames, {traj.n_atoms} atoms.")
print(f"Topology has {traj.n_residues} residues.")

# Example calculation: compute distance between atoms 1 and 2 (CA and C)
# Indices are 0-based
distances = md.compute_distances(traj, [[1, 2]])
print(f"Distance between atom 1 and 2: {distances[0][0]:.3f} nm")

# Clean up the dummy file
os.remove(pdb_filename)