Tess¶
A 3D cell-based Voronoi library based on voro++¶
This library includes Python bindings, using Cython.
Code available on Github.
Documentation available at Read the Docs.
Description¶
Tess is a library to calculate Voronoi (and Laguerre) tessellations in 3D and analyze their
structure. The tessellation is calculated as a list of Cell
objects, each of which
can give information on its volume, centroid, number of faces, surface area, etc. The library is
made with packings of spherical particles in mind, possibly with variable sizes.
voro++¶
The Tess library is a set of Python bindings to the Voro++ library. Voro++ provides all the algorithms, and Tess provides an easy to use interface to the voro++ library for Python, using Cython to do so.
Original work on voro++ by Chris H. Rycroft (UC Berkeley / Lawrence Berkeley Laboratory).
Quick Start¶
Installation¶
To install, use pip
(or easy_install
):
pip install --user tess
Or to install from Github:
pip install --user git+git://github.com/wackywendell/tess@master
Usage¶
The first step is to create a Container
:
>>> from tess import Container
>>> cntr = Container([[1,1,1], [2,2,2]], limits=(3,3,3), periodic=False)
A container is a list of Cell
objects, representing Voronoi cells:
>>> [round(v.volume(), 3) for v in cntr] [13.5, 13.5]
Cell
objects have many methods. Here are a few:
>>> [v.pos for v in cntr]
[(1.0, 1.0, 1.0), (2.0, 2.0, 2.0)]
>>> [v.centroid() for v in cntr]
[(1.09375, 1.09375, 1.09375), (1.90625, 1.90625, 1.90625)]
>>> [v.neighbors() for v in cntr]
[[-5, -2, -3, -1, -4, 1, -6], [0, -3, -6, -4, -5, -2, -1]]
>>> [v.face_areas() for v in cntr]
[[7.875, 1.125, 7.875, 7.875, 1.125, 11.691342951089922, 1.125],
[11.691342951089922, 1.125, 7.875, 7.875, 1.125, 7.875, 1.125]]
>>> [v.normals() for v in cntr]
[[(0.0, 0.0, -1.0),
(1.0, 0.0, 0.0),
(0.0, -1.0, 0.0),
(-1.0, 0.0, 0.0),
(0.0, 1.0, 0.0),
(0.5773502691896257, 0.5773502691896257, 0.5773502691896257),
(0.0, 0.0, 1.0)],
[(-0.5773502691896257, -0.5773502691896257, -0.5773502691896257),
(-0.0, -1.0, -0.0),
(0.0, 0.0, 1.0),
(0.0, 1.0, -0.0),
(0.0, 0.0, -1.0),
(1.0, 0.0, -0.0),
(-1.0, -0.0, -0.0)]]
See the Reference for more methods, or just use a Python interpreter or IPython notebook to find them on your own!
Voro++ Copyright And Acknowledgments¶
Copyright Notice¶
Voro++ Copyright (c) 2008, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
If you have questions about your rights to use or distribute this software, please contact Berkeley Lab’s Technology Transfer Department at TTD@lbl.gov.
NOTICE. This software was developed under partial funding from the U.S. Department of Energy. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, and perform publicly and display publicly. Beginning five (5) years after the date permission to assert copyright is obtained from the U.S. Department of Energy, and subject to any subsequent five (5) year renewals, the U.S. Government is granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.
Acknowledgments¶
This work (voro++) was supported by the Director, Office of Science, Computational and Technology Research, U.S. Department of Energy under Contract No. DE-AC02-05CH11231.
Full Contents¶
Reference¶
This is a library to calculate Voronoi cells and access their information.
Basic Process¶
Example
>>> from tess import Container
>>> c = Container([[1,1,1], [2,2,2]], limits=(3,3,3), periodic=False)
>>> [round(v.volume(), 3) for v in c]
[13.5, 13.5]
-
class
tess.
Container
(points, limits=1.0, periodic=False, radii=None, blocks=None)¶ A container (list) of Voronoi cells.
This is the main entry point into the
tess
module. After creation, this will be a list ofCell
objects.The
Container
must be rectilinear, and can have solid boundary conditions, periodic boundary conditions, or a mix of the two.>>> from tess import Container >>> c = Container([[1,1,1], [2,2,2]], limits=(3,3,3), periodic=False) >>> [round(v.volume(), 3) for v in c] [13.5, 13.5]
Parameters: - points (iterable of iterable of float) – The coordinates of the points, size Nx3.
- limits (float, 3-tuple of float, or two 3-tuples of float) – The box limits. If given a float L, then the box limits are [0, 0, 0] to [L, L, L]. If given a 3-tuple (Lx, Ly, Lz), limits are [0, 0, 0] to [Lx, Ly, Lz]. If given two 3-tuples (x0, y0, z0), (x1, y1, z1), limits are [x0, y0, z0] to [x1, y1, z1].
- periodic (bool or 3-tuple of bool, optional) – Periodicity of the x, y, and z walls
- radii (iterable of float, optional) – for unequally sized particles, for generating a Laguerre transformation.
Returns: A list of
Cell
objectsReturn type: Notes
Voronoi Tesselation
A point \(\vec x\) is part of a Voronoi cell \(i\) with nucleus \(\vec{r}_i\) iff
\[\left|\vec{x}-\vec{r}_{i}\right|^{2}<\left|\vec{x}-\vec{r}_{j}\right|^{2} \forall j\neq i\]Laguerre Tesselation, also known as Radical Voronoi Tesselation
A point \(\vec x\) is part of a Laguerre cell \(i\) with nucleus \(\vec{r}_i\) and radius \(R_i\) iff
\[\left|\vec{x}-\vec{r}_{i}\right|^{2}-R_{i}^{2}<\left|\vec{x}-\vec{r}_{j}\right|^{2} - R_{j}^{2}\forall j\neq i\]-
get_widths
()¶ Get the size of the box.
-
order
(l=6, local=False, weighted=True)¶ Returns crystalline order parameter \(Q_l\) (such as \(Q_6\)).
Requires numpy and scipy.
Parameters: - l (int, optional) – Defines which \(Q_l\) you want (6 is standard, for detecting hexagonal lattices)
- local (bool, optional) – Calculate Local \(Q_6\) (true) or Global \(Q_6\)
- weighted (bool, optional) – Whether or not to weight by area the faces of each polygonal side
Notes
For
local=False
, this calculates\[Q_l = \sqrt{\frac{4 \pi}{2 l + 1}\sum_{m=-l}^{l} \left| \sum_{i=1}^{N_b} w_i Y_{lm}\left(\theta_i, \phi_i \right) \right|^2}\]where:
\(N_b\) is the number of bonds
\(\theta_i\) and \(\phi_i\) are the angles of each bond \(i\), in spherical coordinates
\(Y_{lm}\left(\theta_i, \phi_i \right)\) is the spherical harmonic function
\(w_i\) is the weighting factor, either proportional to the area (for weighted) or all equal (\(\frac{1}{N_b}\))
For
local=True
, this calculates\[Q_{l,\mathrm{local}} = \sum_{j=1}^N \sqrt{\frac{4 \pi}{2 l + 1}\sum_{m=-l}^{l} \left| \sum_{i=1}^{n_b^j} w_i Y_{lm}\left(\theta_i, \phi_i \right) \right|^2}\]where variables are as above, and each cell is weighted equally but each bond for each cell is weighted: \(\sum_{i=1}^{n_b^j} w_i = 1\)
Returns: Return type: float
-
tess.
cart_to_spher
(xyz)¶ Converts 3D cartesian coordinates to the angular portion of spherical coordinates, (theta, phi).
Requires numpy.
Parameters: xyz (array-like, Nx3) – Column 0: the “elevation” angle, \(0\) to \(\pi\)
Column 1: the “azimuthal” angle, \(0\) to \(2\pi\)
Returns: Return type: array, Nx2
-
tess.
orderQ
(l, xyz, weights=1)¶ Returns \(Q_l\), for a given l (int) and a set of Cartesian coordinates xyz.
Requires numpy and scipy.
For global \(Q_6\), use \(l=6\), and pass xyz of all the bonds.
For local \(Q_6\), use \(l=6\), and the bonds have to be averaged slightly differently.
Parameters: - l (int) – The order of \(Q_l\)
- xyz (array-like Nx3) – The bond vectors \(\vec r_j - \vec r_i\)
- weights (array-like, optional) – How to weight the bonds; weighting by Voronoi face area is common.
Notes
This calculates
\[Q_l = \sqrt{\frac{4 \pi}{2 l + 1}\sum_{m=-l}^{l} \left| \sum_{i=1}^{N_b} w_i Y_{lm}\left(\theta_i, \phi_i \right) \right|^2}\]where:
\(N_b\) is the number of bonds
\(\theta_i\) and \(\phi_i\) are the angles of each bond \(i\), in spherical coordinates
\(Y_{lm}\left(\theta_i, \phi_i \right)\) is the spherical harmonic function
\(w_i\) are the weights, defaulting to uniform: (\(\frac{1}{N_b}\))
-
class
tess.
Cell
¶ A basic voronoi cell, usually created by
Container
.A Voronoi cell has polygonal faces, connected by edges and vertices.
The various methods of a Cell allow access to the geometry and neighbor information.
-
__repr__
¶
-
__str__
¶
-
centroid
()¶
-
face_areas
()¶ A list of the areas of each face.
Returns: Return type: A list of floats. Each inner list corresponds to a face.
-
face_freq_table
()¶
-
face_perimeters
()¶
-
face_vertices
()¶ A list of the indices of the vertices of each face.
Returns: - A list of lists of ints. Each inner list corresponds to a face, and each index corresponds
- to a vertex from
vertices()
.
-
id
¶ The
id
of the cell, which should generally correspond to its index in theContainer
.
-
max_radius_squared
()¶ Maximum distance from
pos()
to outer edge of the cell (I think, seevoro++
documentation.)
-
neighbors
()¶ Return a list of the neighbors of the current Cell.
This is a list of indices, which correspond to the input points. The exception to this is the walls: walls are numbered -1 to -6, so an index less than 0 in the list of neighbors() indicates that a Cell is neighbors with a wall.
-
normals
()¶ A list of the areas of each face.
Returns: Return type: A list of 3-tuples of floats. Each tuple corresponds to a face.
-
number_of_edges
()¶
-
number_of_faces
()¶
-
pos
¶ The position of the initial point around which this cell was created.
-
radius
¶ The radius of the particle around which this cell was created.
Defaults to 0.
-
surface_area
()¶
-
total_edge_distance
()¶
-
vertex_orders
()¶
-
vertices
()¶ A list of all the locations of the vertices of each face.
Returns: Return type: A list of 3-tuples of floats. Each tuple corresponds to a single vertex.
-
volume
()¶ Cell volume
-
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line