GraphGym

GraphGym 是一个用于设计和评估图神经网络（GNN）的平台。 GraphGym 的提出源自论文 图神经网络的设计空间，作者为 Jiaxuan You、Rex Ying 和 Jure Leskovec，该论文入选 NeurIPS 2020 Spotlight。

此外，您也可以参考 PyG，它是 GraphGym 与 PyTorch Geometric 紧密集成的版本。

主要特点

1. 高度模块化的 GNN 流程

• 数据: 数据加载、数据划分
• 模型: 模块化 GNN 实现
• 任务: 节点级、边级、图级 GNN 任务
• 评估: 准确率、ROC AUC 等

2. 可复现的实验配置

• 每个实验都由 配置文件完整描述

3. 可扩展的实验管理

• 轻松并行启动 数千个 GNN 实验
• 自动生成跨随机种子和实验的分析报告及图表。

4. 灵活的用户自定义功能

• 可轻松在 graphgym/contrib/ 中 注册您自己的模块，例如数据加载器、GNN 层、损失函数等。

最新动态

• GraphGym 0.3.0 已发布。现在您可以通过 pip install graphgym 安装稳定版 GraphGym。
• GraphGym 0.2.0 已发布。除了默认的 DeepSNAP 后端之外，GraphGym 现在也支持 PyTorch Geometric 后端。 您可以在 run_single_pyg.sh 中尝试：

cd run
bash run_single_pyg.sh 

示例应用场景

• 图神经网络的设计空间，Jiaxuan You、Rex Ying、Jure Leskovec，NeurIPS 2020 Spotlight。
• 身份感知图神经网络，Jiaxuan You、Jonathan Gomes-Selman、Rex Ying、Jure Leskovec，AAAI 2021。
• 关系型多任务学习：建模数据与任务之间的关系，Kaidi Cao*、Jiaxuan You*、Jure Leskovec，ICLR 2022 Spotlight。
• ROLAND: 用于动态图的图学习框架，Jiaxuan You、Tianyu Du、Jure Leskovec，KDD 2022。

为什么选择 GraphGym？

简而言之: GraphGym 非常适合 GNN 初学者、领域专家以及 GNN 研究人员。

场景 1: 您是 GNN 初学者，希望理解 GNN 的工作原理。

您可能已经阅读过许多关于 GNN 的精彩论文，并尝试编写自己的 GNN 实现。然而，即使使用现有的 GNN 库，您仍然需要自己实现核心流程。GraphGym 是一个理想的起点，帮助您学习 标准化的 GNN 实现与评估方法。

场景 2: 您希望将 GNN 应用于您的实际项目中。

您可能知道，GNN 的模型组合多达数百种，而选择最佳模型却非常困难。更糟糕的是，我们在论文中表明（arXiv:2011.08843），不同任务的最佳 GNN 设计差异极大。GraphGym 提供了一个 简单接口，可并行尝试数千种 GNN，从而帮助您找到最适合特定任务的设计方案。经过对 1000 万种 GNN 模型与任务组合的分析，GraphGym 还推荐了一套“通用”的 GNN 设计空间。

场景 3: 您是 GNN 研究者，希望创新 GNN 模型或提出新的 GNN 任务。

假设您提出了一种新的 GNN 层 ExampleConv。GraphGym 可以帮助您有力地证明 ExampleConv 比 GCNConv 更优：在固定其他条件（包括计算成本）的情况下，从 1000 万种可能的模型-任务组合中随机抽样时，ExampleConv 胜出的概率更高。此外，GraphGym 还可以帮助您轻松进行超参数搜索，并直观展示哪些设计选择更为优越。总之，GraphGym 能够极大地促进您的 GNN 研究工作。

安装说明

系统要求

• CPU 或 NVIDIA GPU、Linux 操作系统、Python 3
• PyTorch 及其他 Python 包；以下提供这些依赖项的安装说明

