upxo.pxtal.voronoi_tessellation_2d package

Submodules

Module contents

2D Voronoi tessellation package for UPXO.

Exposes high-fidelity 2D Voronoi geometry generation routines: - Periodic Boundary Conditions (PBC) - Laguerre tessellation / Power diagrams (weighted Voronoi) - Centroidal Voronoi Tessellation (CVT) via Lloyd relaxation - Interface perturbation and boundary curvature modeling

upxo.pxtal.voronoi_tessellation_2d.coerce_bounds_2d(bounds: Sequence | Dict | None = None, seeds: numpy.ndarray | None = None, padding_fraction: float = 0.05) → List[List[float]][source]

Coerce bounds specification into standard [[xmin, xmax], [ymin, ymax]].

Parameters:

  • bounds (sequence or dict, optional) – Bounds as [[xmin, xmax], [ymin, ymax]], (xmin, xmax, ymin, ymax), or {'xbound': [xmin, xmax], 'ybound': [ymin, ymax]}.

  • seeds (np.ndarray, optional) – (N, 2) coordinate array to infer bounds from if bounds is None.

  • padding_fraction (float, optional) – Padding factor applied when inferring bounds from seeds. Default 0.05.

Returns:

[[xmin, xmax], [ymin, ymax]]

Return type:

list of list of float

upxo.pxtal.voronoi_tessellation_2d.compute_standard_voronoi_2d(seeds: numpy.ndarray, bounds: Sequence | Dict | None = None, periodic: Tuple[bool, bool] = (False, False), clip: bool = True) → Dict[int, shapely.geometry.Polygon][source]

Compute bounded 2D Voronoi polygons mapped exactly to seed indices.

Parameters:

  • seeds (np.ndarray, shape (N, 2)) – Seed coordinates.

  • bounds (sequence or dict, optional) – Domain bounds [[xmin, xmax], [ymin, ymax]]. If None, inferred from seeds.

  • periodic (tuple of bool, optional) – (periodic_x, periodic_y). Default is (False, False).

  • clip (bool, optional) – Whether to clip cells to the bounding box. Default is True.

Returns:

dict of {int – Mapping from seed index (0 .. N-1) to Shapely polygon.

Return type:

Polygon or MultiPolygon}

upxo.pxtal.voronoi_tessellation_2d.compute_power_diagram_2d(seeds: numpy.ndarray, weights: Sequence[float] | numpy.ndarray | None = None, bounds: Sequence | Dict | None = None, periodic: Tuple[bool, bool] = (False, False), clip: bool = True) → Dict[int, shapely.geometry.Polygon][source]

Compute 2D Laguerre tessellation / Power diagram using the lifted 3D lower convex hull.

For each seed point \(\mathbf{s}_i = (x_i, y_i)\) with weight \(w_i\), the power cell is the set of points \(\mathbf{x}\) satisfying: \(\|\mathbf{x} - \mathbf{s}_i\|^2 - w_i \le \|\mathbf{x} - \mathbf{s}_j\|^2 - w_j\).

Parameters:

  • seeds (np.ndarray, shape (N, 2)) – Seed coordinates.

  • weights (sequence or np.ndarray, shape (N,), optional) – Seed weights (e.g. squared target radii). If None, defaults to uniform weights.

  • bounds (sequence or dict, optional) – Domain bounds [[xmin, xmax], [ymin, ymax]]. If None, inferred from seeds.

  • periodic (tuple of bool, optional) – (periodic_x, periodic_y). Default is (False, False).

  • clip (bool, optional) – Whether to clip cells to the bounding box. Default is True.

Returns:

dict of {int – Mapping from seed index (0 .. N-1) to Shapely polygon.

Return type:

Polygon or MultiPolygon}

upxo.pxtal.voronoi_tessellation_2d.cvt_relax_2d(seeds: numpy.ndarray, bounds: Sequence | Dict | None = None, iterations: int = 10, periodic: Tuple[bool, bool] = (False, False), weights: numpy.ndarray | None = None, max_iter: int | None = None) → numpy.ndarray[source]

Perform Centroidal Voronoi Tessellation (CVT) relaxation via Lloyd’s algorithm.

