Purpose:
Read, create, manipulate ChemCell data files.
Description:
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 Pizza.py 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.
Usage:
c = cdata() create a datafile object
c = cdata("mem.surf") read in one or more ChemCell data files
c = cdata("mem.part.gz mem.surf") can be gzipped
c = cdata("mem.*") wildcard expands to multiple files
c.read("mem.surf") 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
c.box(ID,xlo,ylo,zlo,xhi,yhi,zhi) create a box region c.sphere(ID,x,y,z,r) create a sphere region c.shell(ID,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
c.surf(ID,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
c.center(ID,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
c.select(id1,id2,...) select one or more objects c.select() 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:
Prerequisites: none