brainmass.laplacian_connectivity

brainmass.laplacian_connectivity#

brainmass.laplacian_connectivity(W, *, normalize=None, eps=1e-12, return_diag=False)#

Build graph Laplacian matrix from adjacency/connectivity matrix.

The graph Laplacian is a fundamental matrix representation used in spectral graph theory, graph signal processing, and network analysis. Given an adjacency matrix W and degree matrix D = diag(sum_j W_ij), this function computes one of three standard Laplacian forms.

Unnormalized Laplacian (normalize=None):

\[ L = W - D \]

Random Walk Normalized Laplacian (normalize="rw"):

\[ L_{\mathrm{rw}} = D^{-1} W = D^{-1} L - I \]

This form is asymmetric and commonly used in diffusion processes and random walks on graphs.

Symmetric Normalized Laplacian (normalize="sym"):

\[ L_{\mathrm{sym}} = D^{-1/2} W D^{-1/2} = D^{-1/2} L D^{-1/2} - I \]

This form is symmetric, preserves spectral properties, and is widely used in spectral clustering and graph neural networks.

Parameters:

  • W (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Adjacency or connectivity matrix with shape (N, N) representing weighted edges between N nodes. Should contain non-negative weights. For directed graphs, W[i, j] represents edge weight from node j to node i.

  • normalize (Literal['rw', 'sym'] | None) –

    Normalization mode for the Laplacian:

    • None (default): Returns unnormalized Laplacian L = W - D

    • "rw": Returns random walk normalized Laplacian L_rw = D^{-1}W - I

    • "sym": Returns symmetric normalized Laplacian L_sym = D^{-1/2}W D^{-1/2} - I

  • eps (float) – Small constant added for numerical stability when computing D^{-1} or D^{-1/2}, preventing division by zero for isolated nodes (zero degree).

  • return_diag (bool) – If True, return a tuple (L, d) where L is the Laplacian matrix and d is the degree vector (row sums of W). If False (default), return only the Laplacian matrix.

Returns:

If return_diag=False (default): Returns the graph Laplacian matrix with shape (N, N) and dtype as input W. If return_diag=True: Returns a tuple (L, d) where L is the Laplacian matrix with shape (N, N) and d is the degree vector with shape (N,). If W carries units via brainunit, the output preserves unit consistency.

Return type:

Array | ndarray | bool | number | bool | int | float | complex | Quantity | Tuple[Array | ndarray | bool | number | bool | int | float | complex | Quantity, Array | ndarray | bool | number | bool | int | float | complex | Quantity]

Raises:

ValueError – If normalize is not one of {None, “rw”, “sym”}.

Notes

  • Assumptions: This function assumes non-negative edge weights. For directed graphs, interpretation requires care as the degree matrix D uses row sums.

  • Numerical stability: The eps parameter prevents division-by-zero errors for isolated nodes with degree zero. Nodes with degree < eps will be treated as having degree = eps.

  • Unit safety: Fully compatible with brainunit for unit-safe array operations.

  • Use cases:

    • Unnormalized: Best for preserving absolute connectivity structure and scale

    • Random walk: Suitable for diffusion analysis and probabilistic processes

    • Symmetric: Preferred for spectral analysis, clustering, and eigendecomposition

Examples

Compute unnormalized Laplacian for a simple 3-node graph:

>>> import brainunit as u
>>> W = u.math.asarray([[0., 1., 1.],
...                      [1., 0., 1.],
...                      [1., 1., 0.]])
>>> L = laplacian_connectivity(W)
>>> # L = [[ 2, -1, -1],
>>> #      [-1,  2, -1],
>>> #      [-1, -1,  2]]

Compute symmetric normalized Laplacian:

>>> L_sym = laplacian_connectivity(W, normalize="sym")
>>> # L_sym = [[ 1.0, -0.5, -0.5],
>>> #          [-0.5,  1.0, -0.5],
>>> #          [-0.5, -0.5,  1.0]]