DUMPReader

class sknano.io.DUMPReader(*args, autoread=True, reference_timestep=None, reference_index=None, formatter=None, style=None, dumpattrs=None, dumpattrmap=None, atomattrmap=None, **kwargs)

Bases: sknano.io.StructureIO

Class for reading LAMMPS dump file format.

Parameters:

• *args –

  list of one or more LAMMPS dump files.

• autoread (bool, optional) –

  Automatically read dump files. Default is True

  New in version 0.4.0.

• reference_timestep (int, optional) –

  The timestep corresponding to the timestep of the Trajectorys reference_snapshot. Default is None.

  Note

  Overrides reference_index if not None

  New in version 0.4.0.

• reference_index (int, optional) –

  The list index corresponding to the timestep of the Trajectorys reference_snapshot. Default is None.

  New in version 0.4.0.

• dumpattrmap (class:dict) – Python dict mapping custom dump attributes to Atom attributes.
• atomattrmap (dict) – dict mapping atom type to atom element

trajectory

Examples

Using LAMMPS, one often saves molecular dynamics atom trajectories to one or more custom dump files containing per-atom attributes of of each atom at a given timestep. Often the per-atom attributes are calculated from custom LAMMPS compute commands that one may want to map to a specific Atom attribute.

For example, consider a dump file containing per-atom dump attributes id, mol, type, x, y, z, vx, vy, vz, c_atom_ke, and c_atom_pe, where c_atom_ke and c_atom_pe are the LAMMPS compute-IDs from custom compute commands defined in a LAMMPS input script, which calculate per-atom values for kinetic energy and potential energy, respectively. To map these compute-IDs and their per-atom values to their respective Atom attributes ke and pe, one would use the following dict mapping:

>>> dumpattrmap = {'c_atom_pe': 'pe', 'c_atom_ke': 'ke'}

>>> from sknano.io import DUMPReader
>>> dumps = DUMPReader('dump.*', dumpattrmap=dumpattrmap)
>>> print(repr(dumps.dumpattrs2str()))
'id mol type x y z vx vy vz c_atom_ke c_atom_pe c_atom_CN'
>>> print(repr(dumps.atomattrs2str()))
'id mol type x y z vx vy vz ke pe'

Futhermore, atom attributes such as mass or element symbol are not typically included in a LAMMPS dump. The LAMMPS attribute usually associated with a specic atom element/mass is the type attribute. The atomattrmap parameter takes a dict, mapping keys of 2-tuples of strings of the form (from_attr, to_attr) to dict values of the form {from_attr_value_1: to_attr_value_1, ..., from_attr_value_N: to_attr_value_N}, where (from_attr|to_attr)_value_(i...N) are the explicit key, value pairs for the (from_attr, to_attr) attribute names.

