Dump Handler Engine Utility

Parse LAMMPS dump trajectories into per-frame coordinate payloads.

This module supports both xyz-like dumps and native ITEM: formatted dumps, normalizing frame data into table/array forms used by the LAMMPS adapter. It focuses on trajectory parsing, frame iteration, and optional progress updates.

Usage context

• Trajectory ingestion: Produces frame coordinates/labels for TrajectoryData.
• Box metadata: Captures box bounds when present in ITEM: dumps.
• Streaming workflows: Exposes random-access and iterative frame APIs.

Class: LAMMPSDumpHandler

Bases: BaseHandler

Parser for LAMMPS dump trajectories.

Supported formats: 1) XYZ-like blocks: n_atoms -> comment with timestep -> atom_type x y z rows 2) Native ITEM: dump blocks.

Method: n_frames

Return the number of parsed frames.

Method: n_atoms

Return detected atom count per frame, parsing on first access if needed.

Method: frame

Return one parsed frame payload by index.

Parameters:

Name	Type	Description	Default
i	int	Zero-based frame index.	required

Returns:

Type	Description
dict[str, Any]	Frame payload containing index, iteration, coordinates, atom types, and optional box_bounds.

Examples:

fr0 = handler.frame(0)
coords = fr0["coords"]

Method: iter_frames

Iterate parsed frames with optional stride.

Parameters:

Name	Type	Description	Default
step	int	Positive stride for frame sampling.	1

Returns:

Type	Description
Iterator[dict[str, Any]]	Iterator of frame payload dictionaries from frame(i).

Examples:

for fr in handler.iter_frames(step=10):
    ...