Tessellation Quickstart

To get started, import commensurability.tessellation.Tessellation and call it by passing in your point array or orbit object.

from commensurability.tessellation import Tessellation
tess = Tessellation(points_or_orbit)

This should create a Tessellation object specific to the dimensionality of your points. (For dimensions larger than 3, a generic N-dimensional class is used.)

For more thorough walkthroughs, see the usage guides.

Usage

This example will use numpy to create arrays of data. The package also uses matplotlib for plotting.

import numpy as np
import matplotlib.pyplot as plt

from commensurability.tessellation import Tessellation

Tessellating Points

Tessellation accepts a point array of shape (npoints, ndim) (e.g. 100 two-dimensional points mean a shape of (100, 2)). This is where you may pass in a point array generated from an orbit integration routine. You may also pass in an orbit object from gala or galpy. For demonstration, a random set of points will be generated here.

2D Example

# sample points around a circle
rng = np.random.default_rng(0)
theta = rng.uniform(-np.pi, np.pi, 100)
points = np.transpose([np.cos(theta), np.sin(theta)])

# add random noise
points += rng.normal(0, 0.05, points.shape)

3D Example

# sample points near the equator of a sphere
rng = np.random.default_rng(0)
phi = rng.uniform(-np.pi, np.pi, 200)
theta = rng.uniform(-np.pi/8, np.pi/8, 200)
points = np.transpose([
    np.cos(theta) * np.cos(phi),
    np.cos(theta) * np.sin(phi),
    np.sin(theta),
])

# add random noise
points += rng.normal(0, 0.05, points.shape)

Degeneracy

The Delaunay triangulation fails when the point set is degenerate or co-spherical. The above example would fail if no random noise was added.

This random point set can then be passed into Tessellation.

tess = Tessellation(points)

This returns an object with four attributes of note:

• tess.measure: The normalized commensurability value normalized between 0 and 1.
  • In 2 dimensional tessellations, tess.area is an alias for tess.measure.
  • In 3 dimensional tessellations, tess.volume is an alias for tess.measure.
• tess.points: The original point set passed in during initialization.
• tess.tri: The object returned by scipy.spatial.Delaunay.
• tess.mask: The boolean mask generated by the trimming algorithm across the tessellation—the corresponding simplices are stored in tess.tri.simplices.

Failed Triangulations

If the point set is degenerate or co-spherical,

• tess.tri will be set to a FailedDelaunay instance.
• tess.mask will be set to None.
• tess.measure will be set to 0.0.

Plotting Simplices

For 2 and 3 dimensional tessellations specifically, you can display a plot of the tessellation using tess.plot().

2D Example

fig, ax = plt.subplots()
tess.plot(ax, plot_included=True, plot_removed=True, plot_points=True)
plt.show()

3D Example

fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
tess.plot(ax, plot_included=True, plot_removed=True, plot_points=True)
plt.show()