HamGNN项目最佳实践教程

1、项目介绍

HamGNN是一个基于E(3)等变图神经网络，旨在为分子和固体材料预测从头算紧束缚(Tight-Binding, TB)哈密顿矩阵的项目。它支持与依赖数值原子轨道的常用从头算DFT软件（如OpenMX、Siesta和ABACUS）协同使用，并能够预测具有自旋轨道耦合效应的SU(2)等变哈密顿矩阵。HamGNN提供了一个高保真度近似DFT结果，并能够在不同材料结构间实现可迁移的预测，使其成为大规模系统电子结构计算加速的理想选择。

2、项目快速启动

安装环境

推荐使用Python 3.9。HamGNN所需的Python库包括：

• numpy == 1.21.2
• PyTorch == 1.11.0
• PyTorch Geometric == 2.0.4
• pytorch_lightning == 1.5.10
• e3nn == 0.5.0
• pymatgen == 2022.3.7
• tensorboard == 2.8.0
• tqdm
• scipy == 1.7.3
• yaml

安装环境有两种方法：

1. 使用environment.yaml：

   conda env create -f environment.yaml
   

   注意：使用当前environment.yaml创建的环境可能在训练SOC哈密顿矩阵时出现错误。

2. 使用预构建的Conda环境：

   从Zenodo下载预构建的HamGNN Conda环境（ML.tar.gz文件），解压到conda/envs目录中。

安装HamGNN

git clone https://github.com/QuantumLab-ZY/HamGNN.git
cd HamGNN
python setup.py install

如果从旧版本升级，先卸载旧版本：

pip uninstall HamGNN

确保删除site-packages目录中的残留文件（如HamGNN-x.x.x-py3.9.egg/HamGNN）后再安装新版本。

使用HamGNN

准备哈密顿矩阵训练数据

1. 生成结构文件（如POSCAR或CIF）。
2. 将结构转换为OpenMX格式（.dat）。
3. 在结构文件上运行OpenMX，生成包含哈密顿矩阵和重叠矩阵信息的.scfout二进制文件。
4. 使用openmx_postprocess处理.scfout文件，生成.overlap.scfout文件。

准备哈密顿矩阵评估数据

如果已有训练好的模型，准备评估数据的方法与训练数据类似，区别在于：

1. 跳过OpenMX计算，直接将openmx_postprocess生成的.overlap.scfout文件当作OpenMX生成的.scfout文件使用。

图数据转换

1. 在graph_data_gen.yaml文件中设置路径。

2. 运行以下命令，将结构和哈密顿矩阵数据转换为HamGNN网络的输入文件：

   graph_data_gen --config graph_data_gen.yaml
   

   生成graph_data.npz文件，用于HamGNN的输入。

HamGNN网络训练和预测

1. 配置网络：在config.yaml文件中设置网络和训练参数。

2. 训练HamGNN：运行以下命令，启动训练过程：

   HamGNN2.0/HamGNN1.0 --config config.yaml
   

3. 监控训练：使用TensorBoard跟踪训练进度。

4. 预测：训练完成后，将待预测的结构转换为graph_data.npz，设置config.yaml中的checkpoint_path为训练模型路径和stage为test，然后运行：

   HamGNN2.0 --config config.yaml
   

3、应用案例和最佳实践

HamGNN适用于高吞吐量的电子结构计算，特别是在处理大规模系统时。最佳实践包括：

1. 确保使用的Python和库版本符合HamGNN要求。
2. 在训练模型前，确保准备好的数据质量和完整性。
3. 根据实际情况调整config.yaml中的参数，优化模型性能。
4. 使用TensorBoard监控训练过程，及时调整模型和参数。

4、典型生态项目

HamGNN与其他开源项目协同工作，例如：

1. OpenMX：用于生成紧束缚哈密顿矩阵。
2. Siesta：用于计算电子结构。
3. ABACUS：用于研究电子结构、力学和热力学性质。
4. PyTorch Geometric：用于构建图神经网络。

通过遵循以上最佳实践和利用HamGNN及其生态项目的强大功能，可以有效地进行高吞吐量的电子结构计算。