1. Python 环境（可选）: 建议使用 Conda 包管理器

conda create -n graphgym python=3.7
source activate graphgym

2. PyTorch: 请安装 PyTorch。我们已在 PyTorch 1.8.0 下验证了 GraphGym，它也应兼容 PyTorch 1.4.0 及以上版本。例如：

# CUDA 版本：cpu、cu92、cu101、cu102、cu111
pip install torch==1.8.0+cu101 -f https://download.pytorch.org/whl/torch_stable.html

3. PyTorch Geometric: 请按照其官方文档安装 PyTorch Geometric。例如：

# CUDA 版本：cpu、cu92、cu101、cu102、cu111

# TORCH版本：1.4.0、1.5.0、1.6.0、1.7.0、1.8.0
CUDA=cu101
TORCH=1.8.0
pip install torch-scatter -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-sparse -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-cluster -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-spline-conv -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-geometric

4. GraphGym及其他依赖：

git clone https://github.com/snap-stanford/GraphGym
cd GraphGym
pip install -r requirements.txt
pip install -e .  # 从最新版本安装
pip install graphgym # （可选）从PyPI稳定版安装

5. 测试安装

运行单个实验。 使用GraphGym的run_single.sh脚本运行一个测试GNN实验。 配置文件指定在example.yaml中。 该实验是关于Cora数据集上的节点分类任务（随机80/20划分训练集和验证集）。

cd run
bash run_single.sh # 运行单个实验

运行一批实验。 使用GraphGym的run_batch.sh脚本运行一批GNN实验。 配置文件分别指定在example.yaml（控制基本架构）和example.txt（控制网格搜索方式）中。 该实验在两个图分类数据集上，考察了推荐的GNN设计空间中的96种模型。 每个实验重复3次，并设置允许同时运行8个作业。 根据你的硬件条件，完成所有实验可能需要较长时间；你可以通过Ctrl-C终止实验（GraphGym会妥善关闭所有进程）。

cd run
bash run_batch.sh # 运行一批实验 

(可选) 使用CPU后端运行GraphGym。 GraphGym也支持CPU后端——你只需在.yaml文件中添加一行device: cpu即可。以下是一个示例。

cd run
bash run_single_cpu.sh # 使用CPU后端运行单个实验

(可选) 使用PyG后端运行GraphGym。 可以使用PyTorch Geometric（PyG）后端来运行GraphGym，对应的脚本为run_single_pyg.sh和run_batch_pyg.sh，而不是默认的DeepSNAP后端。 PyG后端遵循原生PyG实现，效率略高于DeepSNAP后端。 目前，PyG后端仅支持用户提供的数据集划分，例如PyG原生数据集或OGB数据集。

cd run
bash run_single_pyg.sh # 使用PyG后端运行单个实验
bash run_batch_pyg.sh # 使用PyG后端运行一批实验 

GraphGym深入使用

1 运行单个GNN实验

完整示例见run/run_single.sh。

1.1 指定配置文件。 在GraphGym中，一个实验完全由.yaml文件指定。 .yaml文件中未指定的配置将使用graphgym/config.py中的默认值填充。 例如，在run/configs/example.yaml中，包含了数据集、训练、模型、GNN等方面的配置。 每项配置的具体说明均在graphgym/config.py中定义。

1.2 启动实验。 以run/run_single.sh为例：

python main.py --cfg configs/example.yaml --repeat 3

可以通过--repeat参数指定重复使用的不同随机种子数量。

1.3 理解结果。 实验结果会自动保存到run/results/${CONFIG_NAME}/目录下； 在上述示例中，路径为run/results/example/。 不同随机种子的结果会保存在不同的子目录中，如run/results/example/2。 所有随机种子的汇总结果会自动生成在run/results/example/agg中， 包括各指标的均值及标准差_std。 训练/验证/测试结果还会进一步保存在子目录中，如run/results/example/agg/val； 其中，stats.json存储了每个epoch在所有随机种子上的汇总结果， best.json则存储了验证准确率最高时的epoch的结果。

