WWW Site - Documentation - Tools

dump tool


Read, write, manipulate dump files and particle attributes.


The dump tool reads one or more LAMMPS dump files, stores their contents as a series of snapshots with 2d arrays of atom attributes, and allows the values to be accessed and manipulated. Other tools use dump objects to convert LAMMPS files to other formats or visualize the atoms.

The constructor method is passed a string containing one or more dump filenames. They can be listed in any order since snapshots are sorted by timestep after they are read and duplicate snapshots (with the same time stamp) are deleted. If a 2nd argument is specified, the files are not immediately read, but snapshots can be read one-at-a-time by the next() method.

The map() method assigns names to columns of atom attributes. The tselect() methods select one or more snapshots by their time stamp. The delete() method deletes unselected timesteps so their memory is freed up. This can be useful to do when reading snapshots one-at-a-time for huge data sets. The aselect() methods selects atoms within selected snapshots. The write() and scatter() methods write selected snapshots and atoms to one or more files.

The scale(), unscale(), wrap(), unwrap(), and owrap() methods change the coordinates of all atoms with respect to the simulation box size. The sort() method sorts atoms within snapshots by their ID or another specified column.

The set() method enables new or existing columns to be set to new values. The minmax() method sets a column to an integer value between the min and max values in another column; it can be used to create a color map. The clone() method copies that column values at one timestep to other timesteps on a per-atom basis.

The time(), atom(), and vecs() methods return time or atom data as vectors of values.

The iterator() and viz() methods are called by tools that visualize snapshots of atoms (e.g. gl, raster, svg tools). You can also use the iterator() method in your scripts to loop over selected snapshots. The atype setting determines what atom column is returned as the atom "type" by the viz() method. The bonds() method can be used to create a static list of bonds that are returned by the viz() method.

Normally, LAMMPS creates the dump files read in by this tool. If you want to create them yourself, the format of LAMMPS dump files is simple. Each snapshot is formatted as follows:

0 3.35919
0 3.35919
0 7.50
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
N 3 0.7 0.5 0.6 

The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the next line, zlo zhi on the last. There are N lines following "ITEM: ATOMS" where N is the number of atoms. As the dump tool commands indicate, atoms do not have to be listed in any particular order. There can be a different number of atoms in each snapshot. The values on each atom line are "ID type x y z" by default, but other quantities can be listed in any desired order. The map() command can be used to specify the ordering if it is not the default.


d = dump("")              read in one or more dump files
d = dump("dump.1 dump.2.gz")	  can be gzipped
d = dump("dump.*")		  wildcard expands to multiple files
d = dump("dump.*",0)		  two args = store filenames, but don't read 
  incomplete and duplicate snapshots are deleted
  atoms will be unscaled if stored in files as scaled
  self-describing column names assigned  
time =             	  read next snapshot from dump files 
  used with 2-argument constructor to allow reading snapshots one-at-a-time
  snapshot will be skipped only if another snapshot has same time stamp
  return time stamp of snapshot read
  return -1 if no snapshots left or last snapshot is incomplete
  no column name assignment or unscaling is performed,"id",3,"x")               assign names to columns (1-N) 
  not needed if dump file is self-describing 
d.tselect.all()			  select all timesteps		  select only timestep N
d.tselect.none()		  deselect all timesteps
d.tselect.skip(M)		  select every Mth step
d.tselect.test("$t >= 100 and $t < 10000")      select matching timesteps
d.delete()	      	      	  delete non-selected timesteps 
  selecting a timestep also selects all atoms in the timestep
  skip() and test() only select from currently selected timesteps
  test() uses a Python Boolean expression with $t for timestep value
    Python comparison syntax: == != < > <= >= and or 
d.aselect.all()	      	                      select all atoms in all steps
d.aselect.all(N)      	                      select all atoms in one step
d.aselect.test("$id > 100 and $type == 2")    select match atoms in all steps
d.aselect.test("$id > 100 and $type == 2",N)  select matching atoms in one step 
  all() with no args selects atoms from currently selected timesteps
  test() with one arg selects atoms from currently selected timesteps
  test() sub-selects from currently selected atoms
  test() uses a Python Boolean expression with $ for atom attributes
    Python comparison syntax: == != < > <= >= and or
    $name must end with a space 