Iteratively updates each seed to the centroid of its Voronoi cell, producing regular, energy-minimized, equiaxed polycrystal seed configurations.

Parameters:

  • seeds (np.ndarray, shape (N, 2)) – Initial seed coordinates.

  • bounds (sequence or dict, optional) – Domain bounds [[xmin, xmax], [ymin, ymax]]. If None, inferred from seeds.

  • iterations (int, optional) – Number of Lloyd relaxation steps. Default is 10.

  • periodic (tuple of bool, optional) – (periodic_x, periodic_y). Default is (False, False).

  • weights (np.ndarray, optional) – Optional seed weights for weighted CVT. Default is None.

  • max_iter (int, optional) – Alias for iterations.

Returns:

Relaxed seed coordinates.

Return type:

np.ndarray, shape (N, 2)

upxo.pxtal.voronoi_tessellation_2d.perturb_interfaces_2d(cells: Dict[int, shapely.geometry.Polygon] | Sequence[shapely.geometry.Polygon] | shapely.geometry.MultiPolygon, bounds: Sequence | Dict | None = None, perturb_factor: float = 0.05, n_subdivisions: int = 2, random_seed: int | None = 42, factor: float | None = None, seed: int | None = None) → Dict[int, shapely.geometry.Polygon] | List[shapely.geometry.Polygon] | shapely.geometry.MultiPolygon[source]

Apply natural non-linear curvature perturbations to shared grain boundaries.

Internal grain boundaries are subdivided and displaced while domain boundary edges and triple/multiple junctions remain topologically pinned, ensuring watertight manifolds.

Parameters:

  • cells (dict, list, or MultiPolygon of Polygons) – Input Voronoi cells.

  • bounds (sequence or dict, optional) – Domain bounds [[xmin, xmax], [ymin, ymax]].

  • perturb_factor (float, optional) – Magnitude of perpendicular perturbation relative to edge length. Default 0.05.

  • n_subdivisions (int, optional) – Number of recursive midpoint subdivisions per edge. Default 2.

  • random_seed (int, optional) – RNG seed for reproducible perturbations. Default 42.

  • factor (float, optional) – Alias for perturb_factor.

  • seed (int, optional) – Alias for random_seed.

Returns:

Cells with curved/perturbed interfaces, preserving input collection type.

Return type:

dict, list, or MultiPolygon

upxo.pxtal.voronoi_tessellation_2d.generate_voronoi_2d(seeds: numpy.ndarray, bounds: Sequence | Dict | None = None, periodic: Tuple[bool, bool] = (False, False), weights: numpy.ndarray | None = None, cvt_iterations: int = 0, perturb_factor: float = 0.0, clip: bool = True, random_seed: int | None = 42) → Dict[str, Dict[int, shapely.geometry.Polygon] | shapely.geometry.MultiPolygon | numpy.ndarray | List[List[float]] | Tuple[bool, bool]][source]

Main orchestration function for high-fidelity 2D Voronoi geometry generation.

Parameters:

  • seeds (np.ndarray, shape (N, 2)) – Seed point coordinates.

  • bounds (sequence or dict, optional) – Domain bounds [[xmin, xmax], [ymin, ymax]]. If None, inferred from seeds.

  • periodic (tuple of bool, optional) – (periodic_x, periodic_y) flags for Periodic Boundary Conditions.

  • weights (np.ndarray, shape (N,), optional) – Seed weights for Laguerre / Power diagram tessellation.

  • cvt_iterations (int, optional) – Number of Lloyd relaxation iterations for Centroidal Voronoi.

  • perturb_factor (float, optional) – Magnitude of non-linear grain boundary interface perturbation.

  • clip (bool, optional) – Whether to clip cells to the bounding box. Default is True.

  • random_seed (int, optional) – RNG seed for perturbation reproducibility. Default is 42.

Returns:

‘cells’ : dict of {int: Polygon} ‘pxtal’ : Shapely MultiPolygon containing all cells ‘seeds’ : np.ndarray of final seed positions ‘bounds’ : standard bounds [[xmin, xmax], [ymin, ymax]] ‘periodic’ : (bool, bool)

Return type:

dict