mDenseGNN

mDenseGNN

mDenseGNN 是一个基于 PyTorch 和 PyTorch Geometric 的独立 DenseGNN 风格晶体图神经网络实现，用于根据 CIF 晶体结构进行带隙回归。

代码保留了本实现采用的主要 DenseGNN 机制，包括消息传递层之间的稠密连接、节点—边—图三级残差更新、结合元素周期表属性的可学习原子嵌入、周期性 Voronoi 晶体图、距离和 Voronoi ridge area 边特征、图级池化与标量回归头。代码使用 pymatgen 和 SciPy 解析 CIF 并构建周期性晶体图，不依赖原始 DenseGNN 仓库及其内部模块。

该单文件版本仅用于单目标 CIF 到带隙的回归任务，不包含力场训练、分类、多任务学习、Matbench 自动下载、交叉验证和消融实验等功能。

环境依赖

1

pip install torch torch-geometric pymatgen scipy numpy pandas openpyxl scikit-learn matplotlib tqdm

仅当 USE_OPTUNA = True 时需要安装 Optuna：

1

pip install optuna

数据准备

在脚本所在目录中准备以下文件：

1
2
3
4
5
6

mDenseGNN_v1.py
data.xlsx
cif/
|-- 1.cif
|-- 2.cif
|-- 3.cif

脚本读取 data.xlsx 的前两列：

第一列必须是数值型 CIF 编号。脚本使用 int(raw_name) 将其转换为整数并添加 .cif 后缀，因此第一列中的 1 对应 ./cif/1.cif。第二列为带隙，单位为 eV。空值、非有限目标值、缺失 CIF、重复编号、无效 CIF，以及无序或部分占位结构会被跳过，并在日志中记录原因。

可以在脚本开头修改输入路径和目标属性信息：

1
2
3
4

EXCEL_PATH = "./data.xlsx"
CIF_DIR = "./cif"
TARGET_NAME = "bandgap"
TARGET_UNIT = "eV"

使用方法

1

python mDenseGNN_v1.py

脚本会自动完成 CIF 检查、周期性 Voronoi 图构建与缓存、固定的 80/10/10 训练集/验证集/测试集划分、目标标准化、模型训练、早停、评估和绘图，随机种子固定为 42。CUDA 可用时自动使用 GPU，否则使用 CPU。

训练采用 nn.MSELoss() 和 AdamW，并以验证集 RMSE 驱动 ReduceLROnPlateau 学习率调度，保存验证集 RMSE 最低的模型。默认配置使用 5 个 DenseGNN 层、128 维隐藏特征、0.10 的 Voronoi ridge-area 阈值、32 的批大小、最多 300 个 epoch，以及 50 个 epoch 的早停耐心值。

将 USE_OPTUNA 设置为 True 可启用可选的 Optuna 搜索，对隐藏维度、网络深度、批大小、学习率和权重衰减进行优化。优化过程中始终复用固定的训练集、验证集和测试集划分。

所有结果保存在由 MODEL_NAME 和 RUN_VERSION 确定的目录中。按照默认设置，输出目录为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

DenseGNN_v1/
|-- DenseGNN_best.pt
|-- figure/
|   |-- DenseGNN_parity_train.jpg
|   |-- DenseGNN_parity_val.jpg
|   |-- DenseGNN_parity_test.jpg
|   |-- DenseGNN_parity_all.jpg
|   `-- DenseGNN_rmse_curve.jpg
|-- dat/
|-- table/
|   `-- DenseGNN_metrics.dat
|-- log/
|   `-- DenseGNN_training.log
|-- split/
|   `-- DenseGNN_split.csv
`-- cache/
    `-- DenseGNN_graphs/

输出内容包括训练集、验证集和测试集的 MAE、RMSE 与 R2，三组独立奇偶图及合并奇偶图和相应 .dat 文件，训练集/验证集 RMSE 曲线及其 .dat 文件，固定数据划分，缓存的晶体图，最佳模型权重和完整训练日志。所有图像均保存为 600 dpi JPG 文件。

保存的模型可以通过 load_trained_model() 在其他程序中加载，并可使用 predict_cifs() 对新的 CIF 文件进行带隙预测。

引用

原始 DenseGNN 文献：

• Du H, Wang J, Hui J, et al. DenseGNN: universal and scalable deeper graph neural networks for high-performance property prediction in crystals and molecules. npj Computational Materials, 2024, 10(1): 292.

原始 DenseGNN 仓库：

• https://github.com/dhw059/DenseGNN

本工作：

论文正式发表后补充。