Common tessellation result

TessellationResult is the shared structured data contract for spatial and planar tessellations. Both public compute() functions return it by default; output='result' selects it explicitly. output='cells' is the supported explicit low-level route for raw cell dictionaries and, when requested, the raw diagnostics tuple.

Structured output is always one object. Diagnostics computed because of return_diagnostics=True or tessellation_check are stored in tessellation_diagnostics. Planar normalized objects are stored in normalized_vertices and normalized_topology. The compatibility name PlanarComputeResult is the identical class object, not a second wrapper; it will be removed in v0.8.

Direct construction is provisional. It validates documented ID, measure, empty-state, representation, and capability metadata, including the exact weight/shift-to-radius relationship for weight-first power input. Normal application code should obtain results from compute(...); the complete cross-field direct-construction contract may still be refined before 1.0. The aligned measure and empty-state arrays are snapshots: later mutation of the shared raw dictionaries does not update those arrays, while boundary access revalidates mutable boundary records against the snapshot before returning them. Empty cells always expose empty boundary collections; adding edge or face records to a shared empty raw cell makes boundary access raise. Deep copies and pickle round trips retain the read-only aligned-array and capability contracts without reinterpreting later permitted raw-record mutation.

The provisional global_vertices and global_edges conveniences preserve the historical planar result access pattern by forwarding to available normalized planar objects.

pyvoro2.result.TessellationResult dataclass

Dimension-neutral structured tessellation data.

TessellationResult records common scientific output without erasing dimension-specific geometry. It is the default return from both public compute functions; callers that deliberately need raw cell dictionaries can select output='cells' explicitly.

Attributes:

Name	Type	Description
dimension	Literal[2, 3]	Explicit spatial dimension, either 2 or 3.
domain	object	Validated domain object used by the computation.
mode	Literal['standard', 'power']	"standard" for a Voronoi diagram or "power" for a power/Laguerre diagram.
sites	ndarray	Read-only (n, dimension) copy of validated input coordinates in original input order.
ids	ndarray	Read-only (n,) integer IDs in original input order. Omitted external IDs are represented by 0..n-1.
cells	list[dict[str, Any]]	Raw user-visible cell dictionaries after external-ID remapping.
cell_measures	ndarray	Read-only (n,) snapshot of input-aligned areas in 2D or volumes in 3D. Hidden cells have measure zero.
empty_mask	ndarray	Read-only input-aligned boolean snapshot. It includes empty cells even when their raw records were omitted.
input_weights	ndarray | None	Read-only copy of mathematical power weights when the caller supplied weights=; otherwise None.
backend_radii	ndarray | None	Read-only copy of the exact non-negative radii supplied to the native power backend; for weight-first input these equal sqrt(input_weights + representation_shift). None in standard mode.
representation_shift	float | None	Common additive weight shift used to obtain the backend radii, or None for standard mode and direct radii.
tessellation_diagnostics	object | None	Dimension-specific tessellation diagnostics, when computed.
normalized_vertices	object | None	Dimension-specific normalized-vertex output, when computed.
normalized_topology	object | None	Dimension-specific normalized-topology output, when computed.

The outer object is frozen and every aligned numeric array is an owned, read-only copy. cells is deliberately different: the exact supplied list is retained, and its dictionaries and nested geometry remain mutable. The measure and empty-mask arrays are construction-time snapshots and do not follow later raw-record mutation. Mutating boundary records does affect later boundary access and may make :meth:require_boundaries raise an inconsistency error. Normalization and diagnostic objects retain their own dimension-specific mutability contracts.

Direct construction is provisional. The constructor validates raw-cell IDs, measures, empty state, representation metadata, and capability metadata against the aligned fields rather than repairing inconsistent input. The private keyword-only _boundaries_available and _periodic_shifts_available parameters carry construction capability state; the shared builder supplies them for normal integration use. Deep copies and pickle round trips preserve the existing snapshot state while restoring read-only owned arrays and capability state, even after allowed raw-record mutation.

boundary_kind property

Dimension-specific raw-cell boundary key.

global_edges property

Global planar edges when topology normalization is available.

global_vertices property

Global planar vertices from the available normalized output.

This provisional convenience preserves the historical PlanarComputeResult access pattern. It is None when no planar normalization output is available.

has_boundaries property

Whether raw boundary geometry was available to the builder.

has_normalized_topology property

Whether dimension-specific topology normalization is present.

has_normalized_vertices property

Whether dimension-specific vertex normalization is present.

has_periodic_shifts property

Whether boundary records carry requested periodic image shifts.

has_tessellation_diagnostics property

Whether dimension-specific tessellation diagnostics are present.

measure_kind property

Dimension-specific name of the values in cell_measures.

__deepcopy__(memo)

Deep-copy snapshots and mutable contents without revalidation.

__post_init__()

Validate the common contract and take ownership of aligned arrays.

__reduce_ex__(protocol)

Use a version-independent pickle restoration path.

require_boundaries()

Return boundary collections aligned with original input order.

Hidden sites always have empty boundary collections, whether their raw records were omitted or contain an explicitly empty collection. When :attr:has_periodic_shifts is true, returned edge or face records contain adjacent_shift annotations.

Raises:

Type	Description
ValueError	If boundary geometry was not available, or if later mutation made the shared raw records internally inconsistent.

require_normalized_topology()

Return normalized topology or raise if none was computed.

require_normalized_vertices()

Return normalized vertices or raise if none were computed.

require_tessellation_diagnostics()

Return tessellation diagnostics or raise if none were computed.

:::