WWW Site - Documentation - Tools

cdata tool


Read, create, manipulate ChemCell data files.


The cdata tool reads and writes ChemCell data files which contain particle and surface information. It enables the creation of geometric models of cells for input to ChemCell.

The cdata constructor reads in the specified ChemCell data file. With no argument, an empty cdata object is created which can have objects added to it later, and then be written out.

A cdata object or file contains "objects" of different types. Each object has a unique user-assigned ID. Objects can be of several types: "group", "triangles", "region", "facets", or "lines". A group is a list of particles, all of the same type. Triangles define a surface and include a list of vertices, triangle definitions, and adjacent edge connections. A region is a geometric object that defines a surface, such as a sphere. Facets are a CUBIT meshing format that defines a set of vertices and triangles; it is converted into a triangles entry. Lines are a collection of line segments.

The box(), sphere(), shell(), cyl(), and cap() methods create a new "region" object. The q() method sets triangulations factors that are used when the region is converted into a triangulated surface for output or visualization.

The line() and ibox() methods create a "lines" object.

The surf() method creates a "triangles" object from a region, using the q() parameters. The surftri() method creats a new "triangles" object from a list of triangle indices belonging to another surface. The surfselect() method applies an if test to vertices and triangles in another surface to choose a subset of them to form a new "triangles" object. The bins() method sets the number of bins in x,y when surfaces are binned for the purpose of creating particles inside/outside the surface.

The part(), part2d(), partarray(), and partring() methods create a "group" of particles inside, outside, or on regions or triangulated surfaces. Particles are 3d by default, or 2d if created on a surface. The partsurf() method can be used to change the name of the surface 2d particles are on, since that attribute is written to a file when the particles are output. The creation of particles uses a random # generator whose initial seed can be set via the seed() method.

The random() method can be used to pick a random point on the surface of a "region" or "triangles" object. The project() method maps particles to the surface of a "region" or "triangulate" object.

The center(), trans(), rotate(), and scale() methods are used to perform a geometric transformation on a "group" of particles or a "triangles" object. The union() method creates a new object of "union" type from a list of objects. The join() method does the same thing except all objects in the list must be of the same type and the new object is also of that type. A join() can only be done for "group", "triangles", or "line" objects. The delete(), rename(), and copy() methods manipulate the IDs of previously defined objects.

Be default all objects are selected when created. The select() and unselect() methods can be used to select a subset of existing objects. The write() and append() methods write out selected objects to a file.

The iterator() and viz() methods are called by tools that visualize snapshots of atoms (e.g. gl, raster, svg tools). Only selected objects are returned to the caller. A cdata file can be visualzed similarly to a snapshots from a dump file. In the case of a cdata file, there is only a single snapshot with index 0.


c = cdata()			   create a datafile object
c = cdata("")              read in one or more ChemCell data files
c = cdata("mem.part.gz")  can be gzipped
c = cdata("mem.*")		   wildcard expands to multiple files"")		   read in one or more data files 
  read() has same argument options as constructor
  files contain the following kinds of entries, each of which becomes an object
    particles, triangles, region, facets
    particles is a list of particles -> becomes a group
    triangles is 3 lists of vertices, triangles, connections -> becomes a surf
    region is a ChemCell command defining a region -> becomes a region
    facets is a CUBIT format of vertices and triangles -> becomes a surf
  each object is assigned an ID = name in file
  ID can be any number or string, must be unique,xlo,ylo,zlo,xhi,yhi,zhi)  create a box region
c.sphere(ID,x,y,z,r)		   create a sphere region,x,y,z,r,rinner)	   create a shell region
c.cyl(ID,'x',c1,c2,r,lo,hi)	   create a axis-aligned cylinder region
c.cap(ID,'x',c1,c2,r,lo,hi)	   create a axis-aligned capped-cylinder region
c.q(ID,q1,q2,...)                  set region triangulation quality factors 
  box() can create an axis-aligned plane, line, or point if lo=hi
  cyl() can create an axis-aligned circle if lo=hi
  for cyl() and cap(): 'x' c1,c2 = y,z; 'y' c1,c2 = x,z; 'z' c,c2 = x,y
  q's are size factors for region triangulation
    for box, q1,q2,q3 = # of divisions per xyz of box
    for sphere or shell, q1 = # of divisions per face edge of embedded cube
    for cyl or cap, q1 = # of divisions per face edge of end cap, must be even
                    q2 = # of divisions along length of cylinder 
