8.9. Experimental APIs

Warning

These functions are still under development and may be removed or changed without deprecation. Use with caution.

Periodic boundary condition utilities

tile_pbc(pts, L, r=None)

Periodic tiling of pts (N,2), with bookkeeping.

Parameters:

• pts (ndarray) – (N,2) original positions.

• L (float) – Box size for periodic boundary conditions.

• r (float | None) – Maximum radius (or denoted as \(\ell\)) used to determine the tiling range (at least \(4\ell\), which ensures both correct cell shapes and forces, whereas \(2\ell\) only ensures correct cell shapes); if None, defaults to \(L\).

Returns:

An (M,2) array containing the tiled positions and an (M,) array containing indices mapping each tiled point back to its original index in 0..N-1.

Return type:

tuple[ndarray, ndarray]

Connectivity utilities

rebuild_connection_matrix(N, connect)

Build a symmetric sparse adjacency matrix from a cell-cell edge list.

Parameters:

• N (int) – Total number of cells.

• connect (ndarray) – (E,2) edge list, where each row is a pair of cell indices.

Returns:

An (N,N) boolean adjacency matrix, symmetrized so that both (i,j) and (j,i) are set for every input edge.

Return type:

csr_matrix

select_daughter_cluster(N, connect)

Randomly pick one connected component (“daughter cluster”) from the connectivity graph.

Parameters:

• N (int) – Total number of cells.

• connect (ndarray) – (E,2) edge list, where each row is a pair of cell indices.

Returns:

A tuple containing: an (N_sub,) numpy.ndarray of global indices for cells in the chosen cluster, the cluster size N_sub, and the (E_sub,2) numpy.ndarray of edges re-indexed to local 0..N_sub-1. If the graph has only one connected component, returns (None, N, connect) unchanged.

Return type:

tuple[ndarray | None, int, ndarray]

get_cluster_sizes(N, connect)

Compute the sizes of all connected components in the connectivity graph.

Parameters:

• N (int) – Total number of cells.

• connect (ndarray) – (E,2) edge list, where each row is a pair of cell indices.

Returns:

A tuple containing: an (n_components,) numpy.ndarray of component sizes, the number of connected components, and an (N,) numpy.ndarray of component labels for each cell.

Return type:

tuple[ndarray, int, ndarray]

Domain decomposition utilities

class DomainDecomposition(domain_id, grid_ix, grid_iy, x_range, y_range, halo_x_range, halo_y_range, local_global_ids, owned_local_ids, local_pts)

Point-only data for one spatial domain plus its halo.

This object stores the index bookkeeping needed to relate a local domain calculation back to the original global point array. It contains no finite Voronoi or AFV-specific data.

Parameters:

• domain_id (int) – Integer id of this spatial domain.

• grid_ix (int) – Domain index in the x direction.

• grid_iy (int) – Domain index in the y direction.

• x_range (tuple[float, float]) – Owned-domain x interval.

• y_range (tuple[float, float]) – Owned-domain y interval.

• halo_x_range (tuple[float, float]) – Local-domain x interval after expanding by the halo width.

• halo_y_range (tuple[float, float]) – Local-domain y interval after expanding by the halo width.

• local_global_ids (ndarray) – Global point ids included in this domain’s local box, including halo points.

• owned_local_ids (ndarray) – Local indices of points uniquely owned by this domain.

• local_pts (ndarray) – Local point coordinates, equivalent to points[local_global_ids].

decompose_points(points, grid_shape=(2, 2), halo_width=0.0, *, domain_bounds=None, method='dense')

Decompose points into owned grid domains plus halo/local points.

Points on internal owned-domain boundaries are assigned to exactly one domain by using right-sided binning and clipping at the outermost boundary. Halo/local domains include points on all halo box edges.

Tip

This function is independent of the finite Voronoi model. It only computes global/local point-index bookkeeping.

Parameters:

• points (ndarray) – (N,2) array of point coordinates.

• grid_shape (tuple[int, int]) – Number of owned domains in the x and y directions.

• halo_width (float) – Width added to each side of every owned domain to collect local halo points.

• domain_bounds (tuple[tuple[float, float], tuple[float, float]] | None) – Optional domain bounds as ((xmin, xmax), (ymin, ymax)). If None, bounds are inferred from points.

• method (Literal['dense', 'binned', 'sorted_x']) – Method used to collect halo points. "dense" builds a dense domain-by-point mask and is usually faster for moderate systems. "binned" reuses the owned-domain bins to reduce the number of candidate points checked for each halo and is usually faster for many domains. "sorted_x" uses less temporary memory.

Returns:

One list of DomainDecomposition objects in row-major order, where each element stores the local and global point information for a single domain.

Return type:

list[DomainDecomposition]

Raises:

• ValueError – If points does not have shape (N,2).

• ValueError – If points contains non-finite values.

• ValueError – If grid_shape, halo_width, domain_bounds, or method is invalid.