qmof介绍，matdeeplearn MOFS 转图数据 附带pymatgen, vasp

QMOF

QMOF是目前最全面的mof数据库，对应有平台https://next-gen.materialsproject.org/

MatDeepLearn 是目前包含QMOF的第一个材料化学GNN baseline框架。vxfung/MatDeepLearn: MatDeepLearn, package for graph neural networks in materials chemistry (github.com)

本文先对qmof的文档中的数据标准（Version History - Materials Project Documentation）进行整理；然后对代码中（ qmof:https://github.com/arosen93/QMOF ） 的抽取mofs结构图数据的方法进行分析。最后对MatDL框架的图数据标准进行分析。。

后续工作包括从CSD即其它数据集上下载更多的数据，理解CIF文件结构与内容，定义我们的MOFS结构图数据标准。

QMOF的数据来源

数据筛选准则：QMOF为了保证数据 DFT-ready 进行去重、去非法结构，为了保证DFT的效率，约束300个原子以下。

数据源：CDS&CORE等9个数据库（Structure Sources - Materials Project Documentation），更新致20376个数据 2021/12/8

其它数据库简介：

Pyrene MOFs：实验表征的含芘 MOF。 Materials Cloud.

(以下都是hMOFs)

TOBACCO ：根据构造单元生成hMOF。 Topology-Based Crystal Constructor (ToBaCCo) code

Anderson and Gómez-Gualdrón dataset ： TOBACCO 生成的hMOF

Woo& Boyd et al. TOBACCO 生成的hMOF Materials Cloud.

Genomic MOF Database: hMOFs, available on Figshare

Hypothetical MOF-74s,Hypothetical MOF-74s: hMOFS, here

QMOF的标准字段

QMOF-ID：qmof-七位16进制 qmof-1abcd2。不同的id有不同的原始单元晶格。不同的依据是 Pymatgen's StructureMatcher.

MOF-ID: SMILE表达式SMILES（一串字符来描述一个三维化学结构）_百度百科 (baidu.com)，用于mof检索，（也可用DOI，CSD refcode）。通过SMILE算法生成。

拓扑结构：点数、边数、构造单元连通性等。通过MOF-ID在 Reticular Chemistry Structure Resource. 上检索得到，该网站包含数千个拓扑结构。

一下是量子性质：（标签）

带隙：通过 Pymatgen's EIGENVAL parser得到。

partial atomic charges，multiple magnetic properties，Bond orders，Density of states，孔隙几何性质。

VASP setting：DFT的参数。

cif文件转图数据

该方法利用pymatgen,ASE 库解析cif文件得到mofs的原子结构（包括邻居和空间信息）。基于该结构，用距离阈值定义化学键，最后使用n最近邻建图。

输出

• 2个邻接表，表示单个mofs原子间的连接关系。（邻居id存一个表，属性另一个表；取最近邻的操作保证表格列数相同）
• 每个节点的特征向量。
• 整张图的标签和id。

输入

数据文件夹root_dir有如下结构：

root_dir
├── id_prop.csv
├── atom_init.json
├── id0.cif
├── id1.cif
├── ...

其中 id0是cif文件。

CIF的语法较复杂，完整cif文件包含的内容很多。其中各项含义可见CIF文件详解 - 百度文库 (baidu.com)， 官方文档(IUCr) A guide to CIF for authors。

data_image0
_cell_length_a 16.991
_cell_length_b 16.991
_cell_length_c 16.991
_cell_angle_alpha 90
_cell_angle_beta 90
_cell_angle_gamma 90

_symmetry_space_group_name_H-M "P 1"
_symmetry_int_tables_number 1

loop_
_symmetry_equiv_pos_as_xyz
'x, y, z'

loop_
_atom_site_label
_atom_site_occupancy
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
_atom_site_thermal_displace_type
_atom_site_B_iso_or_equiv
_atom_site_type_symbol
C1 1.0000 0.37705 0.00790 0.62295 Biso 1.000 C
C2 1.0000 0.36851 0.89914 0.68750 Biso 1.000 C
H1 1.0000 0.37770 0.85890 0.72340 Biso 1.000 H
C3 1.0000 0.40610 0.08550 0.59390 Biso 1.000 C
N1 1.0000 0.40973 0.96832 0.68278 Biso 1.000 N

csv文件包含cif的id和属性的对应。

1,1.0
2,2.0
3,3.0

json文件包含原素的随机初始嵌入向量（可以是onehot)。

"1": [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0],
"2": ...

建图算法流程