2 运行一批 GNN 实验

完整示例在 run/run_batch.sh 中指定。

2.1 指定一个基础配置文件。 GraphGym 支持运行一批实验。首先，用户需要选择一个基础架构 --config。这一批实验将通过扰动基础架构中的某些配置来创建。

2.2（可选）指定用于控制计算预算的基础配置文件。 此外，GraphGym 允许用户选择一个基础架构来 控制网格搜索的计算预算，即 --config_budget。目前，计算预算以可训练参数的数量来衡量；通过自动调整 GNN 的隐藏层维度来实现这一控制。如果未提供 --config_budget，GraphGym 将不会控制计算预算。

2.3 指定一个网格文件。 网格文件描述了如何对基础配置文件进行扰动，从而生成这一批实验。例如，基础配置文件可能指定一个用于 Cora 节点分类任务的 3 层 GCN 实验。然后，网格文件会说明如何沿不同维度对该实验进行扰动，比如层数、模型架构、数据集、任务难度等。

2.4 根据上述信息生成这批实验的配置文件。 例如，在 run/run_batch.sh 中：

python configs_gen.py --config configs/${DIR}/${CONFIG}.yaml \
  --config_budget configs/${DIR}/${CONFIG}.yaml \
  --grid grids/${DIR}/${GRID}.txt \
  --out_dir configs

2.5 启动这一批实验。 例如，在 run/run_batch.sh 中：

bash parallel.sh configs/${CONFIG}_grid_${GRID} $REPEAT $MAX_JOBS

每个实验将重复 $REPEAT 次。我们实现了一个队列系统，按顺序启动所有作业，同时最多允许 $MAX_JOBS 个作业并行运行。实际上，我们的系统在处理数千个作业时表现非常出色。

2.6 理解实验结果。 实验结果将自动保存在目录 run/results/${CONFIG_NAME}_grid_${GRID_NAME}/ 中；在上面的例子中，就是 run/results/example_grid_example/。每次实验完成后，GraphGym 还会自动对不同模型的结果取平均，并保存在 run/results/example_grid_example/agg 中。其中，val.csv 表示每个模型配置在 最终 epoch 的验证准确率；val_best.csv 表示在平均验证误差最高的 epoch 下的结果；val_best_epoch.csv 表示在验证误差最高的 epoch 下，跨不同随机种子取平均后的结果。如果提供了测试集划分，则 test.csv 表示每个模型配置在 最终 epoch 的测试准确率；test_best.csv 表示在平均验证误差最高的 epoch 下的测试集结果；test_best_epoch.csv 表示在验证误差最高的 epoch 下，跨不同随机种子取平均后的测试集结果。

3 分析结果

我们提供了一个便捷工具，可以自动对一批实验进行概览，位于 analysis/example.ipynb。

cd analysis
jupyter notebook
example.ipynb   # 自动提供一批实验的概览

4 用户自定义

GraphGym 的一大亮点是它允许用户轻松注册自己的自定义模块。支持的自定义模块位于目录 graphgym/contrib/ 中，包括：

• 激活函数 graphgym/contrib/act/，
• 自定义配置 graphgym/contrib/config/，
• 特征增强 graphgym/contrib/feature_augment/，
• 特征编码器 graphgym/contrib/feature_encoder/，
• GNN 头部模块 graphgym/contrib/head/，
• GNN 层模块 graphgym/contrib/layer/，
• 数据加载器 graphgym/contrib/loader/，
• 损失函数 graphgym/contrib/loss/，
• GNN 网络架构 graphgym/contrib/network/，
• 优化器 graphgym/contrib/optimizer/，
• GNN 全局池化（仅图分类任务）graphgym/contrib/pooling/，
• GNN 阶段模块 graphgym/contrib/stage/，
• GNN 训练流水线 graphgym/contrib/train/，
• 数据变换 graphgym/contrib/transform/。

