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 or velocities per frame (e.g. MSD and VACF). The frames are parsed from large byte chunks by the slab parser (_slab_parser). Its default float32 mode is bit-identical to the line-based trajectory reader; the optional float64 mode instead preserves the precision of the text with direct strtod conversions. 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,
dtype: str = 'float32',
)[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) array of the frame body (positions, velocities or forces, depending on the trajectory format) in the configured precision 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.

  • dtype ({"float32", "float64"}, optional) – Numeric precision of xyz-family frame values. float32 preserves the established trajectory-reader behavior; float64 parses directly with strtod. Default is float32.

Raises:

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

  • ValueError – If dtype is not float32 or float64.

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) 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 array dtype is selected at construction. In float32 mode the values and cells are bit-identical to those produced by the line-based trajectory reader; float64 mode retains additional digits present in the source text.

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.

try_read_all_frames(
expected_n_atoms: int,
max_bytes: int,
expected_n_frames: int | None = None,
include_cells: bool = True,
*,
include_box_lengths: bool = False,
) → tuple[NpnDNumberArray, list[Cell] | Np2DNumberArray] | None[source]

Read a fixed-topology xyz-family trajectory as one batch.

The peak input-buffer and numeric-array working set must fit below max_bytes. If it does not, or if the file requires one of the permissive line-reader compatibility paths, None is returned and the caller can use raw_frame_generator() instead.

Numeric tokens are converted by the same slab-parser routines as the streaming path. The returned values therefore have identical float32 or float64 bit patterns in the same frame order.

Parameters:

  • expected_n_atoms (int) – Number of physical atoms expected after QMCFC dummy removal.

  • max_bytes (int) – Maximum combined size of the input byte buffers and output value arrays.

  • expected_n_frames (int | None, optional) – Expected total frame count, used as an additional consistency check when the caller already knows it.

  • include_cells (bool, optional) – Build the per-frame cell list. When false, unique box headers are still validated but the returned cell list is empty.

  • include_box_lengths (bool, optional) – Return per-frame orthorhombic box lengths as a float64 array instead of Cell objects. Explicit triclinic boxes and a vacuum cell without a preceding periodic cell are not compatible with this mode and cause the bounded batch path to return None. This option requires include_cells=False.

Returns:

(values, cell_data) with values shaped (n_frames, expected_n_atoms, 3). cell_data is either the Cell list or, when requested, an (n_frames, 3) float64 box length array. Returns None when the bounded batch path cannot be used.

Return type:

tuple or None

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.