Crate gspx 

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.

crates.io | docs.rs

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.

Graph	N	Static (ms)			Dynamic (ms)
		Lowpass	Bandpass	Highpass	Lowpass	Bandpass	Highpass
Hawaii	37	0.00051	0.00101	0.00054	0.00051	0.00118	0.00053
WECC	240	0.00179	0.00344	0.00169	0.00171	0.00359	0.00195
Texas	2k	0.01704	0.03621	0.01754	0.01742	0.03490	0.01720
East	16k	1.63247	3.66904	1.42601	1.26126	2.91676	0.96470
EastWest	65k	2.09393	3.60965	1.53460	2.02737	3.35085	1.74977
USA	82k	2.02103	4.04234	1.45063	1.62788	3.88886	1.52146

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

Constructor and Lowpass

Graph	N	Constructor (ms)	Lowpass (ms)
Texas	2k	0.00286	0.01713
East	16k	0.76098	1.65513
EastWest	65k	0.77505	2.02311
USA	82k	0.80452	2.00556

Dynamic Updates on USA

Operation	Time (ms)
Warmed add_branch_once	1.78406
bandpass_one after 1 update	5.22890
bandpass_one after 10 updates	7.25095
bandpass_one after 50 updates	19.39280

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

Re-exports

pub use conv::ChebyConvolver;

pub use conv::DynamicConvolver;

pub use conv::LowpassOptions;

pub use conv::StaticConvolver;

pub use error::GspError;

pub use fit::ChebyFitOptions;

pub use fit::ChebyModel;

pub use fit::Sampling;

pub use fit::VfFitOptions;

pub use fit::VfModel;

pub use kernel::ChebyKernel;

pub use kernel::VfKernel;

pub use kernel::estimate_spectral_bound;

pub use kernel::impulse;

pub use kernel::impulse_1d;

pub use resource::Dataset;

pub use resource::ExampleData;

pub use resource::GraphKind;

pub use resource::KernelPreset;

pub use resource::load_laplacian;

pub use resource::load_ply_laplacian;

pub use resource::load_ply_xyz;

pub use resource::load_signal;

pub use sgma::ClusterCloud;

pub use sgma::ModeTable;

pub use sgma::NetworkAnalysisResult;

pub use sgma::PeakCloud;

pub use sgma::Peaks;

pub use sgma::Sgma;

Modules

conv

Convolution engines for static, dynamic, and Chebyshev graph filtering.

error

Unified error type for all gspx public APIs.

fit

Kernel fitting utilities for rational vector-fitting and Chebyshev models.

functions

Analytical filter functions used by gspx convolution.

kernel

Kernel definitions and graph helper utilities.

resource

Local resource loading for example-data directories and direct files.

sgma

Spectral Graph Modal Analysis (SGMA) for joint spatial-temporal wavelets.

Type Aliases

CsMat

Laplacian

Sparse graph Laplacian matrix type used throughout gspx.