d.write("file")	   	           write selected steps/atoms to dump file
d.write("file",head,app)	   write selected steps/atoms to dump file
d.scatter("tmp")		   write selected steps/atoms to multiple files 
  write() can be specified with 2 additional flags
    head = 0/1 for no/yes snapshot header, app = 0/1 for write vs append
  scatter() files are given timestep suffix: e.g. tmp.0, tmp.100, etc 
d.scale() 	    	  	   scale x,y,z to 0-1 for all timesteps
d.scale(100)			   scale atom coords for timestep N
d.unscale()			   unscale x,y,z to box size to all timesteps
d.unscale(1000)			   unscale atom coords for timestep N
d.wrap()			   wrap x,y,z into periodic box via ix,iy,iz
d.unwrap()			   unwrap x,y,z out of box via ix,iy,iz
d.owrap("other")		   wrap x,y,z to same image as another atom
d.sort()              	  	   sort atoms by atom ID in all selected steps
d.sort("x")            	  	   sort atoms by column value in all steps
d.sort(1000)			   sort atoms in timestep N 
  scale(), unscale(), wrap(), unwrap(), owrap() operate on all steps and atoms
  wrap(), unwrap(), owrap() require ix,iy,iz be defined
  owrap() requires a column be defined which contains an atom ID
    name of that column is the argument to owrap()
    x,y,z for each atom is wrapped to same image as the associated atom ID
    useful for wrapping all molecule's atoms the same so it is contiguous 
m1,m2 = d.minmax("type")               find min/max values for a column
d.set("$ke = $vx * $vx + $vy * $vy")   set a column to a computed value
d.setv("type",vector)                  set a column to a vector of values
d.spread("ke",N,"color")	       2nd col = N ints spread over 1st col
d.clone(1000,"color")	       	       clone timestep N values to other steps 
  minmax() operates on selected timesteps and atoms
  set() operates on selected timesteps and atoms
    left hand side column is created if necessary
    left-hand side column is unset or unchanged for non-selected atoms
    equation is in Python syntax
    use $ for column names, $name must end with a space
  setv() operates on selected timesteps and atoms
    if column label does not exist, column is created
    values in vector are assigned sequentially to atoms, so may want to sort()
    length of vector must match # of selected atoms
  spread() operates on selected timesteps and atoms
    min and max are found for 1st specified column across all selected atoms
    atom's value is linear mapping (1-N) between min and max
    that is stored in 2nd column (created if needed)
    useful for creating a color map
  clone() operates on selected timesteps and atoms
    values at every timestep are set to value at timestep N for that atom ID
    useful for propagating a color map 
t = d.time()  	     	       	   return vector of selected timestep values
fx,fy,... = d.atom(100,"fx","fy",...)   return vector(s) for atom ID N
fx,fy,... = d.vecs(1000,"fx","fy",...)  return vector(s) for timestep N 
  atom() returns vectors with one value for each selected timestep
  vecs() returns vectors with one value for each selected atom in the timestep 
index,time,flag = d.iterator(0/1)          loop over dump snapshots
time,box,atoms,bonds,tris,lines = d.viz(index)   return list of viz objects
d.atype = "color"                          set column returned as "type" by viz
d.extra(obj)				   extract bond/tri/line info from obj 
  iterator() loops over selected timesteps
  iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
    index = index within dump object (0 to # of snapshots)
    time = timestep value
    flag = -1 when iteration is done, 1 otherwise
  viz() returns info for selected atoms for specified timestep index
    can also call as viz(time,1) and will find index of preceding snapshot
    time = timestep value
    box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
    atoms = id,type,x,y,z for each atom as 2d array
    bonds = id,type,x1,y1,z1,x2,y2,z2,t1,t2 for each bond as 2d array
      if extra() used to define bonds, else NULL
    tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
      if extra() used to define tris, else NULL
    lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
      if extra() used to define lines, else NULL
  atype is column name viz() will return as atom type (def = "type")
  extra() extracts bonds/tris/lines from obj each time viz() is called
    obj can be data object for bonds, cdata object for tris and lines, 
      bdump object for bonds, tdump object for tris, ldump object for lines.
      mdump object for tris 

Related tools:

data, gl, mdump, tdump, raster, svg


Numeric or NumPy Python packages. Gunzip command (if you want to read gzipped files).