gspx

gspx is a Rust crate for sparse graph signal processing. It provides fast implementations of graph convolution using rational kernel fitting and Chebyshev polynomial approximation. Supports dynamic graphs for applications with a changing network topology.

Designed around large sparse networks such as power systems, but the API works with any sparse Laplacian.

License: GPL-3.0-only MSRV: Rust 1.85

Install

[dependencies]
gspx = "0.1"

Quick Start

Load a Laplacian from a .mat file and filter:

use gspx::{StaticConvolver, impulse, load_laplacian};
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let laplacian = load_laplacian(Path::new("graph.mat"))?;
    let signal = impulse(&laplacian, 0, 1)?;

    let mut convolver = StaticConvolver::new(laplacian)?;
    let filtered = convolver.bandpass(signal.view(), &[0.25, 1.0, 4.0], 2)?;
    Ok(())
}

Other loaders: load_signal for .mat signal matrices, load_ply_laplacian and load_ply_xyz for PLY meshes.

Signals

Filtering APIs accept 1D signals (n_vertices,) or 2D matrices (n_vertices, n_signals). For SGMA the signal matrix is (n_vertices, n_times) and the time vector length must match n_times.

Examples

The repository includes runnable examples under examples/. Larger example Laplacians and meshes live under resources/library and are not packaged into the published crate.

use gspx::{Dataset, ExampleData, GraphKind, KernelPreset};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let data = ExampleData::from_dir("resources/library")?;
    let texas = data.graph(Dataset::Texas, GraphKind::Delay)?;
    let coords = data.coords(Dataset::Texas)?;
    let kernel = data.vf_kernel(KernelPreset::ModifiedMorlet)?;
    Ok(())
}

cargo run --example basic_static_filters
cargo run --example basic_dynamic_topology
cargo run --example basic_chebyshev
cargo run --example basic_vf_fit
cargo run --example basic_sgma
cargo run --example basic_resource
cargo run --example basic_local_files

Performance

perf_core measures end-to-end filtering calls with Criterion. Each value is the mean time in milliseconds for one deterministic real N x 1 signal. Exact filters use one scale ([1.0]) and lowpass/bandpass use order 1.

Static vs Dynamic Filtering

Real power-grid Laplacians from resources/library. No branch edits are applied between dynamic calls, isolating filtering cost.

Exact filtering on 65k–82k nodes stays in the low-single-digit millisecond range. Structure matters as much as node count.

Constructor and Lowpass

Dynamic Updates on USA

Platform Notes

• Targets Linux, macOS, and Windows
• Sparse shifted solves use SuiteSparse-backed LDL factorization via sprs-ldl
• The published crate does not include repository example datasets

Citation

If you use gspx for research, cite the associated HICSS paper.

@inproceedings{lowery-gspx-2026,
  title={Using Spectral Graph Wavelets to Analyze Large Power System Oscillation Modes},
  author={Lowery, Luke and Baek, Jongoh and Birchfield, Adam},
  year={2026}
}

The same citation metadata is also available in CITATION.cff.

Links

• Python sgwt: github.com/lukelowry/sgwt
• Python docs: sgwt.readthedocs.io
• Julia: github.com/lukelowry/SpectralGraphWavelet.jl
• SuiteSparse: github.com/DrTimothyAldenDavis/SuiteSparse
• Synthetic grid cases: electricgrids.engr.tamu.edu
• Author: lukelowry.github.io
• Google Scholar: scholar.google.com/citations