Voronoi Analysis

Compute Voronoi-based geometric analyzers from trajectory snapshots.

This module performs Voronoi tessellation over selected trajectory frames and exports geometric metrics and optional cell geometry summaries. It is limited to Voronoi-derived descriptors and does not compute bond-order connectivity.

Usage context

• Spatial partitioning: Quantify local free volume and neighborhood geometry.
• Frame diagnostics: Track Voronoi metrics over selected simulation steps.
• Structural reporting: Export tessellation-derived tables for analysis UIs.

Request: VoronoiRequest

Request for Voronoi tessellation analysis.

This request is shared by metric-only and geometry-producing Voronoi tasks.

Fields

Field	Type	Default	Help	Choices
atom_ids	Optional[Sequence[int]]		Atom IDs to include in output. Empty means all atoms.
atom_types	Optional[Sequence[str]]		Element symbols to include when atom_ids is empty.
frames	Optional[Sequence[int]]		Frame indices to evaluate. Empty means all frames.
every	int	1	Stride over selected frames.
backend	str	scipy	Voronoi backend.	scipy, pyvoro

Examples

req = VoronoiRequest(atom_types=["O"], frames=[0, 50, 100], backend="scipy")

Sample output: VoronoiRequest(...) Meaning: The request selects atoms/frames and backend for Voronoi evaluation.

Result: VoronoiResult

Result of Voronoi metric analysis.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	VoronoiRequest

Examples

result = VoronoiScipyTask().run(data, req)
result.table[["atom_id", "voronoi_volume"]].head()

Sample output: DataFrame rows with one Voronoi metric record per selected atom/frame. Meaning: The table summarizes per-atom Voronoi cell properties.

Result: VoronoiGeometryResult

Result of Voronoi geometry analysis for 2D/3D visualization.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	VoronoiRequest

Notes

faces entries include local vertex indices and neighbor references.

Examples

result = VoronoiGeometryScipyTask().run(data, req)
result.table[["atom_id", "vertices", "faces"]].head(1)

Sample output: One-row DataFrame containing full cell geometry for a selected atom. Meaning: The result can drive 2D/3D Voronoi visualization pipelines.

Task: VoronoiScipyTask

Compute per-atom Voronoi metrics using SciPy.

Notes

SciPy Voronoi is non-periodic and can yield unbounded cells near boundaries.

Method: run(data: TrajectoryData, request: VoronoiRequest, reporter=None)

Compute Voronoi metric table using the SciPy backend.

Works on

TrajectoryData plus VoronoiRequest analyzer inputs

Parameters

Name	Type	Description
data	TrajectoryData	Trajectory coordinates, atom metadata, and optional iterations.
request	VoronoiRequest	Atom/frame selection and backend configuration.
reporter	Any, optional	Optional progress callback for frame-wise processing.

Returns

Type	Description
VoronoiResult	Metric-only Voronoi table and request echo.

Examples

result = VoronoiScipyTask().run(data, req)

Sample output: result.table with voronoi_volume, num_faces, is_bounded. Meaning: One row is produced per selected atom and frame.

Task: VoronoiPyvoroTask

Compute per-atom Voronoi metrics using pyvoro.

Notes

Uses pyvoro native cell outputs and enables periodic tessellation when box lengths are available and consistent with frame coordinates.

Method: run(data: TrajectoryData, request: VoronoiRequest, reporter=None)

Compute Voronoi metric table using the pyvoro backend.

Works on

TrajectoryData plus VoronoiRequest analyzer inputs

Parameters

Name	Type	Description
data	TrajectoryData	Trajectory coordinates, atom metadata, and optional iterations.
request	VoronoiRequest	Atom/frame selection and backend configuration.
reporter	Any, optional	Optional progress callback for frame-wise processing.

Returns

Type	Description
VoronoiResult	Metric-only Voronoi table and request echo.

Examples

result = VoronoiPyvoroTask().run(data, req)

Sample output: Table rows with backend="pyvoro" and per-cell metrics. Meaning: The task returns pyvoro-derived Voronoi metrics per selected atom/frame.

Task: VoronoiGeometryScipyTask

Compute per-atom Voronoi geometry using SciPy.

Face connectivity and neighbor mapping are reconstructed from SciPy ridge structures to produce per-cell geometry records.

Method: run(data: TrajectoryData, request: VoronoiRequest, reporter=None)

Compute Voronoi geometry table using the SciPy backend.

Works on

TrajectoryData plus VoronoiRequest analyzer inputs

Parameters

Name	Type	Description
data	TrajectoryData	Trajectory coordinates, atom metadata, and optional iterations.
request	VoronoiRequest	Atom/frame selection and backend configuration.
reporter	Any, optional	Optional progress callback for frame-wise processing.

Returns

Type	Description
VoronoiGeometryResult	Geometry-rich Voronoi table and request echo.

Examples

result = VoronoiGeometryScipyTask().run(data, req)

Sample output: Rows containing vertices, faces, and neighbor atom IDs per cell. Meaning: Each row captures full geometric context for one Voronoi cell.

Task: VoronoiGeometryPyvoroTask

Compute per-atom Voronoi geometry using pyvoro native cell outputs.

Method: run(data: TrajectoryData, request: VoronoiRequest, reporter=None)

Compute Voronoi geometry table using the pyvoro backend.

Works on

TrajectoryData plus VoronoiRequest analyzer inputs

Parameters

Name	Type	Description
data	TrajectoryData	Trajectory coordinates, atom metadata, and optional iterations.
request	VoronoiRequest	Atom/frame selection and backend configuration.
reporter	Any, optional	Optional progress callback for frame-wise processing.

Returns

Type	Description
VoronoiGeometryResult	Geometry-rich Voronoi table and request echo.

Examples

result = VoronoiGeometryPyvoroTask().run(data, req)

Sample output: Rows containing pyvoro-native cell geometry fields. Meaning: The output is suitable for geometry-aware Voronoi visualization.