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)[source] [edit on github][source]

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)[source] [edit on github][source]

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)[source] [edit on github][source]

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)[source] [edit on github][source]

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

read()[source] [edit on github][source]

Read all snapshots from each dump file.

read_snapshot(f)[source] [edit on github][source]

Read snapshot from file.

scale()[source] [edit on github][source]

Scale cartesian coordinates to fractional coordinates.

todict()[source] [edit on github][source]

Return dict of constructor parameters.

unscale()[source] [edit on github][source]

Unscale fractional coordinates to cartesian coordinates.

unwrap()[source] [edit on github][source]

Unwrap coordinates from inside box to outside.

update_dumpattr(attr, values=None)[source] [edit on github][source]

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()[source] [edit on github][source]

Wrap coordinates from outside box to inside.