Spectral Graph Modal Analysis

SGMA performs joint spatial-temporal wavelet transforms on graph signals to identify oscillatory modes in the wavenumber-frequency domain. The SGWT is constructed from the graph Laplacian \(\mathbf{L}\), whose eigenvalues \(\lambda\) correspond to squared wavenumber \(k^2\).

API Reference

class SGMA(L, scales, freqs, order=10, w0=2 * np.pi)

Bases: object

Spectral Graph Modal Analysis (SGMA) engine.

Performs joint spatial-temporal wavelet transforms on graph signals to identify oscillatory modes. The joint wavelet transform is computed as:

\[W_{n,\tau}(s, f) = \langle \psi_s^{(n)}, X \phi_{f,\tau} \rangle\]

where \(\psi_s^{(n)}\) is the SGWT kernel localized at node n and scale s, and \(\phi_{f,\tau}\) is the temporal wavelet at frequency f centered at time \(\tau\).

Parameters:

• L (sparse matrix) – Graph Laplacian of shape (n_nodes, n_nodes). Must be symmetric PSD.

• scales (array_like) – Spatial scales for the SGWT (recommend log-spaced).

• freqs (array_like) – Temporal frequencies (Hz) to analyze.

• order (int, optional) – Bandpass filter order. Default is 10.

• w0 (float, optional) – Wavelet center frequency parameter. Default is 2*pi.

Ts

Temporal scales derived from frequencies.

Type:

ndarray

wavlen

Spatial wavelengths (sqrt of scales).

Type:

ndarray

analyze(V, t, bus, time, top_n=5, min_dist=5)

Compute spectrum and find peaks for a single bus.

analyze_many(V, t, time, buses=None, top_n=5, min_dist=5, verbose=True)

Extract peaks across multiple buses.

Pre-computes V @ B once for efficiency.

Parameters:

• V (ndarray) – Signal matrix of shape (n_nodes, n_time).

• t (ndarray) – Time vector.

• time (float) – Time instant for temporal wavelet center.

• buses (list of int, optional) – Bus indices to analyze. Default is all.

• top_n (int, optional) – Max peaks per bus.

• min_dist (int, optional) – Min index distance between peaks.

• verbose (bool, optional) – Print progress updates.

Returns:

Named tuple with peaks dict and clusters dict.

Return type:

NetworkAnalysisResult

close()

Release cached convolution resources and free CHOLMOD memory.

find_modes(spectrum, top_n=5, min_dist=5)

Identify oscillatory modes with damping estimation.

Damping is estimated via the log-gradient method. For spectrum \(M = |M|e^{j\phi}\):

\[\frac{\partial \log M}{\partial \omega} = \frac{\partial \ln|M|}{\partial \omega} + j\frac{\partial \phi}{\partial \omega}\]

At resonance for a second-order system:

\[\frac{\partial \log H}{\partial \omega}\bigg|_{\omega_n} = \frac{-j}{\zeta \omega_n}\]

Thus the damping ratio is:

\[\zeta = \frac{-1}{\omega_n \cdot \mathrm{Im}(\partial \log M / \partial \omega)} = \frac{-1}{2\pi f_0 \cdot (\partial \phi / \partial f)}\]

Parameters:

• spectrum (ndarray) – Complex spectrum from spectrum(…, return_complex=True).

• top_n (int, optional) – Maximum modes to identify.

• min_dist (int, optional) – Minimum index distance between peaks.

Returns:

Identified modes with frequency, damping, wavelength, magnitude.

Return type:

ModeTable

find_peaks(spectrum, top_n=5, min_dist=5, return_indices=False)

Identify local maxima in the spectrum.

Parameters:

• spectrum (ndarray) – Spectrum of shape (n_scales, n_freqs).

• top_n (int, optional) – Maximum peaks to return.

• min_dist (int, optional) – Minimum index distance between peaks.

• return_indices (bool, optional) – If True, include ScaleIdx and FreqIdx in output.

Returns:

Keys: Wavelength, Frequency, Magnitude, [ScaleIdx, FreqIdx].

Return type:

dict

spectrum(V, t, bus, time, VB=None, return_complex=False)

Compute the SGMA spectrum at a specific bus and time.

Parameters:

• V (ndarray) – Signal matrix of shape (n_nodes, n_time).

• t (ndarray) – Time vector of shape (n_time,).

• bus (int) – Node index for localized analysis.

• time (float) – Time instant (seconds) to center the temporal wavelet.

• VB (ndarray, optional) – Pre-computed V @ B matrix for the given time.

• return_complex (bool, optional) – If True, return complex spectrum. Default is False (magnitude).

Returns:

Spectrum of shape (n_scales, n_freqs).

Return type:

ndarray

class ModeTable(frequency, damping, wavelength, magnitude)

Bases: object

Container for identified oscillatory modes with tabular display. Stores mode parameters (frequency, damping ratio, wavelength, magnitude) and provides a formatted string representation for easy inspection. .. attribute:: frequency

Oscillation frequencies in Hz.

type:

ndarray

damping

Damping ratios (dimensionless). Positive values indicate stable modes.

Type:

ndarray

wavelength

Spatial wavelengths (sqrt of spatial scale). Larger values indicate inter-area modes; smaller values indicate local modes.

Type:

ndarray

magnitude

Transform magnitudes at peak locations.

Type:

ndarray

to_array()

Return mode data as a 2D array (n_modes x 4).

to_dict()

Return mode data as a dictionary.