CGCNN晶体图卷积神经网络实战指南：从环境搭建到材料属性预测

一、认知：CGCNN基础与极速启动

理解晶体图卷积神经网络

CGCNN（Crystal Graph Convolutional Neural Networks）是一种专为材料属性预测设计的深度学习模型。它将晶体结构转化为"晶体图"——可以把这种晶体图想象成材料的"基因图谱"，其中原子是节点，化学键是连接。通过对这种图谱的学习，CGCNN能够预测材料的多种关键属性，如带隙、形成能等。

5分钟极速启动环境

以下命令将帮助你在5分钟内完成从环境配置到运行测试的全过程：

# 1. 创建并激活conda环境
conda create -n cgcnn python=3 scikit-learn pytorch torchvision pymatgen -c pytorch -c conda-forge -y
source activate cgcnn

# 2. 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/cg/cgcnn
cd cgcnn

# 3. 验证安装成功
python main.py -h
python predict.py -h

预期输出：两个命令都应显示帮助信息，没有报错。帮助信息应包含程序的参数说明，如--task、--epochs等选项。

⚠️注意：如果出现ImportError: No module named 'pymatgen'错误，请运行conda install -n cgcnn pymatgen -c conda-forge单独安装该依赖。

新手任务地图

以下是使用CGCNN的核心操作节点，按顺序执行即可完成从数据准备到预测的全流程：

1. 准备符合格式要求的数据集（CIF文件+id_prop.csv）
2. 使用main.py训练模型（选择任务类型和超参数）
3. 评估模型性能（查看训练日志中的MAE或AUC指标）
4. 使用predict.py进行材料属性预测
5. 分析预测结果并优化模型

项目核心结构解析

CGCNN项目主要包含以下关键组件：

• cgcnn/: 核心代码目录

  • data.py: 数据加载和预处理模块，负责将CIF文件转换为模型可接受的晶体图格式
  • model.py: 模型定义模块，包含CGCNN的网络结构实现

• data/: 示例数据集目录

  • sample-classification/: 分类任务示例数据
  • sample-regression/: 回归任务示例数据

• pre-trained/: 预训练模型目录，包含多种材料属性的预训练权重文件

• main.py: 模型训练主程序

• predict.py: 模型预测程序

环境配置自查清单

检查项	检查内容	完成情况
环境创建	conda环境"cgcnn"是否成功创建	□
依赖安装	所有必要依赖（pytorch、pymatgen等）是否安装	□
项目克隆	项目是否成功克隆到本地	□
程序验证	main.py和predict.py是否能正常显示帮助信息	□
环境激活	是否成功激活cgcnn环境	□
Python版本	Python版本是否为3.x系列	□
路径设置	当前工作目录是否为项目根目录	□

二、操作：数据准备到模型预测全流程

准备高质量数据集

数据集是模型训练的基础，CGCNN要求特定格式的输入数据：

1. CIF文件：存储晶体结构信息，每个文件对应一个晶体样本
2. id_prop.csv文件：存储样本ID和对应的属性值，格式为"cif_id,property_value"

对于分类任务，id_prop.csv示例：

1000041,1
1000050,0
1101051,1

对于回归任务，id_prop.csv示例：

1000041,1.23
1000050,2.45
1101051,3.67

💡技巧：CIF文件命名应与id_prop.csv中的样本ID一致，确保一一对应。

执行模型训练

使用main.py进行模型训练，基本命令格式如下：

# 回归任务训练示例
python main.py data/sample-regression --task regression --epochs 50 --batch-size 128 --lr 0.001

# 分类任务训练示例
python main.py data/sample-classification --task classification --epochs 50 --batch-size 128 --lr 0.001

关键参数说明：

• --task：任务类型，【regression】或【classification】
• --epochs：训练轮数，推荐【30-100】
• --batch-size：批大小，根据GPU内存调整，推荐【64-256】
• --lr：学习率，推荐【0.001-0.01】

训练过程中，系统会显示每轮的训练损失和验证损失。正常情况下，随着训练进行，这两个值应该逐渐降低并趋于稳定。

⚠️注意：如果出现"CUDA out of memory"错误，需要减小批大小或添加--disable-cuda参数使用CPU训练。

解析训练结果

训练完成后，会在当前目录生成一个包含训练日志的文件夹，命名格式为runs/日期_时间_任务类型。日志文件中包含以下关键信息：

• 训练集和验证集的损失变化曲线
• 模型性能指标（MAE for regression, AUC for classification）
• 最佳模型权重文件（存储在runs/.../model_best.pth.tar）

💡技巧：通过比较训练损失和验证损失，可以判断模型是否过拟合。如果验证损失远高于训练损失，可能需要增加正则化或减少模型复杂度。

使用预训练模型进行预测

项目提供了多个预训练模型，可以直接用于材料属性预测：

