mechanochat.tools.signal_tensor#

mechanochat.tools.signal_tensor(xc: ndarray[Any, dtype[_ScalarType_co]], xc2grid_map: dict, grid_center: dict, sig_mat: csr_matrix, Nc_grid_min: int = 3)[source]#

Signal orientation tensor per grid cell.

Each cell contributes the signal-weighted outer product of the unit vectors towards its partners,

\[S_i = \sum_j s_{ij}\, \hat{u}_{ij} \otimes \hat{u}_{ij}, \qquad \hat{u}_{ij} = \frac{x_j - x_i}{\|x_j - x_i\|}\]

which is averaged over the cells of a grid cell and diagonalized. Unlike signal_direction, the tensor is sign-free: it describes the axis along which a grid cell communicates, not the direction.

Parameters:

xc (numpy.ndarray) – (nc, dim) cell coordinates.
xc2grid_map (dict) – Cell-to-grid mapping from cell2grid.
grid_center (dict) – Grid centers from cell2grid.
sig_mat (csr_matrix) – (nc, nc) signal matrix.
Nc_grid_min (int) – Minimum number of cells for a grid cell to be kept.

Returns:

Xgrid (numpy.ndarray) – (n_grid, dim) center of each retained grid cell.
Vegrid (numpy.ndarray) – (n_grid, dim, dim) eigenvectors scaled by their eigenvalue, sorted by ascending eigenvalue; column k is the k-th axis, so Vegrid[:, :, -1] is the dominant one.
Sgrid (numpy.ndarray) – (n_grid, dim, dim) mean tensor of each retained grid cell.