How to read a trajectory#

Goal#

Attach trajectory frames to a topology Molecule so that all frames are available for analysis.

Minimal example#

from moleculekit.molecule import Molecule

# Load topology first, then attach the trajectory
mol = Molecule("topology.psf")
mol.read("trajectory.xtc")
print(mol.numFrames)

Parameters that matter#

Parameter

Type

Default

What it does

frames

list

None (all)

Read only the listed frame indices from the trajectory

skip

int

None

Skip every N frames (e.g. skip=10 reads 1 in 10)

append

bool

False

Append frames to existing coordinates instead of replacing them

Common variations#

# Load topology first, then read a specific frame range
mol = Molecule("topology.psf")
mol.read("trajectory.xtc", frames=list(range(0, 500)))

# Concatenate two trajectory files
mol = Molecule("topology.psf")
mol.read("run1.xtc")
mol.read("run2.xtc", append=True)
print(mol.numFrames)

Gotchas#

  • All frames are loaded into memory at once; for very long trajectories use frames= to read a slice.

  • The atom count of the trajectory must exactly match the topology — a mismatch raises an error.

  • skip and frames can be combined: frames selects the subset to consider, then skip further subsamples within that subset.

  • When append=False (default) a second mol.read(traj) call replaces the existing coordinates rather than extending them.

See also#