PyTorch Geometric-based framework for analyzing, implementing, and benchmarking spectral GNNs with effectiveness and efficiency evaluations.

[!NOTE] :tada: [2025.05.23] Our paper "A Comprehensive Benchmark on Spectral GNNs: The Impact on Efficiency, Memory, and Effectiveness" is accpeted by SIGMOD 2026! The full tech report can be accessed here as well as at arXiv. Welcome to cite our paper as:
Ningyi Liao, Haoyu Liu, Zulun Zhu, Siqiang Luo, and Laks V.S. Lakshmanan. A Comprehensive Benchmark on Spectral GNNs: The Impact on Efficiency, Memory, and Effectiveness. Proceedings of the ACM on Management of Data, 3(4), 2025. doi:10.1145/3749156.

[!IMPORTANT] Why this project?
We list the following highlights of our framework compared to PyG and similar works: - Unified Framework: We offer a plug-and-play collection for spectral models and filters in unified and efficient implementations, rather than a model-specific design. Our rich collection greatly extends the PyG model zoo. - Spectral-oriented Design: We decouple non-spectral designs and feature the pivotal spectral kernel being consistent throughout different settings. Most filters are thus easily adaptable to a wide range of model-level options, including those provided by PyG and PyG-based frameworks. - High scalability: As spectral GNNs are inherently suitable for large-scale learning, our framework is feasible to common scalable learning schemes and acceleration techniques. Several spectral-oriented approximation algorithms are also supported.

---

• Installation
• Reproduce Experiments
  • Main Experiments
  • Additional Experiments
• Customization
  • Configure Experiment Parameters
  • Add New Experiment Dataset
  • Add New Spectral Filter
• Framework Arrangement
  • Covered Models
  • Covered Datasets
  • Code Structure
• Roadmap

Installation

This package can be easily installed by running pip at package root path: bash pip install -r requirements.txt pip install -e .[benchmark]

The installation script already covers the following core dependencies: - PyTorch (>=2.0[^1]) - PyTorch Geometric (>=2.5.3) - TorchMetrics (>=1.0): only required for benchmark/ experiments. - Optuna (>=3.4): only required for hyperparameter search in benchmark/ experiments.

[^1]: Please refer to the official guide if a specific CUDA version is required for PyTorch.

For additional installation of the C++ backend, please refer to propagations/README.md.

Reproduce Experiments

Main Experiments

Acquire results on the effectiveness and efficiency of spectral GNNs. Datasets will be automatically downloaded and processed by the code.

Run full-batch models:

bash cd benchmark bash scripts/runfb.sh

Run mini-batch models:

bash bash scripts/runmb.sh

Additional Experiments

Effect of graph normalization:

bash bash scripts/eval_degng.sh

Figures can be plotted by: benchmark/notebook/fig_degng.ipynb.

Effect of propagation hops:

bash bash scripts/eval_hop.sh

Figures can be plotted by: benchmark/notebook/fig_hop.ipynb.

Frequency response:

bash bash scripts/exp_regression.sh

Customization

Configure Experiment Parameters

Refer to the help text by: bash python benchmark/run_single.py --help usage: python run_single.py options: --help show this help message and exit # Logging configuration --seed SEED random seed --dev DEV GPU id --suffix SUFFIX Result log file name. None:not saving results -quiet File log. True:dry run without saving logs --storage {state_file,state_ram,state_gpu} Checkpoint log storage scheme. --loglevel LOGLEVEL Console log. 10:progress, 15:train, 20:info, 25:result # Data configuration --data DATA Dataset name --data_split DATA_SPLIT Index or percentage of dataset split --normg NORMG Generalized graph norm --normf [NORMF] Embedding norm dimension. 0: feat-wise, 1: node-wise, None: disable # Model configuration --model MODEL Model class name --conv CONV Conv class name --num_hops NUM_HOPS Number of conv hops --in_layers IN_LAYERS Number of MLP layers before conv --out_layers OUT_LAYERS Number of MLP layers after conv --hidden_channels HIDDEN Number of hidden width --dropout_lin DP_LIN Dropout rate for linear --dropout_conv DP_CONV Dropout rate for conv # Training configuration --epoch EPOCH Number of epochs --patience PATIENCE Patience epoch for early stopping --period PERIOD Periodic saving epoch interval --batch BATCH Batch size --lr_lin LR_LIN Learning rate for linear --lr_conv LR_CONV Learning rate for conv --wd_lin WD_LIN Weight decay for linear --wd_conv WD_CONV Weight decay for conv # Model-specific --theta_scheme THETA_SCHEME Filter name --theta_param THETA_PARAM Hyperparameter for filter --combine {sum,sum_weighted,cat} How to combine different channels of convs # Conv-specific --alpha ALPHA Decay factor --beta BETA Scaling factor # Test flags --test_deg Call TrnFullbatch.test_deg()

Add New Experiment Dataset

