polyphys.simulate.dump#

LAMMPS dump files — polyphys.simulate.dump#

The dump module reads the text dump files written by the LAMMPS dump atom and dump custom commands into NumPy arrays, one frame at a time. It needs NumPy and the standard library only, so an install without MDAnalysis can read dumps.

Added in version 0.6.0.

Contents#

iter_dump() yields the frames of a file one at a time, and read_dump_frame() returns one of them. Each frame is a DumpFrame: its timestep, its box as a Box, the names of the per-atom columns, and the per-atom values. DumpFrame.positions() returns Cartesian coordinates from whichever coordinate columns the frame has. BrokenDumpError, a LammpsFormatError, reports a file that is cut off or does not follow the format.

Format#

A dump is a sequence of frames, each a header and one line per atom:

ITEM: TIMESTEP
1000
ITEM: NUMBER OF ATOMS
2
ITEM: BOX BOUNDS pp pp pp
0.0 10.0
0.0 10.0
0.0 10.0
ITEM: ATOMS id type x y z
1 1 1.0 5.0 5.0
2 1 2.0 5.0 5.0
  • ITEM: UNITS and ITEM: TIME, each followed by its value, may come before ITEM: TIMESTEP; dump_modify units yes writes the first in the first frame only, and dump_modify time yes the second in every frame.

  • ITEM: BOX BOUNDS ends with three boundary flags, such as pp ff pp, and is followed by one lo hi line per dimension. For a restricted triclinic box it reads ITEM: BOX BOUNDS xy xz yz pp pp pp and its lines are xlo_bound xhi_bound xy, ylo_bound yhi_bound xz, and zlo_bound zhi_bound yz: the bounds of the orthogonal box that encloses the triclinic box, then a tilt factor. The general triclinic form, ITEM: BOX BOUNDS abc origin, is not supported.

  • ITEM: ATOMS names the per-atom columns. Unless dump_modify sort is set, the atom lines are in no fixed order.

Coordinates#

x y z are Cartesian coordinates wrapped into the box, and xu yu zu are unwrapped by the image flags ix iy iz. xs ys zs and xsu ysu zsu are the same coordinates scaled: fractions of the box edge vectors, converted as polyphys.simulate.core describes. dump atom writes id type xs ys zs unless dump_modify scale no is set. The module converts no units; values are in the units of the run.

Complexity#

Reading a file takes \(O(n_f n_a n_c)\) time for \(n_f\) frames of \(n_a\) atoms with \(n_c\) columns. iter_dump() holds one frame at a time, \(O(n_a n_c)\) memory, plus the frames the caller keeps.

References

The format follows the LAMMPS documentation of dump and Howto_triclinic, and these lines of the LAMMPS source, release stable_30Sep2026_update1; the coordinate formulas are cited in polyphys.simulate.core:

Dependencies#

  • Python standard library: contextlib, dataclasses, itertools, logging, pathlib

  • Third-party: numpy

  • PolyPhys: polyphys.simulate.core

Functions

iter_dump(path, *[, sort_by_id])

Yield the frames of a LAMMPS dump file one at a time.

read_dump_frame(path[, index, sort_by_id])

Read one frame of a LAMMPS dump file.

Classes

DumpFrame(timestep, box, columns, data[, ...])

One frame of a LAMMPS dump.

Exceptions

BrokenDumpError

A LAMMPS dump is cut off or does not follow the dump format.

exception polyphys.simulate.dump.BrokenDumpError[source]#

Bases: polyphys.simulate.core.LammpsFormatError

A LAMMPS dump is cut off or does not follow the dump format.

Added in version 0.6.0.

Examples

A run killed while writing its second frame leaves that frame short of atom lines:

