ashp.alphacomplex#

The alpha complex — the simplicial complex underlying an alpha shape.

Where ashp.alphashape() returns the geometric boundary, the alpha complex is the full combinatorial object: every Delaunay simplex of every dimension (vertices, edges, triangles, tetrahedra, …) tagged with the filtration value at which it enters. It is homotopy-equivalent to the union of balls around the points, so it captures the topology (components, holes, voids) exactly.

The filtration value of each simplex is built with the Edelsbrunner–Mücke algorithm used by GUDHI [Edelsbrunner and Mücke, 1994]: a top-dimensional cell takes its squared circumradius; processing dimensions top-down, a face that is Gabriel (its circumball is empty — the opposite apex lies outside it) keeps its own squared circumradius, otherwise it inherits the smallest value among its cofaces.

Classes#

AlphaComplex

An alpha complex: Delaunay simplices by dimension with filtration values.

Functions#

alpha_complex(→ AlphaComplex)

Build the alpha complex of a point set.

Module Contents#

class ashp.alphacomplex.AlphaComplex#

An alpha complex: Delaunay simplices by dimension with filtration values.

Variables:

points (numpy.ndarray) – The point coordinates the complex was built on.
simplices (list of numpy.ndarray) – simplices[k] is an (N_k, k + 1) array of vertex indices for the k-dimensional simplices (k = 0 vertices, 1 edges, …).
filtration (list of numpy.ndarray) – filtration[k] is the matching (N_k,) array of squared circumradii at which each simplex enters (the GUDHI convention). A simplex is present in the alpha shape at alpha when this value is at most (1 / alpha) ** 2.

points: numpy.ndarray#

simplices: List[numpy.ndarray]#

filtration: List[numpy.ndarray]#

property dim: int#: Ambient dimension (top simplices have dim + 1 vertices).

simplices_at(alpha: float) → List[numpy.ndarray]#

The simplices present at alpha (ashp convention, 1 / radius).

Parameters:: alpha (float) – 0 (or less) returns the whole Delaunay complex; larger values keep fewer simplices.
Returns:: The kept simplices, by dimension.
Return type:: list of numpy.ndarray

betti_chi(alpha: float) → int#

Euler characteristic of the complex at alpha.

The alternating sum of simplex counts, V - E + F - ...; for a 2-D filled complex this equals components - holes.

Parameters:: alpha (float) – The scale, in ashp’s 1 / radius convention.
Returns:: The Euler characteristic.
Return type:: int

metrics(n_steps: int = 120) → ComplexMetrics#

Edge-length spread and Betti numbers as alpha sweeps (2-D only).

At each alpha the metrics use the edges present in the complex (every Delaunay edge, interior and boundary, whose filtration value is below the threshold): the spread (std / coefficient of variation) of their lengths, plus b0 (components) and b1 (holes, = b0 - chi). The whole sweep is one sort + prefix sums + a single union-find pass.

Parameters:: n_steps (int, default 120) – Number of alpha samples.
Returns:: The metrics as functions of alpha (ascending).
Return type:: ComplexMetrics

betti_curve(n_steps: int = 120)#: Betti numbers (alpha, b0, b1) as alpha sweeps; see metrics().

persistence_1d() → numpy.ndarray#

One-dimensional persistence: the birth and death of every loop (2-D).

Each independent cycle (hole) is born when an edge closes it and dies when a triangle fills it. The standard boundary-matrix reduction (restricted to the triangle columns, which is all that 1-D persistence needs) pairs each filling triangle with the loop it kills.

A loop’s lifetime — e.g. log(death / birth) in squared radius — separates real holes (long-lived, like a ring’s centre) from triangulation noise (short-lived), denoising the raw b1 count.

Returns:: A (P, 2) array of (birth, death) filtration values (squared circumradii). Convert to ashp alpha with 1 / sqrt(value).
Return type:: numpy.ndarray

ashp.alphacomplex.alpha_complex(points: List[Tuple[float]] | numpy.ndarray) → AlphaComplex#

Build the alpha complex of a point set.

Parameters:: points (list of tuple of float or numpy.ndarray) – An iterable container of 2-D or 3-D points.
Returns:: Every Delaunay simplex tagged with its filtration value.
Return type:: AlphaComplex