---

文档 | 外部资源 | 数据集

PyTorch Geometric Temporal 是 PyTorch Geometric 的一个时序（动态）扩展库。

该库包含来自各类已发表研究论文中的多种动态与时序几何深度学习、嵌入以及时空回归方法。此外，它还配备了一个易于使用的数据集加载器、训练-测试分割工具和用于动态及时序图的时序快照迭代器。框架天然支持 GPU 加速，并附带了来自流行病预测、共享经济、能源生产和网络流量管理等领域的多个基准数据集。最后，用户也可以创建自己的数据集。

PyTorch Geometric Temporal 现在新增了索引批处理功能——一种新的批处理技术，可在不影响精度的情况下提升时空内存效率。请查看 索引批处理示例，这些示例让用户能够轻松地根据自身需求定制训练过程，并扩展到比以往更大的数据集。此外，PyTorch Geometric Temporal 还支持结合索引批处理使用 Dask-DDP 进行内存高效的分布式数据并行训练。

该软件包可与 Pytorch Lightning 良好兼容，从而开箱即用地支持在 CPU、单 GPU 或多 GPU 上进行训练。请参阅此 入门示例，了解如何将 PyTorch Geometric Temporal 与 Pytorch Lightning 结合使用。

我们还为每种 循环模型 提供了详细示例，并为基于注意力机制的模型准备了 笔记本。

---

案例教程

我们在 文档 中提供了深入的案例教程，每个教程都涵盖了 PyTorch Geometric Temporal 功能的一个方面。

增量训练：流行病预测案例教程

累积训练：网络流量管理案例教程

---

引用

如果您在研究中发现 PyTorch Geometric Temporal 及其新数据集很有帮助，请考虑添加以下对原始工作及其最新扩展的引用：

@inproceedings{rozemberczki2021pytorch,
               author = {Benedek Rozemberczki 和 Paul Scherer、Yixuan He、George Panagopoulos、Alexander Riedel、Maria Astefanoaei、Oliver Kiss、Ferenc Beres、Guzman Lopez、Nicolas Collignon 和 Rik Sarkar},
               title = {{PyTorch Geometric Temporal: 基于神经机器学习模型的时空信号处理}},
               year = {2021},
               booktitle={第30届 ACM 国际信息与知识管理会议论文集},
               pages = {4564–4573},
}

