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: UNITSandITEM: TIME, each followed by its value, may come beforeITEM: TIMESTEP;dump_modify units yeswrites the first in the first frame only, anddump_modify time yesthe second in every frame.ITEM: BOX BOUNDSends with three boundary flags, such aspp ff pp, and is followed by onelo hiline per dimension. For a restricted triclinic box it readsITEM: BOX BOUNDS xy xz yz pp pp ppand its lines arexlo_bound xhi_bound xy,ylo_bound yhi_bound xz, andzlo_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: ATOMSnames the per-atom columns. Unlessdump_modify sortis 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:
Frame headers: dump_custom.cpp, lines 660 to 725, and the same in dump_atom.cpp, lines 388 to 450; the bounds of a triclinic box: dump.cpp, lines 327 to 344.
Dependencies#
Python standard library: contextlib, dataclasses, itertools, logging, pathlib
Third-party: numpy
PolyPhys:
polyphys.simulate.core
Functions
|
Yield the frames of a LAMMPS dump file one at a time. |
|
Read one frame of a LAMMPS dump file. |
Classes
|
One frame of a LAMMPS dump. |
Exceptions
A LAMMPS dump is cut off or does not follow the dump format. |
- exception polyphys.simulate.dump.BrokenDumpError[source]#
Bases:
polyphys.simulate.core.LammpsFormatErrorA 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:
objectOne frame of a LAMMPS dump.
Added in version 0.6.0.
- Variables:
timestep (
int) – TheITEM: TIMESTEPvalue.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 (
tupleofstr) – The per-atom column names ofITEM: 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 asidare exact up to \(2^{53}\). Read-only.time (
floatorNone) – TheITEM: TIMEvalue (simulated time), or None if the frame has none.units (
strorNone) – TheITEM: UNITSvalue, 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:
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.]])
- column(name)[source]#
Return the values of one per-atom column.
- Parameters:
- Returns:
Shape
(n_atoms,): int64 for the integer attributesid,mol,proc,procp1,type,ix,iy, andiz, else a read-only float64 view ofdata.- Return type:
- 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])
- data: numpy.typing.NDArray[numpy.float64]#
- 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:
- Raises:
KeyError – If the frame lacks the columns for the requested coordinates.
Notes
Wrapped coordinates come from
x y z, else fromxs ys zs. Unwrapped ones come fromxu yu zu, else fromxsu ysu zsu, else from the wrapped coordinates and the image flagsix iy iz. Scaled coordinates are converted byto_cartesian()and image flags applied byunwrap(), as LAMMPS’sDomain::lamda2xandDomain::unmapcompute 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. ]])
- 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 ofdump atomordump custom; a name ending in.gzis read through gzip.sort_by_id (
bool) – True to order each frame’s rows by theidcolumn; LAMMPS writes atoms in no fixed order unlessdump_modify sortis set. A frame without anidcolumn 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:
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:
path (
str|pathlib.Path) – As foriter_dump().index (
int) – Position of the frame in the file, from 0.sort_by_id (
bool) – As foriter_dump().
- Return type:
- 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. ]]))