raw_frame_reader

A module containing a raw fast-path reader for xyz-family trajectory files (xyz, vel, force).

The RawTrajectoryReader streams the numeric per-frame data of a trajectory as plain numpy arrays together with the corresponding Cell objects, without building AtomicSystem or Atom objects for every frame. It is an additive fast path intended for analyses that only need the raw coordinates/velocities per frame (e.g. MSD and VACF) and produces bit-identical values compared to frame_generator(): the frames are parsed from large byte chunks by the slab parser (_slab_parser), whose strtof conversions are bitwise identical to the sscanf("%f") conversions of the line parsing routine (process_lines()) used by the line based readers. When the compiled slab parser is not available, the pure Python implementation (_slab_parser_py), which reuses the current per-line machinery, is used instead.

Summary

Classes:

RawTrajectoryReader

A fast-path reader that streams raw per-frame data of xyz-family trajectory files.

Reference

class RawTrajectoryReader(
filename: str | list[str],
traj_format: TrajectoryFormat | str = TrajectoryFormat.AUTO,
md_format: MDEngineFormat | str = MDEngineFormat.PQ,
)[source]

Bases: BaseReader

A fast-path reader that streams raw per-frame data of xyz-family trajectory files.

In contrast to TrajectoryReader, this reader does not construct AtomicSystem/Atom objects per frame. Instead, raw_frame_generator() yields (values, cell) tuples, where values is the (n_atoms, 3) float32 array of the frame body (positions, velocities or forces, depending on the trajectory format) and cell is the unit cell of the frame.

The reader follows the exact same semantics as frame_generator():

  • Multiple files are read one after another.

  • For the QMCFC MD engine format the leading dummy atom row is stripped from every frame (and it is checked to be an X atom).

  • Frames without box information in the header (vacuum frames) inherit the cell of the last frame that had one - also across file boundaries.

As a performance optimization, the reader caches Cell objects by the (textual) box information of the header line. Consecutive frames with an identical header box string share the same Cell object (NPT trajectories with changing boxes still get a new Cell per unique box string). The yielded Cell objects must therefore be treated as immutable by consumers.

For topology-dependent setup (e.g. selections), read_first_frame() reads only the first frame of the trajectory the normal way and returns it as an AtomicSystem. This does not consume any frames of raw_frame_generator(): every call to raw_frame_generator() always streams the trajectory from the very first frame, so analyses can bootstrap their topology from read_first_frame() and afterwards still consume every frame of the trajectory exactly once and in order.

Parameters:

  • filename (str or list of str) – The name of the file to read from or a list of filenames to read from.

  • traj_format (TrajectoryFormat | str, optional) – The format of the trajectory. Default is TrajectoryFormat.AUTO. The format is inferred from the file extension. Only the xyz-family formats XYZ, VEL and FORCE are supported by this reader.

  • md_format (MDEngineFormat | str, optional) – The format of the MD engine. Default is MDEngineFormat.PQ.

Raises:

TrajectoryReaderError – If the trajectory format is not an xyz-family format.

count_frames() → int[source]

Counts the number of frames of the trajectory.

The count is done with a cheap single-pass block scan of the files, without materializing the lines of the files. The number of atoms is taken from the first line of every file, exactly as in the frame counting of TrajectoryReader.

Returns:

The total number of frames of the trajectory.

Return type:

int

Raises:

TrajectoryReaderError – If the number of lines of a file is not divisible by its frame size or the number of atoms in the first line of a file is invalid.

raw_frame_generator() → Generator[tuple[Np2DNumberArray, Cell]][source]

A generator that yields the raw data of the trajectory frames.

For every frame a tuple (values, cell) is yielded, where values is the (n_atoms, 3) float32 array parsed from the frame body (positions, velocities or forces, depending on the trajectory format) and cell is the unit cell of the frame. The values and cells are bit-identical to the ones produced by frame_generator().

The generator always starts at the first frame of the trajectory, so it can be restarted by simply calling this method again.

Yields:

Generator[Tuple[Np2DNumberArray, Cell]] – The raw values and the cell of the frames of the trajectory.

Raises:

  • FrameReaderError – If a frame of the trajectory is incomplete or its body cannot be parsed.

  • ValueError – If the atom count of a frame header cannot be parsed as an integer.

read_first_frame() → AtomicSystem[source]

Reads only the first frame of the trajectory the normal way.

This is meant as a topology bootstrap for analyses that use raw_frame_generator(): the first frame is read as a full AtomicSystem (including Atom objects), so that selections/topologies can be built from it. The raw frame stream is not affected by this method - it always starts at the first frame.

Returns:

The first frame of the trajectory.

Return type:

AtomicSystem

Raises:

TrajectoryReaderError – If the trajectory contains no frames.

logger = <CustomLogger PQAnalysis.RawTrajectoryReader (INFO)>
RAW_READER_TRAJ_FORMATS = (TrajectoryFormat.XYZ, TrajectoryFormat.VEL, TrajectoryFormat.FORCE)

The trajectory formats supported by the raw fast-path reader.