KoopmanGraph：融合Koopman算子理论与图神经网络的时空图动力学建模框架

KoopmanGraph是一个开源PyTorch库，将图神经网络（GNN）与Koopman算子理论相结合，为交通网络、智能电网、流行病建模等场景提供拓扑感知的时空动态预测能力。它旨在弥合传统方法的鸿沟：Koopman算子方法能捕捉线性演化规律却忽略图拓扑，而GNN能建模节点关系却缺乏显式线性动态机制。

现实复杂系统（如交通、电网、流行病）的动态过程发生在图结构上。传统方法面临两难：基于Koopman算子的方法捕捉线性演化规律，但忽略图拓扑；图神经网络建模节点关系，却缺乏显式线性动态机制。KoopmanGraph诞生以融合两者优势，提供全新的时空图数据建模思路。

KoopmanGraph的预测流程分为三阶段：

1. 拓扑感知编码：输入节点特征经GCN/GAT编码器，将物理空间特征提升到潜在空间，得到拓扑感知的潜在状态。
2. 线性Koopman演化：潜在状态通过可学习的Koopman矩阵K线性演化（z_{t+1}=K·z_t），将非线性动态转化为线性域，支持谱分析。
3. 解码重建：演化后的潜在状态经GNN解码器映射回物理空间，保持拓扑特性。

KoopmanGraph的核心特性包括：

• GraphKoopmanModel：封装完整流程，提供fit/predict/evaluate等API，类似scikit-learn。
• 谱分析工具：计算Koopman算子的特征值/向量，揭示系统内在模式（增长/衰减模式、能量分布）。
• 一致性损失：优化前向/后向一致性，可选特征值稳定性正则化。
• 控制输入支持：处理外部驱动系统（z_{t+1}=K·z_t+B·u_t）。
• 动态拓扑支持：允许每个时间步传入不同edge_index，建模动态图。

内置数据集：SyntheticDynamicGraphBenchmark（合成）、GridBenchmark（规则网格）、IEEE 118-bus（电力系统）、METR-LA（交通流量）。 应用场景：

• 智能电网负荷预测：捕捉电力需求时空相关性，多步预测。
• 交通流量预测：理解路口影响，高效多步滚动预测。
• 流行病传播建模：识别超级传播节点和路径。
• 物理仿真加速：学习低维近似，快速预测。

快速上手：通过代码可在合成数据上训练模型并预测未来时间步（示例代码见原文）。 项目生态：基于PyTorch/PyTorch Geometric，Apache 2.0许可证，pip安装（pip install koopman-graph），文档托管在Read the Docs，含API参考、教程，CI保障质量，测试覆盖率80%+，提供与经典基线（DMD、EDMD）的比较。

KoopmanGraph融合Koopman算子的线性视角与GNN的拓扑感知能力，提升预测性能并提供可解释性（通过谱分析）。对时空预测、网络动态建模或科学机器学习的研究者/工程师，是值得探索的工具。开源性质和完善文档降低入门门槛，模块化设计支持扩展定制。