>>> import tempfile
>>> frame = '''ITEM: TIMESTEP
... {step}
... ITEM: NUMBER OF ATOMS
... 2
... ITEM: BOX BOUNDS pp pp pp
... 0 10
... 0 10
... 0 10
... ITEM: ATOMS id type x y z
... 1 1 1.0 5.0 5.0
... '''
>>> second_atom = "2 1 2.0 5.0 5.0\n"
>>> text = frame.format(step=0) + second_atom + frame.format(step=100)
>>> with tempfile.TemporaryDirectory() as tmp:
...     path = Path(tmp) / "killed.lammpstrj"
...     _ = path.write_text(text)
...     steps = []
...     try:
...         for dump_frame in iter_dump(path):
...             steps.append(dump_frame.timestep)
...     except BrokenDumpError as err:
...         print(str(err).split(": ", 1)[1])
frame 1 (timestep 100), line 21: 1 of 2 atom lines; the dump may be cut off
>>> steps
[0]
class polyphys.simulate.dump.DumpFrame(timestep, box, columns, data, time=None, units=None)[source]#

Bases: object

One frame of a LAMMPS dump.

Added in version 0.6.0.

Variables:
  • timestep (int) – The ITEM: TIMESTEP value.

  • box (Box) – The simulation box, with the boundary flags of the frame; for a triclinic box, its own bounds, not those the dump writes.

  • columns (tuple of str) – The per-atom column names of ITEM: ATOMS, in file order, such as ('id', 'type', 'xs', 'ys', 'zs').

  • data (numpy.ndarray) – Shape (n_atoms, n_columns), float64: one row per atom, one column per name in columns. Integer columns such as id are exact up to \(2^{53}\). Read-only.

  • time (float or None) – The ITEM: TIME value (simulated time), or None if the frame has none.

  • units (str or None) – The ITEM: UNITS value, such as 'lj', or None. LAMMPS writes it in the first frame only; iter_dump() gives it to every frame.

Raises:

ValueError – If data is not two-dimensional with one column per name in columns, or a column name repeats.

Parameters:
  • timestep (int)

  • box (Box)

  • columns (tuple[str, ...])

  • data (NDArray[float64])

  • time (float | None)

  • units (str | None)

Examples

>>> box = Box(lo=np.zeros(3), hi=np.full(3, 10.0))
>>> frame = DumpFrame(timestep=0, box=box,
...                   columns=("id", "type", "xs", "ys", "zs"),
...                   data=np.array([[1, 1, 0.1, 0.5, 0.5],
...                                  [2, 1, 0.2, 0.5, 0.5]]))
>>> frame.n_atoms
2
>>> frame.column("id")
array([1, 2])
>>> frame.positions()
array([[1., 5., 5.],
       [2., 5., 5.]])
box: polyphys.simulate.core.Box#
column(name)[source]#

Return the values of one per-atom column.

Parameters:

name (str) – A name in columns.

Returns:

Shape (n_atoms,): int64 for the integer attributes id, mol, proc, procp1, type, ix, iy, and iz, else a read-only float64 view of data.

Return type:

numpy.typing.NDArray[numpy.double | numpy.int_]

Raises:

KeyError – If the frame has no column name.

Examples

>>> box = Box(lo=np.zeros(3), hi=np.full(3, 10.0))
>>> frame = DumpFrame(timestep=0, box=box,
...                   columns=("id", "type", "x"),
...                   data=np.array([[1, 2, 0.5], [2, 1, 1.5]]))
>>> frame.column("type")
array([2, 1])
>>> frame.column("x")
array([0.5, 1.5])
columns: tuple[str, ...]#
data: numpy.typing.NDArray[numpy.float64]#
property n_atoms: int#

The number of atoms in the frame.

positions(unwrapped=False)[source]#

Return the Cartesian coordinates of the atoms.

Parameters:

unwrapped (bool) – False for coordinates wrapped into the box; True for coordinates unwrapped by the image flags.

Returns:

Shape (n_atoms, 3), float64, in the length unit of the run.

Return type:

numpy.typing.NDArray[numpy.double]

Raises:

KeyError – If the frame lacks the columns for the requested coordinates.

Notes

Wrapped coordinates come from x y z, else from xs ys zs. Unwrapped ones come from xu yu zu, else from xsu ysu zsu, else from the wrapped coordinates and the image flags ix iy iz. Scaled coordinates are converted by to_cartesian() and image flags applied by unwrap(), as LAMMPS’s Domain::lamda2x and Domain::unmap compute them. Time and memory are \(O(n_a)\) for \(n_a\) atoms.