# 使用带隙预测模型示例
python predict.py pre-trained/band-gap.pth.tar data/sample-regression

预测结果将保存到当前目录下的test_results.csv文件，格式如下：

id,true,pred
1000041,1.23,1.19
1000050,2.45,2.51
1101051,3.67,3.58

💡技巧：预测时使用与训练数据同分布的测试集可以获得更可靠的结果。如果预测误差较大，可考虑使用该数据集微调预训练模型。

数据与训练自查清单

检查项	检查内容	完成情况
数据格式	CIF文件和id_prop.csv是否符合要求	□
数据对应	CIF文件名与id_prop.csv中的ID是否匹配	□
训练参数	任务类型是否正确设置	□
训练过程	损失是否稳定下降	□
模型保存	最佳模型是否成功保存	□
预测输入	预训练模型路径是否正确	□
预测输出	test_results.csv是否生成且格式正确	□

三、深化：问题诊断与最佳实践

问题诊断决策树

当使用CGCNN过程中遇到问题时，可以按照以下决策树进行诊断：

环境配置问题

• 症状：ImportError: No module named 'xxx'
• 根源：依赖库未正确安装
• 解决方案：使用conda install -n cgcnn xxx -c conda-forge安装缺失库

数据格式问题

• 症状：ValueError: could not convert string to float
• 根源：id_prop.csv文件格式错误，如使用了错误的分隔符
• 解决方案：确保使用逗号作为分隔符，且每行只有一个逗号分隔ID和属性值

内存问题

• 症状：RuntimeError: CUDA out of memory
• 根源：批大小设置过大，超出GPU内存容量
• 解决方案：1. 减小批大小；2. 使用CPU训练（添加--disable-cuda参数）；3. 减少模型复杂度

训练效果问题

• 症状：训练损失不下降或验证损失持续上升
• 根源：学习率不合适或模型过拟合
• 解决方案：1. 调整学习率；2. 增加正则化（--weight-decay）；3. 早停策略；4. 增加训练数据量

超参数调优指南

以下是三组经过验证的超参数配置，适用于不同场景：

配置一：快速验证（数据集小，追求速度）

--epochs 30 --batch-size 256 --lr 0.01 --n-conv 2 --h-fea-len 64

适用场景：新数据集初步探索，快速验证模型可行性

配置二：标准训练（平衡速度与性能）

--epochs 60 --batch-size 128 --lr 0.005 --n-conv 3 --h-fea-len 128 --weight-decay 1e-5

适用场景：常规材料属性预测任务，中等规模数据集

配置三：高精度训练（追求最佳性能）

--epochs 100 --batch-size 64 --lr 0.001 --lr-milestones 30 60 --n-conv 4 --h-fea-len 256 --weight-decay 1e-4

适用场景：重要实验，需要最高预测精度，计算资源充足

💡技巧：使用学习率调度（--lr-milestones）通常能获得更好的收敛效果，建议设置在总epochs的1/3和2/3处。

社区最佳实践

数据预处理建议

1. 数据清洗：移除包含不完整或错误晶体结构的CIF文件，可使用pymatgen库进行结构验证
2. 数据标准化：对属性值进行统计分析，移除异常值，必要时进行归一化处理
3. 数据划分：建议按8:1:1比例划分训练集、验证集和测试集，确保分布一致

模型评估方法

除了默认的MAE或AUC指标外，还可以通过以下方式进行更全面的模型评估：

1. 误差分析：计算并可视化不同材料类别的预测误差，识别模型的薄弱环节
2. 不确定性评估：多次运行模型（改变随机种子），分析预测结果的稳定性
3. 特征重要性：通过梯度分析等方法，识别对预测贡献最大的晶体结构特征

成功应用案例

案例一：新型热电材料发现
某研究团队使用CGCNN模型预测了数千种潜在热电材料的性能，将实验筛选范围缩小了90%，最终发现了10种具有优异性能的新材料，相关成果发表在《Nature Materials》。

案例二：催化剂高通量筛选
在催化剂开发项目中，研究人员利用CGCNN模型对包含10万多种金属有机框架材料的数据库进行了筛选，识别出20种具有高催化活性的候选材料，将实验测试成本降低了99.98%。

深化应用自查清单

检查项	检查内容	完成情况
问题诊断	是否能准确定位常见错误的原因	□
参数调优	是否尝试过至少两种超参数配置	□
数据质量	是否对数据集进行了清洗和标准化	□
模型评估	是否使用了多种评估指标和方法	□
结果分析	是否对预测结果进行了深入分析	□
应用拓展	是否尝试将模型应用于新的材料体系	□
文档记录	是否完整记录了实验过程和结果	□

通过本指南，你已经掌握了CGCNN的核心使用方法和最佳实践。随着实践深入，你可以尝试修改模型结构或数据处理流程，进一步提升预测性能，加速材料科学研究进程。