QMOF数据库技术指南：从环境搭建到材料性能预测的完整路径

一、环境搭建与项目结构解析

1.1 快速部署QMOF工作环境

QMOF数据库提供了金属有机框架（MOF）材料研究的完整解决方案，涵盖数据处理、机器学习和DFT计算流程。以下是快速部署步骤：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/qm/QMOF
cd QMOF

项目核心目录结构：

• database_tools/: MOF结构数据处理工具集
• machine_learning/: 材料性质预测模型与特征生成器
• other/dft_workflow/: 密度泛函理论计算工作流
• other/example_dos/: DFT计算结果示例数据

1.2 环境依赖配置建议

建议使用Python 3.8+环境，并安装必要依赖：

# 安装基础依赖（示例）
pip install numpy pandas scikit-learn ase

各模块详细依赖可参考对应目录下的requirements.txt文件。

二、数据处理核心功能详解

2.1 MOF结构格式转换工具使用

database_tools/目录提供多种格式转换工具，支持CIF与XYZ格式的双向转换：

# CIF转XYZ格式示例
python database_tools/cifs_to_xyz.py --input_dir ./data --output_dir ./output

应用场景：将晶体结构数据转换为机器学习模型可接受的格式，为特征提取做准备。

2.2 数据清洗与结构优化工具链

• deduplicate.py: 移除重复结构
• lone_atom_check.py: 检测并修复孤立原子
• make_primitive.py: 生成原始胞结构

操作流程：

1. 使用check_dist.py验证结构合理性
2. 运行false_terminal_oxo_checker.py检测氧化态问题
3. 通过ase_formatter.py标准化结构数据

三、机器学习模块实践指南

3.1 特征提取方法对比与选择

QMOF提供多种材料表征方法，位于machine_learning/目录：

• SOAP核函数 (soap_kernel/): 适用于局部化学环境描述
• 正弦矩阵 (sine_matrix/): 高效捕捉长程结构信息
• 轨道场矩阵 (orbital_field_matrix/): 结合电子结构特性

选择策略：

• 预测吸附能：优先使用SOAP核函数
• 预测力学性质：推荐正弦矩阵或轨道场矩阵

3.2 模型训练与评估完整流程

以SOAP核函数为例，训练能带隙预测模型：

# 生成SOAP特征矩阵
python machine_learning/soap_kernel/soap_matrix_generator.py --input data.csv --output features/

# 训练KRR模型
python machine_learning/soap_kernel/soap_krr.py --features features/ --target band_gap

评估方法：

• 使用*_learning_curves.py脚本生成学习曲线
• 分析模型在不同训练集大小下的表现

金属有机框架材料的高通量计算筛选流程示意图，展示从MOF数据库到DFT计算再到候选材料筛选的完整路径

四、DFT计算工作流应用

4.1 高通量计算任务配置

other/dft_workflow/mof_screen/提供自动化DFT计算框架：

# 配置计算参数
from pymofscreen.screen import MOFScreen
screen = MOFScreen(cif_path='structures/', calculator='vasp')

# 提交批量计算
screen.run_screening()

关键组件：

• default_calculators.py: 预设VASP等计算软件参数
• kpts_handler.py: 自动生成k点网格
• vtst_handler.py: 过渡态搜索工具

4.2 计算结果分析工具使用

other/example_dos/目录提供态密度（DOS）分析示例：

# 运行DOS分析脚本
python other/example_dos/GUTYAW/dos.py

输出内容：

• 能带结构图
• 总态密度与分波态密度曲线
• 费米能级位置标注

五、高级应用与案例研究

5.1 材料性能预测模型构建案例

案例：使用UMAP降维分析MOF结构空间

# 运行UMAP降维
python machine_learning/umap/umap_reduction.py --features features.csv --n_components 2

应用价值：直观展示不同MOF拓扑结构的分布规律，辅助材料分类与筛选。

5.2 多模块协同工作流设计

推荐流程：

1. 使用database_tools/预处理结构数据
2. 通过machine_learning/stoich45_*生成元素属性特征
3. 利用dft_workflow/验证预测结果
4. 使用UMAP可视化分析构效关系

六、常见问题与优化策略

6.1 数据处理常见错误解决

• 结构转换失败：检查CIF文件完整性，使用cif_handler.py修复格式问题
• 特征维度爆炸：通过umap_reduction.py降低维度，或增加正则化项

6.2 计算效率提升技巧

• 对于大规模数据集，使用soap_avg_kernel_generator.py生成平均SOAP特征
• 调整runner/sub_slurm.job中的并行参数优化计算资源利用

七、项目维护与资源更新

• 定期查看updates.md获取功能更新信息
• 参考benchmarks.md验证新方法性能
• 通过data_sources.md了解数据库扩展与更新策略

通过本指南，您可以系统掌握QMOF数据库的核心功能，从数据处理到模型构建，再到DFT计算验证，形成完整的MOF材料研究工作流。建议从示例数据入手，逐步扩展至自定义研究任务。