Trajectory

class mdcraft.core.Trajectory(filenames: str | Path | Iterable[str | Path], *, formats: str | Iterable[str] | None = None, **kwargs)

Bases: object

Simulation trajectory.

A trajectory contains all data found in the frames from one or more trajectory files. Information includes simulation times, timesteps, atom positions, forces, velocities, and other global, group, or per-atom attributes depending on the trajectory format.

When multiple trajectory files are provided, they are first ordered by their starting times and then by their ending times to form a continuous trajectory proceeding forward in time.

Note

All trajectory files must use the same unit system, especially for LAMMPS dump files.

When the trajectory files have overlapping frames, the frames from the later files are used. With o denoting kept frames, x denoting discarded frames, and f denoting frames available in the stitched trajectory, a simple example is:

FILE 0:     ooxxxx
FILE 1:       oooooo
FILE 2:             oooooo
TRAJECTORY: ffffffffffffff

More complex interleaving of frames is also possible, but is not guaranteed to be handled correctly. Examples include:

FILE 0:     xooxoo
FILE 1:     o  o  o  x  o  x
FILE 2:              o o o o
TRAJECTORY: fffffff  f fff f

and:

FILE 0:     x o o x o o
FILE 1:     o  x  o  x  o  x  o
FILE 2:      o o o o
FILE 3:              o o o o o o
TRAJECTORY: ffffffffffffff f fff

Individual frames can be accessed through indexing or iteration.

Parameters:

filenamesstr, pathlib.Path, or array-like

Path to the trajectory files.

formatsstr, keyword-only, optional

Formats of the trajectory files. If not specified, the formats are determined from the file extensions.

**kwargsdict

Additional keyword arguments to pass to all trajectory readers.

Methods

get_frames

Gets one or more frames from the trajectory.

property dt: float | None

Time step size between timesteps in the trajectory. If None, the time step size is not constant across frames or could not be determined from the trajectory.

Reference unit: \(\mathrm{ps}\).

get_frames(frame_indices: int | slice | Iterable[int], /) → TrajectoryFrame | list[TrajectoryFrame]

Gets one or more frames from the trajectory.

Parameters:

frame_indicesint, slice, or array-like, positional-only

Indices of frames to get.

Returns:

framesTrajectoryFrame or list

Trajectory frame(s).

property n_atoms: int | None

Number of atoms in each frame. If None, the number of atoms is not constant across frames or the trajectory does not contain atom data.

property n_frames: int

Number of frames in the trajectory.

property time_step: float | None

Time step between frames in the trajectory. If None, the time step is not constant across frames.

Reference unit: \(\mathrm{ps}\).

property times: ndarray[float64]

Simulation times found in the trajectory.

Reference unit: \(\mathrm{ps}\).

property timesteps: ndarray[uint32] | None

Simulation timesteps found in the trajectory. If None, the timesteps could not be determined from the trajectory.