KoopmanGraph: A Spatiotemporal Graph Dynamics Modeling Framework Fusing Koopman Operator Theory and Graph Neural Networks

KoopmanGraph is an open-source PyTorch library that combines graph neural networks (GNNs) with Koopman operator theory, providing topology-aware spatiotemporal dynamic prediction capabilities for scenarios such as traffic networks, smart grids, and epidemic modeling. It aims to bridge the gap between traditional methods: Koopman operator methods can capture linear evolution laws but ignore graph topology, while GNNs can model node relationships but lack explicit linear dynamic mechanisms.

The dynamic processes of real-world complex systems (e.g., traffic, power grids, epidemics) occur on graph structures. Traditional methods face a dilemma: Koopman operator-based methods capture linear evolution laws but ignore graph topology; graph neural networks model node relationships but lack explicit linear dynamic mechanisms. KoopmanGraph was born to fuse the advantages of both, providing a new approach to spatiotemporal graph data modeling.

KoopmanGraph's prediction process is divided into three stages:

1. Topology-Aware Encoding: Input node features are processed by GCN/GAT encoders, lifting physical space features to a latent space to obtain topology-aware latent states.
2. Linear Koopman Evolution: Latent states evolve linearly via a learnable Koopman matrix K (z_{t+1}=K·z_t), converting nonlinear dynamics into a linear domain and supporting spectral analysis.
3. Decoding Reconstruction: The evolved latent states are mapped back to the physical space via a GNN decoder, preserving topological properties.

KoopmanGraph's core features include:

• GraphKoopmanModel: Encapsulates the complete process, providing APIs like fit/predict/evaluate, similar to scikit-learn.
• Spectral Analysis Tools: Calculates eigenvalues/vectors of Koopman operators to reveal intrinsic system patterns (growth/decay patterns, energy distribution).
• Consistency Loss: Optimizes forward/backward consistency, with optional eigenvalue stability regularization.
• Control Input Support: Handles externally driven systems (z_{t+1}=K·z_t+B·u_t).
• Dynamic Topology Support: Allows passing different edge_index at each time step to model dynamic graphs.

Built-in Datasets: SyntheticDynamicGraphBenchmark (synthetic), GridBenchmark (regular grid), IEEE 118-bus (power system), METR-LA (traffic flow). Application Scenarios:

• Smart Grid Load Forecasting: Captures spatiotemporal correlations of power demand for multi-step prediction.
• Traffic Flow Forecasting: Understands intersection impacts for efficient multi-step rolling prediction.
• Epidemic Spread Modeling: Identifies super-spreader nodes and paths.
• Physical Simulation Acceleration: Learns low-dimensional approximations for fast prediction.

Quick Start: Models can be trained on synthetic data and predict future time steps via code (example code see original text). Project Ecosystem: Based on PyTorch/PyTorch Geometric, licensed under Apache 2.0, installable via pip (pip install koopman-graph), documentation hosted on Read the Docs (including API references and tutorials), quality guaranteed by CI, test coverage over 80%, and provides comparisons with classic baselines (DMD, EDMD).

KoopmanGraph fuses the linear perspective of Koopman operators with the topology-aware capability of GNNs, improving prediction performance and providing interpretability (via spectral analysis). For researchers/engineers in spatiotemporal prediction, network dynamic modeling, or scientific machine learning, it is a tool worth exploring. Its open-source nature and comprehensive documentation lower the entry barrier, and its modular design supports extension and customization.