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
-