{"id":8311,"library":"mdtraj","title":"MDTraj","description":"MDTraj is a modern, open-source library for the analysis of molecular dynamics (MD) trajectories in Python. It provides high-performance tools for reading, writing, and manipulating MD data, supporting a wide range of file formats. The current version is 1.11.1.post1, and it typically has a few releases per year, often driven by new feature development, bug fixes, or compatibility updates.","status":"active","version":"1.11.1.post1","language":"en","source_language":"en","source_url":"https://github.com/mdtraj/mdtraj","tags":["molecular dynamics","cheminformatics","bioinformatics","simulation","chemistry","trajectory analysis"],"install":[{"cmd":"pip install mdtraj","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Core numerical computations and array handling.","package":"numpy"},{"reason":"Scientific computing utilities, often used for advanced analysis.","package":"scipy"},{"reason":"Used for performance-critical compiled extensions.","package":"cython"},{"reason":"Used for efficient serialization and deserialization of data.","package":"msgpack"},{"reason":"Required for HDF5 file format support (e.g., TRR, XTC, own HDF5 format).","package":"h5py"},{"reason":"For robust version comparisons and dependency management.","package":"packaging"}],"imports":[{"note":"The convention is to import mdtraj as 'md'.","symbol":"mdtraj","correct":"import mdtraj as md"},{"symbol":"Trajectory","correct":"import mdtraj as md\ntraj = md.Trajectory(...)"}],"quickstart":{"code":"import mdtraj as md\nimport os\n\n# Create a minimal PDB file for demonstration\npdb_content = \"\"\"\nATOM      1  N   ALA A   1       1.000   2.000   3.000  1.00 10.00           N\nATOM      2  CA  ALA A   1       2.000   2.000   3.000  1.00 10.00           C\nATOM      3  C   ALA A   1       3.000   2.000   3.000  1.00 10.00           C\nTER\n\"\"\"\npdb_filename = \"minimal.pdb\"\nwith open(pdb_filename, \"w\") as f:\n    f.write(pdb_content)\n\n# Load a trajectory\ntraj = md.load(pdb_filename)\n\nprint(f\"Trajectory loaded: {traj.n_frames} frames, {traj.n_atoms} atoms.\")\nprint(f\"Topology has {traj.n_residues} residues.\")\n\n# Example calculation: compute distance between atoms 1 and 2 (CA and C)\n# Indices are 0-based\ndistances = md.compute_distances(traj, [[1, 2]])\nprint(f\"Distance between atom 1 and 2: {distances[0][0]:.3f} nm\")\n\n# Clean up the dummy file\nos.remove(pdb_filename)","lang":"python","description":"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."},"warnings":[{"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 Å.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Loading very large trajectories (many frames, many atoms) entirely into memory using `md.load()` can quickly exhaust available RAM, leading to `MemoryError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Versions 1.9.x to 1.10.x, 1.10.x to 1.11.x, and future major updates."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to load a trajectory that is too large to fit into available RAM.","error":"MemoryError: Unable to allocate ... / numpy.core._exceptions._ArrayMemoryError: Unable to allocate ..."},{"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`.","cause":"Users accustomed to other MD libraries might expect direct access to coordinates via `traj.x`, `traj.y`, `traj.z`.","error":"AttributeError: 'Trajectory' object has no attribute 'x'"},{"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.","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.","error":"TypeError: expected an input topology"},{"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`.","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.","error":"ValueError: No atoms selected by '...' (where '...' is your selection string)"}]}