lammpskit.io.read_structure_info

lammpskit.io.read_structure_info(filepath)[source]

Extract simulation metadata from LAMMPS trajectory file header.

Parses LAMMPS dump file to extract timestep, atom count, and simulation box dimensions. Essential for setting up analysis workflows and validating trajectory consistency. Robust to common file format variations and provides detailed error diagnostics.

Parameters:

filepath (str) – Path to LAMMPS trajectory file (.lammpstrj or .dump format). Supports both absolute and relative paths.

Return type:

Tuple[int, int, float, float, float, float, float, float]

Returns:

  • timestep (int) – Simulation timestep number. Used for temporal analysis and file sequencing.

  • total_atoms (int) – Total number of atoms in simulation. Critical for memory allocation and validation.

  • xlo, xhi (float) – Lower and upper x-bounds of simulation box (Angstroms). Defines spatial domain for analysis.

  • ylo, yhi (float) – Lower and upper y-bounds of simulation box (Angstroms). Used for periodic boundary condition handling.

  • zlo, zhi (float) – Lower and upper z-bounds of simulation box (Angstroms). Essential for layer analysis in electrochemical cells.

Raises:

  • FileNotFoundError – If trajectory file doesn’t exist at specified path.

  • EOFError – If file is truncated or missing required header sections.

  • ValueError – If header data is malformed or non-numeric values found.

  • OSError – If file permissions or disk I/O errors occur.

Notes

Function expects standard LAMMPS dump format with fixed header structure. Box bounds are returned in simulation units (typically Angstroms for MD). For triclinic cells, only orthogonal bounds are extracted.

Performance

Computational complexity: O(1) - reads only file header Memory usage: O(1) - minimal memory footprint Typical execution time: <1ms for standard trajectory files

Examples

Extract metadata for single trajectory:

>>> timestep, atoms, xlo, xhi, ylo, yhi, zlo, zhi = read_structure_info('dump.100000.lammpstrj')
>>> box_size_z = zhi - zlo  # Calculate electrode separation
>>> print(f"Timestep {timestep}: {atoms} atoms, box height {box_size_z:.2f} Å")

Validate trajectory sequence:

>>> import glob
>>> files = sorted(glob.glob('dump.*.lammpstrj'))
>>> for f in files:
...     ts, atoms, *box = read_structure_info(f)
...     print(f"File {f}: timestep {ts}, {atoms} atoms")