1. 得到所有原子：Structure.from_file(id0.cif）:将cif读入，转化为pymatgen.structure

2. 得到原子的特征向量（初始嵌入向量）atom_fea： AtomCustomJSONInitializer.get_atom_fea

3. 得到原子的邻居all_nbrs: Structure.get_all_neighbors

4. 建图 ，得到nbr_id，nbr_fea： 以radius为阈值建边，取最近的max_num_nbr个。不足的对属性向量进行进行正规化（？）.最后调用GaussianDistance.expand

总结：根据距离阈值连化学键，再取最邻近的n个，（nbr_fea也可以看出是键的特征）属性中有一些人工提取的距离特征（正规化，高斯距离）。

改进：额外考虑键的3维特征（ALIGNN），额外考虑子图特征（官能团、次级结构）。

CDS cif转 mofs cif

从 Cambridge Structural Database 的原始cif文件经过处理转换，得到qmof数据库文件的流程。目的是去除失真的结构（maximize structural fidelity），涉及化学知识。

流程

1通过ase库规范化CIF文件

from ase.io import read, write
for cif in cifs:
mof = read(os.path.join(cif_path, cif))
write(os.path.join(cif_path, cif), mof)

2通过pymatgen库得到晶体最小的重复单元

structure = Structure.from_file(os.path.join(folder,entry),primitive=True)

3去除非法的cif文件，依据有dist，lone，duplicate，oxo

4 支持xyz文件相互转换

ASE-formatted appended XYZ file to a folder of CIFs.

matDL的建图标准

使用了pytorch geometric 包来实现GNN算法。

读取json格式的qmof数据，转换成如下格式：

├──dictionary_source.json
├──root_dir
├── targets.csv
├── qmof-1234567.json
├── qmof-89abcde.json
├── ...

json的格式为:

{"1": {
 "cell": {"array": {"__ndarray__": [[3, 3], "float64", [9.806075328, 0.108025938, 8.4506e-05, -2.412034763, 9.564903313, -3.8425e-05, 0.000113935, -2.188e-05, 13.246085401]]}, "__ase_objtype__": "cell"},
 "ctime": 22.202870969564355,
 "mtime": 22.202870969564355,
 "numbers": {"__ndarray__": [[108], "int32", [27, 27, 27, 27, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 7, 7, 7, 7, 7, 7, 7, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8]]},
 "pbc": {"__ndarray__": [[3], "bool", [true, true, true]]},
 "positions": {"__ndarray__": [[108, 3], "float64", [9.000000002061375e-05, -1.0000000015167157e-05, 6.623059999999954, 3.6971139349999804, 4.836458119999971, 13.246105400999976, ...,]]},
 "unique_id": "fc8de825d5b9a6edc082f11ef7e5db52",
 "user": null},
"ids": [1],
"nextid": 2}

dataloader

（pyg的dataloader分为处理小规模数据的in memory loader和对应的dataloader。核心是process函数；dictionary_source: 元素的onehot）

Data(edge_index=[2, 507], edge_weight=[507], y=0.6325269937515259,
z=[39], u=[1, 3], structure_id=[1], x=[39, 114], edge_attr=[507, 50])

主要属性

edge_index, edge_weight ：稀疏邻接矩阵，直接通过ase_crystal.get_all_distances后矩阵处理得到：

##Obtain distance matrix with ase
distance_matrix = ase_crystal.get_all_distances(mic=True)

##Create sparse graph from distance matrix
distance_matrix_trimmed = threshold_sort(
distance_matrix,
processing_args["graph_max_radius"],
processing_args["graph_max_neighbors"],
adj=False,
)

distance_matrix_trimmed = torch.Tensor(distance_matrix_trimmed)
out = dense_to_sparse(distance_matrix_trimmed)
edge_index = out[0]
edge_weight = out[1]

X:节点嵌入向量，初始值式mofs每个原子的onehot向量堆叠

y label 一维tensor

辅助信息

structure_id : QMOF ID

u placeholder for state feature？[3*n]

z 原子总数

额外的descriptor

edge_vonoroi,SOAP,SM,edge_descriptor

图数据集的属性:length,species(desctiptor 可能用到)

化学计算库介绍

pymatgen

https://pymatgen.org/ for materials analysis。

conda install --channel conda-forge pymatgen

qmof中主要用来读取cif文件并利用其中的Structure类来表示cif，并建图。

核心类

pymatgen.core包提供了分子和晶体结构的数据结构，核心的类包括：

species是元素（形态）,

composition是元素及其量的键值对{element:amount}

site是composition及其在空间上的位置, 以及可能的属性（如磁性）。

periodic site 是有lattice system的cite

lattice system 晶格？

molecule和 stucture （有周期）, 是site/periodic site 的数组。

属性包括：occupancies， ang, occupancy，length units are in Angstroms and angles are in degrees.

ASE

conda install --channel conda-forge pymatgen 时会一起安装

ASE是一个用Python编程语言编写的原子模拟环境，旨在设置、指导和分析原子模拟。qmof中主要用来读取cif文件。

VASP

VASP是维也纳大学Hafner小组开发的进行电子结构计算和量子力学-分子动力学模拟软件包。它是目前材料模拟和计算物质科学研究中最流行的商用软件之一。用户需要确保版权。之后可以可以用来计算mof结构的性质。

# 导入编译器
module load intel/2017.1
tar xf vasp.5.4.4.tar.gz
cd vasp.5.4.4
cp arch/makefile.include.linux_intel ./makefile.include
make all
# 编译完成后会在vasp.5.4.4的文件夹下的bin文件夹里生成vasp_gam、vasp_ncl、vasp_std三个可自行文件。

# gpu版本安装
module load intel/2017.1
tar xf vasp.5.4.4.tar.gz
cd vasp.5.4.4
cp arch/makefile.include.linux_intel makefile.include
# 修改 -openmp 为 -qopenmp
make gpu
# GPU版本使用的时候需要载入cuda，高版本如2018的intel编译器编译时会报错

VASP:Vasp · Doc (pku.edu.cn) 科学网—VASP 固定POSCAR中部分原子的四类方法 - 郭令举的博文 (sciencenet.cn)

总结

QMOF的gcn和matDL的输入文件相似，只是前者用cif，后者是json，两者都可以用ase库处理。

matDL pyg框架下，用矩阵技巧处理，并增加了很多特性用于扩展到多种GNN算法。 QMOF是pytorch简单实现的gcn。