For example, suppose that we want to use the dump attribute type values to set the element values, where we have knowledge of the fact that atoms with type=1 correspond to Carbon atoms (i.e. element='C'), while atoms with type=2 correspond to Nitrogen atoms (i.e., element='N'). We would like to pass this metadata to the `DUMPReader constructor so that the Atoms object returned by the Trajectory Snapshots atoms attribute will have the correct elements corresponding to the atom types. To achieve this, we would call DUMPReader with the atomattrmap keyword argument set as follow:

>>> dumps = DUMPReader('dump.*', dumpattrmap=dumpattrmap,

... atomattrmap={(‘type’, ‘element’): {1:’C’, 2:’Ar’}}) >>> atoms = dumps[0].atoms >>> print(atoms[0])

Attributes

atoms	Structure Atoms.
basis	Structure BasisAtoms.
comment_line	Comment line.
crystal_cell	Structure CrystalCell.
fmtstr	Format string.
lattice	Structure Crystal3DLattice.
lattice_shift	Lattice displacement vector.
reference_index	Reference snapshot index.
reference_timestep	Reference snapshot timestep.
scaling_matrix	CrystalCell.scaling_matrix.
structure	An alias to self.
unit_cell	Structure UnitCell.

Methods

clear()	Clear list of StructureMixin.atoms.
make_supercell(scaling_matrix[, wrap_coords])	Make supercell.
map(*pairs)	Update dumpattrs2index mapping.
new_dumpattr(attr[, values])	Add new dump attr to snapshots.
newcolumn(name)	An alias for DUMPReader.new_dumpattr for compatibility LAMMPS pizza.py dump module.
read()	Read all snapshots from each dump file.
read_data(*args, **kwargs)	Read LAMMPS Data file.
read_dump(*args, **kwargs)	Read LAMMPS Dump file.
read_pdb(*args, **kwargs)	Read PDB file.
read_snapshot(f)	Read snapshot from file.
read_xyz(*args, **kwargs)	Read XYZ file.
rotate(**kwargs)	Rotate crystal cell lattice, basis, and unit cell.
scale()	Scale cartesian coordinates to fractional coordinates.
todict()	Return dict of constructor parameters.
transform_lattice(scaling_matrix[, ...])	Transform structure lattice.
translate(t[, fix_anchor_points])	Translate crystal cell lattice, basis, and unit cell.
unscale()	Unscale fractional coordinates to cartesian coordinates.
unwrap()	Unwrap coordinates from inside box to outside.
update_dumpattr(attr[, values])	Add new dump attr to snapshots.
wrap()	Wrap coordinates from outside box to inside.
write(*args, **kwargs)	Write structure data to file.
write_data(**kwargs)	Write LAMMPS data file.
write_dump(**kwargs)	Write LAMMPS dump file.
write_pdb(**kwargs)	Write pdb file.
write_xyz(**kwargs)	Write xyz file.

Attributes Summary

reference_index	Reference snapshot index.
reference_timestep	Reference snapshot timestep.

Methods Summary

map(*pairs)	Update dumpattrs2index mapping.
new_dumpattr(attr[, values])	Add new dump attr to snapshots.
newcolumn(name)	An alias for DUMPReader.new_dumpattr for compatibility LAMMPS pizza.py dump module.
read()	Read all snapshots from each dump file.
read_snapshot(f)	Read snapshot from file.
scale()	Scale cartesian coordinates to fractional coordinates.
todict()	Return dict of constructor parameters.
unscale()	Unscale fractional coordinates to cartesian coordinates.
unwrap()	Unwrap coordinates from inside box to outside.
update_dumpattr(attr[, values])	Add new dump attr to snapshots.
wrap()	Wrap coordinates from outside box to inside.

Attributes Documentation

reference_index

Reference snapshot index.

reference_timestep

Reference snapshot timestep.

Methods Documentation

map(*pairs)

Update dumpattrs2index mapping.

This method is defined for compatibility with the LAMMPS pizza.py dump module.

Parameters:pairs (tuple) – 2 tuples of (column number, column name) pairs.

Notes

This function maps column numbers to dump attribute names, not the column index.

new_dumpattr(attr, values=None)

Add new dump attr to snapshots.

This method adds a new dump attribute to the DUMPFormatter.dumpattrs list and adds a new column of data to the _atoms_array with values of 0.0 if values=None.

This method has no effect if attr already exists.

Parameters:

• attr (str) –
• values ({float, array_like}, optional) –

newcolumn(name)

An alias for DUMPReader.new_dumpattr for compatibility LAMMPS pizza.py dump module.

read()

Read all snapshots from each dump file.

read_snapshot(f)

Read snapshot from file.

scale()

Scale cartesian coordinates to fractional coordinates.

todict()

Return dict of constructor parameters.

unscale()

Unscale fractional coordinates to cartesian coordinates.

unwrap()

Unwrap coordinates from inside box to outside.

update_dumpattr(attr, values=None)

Add new dump attr to snapshots.

This method adds a new dump attribute to the DUMPFormatter.dumpattrs list and adds a new column of data to the _atoms_array with values of 0.0 if values=None.

This method has no effect if attr already exists.

Parameters:

• attr (str) –
• values ({float, array_like}, optional) –

wrap()

Wrap coordinates from outside box to inside.