在每个目录中，至少会提供一个示例，展示如何注册用户自定义模块。需要注意的是，新的用户自定义模块可能会带来新的配置项；在这种情况下，可以在 graphgym/contrib/config/ 中注册新的配置字段。

注：应用于您自己的数据集。 常见的用法是将 GraphGym 应用于您喜爱的数据集。为此，您可以参考 graphgym/contrib/loader/example.py 中的示例。GraphGym 目前接受 NetworkX 图或 PyG 数据集的列表。

使用案例：图神经网络的设计空间（NeurIPS 2020 Spotlight）

重现 图神经网络的设计空间 中的实验，作者为 Jiaxuan You、Rex Ying 和 Jure Leskovec，该论文入选 NeurIPS 2020 Spotlight。更多详情请参阅 论文 或 项目主页。

# 注意：我们已包含使用 GraphGym 得到的原始结果
# 如果您运行以下代码，这些结果将会被覆盖。
cd run/scripts/design/
bash run_design_round1.sh   # 第一轮实验，在包含 31.5 万种 GNN 设计的空间上进行
bash run_design_round2.sh   # 第二轮实验，在包含 96 种 GNN 设计的空间上进行
cd ../analysis
jupyter notebook
design_space.ipynb   # 重现论文中的所有分析

使用案例：身份感知的图神经网络（AAAI 2021）

重现 身份感知的图神经网络 中的实验，作者为 Jiaxuan You、Jonathan Gomes-Selman、Rex Ying 和 Jure Leskovec，该论文入选 AAAI 2021。更多详情请参阅 论文 或 项目主页。

# 注意：我们在 analysis/idgnn.csv 中包含了 ID-GNN 的原始结果
cd run/scripts/IDGNN/
bash run_idgnn_node.sh   # 复现 ID-GNN 的节点级别结果
bash run_idgnn_edge.sh   # 复现 ID-GNN 的边级别结果
bash run_idgnn_graph.sh   # 复现 ID-GNN 的图级别结果

使用场景：关系多任务学习：建模数据与任务之间的关系（ICLR 2022 Spotlight）

复现 关系多任务学习：建模数据与任务之间的关系 中的实验，作者：Kaidi Cao*、Jiaxuan You*、Jure Leskovec，ICLR 2022。

# 注意：我们在 analysis/idgnn.csv 中包含了 ID-GNN 的原始结果
git checkout meta_link
cd run/scripts/MetaLink/
bash run_metalink.sh.sh   # 复现 MetaLink 在图分类任务上的结果

使用场景：ROLAND：面向动态图的图学习框架（KDD 2022）

ROLAND：面向动态图的图学习框架，作者：Jiaxuan You、Tianyu Du、Jure Leskovec，KDD 2022。 ROLAND 基于 GraphGym 的实现进行了分支。请访问 ROLAND 的对应仓库。

贡献者

Jiaxuan You 发起并主导了该项目，为整个 GraphGym 平台做出了主要贡献。 Rex Ying 负责特征增强模块的开发。 Jonathan Gomes Selman 使 GraphGym 支持 OGB 数据集。

GraphGym 的设计灵感来源于 pycls 框架。 GraphGym 默认采用 DeepSNAP 作为数据表示方式。 GraphGym 的部分功能依赖于 Pytorch Geometric 提供的能力。

参与贡献

我们热烈欢迎社区参与 GraphGym 的开发与贡献。 GraphGym 特别设计为便于简单地进行贡献和定制。 例如，您可以通过创建拉取请求，将您的模块提交到 graphgym/contrib/ 目录中。

引用 GraphGym

如果您认为 GraphGym 或我们的论文对您有所帮助，请引用我们的论文：