In benchmark/trainer/load_data.py, append the SingleGraphLoader._resolve_import() method to include new datasets under respective protocols. benchmark/dataset/ manages the import of datasets from other frameworks.

Add New Spectral Filter

New spectral filters to pyg_spectral/nn/conv/ can be easily implemented by only three steps, then enjoys a range of model architectures, analysis utilities, and training schemes.

Step 1: Define propagation matrix

The base class BaseMP provides essential methods for building spectral filters. We can define a new filter class SkipConv by inheriting from it: ```python from torch import Tensor from pygspectral.nn.conv.basemp import BaseMP

class SkipConv(BaseMP): def init(self, numhops, hop, cached, **kwargs): kwargs['propagatemat'] = 'A-I' super(SkipConv, self).init(num_hops, hop, cached, **kwargs) ```

The propagation matrix is specified by the propagate_mat argument as a string. Each matrix can be the normalized adjacency matrix (A) or the normalized Laplacian matrix (L), with optional diagonal scaling, where the scaling factor can either be a number or an attribute name of the class. Multiple propagation matrices can be combined by ,. Valid examples: A, L-2*I, L,A+I,L-alpha*I.

Step 2: Prepare representation matrix

Similar to PyG modules, our spectral filter class takes the graph attribute x and edge index edge_index as input. The _get_convolute_mat() method prepares the representation matrices used in recurrent computation as a dictionary: python def _get_convolute_mat(self, x, edge_index): return {'x': x, 'x_1': x}

The above example overwrites the method for SkipConv, returning the input feature x and a placeholder x_1 for the representation in the previous hop.

Step 3: Derive recurrent forward

The _forward() method implements recurrent computation of the filter. Its input/output is a dictionary combining the propagation matrices defined by propagate_mat and the representation matrices prepared by _get_convolute_mat(). ```python def forward(self, x, x1, prop): if self.hop == 0: # No propagation for k=0 return {'x': x, 'x_1': x, 'prop': prop}

    h = self.propagate(prop, x=x)
    h = h + x_1
    return {'x': h, 'x_1': x, 'prop': prop}

```

Similar to PyG modules, the propagate() method conducts graph propagation by the given matrices. The above example corresponds to the graph propagation with a skip connection to the previous representation: $H^{(k)} = (A-I)H^{(k-1)} + H^{(k-2)}$.

Build the model!

Now the SkipConv filter is properly defined. The following snippet use the DecoupledVar model composing 10 hops of SkipConv filters, which can be used as a normal PyTorch model: ```python from pyg_spectral.nn.models import DecoupledVar

model = DecoupledVar(conv='SkipConv', numhops=10, inchannels=x.size(1), hiddenchannels=x.size(1), outchannels=x.size(1)) out = model(x, edge_index) ```

Framework Arrangement

Covered Models

| Category | Model | |:------------:|:----------| | Fixed Filter | GCN, SGC, gfNN, GZoom, S²GC, GLP, APPNP, GCNII, GDC, DGC, AGP, GRAND+| |Variable Filter|GIN, AKGNN, DAGNN, GPRGNN, ARMAGNN, ChebNet, ChebNetII, HornerGCN / ClenshawGCN, BernNet, LegendreNet, JacobiConv, FavardGNN / OptBasisGNN| |Filter Bank|AdaGNN, FBGNN, ACMGNN, FAGCN, G²CN, GNN-LF/HF, FiGURe|

Covered Datasets

The following datasets are evaluated in the paper and are automatically available in the framework.

| Source | Graph | |:------------:|:----------| | PyG | cora, citeseer, pubmed, flickr, actor, ... | | OGB | ogbn-arxiv, ogbn-mag, ogbn-products, ... | | LINKX | penn94, arxiv-year, genius, twitch-gamer, snap-patients, pokec, wiki | | Yandex | chameleon, squirrel, roman-empire, minesweeper, amazon-ratings, questions, tolokers |

Code Structure

• benchmark/: codes for benchmark experiments.
• pyg_spectral/: core codes for spectral GNNs designs, arranged in PyG structure.
  • nn.conv: spectral spectral filters, similar to torch_geometric.nn.conv.
  • nn.models: common neural network architectures, similar to torch_geometric.nn.models.
  • nn.propagations: C++ backend for efficient propagation algorithms.
• log/: experiment log files and parameter search results.
• data/: raw and processed datasets arranged following different protocols.

Roadmap

• [ ] Support C++ propagation backend with efficient algorithms.
  • [x] Unifews
  • [ ] SGC
  • [ ] GBP/AGP
• [ ] Support more transformation operations.
  • [ ] Generalize ACMGNN
  • [ ] LD2
  • [ ] Var models weight norm
• [ ] Support iterative eigen-decomposition for full-spectrum spectral filters.
  • [ ] Jacobi method
  • [ ] Lanczos method

Misc

• This project is licensed under the MIT LICENSE.
• Please export CITATION by using "Cite this repository" in the right sidebar. <!-- - Please refer to the CONTRIBUTING guide for contributing to this project. -->