mReciNet

mReciNet

mReciNet 是一个基于 PyTorch 和 PyTorch Geometric 的独立 ReciNet 实现，用于根据 CIF 晶体结构预测材料带隙。

代码将周期性局域晶体图与倒空间长程建模相结合，保留了 ReciNet 的主要组成部分，包括门控局域消息传递、根据每个晶体的晶格生成倒格矢、倒空间结构因子更新、局域与长程表示的逐层融合、图级平均池化和标量回归头。代码使用 pymatgen 解析 CIF 并构建周期性晶体图，不依赖 JARVIS、原始 ReciNet 仓库、YAML 配置文件或仓库内部模块。

默认模型使用92维占据率加权原子序数特征、4.0 Å局域截断半径、每个原子最多16个邻居、16个最短非零倒格矢、4层局域/倒空间交互层、256维隐藏表示和64维倒空间降维表示。

环境依赖

1

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

torch-scatter 为可选依赖。若已安装，脚本使用 torch_scatter.scatter_add；若未安装，则自动回退到 PyTorch 原生的 index_add_。

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

1

pip install optuna

数据准备

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

1
2
3
4
5
6

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

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

第一列会转换为整数形式的 CIF 编号。例如，1 对应 ./cif/1.cif。无效标签、缺失的 CIF 文件、没有有效周期邻居的结构以及 CIF 解析失败样本会被跳过，并记录在训练日志中。

使用方法

1

python mReciNet_v1.py

脚本会自动完成 CIF 检查与晶体图缓存、以42为随机种子的固定80/10/10训练集/验证集/测试集划分、仅在训练集上拟合的标签归一化、采用 MSE 损失的模型训练、基于验证集 RMSE 的早停、最佳权重重新加载、最终评估和绘图。当 CUDA 可用时自动使用 GPU，否则使用 CPU。

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

1
2
3
4
5
6
7
8

ReciNet_v1/
|-- ReciNet_best.pt
|-- figure/
|-- dat/
|-- table/
|-- log/
|-- split/
|-- cache/

输出内容包括训练集、验证集和测试集的 MAE、RMSE 与 R2，单独及合并的奇偶图与源数据，RMSE 训练曲线与源数据，可复用的固定数据划分，缓存的晶体图，最佳模型权重和完整训练日志。最佳模型文件保存模型配置、晶体图配置、标签归一化参数、最佳 epoch、验证集 RMSE 和模型权重。脚本还提供 load_trained_model() 和 predict_cifs()，可用于预测新的 CIF 文件。

将 USE_OPTUNA 设置为 True 后，可仅使用训练集和验证集优化批量大小、学习率、权重衰减、隐藏维度、交互层数、倒空间降维维度和 dropout。测试集不参与超参数选择。

引用

原始 ReciNet 文献：

• Nie J, Xiao P, Ji K, et al. ReciNet: Reciprocal space-aware long-range modeling for crystalline property prediction. arXiv preprint arXiv:2502.02748, 2025.

本工作：

论文正式发表后补充。