Pizza.py WWW Site - Pizza.py Documentation - Pizza.py Tools

### dump tool

Purpose:

Read, write, manipulate dump files and particle attributes.

Description:

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 Pizza.py 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:

    ITEM: TIMESTEP
    100
    ITEM: NUMBER OF ATOMS
    32
    ITEM: BOX BOUNDS
    0 3.35919
    0 3.35919
    0 7.50
    ITEM: ATOMS
    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.

Usage:

    d = dump("dump.one")              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

    time = d.next()             	  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

    d.map(1,"id",3,"x")               assign names to atom columns (1-N)

      not needed if dump file is self-describing

    d.tselect.all()			  select all timesteps
    d.tselect.one(N)		  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

Prerequisites:

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