Examples

>>> box = Box(lo=np.zeros(3), hi=np.full(3, 10.0))
>>> frame = DumpFrame(timestep=0, box=box,
...                   columns=("id", "x", "y", "z", "ix", "iy", "iz"),
...                   data=np.array([[1, 9.5, 5.0, 5.0, -1, 0, 0]]))
>>> frame.positions()
array([[9.5, 5. , 5. ]])
>>> frame.positions(unwrapped=True)
array([[-0.5,  5. ,  5. ]])
time: float | None = None#
timestep: int#
units: str | None = None#
polyphys.simulate.dump.iter_dump(path, *, sort_by_id=True)[source]#

Yield the frames of a LAMMPS dump file one at a time.

Added in version 0.6.0.

Parameters:
  • path (str | pathlib.Path) – A text dump of dump atom or dump custom; a name ending in .gz is read through gzip.

  • sort_by_id (bool) – True to order each frame’s rows by the id column; LAMMPS writes atoms in no fixed order unless dump_modify sort is set. A frame without an id column keeps its file order.

Yields:

DumpFrame – The frames in file order, each read only when it is requested.

Raises:
  • BrokenDumpError – If a frame is cut off or does not follow the format; the frames before it have been yielded. The message names the file, the frame (from 0), its timestep when known, and the line (from 1).

  • FileNotFoundError – If path does not exist, raised when the first frame is requested.

Return type:

Generator[DumpFrame, None, None]

Notes

A frame whose timestep is not larger than the one before, as when a restarted run writes its restart step again, is yielded and logged as a warning.

Time is \(O(n_a n_c)\) per frame for \(n_a\) atoms and \(n_c\) columns; memory is that of one frame, plus the frames the caller keeps. Each frame’s atom lines are parsed by one split and one conversion to float64, with no loop over atoms in Python.

Examples

>>> import tempfile
>>> text = '''ITEM: TIMESTEP
... 0
... ITEM: NUMBER OF ATOMS
... 2
... ITEM: BOX BOUNDS pp pp pp
... 0.0 10.0
... 0.0 10.0
... 0.0 10.0
... ITEM: ATOMS id type xs ys zs
... 2 1 0.2 0.5 0.5
... 1 1 0.1 0.5 0.5
... '''
>>> with tempfile.TemporaryDirectory() as tmp:
...     path = Path(tmp) / "chain.lammpstrj"
...     _ = path.write_text(text)
...     frames = list(iter_dump(path))
>>> [(frame.timestep, frame.n_atoms) for frame in frames]
[(0, 2)]
>>> frames[0].column("id")
array([1, 2])
>>> frames[0].positions()
array([[1., 5., 5.],
       [2., 5., 5.]])
polyphys.simulate.dump.read_dump_frame(path, index=0, *, sort_by_id=True)[source]#

Read one frame of a LAMMPS dump file.

Added in version 0.6.0.

Parameters:
Return type:

polyphys.simulate.dump.DumpFrame

Raises:
  • IndexError – If index is negative or the file has no frame index.

  • BrokenDumpError – If a frame up to and including frame index is broken.

Notes

Every frame before index is parsed: time is \(O((index + 1) n_a n_c)\), memory that of one frame.

Examples

>>> import tempfile
>>> frame = '''ITEM: TIMESTEP
... {step}
... ITEM: NUMBER OF ATOMS
... 1
... ITEM: BOX BOUNDS pp pp pp
... 0 10
... 0 10
... 0 10
... ITEM: ATOMS id type x y z
... 1 1 {x} 5.0 5.0
... '''
>>> text = frame.format(step=0, x=1.0) + frame.format(step=500, x=1.5)
>>> with tempfile.TemporaryDirectory() as tmp:
...     path = Path(tmp) / "bead.lammpstrj"
...     _ = path.write_text(text)
...     second = read_dump_frame(path, 1)
>>> second.timestep, second.positions()
(500, array([[1.5, 5. , 5. ]]))