LAMMPSDumpReader

class mdcraft.io.reader.LAMMPSDumpReader(filename: str | Path, /, coordinate_formats: str | list[str] | None = None, *, dt: float | Quantity | Quantity | None = None, extras: bool | str | list[str] | None = None, units_style: str | None = None, n_workers: int | None = 1, **kwargs)

Bases: BaseTrajectoryReader

LAMMPS dump file reader.

This class is not a full-featured LAMMPS dump file reader, but can process most, if not all, dump files written using a single dump command with atom, custom, grid, or local styles. Notably, it supports

• both compressed (.bz2) and text dump files,

• frame headers with units and/or time information (using dump_modify units yes and/or dump_modify time yes, respectively),

• frames with different numbers of atoms/entities,

• orthogonal, restricted triclinic, and general triclinic simulation boxes,

• any combination of (un)scaled and (un)wrapped coordinates, and

• all standard and custom attributes.

Furthermore, it can read in parallel, which can be much faster for parsing large dump files and performing analyses on multiple frames in those dump files.

Important

If the dump_modify command is used to alter the output in the dump file, the colname and header keywords must not be used. If the dump file is written in the local style, the label ATOMS option must also not be used.

Note

Frames in a dump file are ordered by their timestep numbers and are expected to proceed forward in time. If the reset_timestep command is used in the LAMMPS input script used to generate the dump file, this trajectory reader may behave unexpectedly.

See also

For more information on the LAMMPS dump file format, see the dump command page of the LAMMPS documentation.

Parameters:

filenamestr or pathlib.Path, positional-only

Filename or path to the dump file.

coordinate_formatsstr or list of str, optional

Coordinate formats. If a str is provided, it is used for all axes. If the trajectory does not contain particle positions for a specific axis, use None for that axis.

Valid values:

• "" for unscaled and wrapped coordinates,

• "s" for scaled and wrapped coordinates,

• "u" for unscaled and unwrapped coordinates, or

• "su" for scaled and unwrapped coordinates.

dtfloat, optional

Simulation time step size. Only used when the dump file was not written with dump_modify time yes. If not specified and the dump file does not contain time information, the step size is assumed to be the LAMMPS default for the style of units used.

extrasbool, str or list of str, keyword-only, optional

Extra per-atom information to read if the dump file was written in the atom or custom styles. If True, all extra attributes found in the trajectory are read.

Valid values:

Attribute	LAMMPS dump attribute(s)	Per-atom data type
"dipole_moments"	(mux, muy, muz)	numpy.ndarray[float]
"dipole_moments_magnitudes"	mu	float
"angular_velocities"	(omegax, omegay, omegaz)	numpy.ndarray[float]
"angular_momenta"	(angmomx, angmomy, angmomz)	numpy.ndarray[float]
"torques"	(tqx, tqy, tqz)	numpy.ndarray[float]
"c_{compute_id}"	(c_{compute_id}[i], …)	numpy.ndarray[float]
"d_{name}"	(d_{name}[i], …)	numpy.ndarray[float]
"d2_{name}[i]"	(d2_{name}[i][j], …)	numpy.ndarray[float]
"f_{fix_id}"	(f_{fix_id}[i], …)	numpy.ndarray[float]
"i_{name}"	(i_{name}[i], …)	numpy.ndarray[int]
"i2_{name}[i]"	(i2_{name}[i][j], …)	numpy.ndarray[int]
"v_{name}"	(v_{name}[i], …)	numpy.ndarray[float]

units_stylestr, optional

Style of units used in the dump file. If not specified, the style of units is determined from the file (when dump_modify units yes was used) or assumed to be units lj (the LAMMPS default) otherwise.

Valid values: "lj", "real", "metal", "si", "cgs", "electron", "micro", and "nano".

n_workersint, keyword-only, default: 1

Number of threads to use when reading the file. If None, the number of available logical threads is used.

Important

n_workers should be set to a value that is less than half the number of frames in the dump file if dt is not specified and is to be determined automatically.

Examples

The simplest way to load a LAMMPS dump file dump.lammpstrj containing atom trajectories is:

>>> reader = LAMMPSDumpReader("dump.lammpstrj")

Trajectory properties, like the coordinate formats, time step size, and style of units, are automatically determined from the file (if possible). Alternatively, the LAMMPSDumpReader constructor accepts keyword arguments—coordinate_formats, dt, and units_style, respectively—to directly specify these properties. Additionally, the constructor also accepts the extras keyword argument to specify extra attributes to read from the dump file, and the n_workers keyword arguments to control parallel parsing of the dump file.

For example, to parse the same dump file in parallel with 4 CPU threads and specify that it is in reduced Lennard-Jones units, the coordinates are scaled and unwrapped in the \(x\)- and \(y\)-directions but unscaled and wrapped in the \(z\)-direction, the time step size is \(\Delta t^*=0.005\), and all extra attributes should be read:

>>> reader = LAMMPSDumpReader(
...    "dump.lammpstrj",
...    ["su", "su", ""],
...    dt=0.005,
...    extras=True,
...    units_style="lj",
...    n_workers=4
... )

Then, the reader instance can be used to get basic trajectory properties:

>>> reader.dt
0.005
>>> reader.timestep
5
>>> reader.times
array([ 0.,  5., 10., 15., 20.])
>>> reader.n_frames
5
>>> reader.n_atoms
1000

or get raw data, like dimensions and positions, from frames:

>>> reader.read_frames([0, 1])
[{'time': 0, 'timestep': 0, 'dimensions': array([10., 10., 10., 90., 90., 90.]), ...},
 {'time': 5, 'timestep': 1, 'dimensions': array([10., 10., 10., 90., 90., 90.]), ...}]

Methods

close	Closes the LAMMPS dump file and deletes the handle.
open	Opens the LAMMPS dump file and stores a handle to it.
read_frames	Reads data from one or more frames from the trajectory file.

close() → None

Closes the LAMMPS dump file and deletes the handle.

property dt: float | None

Time step size between timesteps in the trajectory. If None, the step size is not constant across frames.

Reference unit: \(\mathrm{ps}\).

property n_atoms: int | None

Number of atoms in each frame. Only available if the dump file was written in the atom or custom styles. If None, the number of atoms is not constant across frames.

property n_entities: int | None

Number of atoms (atom or custom dump styles), grids (grid dump style), or local entities (local dump style) in each frame. If None, the number of entities is not constant across frames.

property n_frames: int

Number of frames in the trajectory.

property n_grids: tuple[int, int, int] | None

Number of grid cells in each dimension. Only available if the dump file was written in the grid style.

open() → None

Opens the LAMMPS dump file and stores a handle to it.

read_frames(frame_indices: int | slice | Iterable[int], /, *, _convert_units: bool = True) → dict[str, Any] | list[dict[str, Any]]

Reads data from one or more frames from the trajectory file.

Parameters:

frame_indicesint, slice, or array-like, positional-only

Indices of frames to read.

Returns:

datadict or list

Data from the frame(s).

property time_step: float | None

Time step between frames in the trajectory. If None, the time step is not constant across frames.

Reference unit: \(\mathrm{ps}\).

property times: ndarray[float64]

Simulation times found in the trajectory. May not be accurate if the time step size (dt) was not specified and could not be determined from the dump file.

Reference unit: \(\mathrm{ps}\).

property timesteps: ndarray[uint32]

Simulation timesteps found in the trajectory.