# 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 of Cell 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. A list of Cell objects Container

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: 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$$ 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: 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 the Container.

max_radius_squared()

Maximum distance from pos() to outer edge of the cell (I think, see voro++ 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: 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: A list of 3-tuples of floats. Each tuple corresponds to a single vertex.
volume()

Cell volume