@misc{ockerman2025pgtiscalingspatiotemporalgnns,
      title={PGT-I：通过内存高效分布式训练扩展时空 GNN}， 
      author={Seth Ockerman、Amal Gueroudji、Tanwi Mallick、Yixuan He、Line Pouchard、Robert Ross 和 Shivaram Venkataraman},
      year={2025},
      eprint={2507.11683},
      archivePrefix={arXiv},
      primaryClass={cs.DC},
      url={https://arxiv.org/abs/2507.11683}, 
}

---

一个简单示例

PyTorch Geometric Temporal 使得实现动态与时序图神经网络变得相当容易——请参阅随附的 教程。例如，要实现一个包含两个连续的 图卷积 GRU 单元和一个线性层的循环图卷积网络，只需如下代码：

import torch
import torch.nn.functional as F
from torch_geometric_temporal.nn.recurrent import GConvGRU

class RecurrentGCN(torch.nn.Module):

def __init__(self, node_features, num_classes):
        super(RecurrentGCN, self).__init__()
        self.recurrent_1 = GConvGRU(node_features, 32, 5)
        self.recurrent_2 = GConvGRU(32, 16, 5)
        self.linear = torch.nn.Linear(16, num_classes)

    def forward(self, x, edge_index, edge_weight):
        x = self.recurrent_1(x, edge_index, edge_weight)
        x = F.relu(x)
        x = F.dropout(x, training=self.training)
        x = self.recurrent_2(x, edge_index, edge_weight)
        x = F.relu(x)
        x = F.dropout(x, training=self.training)
        x = self.linear(x)
        return F.log_softmax(x, dim=1)

---

包含的方法

具体而言，实现了以下几种时序图神经网络。

循环图卷积网络

• DCRNN 来自 Li 等人：《扩散卷积递归神经网络：数据驱动的交通预测》（ICLR 2018）

• GConvGRU 来自 Seo 等人：《基于图卷积递归网络的结构化序列建模》（ICONIP 2018）

• GConvLSTM 来自 Seo 等人：《基于图卷积递归网络的结构化序列建模》（ICONIP 2018）

• GC-LSTM 来自 Chen 等人：《GC-LSTM：用于动态链接预测的图卷积嵌入 LSTM》（CoRR 2018）

• LRGCN 来自 Li 等人：《在随时间演化的图中预测路径故障》（KDD 2019）

• DyGrEncoder 来自 Taheri 等人：《利用递归模型学习动态图的演化表示》

• EvolveGCNH 来自 Pareja 等人：《EvolveGCN：面向动态图的演化图卷积网络》

• EvolveGCNO 来自 Pareja 等人：《EvolveGCN：面向动态图的演化图卷积网络》

• T-GCN 来自 Zhao 等人：《T-GCN：用于交通预测的时序图卷积网络》

• A3T-GCN 来自 Zhu 等人：《A3T-GCN：用于交通预测的注意力时序图卷积网络》

• AGCRN 来自 Bai 等人：《用于交通预测的自适应图卷积递归网络》（NeurIPS 2020）

• MPNN LSTM 来自 Panagopoulos 等人：《用于疫情预测的迁移图神经网络》（AAAI 2021）

注意力聚合型时序图卷积网络

• STGCN 来自 Yu 等人：《时空图卷积网络：一种用于交通预测的深度学习框架》（IJCAI 2018）

• ASTGCN 来自 Guo 等人：《基于注意力的时空图卷积网络用于交通流量预测》（AAAI 2019）

• MSTGCN 来自 Guo 等人：《基于注意力的时空图卷积网络用于交通流量预测》（AAAI 2019）

• GMAN 来自 Zheng 等人：《GMAN：一种用于交通预测的图多注意力网络》（AAAI 2020）

• MTGNN 来自 Wu 等人：《连接各点：利用图神经网络进行多元时间序列预测》（KDD 2020）

• 2S-AGCN 来自 Shi 等人：《用于基于骨骼的动作识别的双流自适应图卷积网络》（CVPR 2019）

• DNNTSP 来自 Yu 等人：《用深度神经网络预测时间序列集合》（KDD 2020）

辅助图卷积网络

• TemporalConv 来自 Yu 等人：《时空图卷积网络：一种用于交通预测的深度学习框架》（IJCAI 2018）

• DConv 来自 Li 等人：《扩散卷积循环神经网络：数据驱动的交通流量预测》（ICLR 2018）

• ChebConvAttention 来自 Guo 等人：《基于注意力机制的时空图卷积网络用于交通流量预测》（AAAI 2019）

• AVWGCN 来自 Bai 等人：《用于交通预测的自适应图卷积循环网络》（NeurIPS 2020）

---

请前往我们的文档了解更多关于安装、数据集创建以及已实现方法和可用数据集的完整列表。 若想快速入门，可查看 examples/ 目录下的示例。

如果您发现任何异常情况，请提交一个问题。如果您希望添加某个特定的方法，也欢迎提出功能请求。

---

安装

首先安装 PyTorch 和 PyTorch Geometric，然后运行：

pip install torch-geometric-temporal

若需安装支持索引批处理的功能，可运行：

pip install torch-geometric-temporal[index]

若需同时安装索引批处理和分布式数据并行（DDP）支持，可运行：

pip install torch-geometric-temporal[ddp]

---

运行测试

$ python -m pytest test

---

许可证

• MIT 许可证

PyTorch Geometric Temporal 快速上手指南

PyTorch Geometric Temporal 是 PyTorch Geometric 的时间（动态）扩展库，专为处理动态图、时空回归和时序嵌入任务设计。它内置了多种经典的时空图神经网络模型（如 DCRNN, GConvGRU, STGCN 等），并提供了高效的数据加载器和训练工具。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python: 3.7 及以上版本
• 核心依赖:
  • PyTorch (建议安装最新稳定版)
  • PyTorch Geometric (必须预先安装，版本需兼容)
  • CUDA (可选，如需 GPU 加速请确保已正确配置)

注意：由于 PyTorch Geometric 的安装依赖于具体的 PyTorch 和 CUDA 版本，请务必先参考 PyG 官方安装指南 完成基础环境的搭建。

安装步骤

推荐使用 pip 进行安装。国内开发者可使用清华源或阿里源加速下载。

1. 安装基础依赖 (PyTorch & PyG)

如果您尚未安装 PyTorch 和 PyTorch Geometric，请先执行以下命令（以 CPU 版本为例，GPU 版本请替换对应的 wheel 地址）：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install pyg-lib torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-2.0.0+cpu.html

(注：请将上述命令中的 torch-2.0.0+cpu 替换为您实际安装的 PyTorch 版本和计算平台)

2. 安装 PyTorch Geometric Temporal

使用国内镜像源安装主包：

pip install torch-geometric-temporal -i https://pypi.tuna.tsinghua.edu.cn/simple

或者直接从 GitHub 安装最新开发版：

pip install git+https://github.com/benedekrozemberczki/pytorch_geometric_temporal.git

基本使用

本库使得构建动态图神经网络变得非常简洁。以下是一个最简单的示例，展示如何定义一个包含两个 GConvGRU 层和一个线性层的循环图卷积网络。

代码示例

import torch
import torch.nn.functional as F
from torch_geometric_temporal.nn.recurrent import GConvGRU

class RecurrentGCN(torch.nn.Module):

    def __init__(self, node_features, num_classes):
        super(RecurrentGCN, self).__init__()
        # 定义两个连续的 GConvGRU 层
        self.recurrent_1 = GConvGRU(node_features, 32, 5)
        self.recurrent_2 = GConvGRU(32, 16, 5)
        self.linear = torch.nn.Linear(16, num_classes)

    def forward(self, x, edge_index, edge_weight):
        # 第一层递归卷积
        x = self.recurrent_1(x, edge_index, edge_weight)
        x = F.relu(x)
        x = F.dropout(x, training=self.training)
        
        # 第二层递归卷积
        x = self.recurrent_2(x, edge_index, edge_weight)
        x = F.relu(x)
        x = F.dropout(x, training=self.training)
        
        # 输出层
        x = self.linear(x)
        return F.log_softmax(x, dim=1)

# 实例化模型
# 假设节点特征维度为 4，分类任务类别数为 2
model = RecurrentGCN(node_features=4, num_classes=2)

# 模拟输入数据 (批次大小=1, 节点数=10, 特征数=4)
x = torch.randn(10, 4)
edge_index = torch.tensor([[0, 1, 1, 2], [1, 0, 2, 1]], dtype=torch.long)
edge_weight = torch.ones(edge_index.size(1))

# 前向传播
output = model(x, edge_index, edge_weight)
print(output.shape)

下一步

• 数据集加载：库中内置了流行病学预测、共享经济、能源生产等领域的基准数据集，可直接通过 torch_geometric_temporal.dataset 调用。
• 高级特性：支持索引批处理（Index-batching）以提升显存效率，以及结合 Dask-DDP 进行分布式训练。
• 文档资源：更多详细教程和案例研究请访问 官方文档。