c.line(ID,x1,y1,z1,x2,y2,z2)       create a line object with one line
c.lbox(ID,xlo,ylo,zlo,xhi,yhi,zhi) create a line object with 12 box lines,id-region)               create a triangulated surf from a region
c.surftri(ID,id-surf,t1,t2,...)    create a tri surf from list of id-surf tris
c.surfselect(ID,id-surf,test)      create a tri surf from test on id-surf tris
c.bins(ID,nx,ny)                   set binning parameters for a surf 
  triangulation of a shell is just done for the outer sphere
  for surftri(), one or more tri indices (1-N) must be listed
  for surfselect(), test is string like "$x < 2.0 and $y > 0.0"
  bins are used when particles are created inside/outside a surf 
c.part(ID,n,id_in)  	           create N particles inside object id_in
c.part(ID,n,id_in,id_out)	   particles are also outside object id_out
c.part2d(ID,n,id_on)               create 2d particles on object id_on
c.partarray(ID,nx,nz,nz,x,y,z,dx,dy,dz)   create 3d grid of particles
c.partring(ID,n,x,y,z,r,'x')              create ring of particles
c.partsurf(ID,id_on)               change surf of existing 2d particle group
c.seed(43284)			   set random # seed (def = 12345) 
  generate particle positions randomly (unless otherwise noted)
  for part(), id_in and id_out must be IDs of a surf, region, or union object
    inside a union object means inside any of the lower-level objects
    outside a union object means outside all of the lower-level objects
  for part2d(), id_on must be ID of a surf, region, or union object
  for part2d(), particles will be written as 2d assigned to surf id_on
  for partring(), ring axis is in 'x','y', or 'z' direction
  partsurf() changes surf id_on for an existing 2d particle group 
x,n = c.random(ID)                 pick a random pt on surf of object ID
c.project(ID,ID2,dx,dy,dz,eps,fg)  project particles in ID to surf of obj ID2 
  random() returns pt = [x,y,z] and normal vec n [nx,ny,nz]
  for random(), ID can be surf or region obj
  project() remaps particle coords in group ID
    moves each particle along dir until they are within eps of surface
    if no fg arg, dir = (dx,dy,dz)
    if fg arg, dir = line from particle coord to (dx,dy,dz)
    ID2 can be surf or region obj
    particles are converted to 2d assigned to surf ID2,x,y,z)                 set center point of object
c.trans(ID,dx,dy,dz)   	 	   translate an object
c.rotate(ID,'x',1,1,0,'z',-1,1,0)  rotate an object
c.scale(ID,sx,sy,sz)		   scale an object 
  objects must be surface or particle group, regions cannot be changed
  for center(), default is middle of bounding box (set when obj is created)
  for rotate(), set any 2 axes, must be orthogonal, 3rd is inferred
    object is rotated so that it's current xyz axes point along new ones
  rotation and scaling occur relative to center point 
c.union(ID,id1,id2,...)		   create a new union object from id1,id2,etc
c.join(ID,id1,id2,...)             create a new object by joining id1,id2,etc
c.delete(id1,id2,...)              delete one or more objects
c.rename(ID,IDnew)                 rename an object
c.copy(ID,IDnew) 	           create a new object as copy of old object 
  for union, all lower-level objects must be of surface, region, or union style
  for join, all joined objects must be of same style: group, surf, line
    new object is the same style,id2,...)              select one or more objects                         select all objects
c.unselect(id1,id2,...)            unselect one or more objects
c.unselect()                       unselect all objects 
  selection applies to write() and viz() 
c.write("file")			   write all selected objs to ChemCell file
c.write("file",id1,id2,...)	   write only listed & selected objects to file
c.append("file")		   append all selected objs to ChemCell file
c.append("file",id1,id2,...)	   append only listed & selected objects 
  union objects are skipped, not written to file 
index,time,flag = c.iterator(0/1)          loop over single snapshot
time,box,atoms,bonds,tris,lines = c.viz(index)   return list of viz objects 
  iterator() and viz() are compatible with equivalent dump calls
  iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
    index = timestep index within dump object (only 0 for data file)
    time = timestep value (only 0 for data file)
    flag = -1 when iteration is done, 1 otherwise
  viz() returns info for selected objs for specified timestep index (must be 0)
    time = 0
    box = [xlo,ylo,zlo,xhi,yhi,zhi]
    atoms = id,type,x,y,z for each atom as 2d array
      NULL if atoms do not exist
    bonds = NULL
    tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
      regions are triangulated according to q() settings by viz()
      NULL if surfaces do not exist
    lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
      NULL if lines do not exist
    types are assigned to each object of same style in ascending order 

Related tools:

olog, data, gl, raster, svg

Prerequisites: none