7.7. Experimental API

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)[source]

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 \(2\ell\)); if None, defaults to \(L/2\).

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)[source]

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)[source]

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)[source]

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]