@InProceedings{you2020design,
  title = {图神经网络的设计空间},
  author = {You, Jiaxuan 和 Ying, Rex 和 Leskovec, Jure},
  booktitle = {NeurIPS},
  year = {2020}
}

GraphGym 快速上手指南

GraphGym 是一个用于设计和评估图神经网络（GNN）的模块化平台。它支持高度可配置的实验流程，能够轻松并行运行数千个 GNN 实验，并自动生成分析报告。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux
• 硬件: CPU 或 NVIDIA GPU
• Python 版本: Python 3.7+ (推荐 3.7)
• 核心依赖:
  • PyTorch (验证版本：1.8.0，支持 1.4.0+)
  • PyTorch Geometric (PyG)
  • 其他 Python 包 (通过 requirements.txt 安装)

提示：国内用户建议使用 Conda 管理环境，并在安装 PyTorch 及相关库时使用清华或中科大镜像源以加速下载。

2. 安装步骤

2.1 创建 Python 环境 (推荐)

使用 Conda 创建隔离环境：

conda create -n graphgym python=3.7
conda activate graphgym

2.2 安装 PyTorch

根据您的 CUDA 版本安装 PyTorch。以下以 CUDA 10.1 为例（国内用户可替换为清华源）：

# 官方源示例
pip install torch==1.8.0+cu101 -f https://download.pytorch.org/whl/torch_stable.html

# 国内用户推荐 (清华源示例，请根据实际 cuda 版本调整)
# pip install torch==1.8.0+cu101 -f https://mirrors.tuna.tsinghua.edu.cn/pytorch-wheels/torch_stable.html

2.3 安装 PyTorch Geometric (PyG)

需要先安装 torch-scatter, torch-sparse 等扩展库。请设置对应的环境变量：

export CUDA=cu101
export TORCH=1.8.0

pip install torch-scatter -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-sparse -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-cluster -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-spline-conv -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-geometric

2.4 安装 GraphGym

您可以选择从源码安装（最新功能）或从 PyPI 安装（稳定版）。

方式 A：从源码安装 (推荐)

git clone https://github.com/snap-stanford/GraphGym
cd GraphGym
pip install -r requirements.txt
pip install -e .

方式 B：从 PyPI 安装 (稳定版)

pip install graphgym

3. 基本使用

3.1 运行单个实验

这是最简单的使用方式，用于在 Cora 数据集上运行节点分类任务。

1. 进入运行目录：

   cd run
   

2. 执行脚本：

   bash run_single.sh
   

   该命令会读取 configs/example.yaml 配置文件，默认重复实验 3 次（不同随机种子）。

3. 查看结果： 实验结果将自动保存在 run/results/example/ 目录下。

   • 不同种子的结果位于子文件夹（如 2）。
   • 聚合后的统计结果（均值、标准差）位于 run/results/example/agg。
   • best.json 文件记录了验证集准确率最高时的测试结果。

3.2 运行批量实验 (网格搜索)

如果您想对比多种模型架构或超参数，可以运行批量实验。

1. 进入运行目录：

   cd run
   

2. 执行批处理脚本：

   bash run_batch.sh
   

   该脚本会根据 configs/example.yaml (基础架构) 和 grids/example.txt (搜索网格) 生成 96 个不同的实验配置，并并发运行。

3. 控制并发数： 您可以在 run_batch.sh 中修改 $MAX_JOBS 变量来控制同时运行的任务数量，以适应您的硬件资源。

3.3 自定义配置 (进阶)

GraphGym 的核心在于 .yaml 配置文件。您可以复制 run/configs/example.yaml 并修改以下关键部分来定制实验：

• dataset: 更换数据集
• model: 更改 GNN 层类型、层数、隐藏维度
• train: 调整学习率、Batch Size、优化器等
• device: 设置为 cpu 即可在无 GPU 环境下运行

修改后，通过以下命令运行自定义配置：

python main.py --cfg configs/your_config.yaml --repeat 3