Name: QMOF Database（Quantum MOF Database，金属有机框架量子化学数据库）
Creator: Andrew S. Rosen 等（Northwestern University / University of Minnesota / MIT 合作）
Published: 2026-10-23
License: https://creativecommons.org/licenses/by/4.0/

信息速览

数据集名称QMOF — 20,372 个金属有机框架，四种泛函的带隙

数据类型20,372 个 MOF,231 万原子,79 种元素,四档泛函带隙,DDEC6/CM5/Bader 电荷,CC BY 4.0,需注册 CSD 才能取初始结构

规模不适用（材料化学数据库，无生物个体；结构来源中 0 个涉及人体样本）

接入方式QMOF Database（Figshare / Materials Project MOF Explorer） url: https://figshare.com/articles/dataset/QMOF_Database/13147324

AI 就绪度

INFOBOX

项	值
全名	QMOF Database（Quantum MOF Database）
维护方	Andrew S. Rosen（Northwestern → MIT 时期工作），合作者含 R.Q. Snurr、K.A. Persson 等
当前版本	v18（2025-11-15），v1 起共 18 个版本
结构数	20,372
原子总数	2,312,743
单结构原子数	17 – 500（均值 114，中位 96）
元素种类	79（H 至 Pu）
带隙覆盖	PBE 全库；HLE17 10,756 / HSE06* 10,811 / HSE06 10,810
泛函	PBE-D3(BJ)（几何优化）+ HLE17 + HSE06*（10% HF）+ HSE06（25% HF）
软件	VASP 5.4.4 + ASE 3.20.0b1
算力	超 170 CPU 年（仅 PBE 优化部分）
许可	CC BY 4.0（数据）；仓库代码 MIT
最大的坑	`synthesized` 字段一定要看——20,372 个结构里混着实验合成的和纯假设的，不筛掉假设结构就做「真实材料」预测，等于拿生成数据当真实分布

§0 本条目怎么来的、不做什么

我们是谁：千方病案医学编辑部，为中文医学 AI 社区整理可训练数据集的结构化说明。

本条目怎么来的：数字主源是 QMOF 官方 GitHub 仓库的 README.md、updates.md、data_sources.md、benchmarks.md、mofid_search.md 五个文件原文（2026-10-23 抓取），加上 Figshare 页面 v18 的版本历史 18 条（逐条日期可核），加上两篇原始论文（Matter 2021 的 DOI 页与 npj Comput Mater 2022 的全文）与 Materials Project 官方文档 Downloading the Data，再加上第三方 Hugging Face 重打包仓库的 README.md——后者给出了本条目最关键的三个数（20,372 结构 / 2,312,743 原子 / 79 元素）与三档带隙的覆盖数（10,756 / 10,811 / 10,810）。

我们不做什么：本条目不做任何 DFT 计算，不评价任何泛函的准确性，不下载主归档（Figshare 的 API 与页面在本环境均返回 403/202，无法程序化取到文件清单与体积）。§7 的口径核对只解释「为什么不同来源给的带隙覆盖数不完全一致」，不判定谁对谁错。

已知局限：

主归档的文件清单与总体积我们没有拿到。Figshare 的 api.figshare.com/v2/articles/13147324 在本环境返回 403，页面直连返回 202 空响应，ndownloader 端点返回的是一个 1.18 MB 的 zip 片段（非完整归档）。所以本条目不给「总下载体积」这个数。
Materials Project 的 MOF Explorer 与 MPContribs API 在本环境被 IP 级封禁（返回 blocked，原因是「inefficient or abusive traffic」——沙箱出口 IP 的共享特征触发），官方在 Explorer 上的实时统计我们没取到。
ENERGY 相关参数（ENCUT、k 点密度、EDIFF）没有核实到确切值。两篇论文正文都写明这些在 Supplementary Information 里，正文未列。本条目不给这些参数的猜测值。

§1 数据集概览

§1.0 📌 30 秒速览

QMOF 做的事情，一句话：把「金属有机框架」这一类材料的量子化学性质，用同一套周期性 DFT 流程在 20,372 个结构上算了一遍，并把四种泛函的结果并排放在一起。

规模（2026-10-23 实测）：

指标	数值	说明
结构数	20,372	v18
原子总数	2,312,743	平均每结构 114 个
单结构原子数	17 – 500	中位 96，十分之一的结构超过 200 个原子
元素	79	H 至 Pu
PBE 带隙	20,372（全库）	主标签，双峰：0.90 / 2.93 eV
HLE17 带隙	10,756	高精度子集
HSE06* 带隙（10% HF）	10,811
HSE06 带隙（25% HF）	10,810
闭壳层 / 开壳层	8,628 / 2,092	合计 10,720（论文口径）
算力	170+ CPU 年	仅 PBE 优化

三个必须先知道的形状问题：

「MOF」这个词在库里被放宽了。 data_sources.md 原文：「given the loose definition of a MOF in the CSD MOF Subset, some of these materials may be better classified as coordination polymers」。这意味着库里有相当一部分不是多孔的框架材料，而是配位聚合物。 如果你的任务依赖「有多孔结构」这个前提（比如气体吸附、分子筛分），必须先用 pld/lcd 或空隙率过滤，否则会混进一堆无孔材料。
实验结构与假设结构混在一起。 synthesized 字段 1 = 来自 CSD 或 CoRE（实验合成），0 = 来自 ToBaCCo / Boyd & Woo / GMOF（纯计算假设）。从 v6 起陆续加入假设结构，到 v18 已占相当比例。 做「预测真实材料性质」时，不筛 synthesized=1 就等于拿生成数据当真实分布——这是本库最容易被忽略的一刀。
四档泛函覆盖的是不同的子集。 PBE 全库 20,372 条，但三档高精度泛函只有约 1.07 万条（各档之间还差几十条）。做「泛函对比」只能在交集上做，而这个交集的闭壳层/开壳层比例是 8628:2092——不是随机子集，是刻意选的（进一步说：开壳层含 3d 过渡金属，理论处理本就难，选样有偏）。

如果你要做带隙预测、要训晶体图神经网络、要做MOF 筛选、要研究泛函选择如何改变结论，QMOF 是公开渠道里唯一同时具备「周期性 DFT + 多泛函 + 逐原子电荷 + 20k 规模」的库；如果你要的是分子（不是晶体），QM9 / PCQM4Mv2 / GEOM / MD17 更合适；如果你要的是无机晶体，Materials Project / OQMD / Alexandria 覆盖更广。

§1.1 技术摘要

维度	值
对象	MOF 与配位聚合物（周期性晶体）
规模	20,372 结构 / 2,312,743 原子
几何优化级别	PBE-D3(BJ)，VASP 5.4.4
单点级别	HLE17 / HSE06*（10% HF）/ HSE06（25% HF）
主要属性	带隙（四档）、原子电荷（DDEC6/CM5/Bader）、键级（DDEC6）、自旋密度、磁矩、孔径（PLD/LCD）、密度
标识符	qmof_id（哈希）、name（来源库名）、MOFid / MOFkey
来源	CSD MOF Subset、CoRE MOF 2019、Pyrene、ToBaCCo、Boyd & Woo、GMOF、Haranczyk MOF-5/MOF-74
分发	Figshare（主）/ NOMAD（VASP 文件）/ Globus（电荷密度）/ MPContribs（MP 镜像）
许可	CC BY 4.0

§1.2 战略价值

第一，它把「泛函选择」这个隐形变量变成了可见的实验。 这是 QMOF 最不可替代的一点。绝大多数材料数据库只给一档泛函的结果（通常 PBE），使用者默认「泛函是可换的、结论是稳的」。QMOF 用同一批 10,720 个结构做了四档：

PBE 带隙双峰：峰在 0.90 eV 与 2.93 eV
HLE17 双峰：峰在 0.86 eV 与 3.21 eV
HSE06*（10% HF）：两个分布显著重叠
HSE06（25% HF）：几乎完全重叠，整体趋近单峰

这组数字的含义是：PBE 得到的「双峰」不是材料的真实性质，而是闭壳层材料与开壳层材料在低精度泛函下的伪分离。论文原话说 PBE 的缺陷「go beyond a simple underprediction of the band gap」——不只是数值偏低，而是定性趋势都错了。如果两批材料一个闭壳层一个开壳层，用 PBE 带隙比较它们的高低，结论可能完全反过来。

第二，它把「每个百分点的 HF 交换能换多少 eV」量化了。 论文给出的线性关系：闭壳层框架的中位带隙随 HF 交换比例每增加 1% 上升约 0.05 eV；开壳层约 每 1% 上升 0.10 eV。开壳层对泛函的敏感度是闭壳层的两倍。 这是「为什么含过渡金属的 MOF 模拟特别难」的一个可量化答案。

第三，它把「结构保真度」这个脏活写进了版本日志。 updates.md 逐版记录了什么被移除、为什么移除——v12 因 Genomic MOF 库缺 H 原子而整批剔除；v15/v16/v17 各移除 1 个结构；poor_fidelity.txt 提前公告下一版要删哪些。这份日志本身就是一份「材料数据库怎么做质量治理」的教材，比绝大多数数据库的「本库经过严格质控」一句空话有用得多。

第四，它对能源领域有直接通道。 MOF 的核心应用是气体分离、储氢、催化，而这些都依赖电子结构（带隙决定导电性与光催化活性，电荷分布决定吸附位点与催化活性位）。QMOF 的逐原子 DDEC6 电荷与键级，正好是「结构 → 电子 → 功能」这条链的中间层数据。

§1.3 同类资源横向对比

资源	对象	规模	泛函档数	逐原子电荷	与 QMOF 的分工
QMOF	MOF / 配位聚合物	20,372	4（PBE/HLE17/HSE06/HSE06）*	有（3 种方案）	基准。唯一「多泛函 + 逐原子电荷 + 2 万级」的 MOF 库
CoRE MOF 2019	MOF	约 1.4 万（FSR 版）	0（只有结构）	无	QMOF 的上游原料之一。CoRE 给结构，QMOF 给性质
hMOF / Boyd & Woo	假设 MOF	约 13.9 万	0	无	QMOF 的上游原料之二。规模大两个数量级但无 DFT 性质
Materials Project	无机晶体为主	15 万+	1（PBE/GGA+U 为主）	部分	无机材料为主，MOF 部分依托 QMOF（MOF Explorer）
OQMD	无机晶体	100 万+	1（PBE）	无	规模取胜，无 MOF，无多泛函
Alexandria	无机晶体	500 万+	1（PBE）	无	同上
QM9 / PCQM4Mv2	分子（非晶体）	13 万 / 374 万	1（B3LYP 等）	有（部分）	对象不同：分子 vs 周期性晶体。库内已有，不能与 QMOF 混用
MD17 / MD22	分子轨迹	10 个分子 / 3,817,604 构象	1	无	分子动力学轨迹，QMOF 明确「无轨迹」
NOMAD 上的 QMOF	同上	条目数可能更多	4	同上	不是独立资源，是 QMOF 的 VASP 文件宿主；条目数多于官方库（移除的删不掉）

一句话分工：要 MOF 的电子结构只有 QMOF；要 MOF 的结构数量有 hMOF 与 CoRE；要无机晶体有 MP / OQMD / Alexandria；要分子有 QM9 / PCQM4Mv2。四类对象不可混。

§1.4 版本时间轴

updates.md 与 Figshare 版本历史合并（18 个版本，全部日期可核）：

版本	日期	变更要点
v18	2025-11-15	加入 QMOF Thermo Database 初步版
v17	2025-10-27	移除 qmof-98c279d
v16	2025-06-03	移除 qmof-42b55bb
v15	2025-01-16	移除 qmof-7d69ad1
v14	2021-12-09	新增 HLE17 / HSE06*（10% HF）/ HSE06（25% HF）单点计算
v13	2021-09-16	锁版，与上传到 NOMAD 的文件永久一致
v12	2021-09-15	剔除 Genomic MOF 库中缺 H 原子的结构；新增高 k 点的 NSCF 结果（v13 已回滚，因 LMAXMIX 设置不足）；VASP 原文件移出到 NOMAD；引入哈希式 qmof_id
v11	2021-09-13	同 v12 变更，但 bandgaps.csv 未做向后兼容
v10	2021-09-02	精减 JSON 冗余字段，减小体积
v9	2021-09-02	新增约 3,000 个 DFT 优化结构（CoRE / GMOF / CSD MOF Subset）；新增空间群；新增 synthesized 标记；补 PLD/LCD；修正 186 个 EDIFF 设错的结构（1e-4 → 1e-6）；用 StructureMatcher 去重
v8	2021-07-13	新增 1,243 个结构（Boyd & Woo 623 / CoRE 485 / ToBaCCo Cu 三角 92 / Hf MOF 44）；单胞原子上限提到 500
v7	2021-06-08	移除 12 个结构；JSON 增补属性并改善可解析性
v6	2021-05-07	新增 2,620 个结构（CSD 1217 / Boyd & Woo 1188 / Haranczyk 148 / ToBaCCo Zr 48 / Smit pyrene 19）；原子上限 150 → 300
v5	2021-02-13	对应 Matter 论文发表；与 v3 数据无差异，修 `get_subset_data.py` 的 bug
v4	2021-01-12	少量错别字修正，改进 .xlsx 读取
v3	2020-12-24	新增 CM5 电荷与 3,000+ Bader 电荷（含自旋密度）
v2	2020-12-05	新增约 1,500 个 PLD > 2.4 Å 的结构；原子上限 150 → 300
v1	2020-10-29	首版，对应 chemRxiv 预印本

版本机制的关键点：每个版本有独立 DOI 后缀（…13147324/18）。这意味着你可以精确锁定「我用的就是 v13」。官方在 READMEmd 与文档里反复强调「For reproducibility purposes, we recommend noting the version」。这是本库做得比多数数据库好的地方——HMD 就没有版本号（对比本站 rid 1356）。

v13 的特殊地位：updates.md 写「Locked-in version to permanently match the files uploaded to NOMAD」。做泛函对比研究时应该用 v13 或其后继，因为 v13 保证与 NOMAD 上的 VASP 原始文件一一对应。 而 benchmarks.md 给出的 ML 基准也是在 v13 上做的——这一点极易被忽略。

§1.5 典型应用场景

场景	用什么	关键注意
带隙预测（图神经网络）	`band_gap` + 结构图	必报 CGCNN 基线 0.270 eV；按 `synthesized` 分组报
泛函选择研究	四档带隙的交集	交集约 1.07 万，闭壳层/开壳层有偏
原子电荷预测	`ddec6_charges`	三种电荷不可混；DDEC6 覆盖最全
MOF 筛选（多孔）	`pld` / `lcd` + `band_gap`	PLD 是弛豫前算的，见 §4.4
磁性材料	`net_magmom` + 自旋密度	开壳层子集才有意义
催化位点分析	逐原子 DDEC6 电荷 + 键级	需自建「位点」定义
跨库按材料查找	MOFid / MOFkey	例如 MOF-5 的 MOFkey 是 `Zn.KKEYFWRCBNTPAC.MOFkey-v1.pcu`
气体吸附	⚠ 不推荐单独用	QMOF 不含吸附等温线；需转向 CoRE MOF + 分子模拟

§2 计算链：从 CSD 结构到带隙

QMOF 的价值全在「同一套流程」四个字上。这一节把从原始结构到最终属性的链条拆开，每一步都指出它对使用者的实际影响。

§2.1 结构从哪里来：九个来源，两类性质

data_sources.md 列出的来源共九类，分成两组，分组标准是「这个结构有没有被真的合成出来过」：

A 组：实验合成（synthesized = 1）

来源	命名特征	说明
CSD MOF Subset	名称以 `_FSR` 结尾	来自 CSD 的 MOF 子集，已去除游离溶剂（FSR = free solvent removed）。官方提醒这个子集对「MOF」的定义很松，部分是配位聚合物
CoRE MOF 2019	名称以 `core` 开头	用 FSR 版本；采用两条策展路线（v8 用 Kancharlapalli 等的子集，v9 用 Chen & Manz 的子集）以降低结构错误率
Pyrene MOFs	名称含 `pyrene`	少量含芘的 MOF，来自 Smit 组

B 组：计算假设（synthesized = 0）

来源	命名特征	说明
ToBaCCo（Cu 三角）	名称含 `tobacco`	Colón / Gómez-Gualdrón / Snurr 构建的 Cu 三角 MOF；原文的 Cu 三角中心有 H 原子，弛豫前已移除
ToBaCCo（Anderson，Zr/Hf）	名称含 `tobacco` 且含 `_SR_`	Anderson 与 Gómez-Gualdrón 的 Zr-MOF；另通过把 Zr 换成 Hf 造出 Hf-MOF
Boyd & Woo	名称含 `boydwoo`	用 TOBASCCO 代码构建；QMOF 团队做了修改：交换无机节点的金属、把 V 棒 MOF 换成 Al 棒并给桥氧质子化
GMOF（Genomic MOF）	名称含 `gmof`	v12 曾因这个库「上传了相当大比例缺 H 原子的结构」而整批剔除过一批
Haranczyk MOF-5	名称含 `MOF-5`	假设的 MOF-5 类似物
Haranczyk MOF-74	名称含 `mof74`	假设的 MOF-74 类似物

这张表最该记住的两件事：

命名前缀是唯一可靠的来源判据，但它不完整。 官方用 source 字段（CSD / CoRE / Pyrene / Anderson / ToBaCCo / BoydWoo / GMOF / Haranczyk_MOF5 / Haranczyk_MOF74）才是权威。名称前缀只是辅助——尤其 tobacco 同时对应两个 source 值（ToBaCCo 与 Anderson），只按名称筛会把两者混在一起。
B 组的结构是「造」出来的，不是「测」出来的。 Boyd & Woo 那批还经过 QMOF 团队手工改造（换金属、质子化桥氧）。对这些结构做「预测真实材料性能」是有意义的（如果它们可合成），但做「描述已知材料」是错的。

§2.2 为什么要「去除游离溶剂」

这是 MOF 计算里最基础也最容易被外行忽略的一步。

MOF 的晶体结构在实验测定时，孔道里通常塞满溶剂分子（合成时用的 DMF、水、乙醇等）。这些分子不是框架的一部分，它们的位置和取向高度无序，在 X 射线衍射里往往只能看到一个弥散的电子密度团。

如果不去掉：

原子数暴增。一个大孔 MOF 的孔道里可能有上百个溶剂分子，原子数翻倍。QMOF 的 500 原子上限会被大量溶剂占满，真正的框架反而算不细。
几何优化会跑偏。溶剂分子与框架的相互作用会拉着框架变形，优化出来的几何不是「空框架」的几何。
带隙会被污染。溶剂的电子态会混进框架的带隙里，算出一些不属于框架本身的能级。
不同批次的同一材料无法比较。每个实验测出的溶剂含量都不同。

这就是 FSR（free solvent removed）的意义：把孔道清空，只留框架。代价是：算出来的性质是「理想空框架」的性质，不是「实验测到的、带溶剂的那个东西」的性质。 做气体吸附模拟时这一点是前提；做「与实验光谱直接对比」时这一点是障碍。

一个实操后果：CoRE MOF 有 FSR 与非 FSR 两版，QMOF 只用 FSR。如果你想复现 QMOF 的某个结构，拿 CoRE 的非 FSR 版本会对不上。

§2.3 结构保真度：QMOF 最诚实的一段自我批评

updates.md 里散落着大量关于「结构有问题」的记录，把它们按时间排起来，就是一部「自动化结构清洗的踩坑史」：

版本	问题	处理
v9	186 个结构 INCAR 里 EDIFF 误设为 1e-4（应为 1e-6）	重算修正
v9	结构重复	用 Pymatgen 的 StructureMatcher 去重，用户不必自己跑
v9	PLD/LCD 缺失	补齐
v12	Genomic MOF 库相当大比例缺 H 原子	整批剔除
v12	NSCF 高 k 点计算	加入，但v13 回滚——因 `LMAXMIX` 设置不够高，影响部分结构
v12	原始 VASP 文件太大占 Figshare 配额	移到 NOMAD 托管
v7	—	移除 12 个
v8	—	移除 3 个
v15/v16/v17	各 1 个结构发现问题	逐版移除
当前	`poor_fidelity.txt`	提前公告下版将移除的清单

这段历史给出的三条判断：

第一，MOF 结构的「保真度」是一个持续性问题，不是一次性问题。 从 v1 到 v18，每一版都在删结构。这意味着：用旧版本训练的模型，它的训练集里包含后来被判定为错误的结构。 如果模型在这些结构上学到了「某种几何模式 → 某个带隙」的映射，而该几何其实是缺氢造成的假象，那这个映射是错的。

第二，自动化清洗抓不住所有问题。 GMOF 那批缺 H 原子的结构，是被自动化流程放进去的，后来才被发现。官方在 README.md 里专门留了一段「Structures to Remove」，请求使用者「if you identify any materials with structural fidelity issues not captured via the automated filtering steps, please share them」。这是一个明确的信号：保真度问题需要人机结合。

第三，LMAXMIX 那个回滚极有教育意义。 v12 加了「更高 k 点的 NSCF 计算」，v13 立刻回滚，原因是一个 VASP 内部参数（LMAXMIX，控制投影到局部轨道的最大角量子数）设得不够高，导致 d/f 电子体系的结果不可靠。这是「DFT 计算的正确性依赖于大量不显眼的参数」的一个具体例证——同一份输入、同一台机器，只差一个默认参数，结果就不能用。

§2.4 四种泛函：为什么是这四个

QMOF 的泛函选择不是随意拼的，构成一条从便宜到贵的连续谱：

泛函	类型	HF 交换比例	相对成本	在 QMOF 里的角色
PBE-D3(BJ)	GGA + D3(BJ) 色散校正	0%	1×（基准）	几何优化 + 全库带隙
HLE17	meta-GGA	0%	约 1.5–2×	单点
HSE06*	屏蔽杂化	10%	约 10–50×	单点
HSE06	屏蔽杂化（标准）	25%	约 10–50×	单点

为什么加 D3(BJ)：MOF 是多孔材料，框架内部有大量空隙，色散力（范德华）在决定孔道形状与骨架堆叠上作用显著。纯 PBE 不含色散，会把孔道算得偏大、骨架算得偏松。D3(BJ) 是 Grimme 的色散校正方案（Becke-Johnson 阻尼），加上它之后几何才可信。

为什么引入 HSE06*（10% HF）这个「非标准」泛函：标准 HSE06 用 25% HF 交换。但论文指出，HSE06 对某些 MOF（如 MOF-5）会过度修正 PBE 的带隙低估——修正过头了。10% 正好插在 PBE（0%）与 HSE06（25%）之间，用来分离「HF 交换比例」这一个变量的影响。这是一个很讲究的实验设计：不是简单「用更贵的泛函」，而是在连续谱上取三个点，看趋势。

为什么 HLE17：meta-GGA，成本接近 GGA 但在带隙上有改进。论文的结论是：HLE17 提高了中位带隙、减少了低带隙子集的结构数，但保留了双峰形态；而闭壳层框架的带隙分布与 HSE06* 接近。换句话说，HLE17 是「性价比折中」，但对开壳层不够好。

§2.5 带隙定义：自旋分辨这件事

这是 QMOF 最技术性、也最容易出错的一点。

闭壳层（closed-shell，无磁性）：简单

Eg = CBM − VBM

开壳层（open-shell，有磁性，自旋极化）：默认定义是

Eg = min(CBM↑, CBM↓) − max(VBM↑, VBM↓)

这个默认定义会产生什么：它给出的是可能在物理上对应「自旋禁阻跃迁」的带隙——意思是你算出来的这个最小间隙，从自旋向上的价带顶到自旋向下的导带底，这个跃迁在光学上是被禁戒的。

论文的处理：同时给出替代定义

Eg = min(CBM↑ − VBM↑, CBM↓ − VBM↓)

即「同自旋通道内的最小间隙」，并说明趋势与结论不变（Supplementary Fig. 5）。

实操含义：

QMOF 主库的 band_gap 用的是默认定义（跨自旋取 min/max）。如果你的任务关心光学吸收（比如光催化），应该改用同自旋定义，而要重算——数据里不一定直接给了两个自旋的 CBM/VBM 分列值。
8,628 : 2,092 的比例意味着约 19.5% 的结构受这个定义影响。 这不是边角情况。
开壳层材料集中含 3d 过渡金属（论文按出现频率递减列：Cu、Co、Mn、Ni、Fe、V、Cr）。做「含 Cu/Co 的 MOF 带隙预测」时，你的测试集里开壳层比例会很高，因此对带隙定义的敏感度也高。

还有一个必须知道的边界：QMOF 给的是电子带隙，不是光学带隙。 论文明确写不能直接与 UV-Vis 实验的光学带隙比较，尤其当激子结合能不可忽略时（举的例子正是 MOF-5）。拿 QMOF 的带隙去拟合实验光谱，会得到一个系统性的偏移，而这个偏移的大小取决于材料——不可用统一常数校正。

§2.6 属性是怎么算出来的：三种电荷方案

原子电荷是 QMOF 的另一条主线。它给了三种，而且三者数值不可混用：

方案	原理	覆盖	特点
DDEC6	密度导出静电与化学（Density Derived Electrostatic and Chemical）	全库（v3 起）	逐原子电荷 + 键级 + 自旋密度；官方最推荐
CM5	电荷模型 5（基于 Hirshfeld 的改进）	全库（v3 起）	计算便宜，数值相对温和
Bader	分子中原子量子理论（QTAIM）的零通量面划分	约 3,000+（v3 起）	物理基础清晰，但数值对基组敏感、对金属体系常给出反常值

为什么三者不可混：

数值范围不同。同一个原子的 DDEC6 电荷可能是 +1.2，CM5 可能是 +0.6，Bader 可能是 +2.0。用 DDEC6 训练的模型去预测 Bader，误差会大到没有物理意义。
对金属的稳定性不同。Bader 在金属中心上经常给出令人意外的分配（因为电荷密度在金属附近变化平缓，零通量面位置不稳），DDEC6 专门为此设计过。
覆盖不同。Bader 只有约 3,000 条，是 DDEC6 的约 1/7。做多任务学习时，Bader 那一支的样本量小一个数量级。

实操建议：首选 DDEC6。 它覆盖最全、同时给出键级与自旋密度，是三者里信息最完整的。只有当你研究的问题本身与 QTAIM 分划有关（比如拓扑分析），才用 Bader。

还有一个坑：updates.md 记 v3「Added CM5 partial charges for every structure and 3000+ Bader charges (and spin densities)」。注意「every structure」只修饰 CM5，不修饰 Bader。 这句话很容易被读成「三种电荷都是全库」，实际不是。

§2.7 孔隙直径：PLD 与 LCD 算在什么时刻

两个孔径指标：

指标	全称	含义
PLD	pore-limiting diameter	孔道最窄处的直径，决定「什么分子能进去」
LCD	largest cavity diameter	最大腔体的直径，决定「能装多大的分子」

关键细节：updates.md v2 明确写「~1500 new structures with pore-limiting diameter greater than 2.4 Å, computed using Zeo++ prior to structure relaxation」。

「prior to structure relaxation」这四个字很重要：PLD/LCD 是在DFT 优化之前的初始结构上算的，而 qmof.json 里发布的是优化后的几何。

后果：如果你用发布的几何自己跑 Zeo++ 重算 PLD，结果会和库里的 pld 值不一致。差异通常不大（几个百分点），但对「刚好卡在某个阈值」的筛子（比如「PLD > 3.3 Å 以容纳 CO2」）会造成入选名单不同。

实操建议：做孔径筛选时直接用库里的 pld/lcd 列，不要自己重算。 如果你确实需要「优化后几何的孔径」，那就自己算，但要在论文里说明「与库内 pld 不同，因为计算时点不同」。

§3 数据规格与取数通道

§3.0 四条通道，各有各的边界

通道	拿到什么	拿不到什么	门槛
Figshare	优化后几何（XYZ / CIF）、属性表（JSON / CSV / XLSX）	VASP 文件、电荷密度、初始结构	无（公开）
NOMAD	所有 VASP 输入输出（四档泛函各一套）	属性表的便捷整理	无（公开）
MPContribs	与 Materials Project 互操作的镜像，可 API 查询	原始 VASP 文件	需 MP API key
Globus	电荷密度文件	其他一切	需 Globus 端点

这四条通道不是冗余备份，是内容互补。 官方文档写得很清楚：「Additional files and properties beyond those hosted on Figshare (e.g. VASP inputs and outputs, density of states, charge densities) can be obtained from NOMAD and Globus」。

实操顺序建议：

先下 Figshare 主归档——90% 的需求从这里满足（结构 + 属性表）。
要 VASP 文件 → NOMAD，按 external_id（= QMOF ID）查。
要电荷密度 → Globus，这一步通常只在做电子密度可视化或高级分析时才需要。
要与 Materials Project 体系对接 → MPContribs，适合已经在用 mp-api 的团队。

§3.1 文件地图

Figshare 主归档（按第三方重打包仓库的描述，v18 的 qmof_database.zip 内至少含）：

文件	内容
`qmof.json`	主属性表：每个结构的全部计算属性（带隙、电荷、磁矩、能量、孔径、来源、MOFid 等）
`qmof_structure_data.json`	结构数据：晶格、原子坐标、原子序数
`qmof.csv` / `qmof.xlsx`	属性的表格版（v4 起「更好的 .xlsx 读取」）
`bandgaps.csv`	带隙专表（v11 曾因未做向后兼容而被点名）
`logo.jpg`	图标（是的，归档里有这个）

注意一个容易被忽略的事实：bandgaps.csv 在 v11 里没有做向后兼容。updates.md 原文：「Same changes as in v12, but the bandgaps.csv file was not made backwards-compatible here」。如果你写过读 bandgaps.csv 的脚本，在 v11 上会静默给出错误结果。 这是版本升级时最典型的坑。

NOMAD 的四套数据集（按泛函分）：

泛函	NOMAD DOI
PBE	`10.17172/NOMAD/2021.10.10-1`
HLE17	`10.17172/NOMAD/2021.11.17-3`
HSE06*（10% HF）	`10.17172/NOMAD/2021.11.17-2`
HSE06（25% HF）	`10.17172/NOMAD/2021.11.17-1`

按 external_id 查 QMOF ID，加 datasets 限定泛函档。

§3.2 下载预算

本条目不给总体积。 原因：Figshare 的 API 在本环境返回 403，页面直连返回 202 空响应，ndownloader 端点返回的是不完整片段（1.18 MB，无法 unzip）。我们没有拿到可信的总体积数字，所以不写。

能给出的量级判断（基于结构与原子数推算，标注为推算非实测）：

项目	推算依据	量级
结构数据（2,312,743 个原子的坐标）	每原子约 3 个 float × 4 字节 + 原子序数	约 40 MB（未压缩）
属性表（2 万条 × 数十个字段，含逐原子电荷）	逐原子电荷是主要体积来源	约数百 MB
VASP 文件（四档泛函）	单结构若干 MB × 2 万 × 4	TB 级
电荷密度	单结构可达数百 MB	远超 TB

实操建议：先下 Figshare，只取你需要的列。 如果你只需要带隙与结构，qmof.json + qmof_structure_data.json 两个文件就够；不要为了「完整性」把 VASP 文件全下——那是 TB 级的下载，而且绝大多数任务用不到。

§3.3 版本机制：本库做得最好的部分

每个版本有独立 DOI，形如 10.6084/m9.figshare.13147324/18。这带来三个好处：

精确锁定。论文里写「we used QMOF v13」，读者能取到与作者完全相同的文件。
可追溯变更。updates.md 逐版说明改了什么，不是笼统的「数据已更新」。
可回滚验证。如果 v18 的某个结构有问题，可以退回 v17 复现。

官方对此的表述（README.md）：「For reproducibility purposes, we recommend noting the version of the QMOF Database you have used in your work」。这不是客套——v15/v16/v17 每版都各删了 1 个结构，如果不记版本，你无法解释「为什么我的 20,372 条和别人的 20,369 条对不上」。

一个值得注意的现象：版本号在 2021 年 9 月密集跳了三次（v9 / v10 / v11 都在 9 月 1–2 日，v12 / v13 在 9 月 13–16 日）。这说明那一周团队在做一次大幅重构（去重、加空间群、加 synthesized 标记、改 ID 方案、移 VASP 到 NOMAD）。如果要用「稳定版」，v13 之后才合适——v13 是「Locked-in version」。

§3.4 技术栈与溯源链

环节	用什么	对使用者的影响
结构来源	CSD / CoRE / ToBaCCo / Boyd & Woo / GMOF / Haranczyk	需 CSD 许可才能还原初始结构
结构清洗	去溶剂、补缺失原子、StructureMatcher 去重	清洗规则未完全公开，只知「做了什么」不知「怎么做的」
DFT	VASP 5.4.4 + ASE 3.20.0b1	VASP 是商业软件，你没许可就无法复算
电荷分析	DDEC6（需 chargemol）、CM5、Bader（需 VASP 的 TCharges 或 Henkelman 组工具）	DDEC6 需要额外软件，不是 VASP 自带
孔径	Zeo++（在弛豫前结构上）	开源，但版本未标注
分发	Figshare（主）/ NOMAD / Globus / MPContribs	四条通道内容互补

「VASP 是商业软件」这一点必须说清：QMOF 的全部结果依赖 VASP 5.4.4。没有 VASP 许可的研究者无法复算任何一个数，只能使用已发布的数值。这是材料计算领域普遍的结构性问题，QMOF 无法回避。缓解办法是 NOMAD 上公开了全部输入输出文件——你可以看到参数、看到输出，但改参数重算还是需要许可。

§4 记录结构与字段字典

§4.1 一条记录的结构

QMOF 的一条记录 = 一个周期性晶体结构 + 一组量子化学属性。键是 qmof_id。

结构与属性的分离：qmof_structure_data.json 只有几何（晶格、坐标、原子序数），qmof.json 有全部属性。两者通过数组索引或 qmof_id 对齐。第三方重打包时逐结构比对了两者的 MD5，说明对齐是可靠的。

一个重要的缺失：qmof.json 里有 mofid / mofkey，但第三方重打包版本把标识符单独放在 all_index.parquet 里（其 README 明确写「Identifiers are not in the file」）。这说明原始 JSON 与重打包版的字段组织不同，跨版本迁移要注意。

§4.2 标识符体系

QMOF 有三套标识符，用途不同：

标识符	形式	用途	稳定性
`qmof_id`	`qmof-98c279d`（哈希）	主键；跨 NOMAD / MPContribs / 版本追踪	v12 起引入，此前用别的方案
`name`	源库名（如 `LISBIZ_FSR`、`core_xxx`、`tobacco_xxx`）	追溯来源；含来源前缀	随源库变化
`mofid` / `mofkey`	`Zn.KKEYFWRCBNTPAC.MOFkey-v1.pcu`	跨库按材料查找（QMOF ↔ CoRE ↔ MOFDB）	由 MOFid 工具生成，稳定

mofkey 的价值：它把结构分解成「金属 + 拓扑」的形式。MOF-5 的 mofkey 是 Zn.KKEYFWRCBNTPAC.MOFkey-v1.pcu，其中 pcu 是拓扑类型（简单立方），Zn 是金属。用它在 QMOF 里搜 MOF-5，会命中多个条目——官方说「LISBIZ_FSR, MIBQAR_FSR, SAHYIK_FSR, SAHYOQ_FSR, XOKHAH_FSR, and so on (this is a very popular MOF)」。

为什么会有多个：同一个拓扑、同一种金属，但有机配体或晶胞参数略有不同的实验晶体，都被算作「MOF-5 类」。官方建议「取每原子能量最低的那个」——这是一个实用的去重规则。

实操流程（mofid_search.md 给的五步）：

1. 从原始来源下载你要找的 MOF 的 CIF（例如 MOF-5 从 RASPA2 仓库）
2. 用 web-mofid 工具（snurr-group.github.io/web-mofid/）上传，得到 MOFid/MOFkey
3. 记下 MOFkey
4. 在 qmof.json 里搜这个 MOFkey
5. 若命中多个，取能量最低的

§4.3 缺失与特殊值

情况	表现	含义
带隙未计算	`band_gap_hle17` 等为 NaN	该结构不在高精度子集里
`formation_energy_per_atom` / `energy_above_hull`	全部为 NaN	QMOF 不提供这两个量——没有统一参考态、没有凸包
Bader 电荷缺失	该结构无对应字段	只有约 3,000+ 条有
初始结构缺失	无字段	官方不发布初始结构，只发布优化后几何
轨迹缺失	无字段	官方 FAQ 明写「No」

formation_energy_per_atom 与 energy_above_hull 全为 NaN，这一点极重要。 如果你的任务需要「这个材料热力学上稳不稳定」（比如筛选可合成材料），QMOF 给不了答案。你必须转向 Materials Project 或 OQMD 取这两个量，然后按结构匹配——而按结构匹配又要靠 MOFid，且两个库的计算设置不同（见下条），能量不可直接比。

能量不可比的原文（第三方重打包文档）：「total_energy is a raw PBE-D3(BJ) energy with the settings of QMOF. It cannot be compared with the energies of the Materials Project or of LeMat-Bulk, and there is no convex hull.」

§4.4 字段字典

结构字段：

字段	单位	说明
`lattice_vectors`	Å	3×3 矩阵，按行排列
`atomic_positions`	分数坐标	乘晶格得笛卡尔坐标
`atomic_numbers`	—	原子序数，1–94（实际到 Pu = 94）
`pbc`	布尔三元组	三个方向是否周期
`n_atoms`	—	单结构原子数，17–500

属性字段：

字段	单位	覆盖	说明
`band_gap`	eV	全库	PBE 带隙；双峰 0.90 / 2.93
`band_gap_hle17`	eV	10,756
`band_gap_hse06_10hf`	eV	10,811	HSE06*
`band_gap_hse06`	eV	10,810
`cbm` / `vbm`	eV	子集	自旋分辨（↑/↓ 两套）
`ddec6_charges`	e	全库	逐原子
`cm5_charges`	e	全库	逐原子
`bader_charges`	e	约 3,000+	逐原子
`ddec6_bond_order`	—	全库	逐键
`ddec6_spin_density`	e	全库	逐原子
`bader_spin_density`	e	约 3,000+	逐原子
`net_magmom`	μB	全库	净磁矩
`total_energy`	eV	全库	QMOF 特定设置的原始能量，不可跨库比
`energy_vdw`	eV	全库	D3(BJ) 色散部分
`pld` / `lcd`	Å	全库	弛豫前用 Zeo++ 算
`density`	g/cm³	全库
`synthesized`	0/1	全库	1 = 实验来源
`source`	枚举	全库	9 个取值
`spacegroup`	—	v9 起
`mofid` / `mofkey`	字符串	全库	跨库匹配

§4.5 一个容易搞错的地方：`source` 有九个取值

`source` 值	含义	`synthesized`
`CSD`	CSD MOF Subset（去溶剂）	1
`CoRE`	CoRE MOF 2019 FSR	1
`Pyrene`	含芘 MOF（Smit 组）	1
`ToBaCCo`	Cu 三角 MOF	0
`Anderson`	Zr/Hf MOF	0
`BoydWoo`	Boyd & Woo 假设库	0
`GMOF`	Genomic MOF	0
`Haranczyk_MOF5`	假设 MOF-5 类似物	0
`Haranczyk_MOF74`	假设 MOF-74 类似物	0

注意 ToBaCCo 与 Anderson 都来自 ToBaCCo 代码，名称里都有 tobacco。只按名称筛会把这两类混在一起（一类是 Cu 三角，一类是 Zr/Hf）。

§5 检索、抽样与泄漏分析

§5.0 四条定位路径

路径	怎么做	适用
按 ID	`qmof_id == 'qmof-xxxxxxx'`	已知目标结构
按来源	`source == 'CSD'` 或 `synthesized == 1`	只要实验材料
按孔径	`pld > 3.3` 之类的阈值	气体分离筛选
按属性	`band_gap < 1.5`	半导体/光催化候选
跨库按材料	`mofkey` 匹配	从别的库拿材料名找 QMOF 条目

推荐的筛选顺序（我按实操优先级排）：

1. synthesized == 1              ← 先决定「要不要假设结构」
2. pld > <你的阈值>              ← 再决定「要不要多孔」
3. band_gap 在目标区间           ← 最后按任务筛
4. 检查 band_gap_hle17 是否有值  ← 决定能不能做泛函对比较验

为什么 synthesized 排第一：因为它是唯一定义「这批数据代表什么分布」的字段。实验结构的分布 = 真实已被合成的材料；假设结构的分布 = 生成算法造出来的材料。两者混在一起训练，模型会学到一个不存在的「材料总体」。

§5.1 抽样策略：晶体不能按结构随机切

核心原则：QMOF 里有大量「同拓扑、同金属、只差配体」的近重复结构，随机按结构切会造成严重泄漏。

三种正确的切法：

切法	做法	防住了什么	代价
按拓扑切（推荐）	按 MOFkey 的拓扑部分（如 `pcu`、`dia`）分组留出	同拓扑的模板化泄漏	需要先解析 MOFkey
按来源切	训练 CSD，测试 CoRE（或反之）	同源数据库的批次效应	两源结构风格差异大，可能过难
按金属切	留出含某种金属的全部结构	「见过 Cu 就会做所有 Cu-MOF」的泄漏	元素覆盖从 79 掉到 70 左右
按 `synthesized` 分	训练假设结构，测试实验结构	最有价值的泛化测试	难度高，但这是真实部署场景

绝对不能用的切法：

随机按结构切。同拓扑的近重复结构会被分到训练集和测试集两边。
按原子随机切（如果有人做逐原子任务，比如电荷预测）。同一结构里的原子高度相关。
按版本切（用 v13 训练、v18 测试）。v15–v17 删了几个结构，这不是独立的测试集。

§5.1.1 什么时候不该用 QMOF

五种情况应该直接换数据源：

需要「这个材料稳不稳定」。QMOF 的 formation_energy_per_atom 与 energy_above_hull 全是 NaN。转 Materials Project / OQMD。
需要吸附等温线 / 气体吸附量。QMOF 没有。转 CoRE MOF + GCMC 模拟，或专门的吸附数据库。
需要分子（不是晶体）。转 QM9 / PCQM4Mv2 / GEOM / MD17。
需要无机晶体、规模优先。转 Materials Project / OQMD / Alexandria。
需要 VASP 轨迹或初始结构。QMOF 明确不给。初始结构需 CSD 许可 + ConQuest。

§5.2 三类真实泄漏，按危害排序

泄漏一：同拓扑近重复（最严重）

MOF 的构造是「模板化」的：一个拓扑 + 一种金属 + 一种配体 = 一个结构。ToBaCCo 与 Boyd & Woo 就是用模板批量生成的，同一拓扑下可能有几十上百个变体，只差金属或官能团。

后果：随机切分时，训练集里有一个 pcu 拓扑的 Zn-MOF，测试集里有一个 pcu 拓扑的 Cu-MOF。模型学到的是「pcu 拓扑 + 大致配体 → 带隙」，而在测试集上「猜对了」——但它没有学会化学，只学会了模板识别。

判据：如果模型在随机切分上 MAE 是 0.15 eV、在按拓扑切分上是 0.40 eV，那 0.25 eV 的差距就是泄漏量。

泄漏二：total_energy 与带隙的相关性

total_energy 是 PBE-D3(BJ) 的原始总能量，它随原子数单调增长。如果把 total_energy 或 energy_vdw 当特征预测带隙，模型实际上在学「结构大小 → 带隙」，而不是「电子结构 → 带隙」。

而且这个泄漏很隐蔽：因为总能量与带隙确实有物理上的弱相关（大晶胞常见于大孔 MOF，大孔 MOF 常见于低带隙），所以指标会「看起来合理」。

正确做法：用「每原子能量」而不是总能量，或者干脆不用能量类特征。如果要用，至少除以 n_atoms。

泄漏三：三种电荷方案之间的泄漏

DDEC6、CM5、Bader 是同一套电子密度的三种划分。用一个预测另一个，或者用两个预测第三个，都是泄漏——它们在物理上包含相同的信息。

判据：用 CM5 预测 DDEC6，R² 会很高（>0.9），但这不是模型学会了化学，而是两种划分高度相关。

§5.3 结构泄漏：原子数与元素本身就是答案

带隙与组成强相关：含 Cu/Co/Mn/Ni/Fe 等 3d 金属的结构，开壳层比例高，带隙平均更低；纯 Zn/Cd 等闭壳层的，带隙平均更高。

所以：只给「元素组成」，模型就能猜到带隙的大致范围。如果特征工程里放了元素比例，得到的 R² 里有一大半是组成贡献，不是结构贡献。

怎么把这两部分分开：

报「固定组成」的误差。比如只测「都是 Zn-MOF」的子集，看模型能不能区分不同配体。
报「固定拓扑」的误差。同拓扑下不同金属的带隙预测。
报告「组成基线」。比如「只按元素比例线性回归」的 MAE，作为最低基线。

一个可用的基线参考：benchmarks.md 给出的 Mean of Dataset = 0.940 eV（直接猜均值）。任何模型如果 MAE 不低于 0.94，就完全没学到东西。这个基线比多数论文里报的「随机基线」有用得多。

§5.4 一个官方给定、必须用的基准

benchmarks.md 给了一套完整的对比（在 v13 的 80% 训练集上）：

方法	测试集 MAE (eV)
Mean of Dataset（猜均值）	0.940
Sine Matrix Eigenspectrum	0.539 ± 0.004
Stoichiometric-45	0.459 ± 0.005
Stoichiometric-120	0.454 ± 0.006
Orbital Field Matrix	0.410 ± 0.004
Average SOAP kernel	0.344 ± 0.004
CGCNN	0.270 ± 0.011

这张表的四层含义：

CGCNN 的 0.270 eV 是标准基线。任何新模型必须打这个数。论文里的 MEGNet 单任务模型在 0.23–0.29 eV，与 CGCNN 同档。
Stoichiometric-45 与 Stoichiometric-120 只差 0.005 eV（0.459 vs 0.454）。这说明「增加组成特征维度」几乎没用——组成信息在 45 维就饱和了。这是一个很有价值的负结果。
SOAP（0.344）明显好于 Orbital Field Matrix（0.410），而 SOAP 是局部环境描述符。说明局部几何比全局场描述子更重要。
所有方法都远好于 0.940，说明带隙确实可从结构预测，但没有一个接近化学精度（通常认 ±0.1 eV）。

特别提醒：这套数字是 v13 上的、随机 80/20 切分。如果你按拓扑切分，所有数字都会显著变差。 引用 0.270 时必须说明切分方式。

§6 AI 就绪指南

§6.1 最小可用 Pipeline

# 阶段 1：取数（Figshare 下载，无需注册）
#   下 qmof_database.zip（v18），解出 qmof.json 与 qmof_structure_data.json

import json, numpy as np, pandas as pd

# 阶段 2：解析属性表
props = json.load(open('qmof.json'))
# props 是一个 dict：{qmof_id: {属性...}}
df = pd.DataFrame.from_dict(props, orient='index')

# 阶段 3：解析结构
structs = json.load(open('qmof_structure_data.json'))

# 阶段 4：必做的三项过滤
df = df[df['synthesized'] == 1]          # 只要实验结构
df = df[df['pld'] > 3.3]                 # 只要可容纳 CO2 的孔
df = df[df['band_gap'].notna()]          # 只要带隙有值（全库都有，但惯例检查）

# 阶段 5：构造图（原子 = 节点，键 = 边）
#   节点特征：原子序数（one-hot 或 embedding）、DDEC6 电荷
#   边特征：距离、DDEC6 键级
#   全局：晶格参数、空间群、n_atoms

这段代码里最需要注意的一点：df['synthesized'] == 1 这一行。不写这一行，你的「MOF 带隙预测模型」的训练集里会混进大量纯计算造出来的结构，而测试集如果是实验结构，指标会不可解释地差。

§6.2 构建训练样本

任务 A：带隙回归（最主流）

输入：结构图（节点=原子，边=键，含距离与键级）
输出：band_gap（PBE）或三档高精度泛函之一
切分：按拓扑分组留出
基线：CGCNN 0.270 eV（v13，随机 80/20）；自行跑一遍 CGCNN 作为对照
注意：低带隙区（<0.5 eV）误差天然大（样本少 + 开壳层多）

任务 B：泛函迁移（QMOF 独有）

输入：PBE 带隙 + 结构
输出：HLE17 / HSE06* / HSE06 带隙
切分：用交集（三档都有值的结构，约 1.07 万）
基线：直接用 PBE 带隙作为预测值（不做任何建模）
为什么这个任务有价值：如果能从便宜的 PBE 准确外推到 HSE06，就省掉巨量算力。论文的多保真度模型做了这件事并且有效。

任务 C：原子电荷预测

输入：结构图
输出：逐原子 DDEC6 电荷
切分：按结构（不能按原子，否则同结构内泄漏）
指标：MAE（单位 e），必须分元素报告（金属位点的误差通常远大于 C/O）

任务 D：synthesized 分类（弱监督）

输入：结构
输出：这个结构像不像真的被合成过
用途：筛选假设结构里的「可合成候选」
注意：这是一个高度有偏的分类任务（正负样本来自不同的源库，不是随机的）

§6.3 评价指标

任务	指标	必须报的对照
带隙回归（A）	MAE (eV)、RMSE	CGCNN 0.270；Mean-of-Dataset 0.940；按 `synthesized` 分组
泛函迁移（B）	ΔMAE（相对「直接用 PBE」的改善）	naive 基线：预测值 = PBE 带隙
电荷预测（C）	逐原子 MAE (e)	分元素报；分「框架原子」与「金属」
可合成分类（D）	AUROC、PR-AUC	必须在按来源分组切分下报

四条纪律：

必须报 CGCNN 0.270。这是一个已经公开、可复现的强基线，不报等于隐藏了真正的难度。
必须报切分方式。0.270 是随机 80/20 的结果，按拓扑切会差很多。
synthesized 分组报。实验结构与假设结构的误差可能差一倍以上。
低带隙子集单独报。论文明确指出低带隙区误差增大，因为训练样本少且开壳层占比高。

§6.4 MLOps：怎么钉版本

QMOF 的版本管理是本库最强的一环，所以 MLOps 也简单：

记录三项即可完全复现：
1. 版本号（如 v18）+ 对应 DOI（…/13147324/18）
2. 切分方式（按拓扑 / 按来源 / 按金属）
3. 是否过滤 synthesized、pld 阈值

为什么不需要存数据快照：每个版本有独立 DOI 且永久归档，不会变。这与 HMD（无版本号，数据随时修订）形成鲜明对比（见本站 rid 1356）。

一个建议：把 updates.md 也存一份。因为如果 v19 删掉了你用的某个结构，你需要知道「是哪一版删的、为什么」。

§6.5 八个真实坑点

坑点 1：synthesized 字段不看，实验与假设结构混在一起

20,372 个结构里，CSD + CoRE + Pyrene 是实验来源（synthesized=1），ToBaCCo / Boyd & Woo / GMOF / Haranczyk 都是纯假设。不筛这一列，模型学到的「材料分布」是虚构的。

坑点 2：formation_energy_per_atom 与 energy_above_hull 全是 NaN

QMOF 不提供这两个量。想做「稳定性筛选」必须转 MP / OQMD。很多论文把 QMOF 和 MP 混用时不提这一点，结果「稳定性」那一步其实是无源的。

坑点 3：total_energy 不可跨库比较

官方第三方文档明写：QMOF 的 total_energy 是「raw PBE-D3(BJ) energy with the settings of QMOF」，不能与 Materials Project 或 LeMat-Bulk 的能量比，也没有凸包。拿它去算形成能会得到无意义的值。

坑点 4：Bader 电荷只有约 3,000 条，不是全库

updates.md v3 的原文「Added CM5 partial charges for every structure and 3000+ Bader charges」。「every」只修饰 CM5。 如果你的流水线默认「三种电荷都有」，会在 Bader 上遇到大面积缺失。

坑点 5：pld / lcd 是弛豫前算的

见 §2.7。用发布几何重算会得到不同值。做孔径阈值筛选时用库里的列，不要重算。

坑点 6：tobacco 前缀对应两个 source 值

ToBaCCo（Cu 三角）与 Anderson（Zr/Hf）名称里都有 tobacco。按名称筛会把两类混在一起，必须用 source 字段。

坑点 7：NOMAD 条目数多于官方库

官方文档明言「there may be more entries on NOMAD than in the MOF Explorer」，因为移除的结构无法从 NOMAD 删除。按 NOMAD 计数会高估实际结构数；做「全库统计」必须用 Figshare 的 JSON。

坑点 8：v11 的 bandgaps.csv 不向后兼容

updates.md 原文：「Same changes as in v12, but the bandgaps.csv file was not made backwards-compatible here」。读过 v10 的脚本在 v11 上会静默出错。 建议：读 qmof.json 而不是读 bandgaps.csv。

§7 质量评估、口径交叉核对

§7.1 记录级质量

QMOF 的质量控制有一份异常详细的公开日志，但它的质量控制结果不逐条公开：

层	机制	可查性
结构筛选	去溶剂、补缺失原子、StructureMatcher 去重	做了什么可查（`updates.md`），阈值与规则不可查
计算一致性	同一套 VASP 参数（除 186 个 EDIFF 错设的，已修）	参数在 NOMAD 上可查
结果校验	未见专门的校验报告	不可查
版本治理	逐版记录、逐版 DOI、`poor_fidelity.txt` 预告	完全可查，是本库最强项

「做了什么可查、怎么做的不可查」这一点值得展开：updates.md 告诉你 v9「Fixed 186 structures that had EDIFF = 1e-4 instead of EDIFF = 1e-6」——你知道问题是什么、影响了多少条、改成了什么值。但你不知道自动化筛选的完整规则（比如「缺失 H 原子」的判定阈值是什么、StructureMatcher 的容差设多少）。这意味着你无法自己复现「从 CoRE 到 QMOF 的清洗过程」。

§7.2 抽样声明：本条目数字的边界

数字	来源	边界
20,372 结构	第三方重打包 README（宣称逐结构与原库比对过 MD5）	非官方直出，但比对方法可查
2,312,743 原子	同上	同上
79 种元素（H 至 Pu）	同上	Pu 的原子序数是 94，H 是 1，中间有 15 个元素缺席
10,756 / 10,811 / 10,810	同上	三档差异（1–2 条）来源不明，可能是 NaN 处理差异
170+ CPU 年	中文技术社区转述（Matter 论文口径）	未在论文正文核实，标注为「据称」
8,628 / 2,092	npj Comput Mater 2022 正文与图 2 说明	合计 10,720，与「三档带隙约 1.07 万」差几十条
0.90 / 2.93 / 0.86 / 3.21 eV 双峰	npj Comput Mater 2022 正文	精确
0.05 / 0.10 eV per % HF	npj Comput Mater 2022 正文	精确，且论文声明「specific to the QMOF Database」
CGCNN 0.270 ± 0.011	`benchmarks.md`	v13、随机 80/20 切分

一个必须指出的口径差：闭壳层 8,628 + 开壳层 2,092 = 10,720，而三档带隙的覆盖是 10,756 / 10,811 / 10,810。这三个数都不等于 10,720。 可能的解释：①论文的 10,720 是「四种泛函都有值」的严格交集，而各档单独计数更多；②第三方重打包时 NaN 判定不同。

我们的处理：同时报，不强行统一。 引用「做泛函对比可用的交集」时说约 1.07 万，引用论文的闭/开壳层拆分时说 10,720。

§7.3 三个必须知道的效度问题

效度一：synthesized 的分布本身是偏的

实验来源（CSD + CoRE）与假设来源（ToBaCCo / Boyd & Woo / GMOF）在化学空间上的覆盖不同：CSD 偏「已被研究过的、容易合成的」，Boyd & Woo 偏「理论上可行但没见过的大规模枚举」。两者的带隙分布、孔径分布、金属分布都不同。

后果：任何「全库统计」都是两个分布混合的结果，而混合比例不代表任何真实的材料总体。正确表述：「在 QMOF 的 20,372 个结构中……」而非「在 MOF 这一类材料中……」。

效度二：泛函子集的选择不是随机的

10,720 个「四档全算」的结构，闭壳层 8,628 / 开壳层 2,092。这 2,092 个开壳层是怎么选的，文档没有说明。 如果是为了「覆盖代表性金属」而刻意选的，那这个子集在化学空间上可能偏向某些金属；如果是随机的，比例应与全库一致。我们无法核实。

效度三：全部结果依赖 VASP 5.4.4

不同版本的 VASP、不同的 PAW 势、不同的默认参数会给出不同的带隙。QMOF 的结果绑定在「VASP 5.4.4 + 特定 PAW 势 + 特定 INCAR」这一组合上。 想复现必须用同一套环境；想比较必须说明环境。

一个具体的例子：§2.3 提到的 LMAXMIX 问题——一个 VASP 内部参数设置不够高，就导致 v12 的 NSCF 结果不可用。这不是 VASP 的 bug，是「DFT 计算的正确性依赖大量默认参数」的现实。

§7.4 偏倚清单（可核查）

偏倚	方向	怎么核查
合成偏倚	CSD 来源偏「已被研究的」热门 MOF	数各 `source` 的条数；看金属分布是否集中在少数几种
假设结构偏倚	Boyd & Woo 等是算法枚举，偏「规则化、理想化」	对比实验与假设子集的空间群分布、n_atoms 分布
泛函子集偏倚	10,720 的选择规则未公开	无法核查
金属偏倚	开壳层集中 Cu/Co/Mn/Ni/Fe/V/Cr	数开壳层子集的金属频次
原子数偏倚	上限 500，且「十分之一的结构超过 200 原子」	看 n_atoms 直方图
Bader 覆盖偏倚	只有 3,000+ 条	对比这 3,000 条与全库的元素分布
带隙定义偏倚	开壳层用跨自旋 min/max	用 CBM/VBM 分列值可自己重算同自旋定义

§7.5 数据完整性核查表

拿到数据后必做的八项检查：

#	检查	期望	不符说明什么
1	结构数	20,372（v18）	数字不符说明版本不对
2	原子总数	2,312,743	同上
3	`n_atoms` 范围	17 – 500	出现 >500 说明解析错或版本更早
4	元素最大值	94（Pu）	出现 >94 说明数据损坏
5	`synthesized` 取值	只有 0 与 1	出现其他值说明字段含义变了
6	`source` 取值数	9 个	少于 9 说明某来源被合并或删空
7	`band_gap` 缺失数	0（全库有值）	有缺失说明版本不对
8	`formation_energy_per_atom`	全为 NaN	若某些行有值，说明混进了别的库

第 8 项是最有效的「数据源自检」：QMOF 从不提供 formation energy。如果 DataFrame 里这一列有非 NaN 值，说明你把 QMOF 和 Materials Project 的数据拼在一起了。

§7.6 DAIMS 24 项逐项评分

#	维度	分	说明
1	数据集标识	1.0	名称、作者、DOI 清晰
2	版本标识	1.0	18 个版本，每版独立 DOI；`updates.md` 逐条记录。本库最强项
3	许可明确性	1.0	CC BY 4.0，写在 README 与文档两处
4	出处可溯	1.0	9 个来源库逐一点名，附 DOI 与链接
5	采集方法描述	0.5	泛函、软件、版本公开；ENCUT / k 点 / EDIFF 在 SI 里，正文未列
6	处理链可复现	0.5	VASP 是商业软件；清洗规则部分公开
7	数据模型	1.0	结构 + 属性，键明确
8	字段字典	0.5	无集中字段字典；字段靠第三方 README 与论文散落描述
9	单位与量纲	1.0	eV / Å / μB / g·cm⁻³，标注清楚
10	缺失值语义	1.0	NaN 含义明确（未计算）；有专门说明
11	数据量级	0.5	无官方总体积；本条目无法给出
12	覆盖范围声明	1.0	结构数、原子数、元素范围都给了
13	抽样方法	0.5	结构来源是筛选而非抽样，但筛选规则未完全公开
14	偏倚讨论	0.5	论文讨论了泛函偏差，但未系统讨论样本偏倚
15	质量控制	1.0	`updates.md` 逐版记录问题与修复；`poor_fidelity.txt` 预告；罕见的高透明度
16	已知问题清单	1.0	FAQ（虽只有一条但极关键）、`poor_fidelity.txt`
17	更新政策	1.0	版本化 + 逐版说明
18	访问方式	1.0	Figshare 直下，无需注册；另有 NOMAD / MPContribs API
19	访问门槛	0.5	数据无门槛，但初始结构与 VASP 文件需 CSD 许可
20	格式规范	1.0	JSON + CSV + XLSX + CIF + XYZ，标准格式
21	可机读性	1.0	JSON 直读；另有 HDF5 重打包
22	文档完整性	1.0	五个 md 文件（README / updates / data_sources / benchmarks / mofid_search）+ 两篇论文
23	引用规范	1.0	明确要求「20k+ 结构时两篇都引」；Thermo 库另有一篇
24	社区与支持	1.0	GitHub Issues；有 Twitter 账号；作者直接回邮件

总分：20.5 / 24 = 85.4%

这是本站目前已评分条目里的最高分之一。 得分高的原因集中在两点：版本治理（2、17）做到了教科书级，质量控制透明度（15）罕见——主动公告「下一版要删哪些结构」这种事，多数数据库不会做。

扣分集中在工程侧（5、6、8、11）：参数散落在 SI、无集中字段字典、无官方总体积。这些是学术项目的通病，不影响数据本身质量。

§7.7 口径交叉核对矩阵（不是模型性能验证）

核对项	来源 A	来源 B	差异解释
结构数	GitHub README「20,000+」	第三方重打包「20,372」	README 是概数，以重打包的精确数为准
原子总数	仅有第三方	—	单一来源，标注为待官方确认
元素范围	第三方「79，H 至 Pu」	结构文件中原子序数最大值	一致（Pu = 94）✓
闭/开壳层	论文 8,628 / 2,092（=10,720）	三档带隙覆盖 10,756 / 10,811 / 10,810	不相等，见 §7.2
带隙双峰	论文 PBE 0.90 / 2.93 eV	中文社区转述「0.9 / 2.9」	一致（四舍五入）✓
CGCNN 基线	`benchmarks.md` 0.270 ± 0.011	—	单一来源，明确标注 v13、80/20
算力	中文社区「170 CPU 年」	论文正文未核到	标注为「据称」
版本数	`updates.md` 18 条（v1–v18）	Figshare 版本历史 18 个	一致 ✓
最新版日期	`updates.md` v18	Figshare「v18 2025-11-15」	一致 ✓
许可	README「CC BY 4.0」	Figshare 页面标注	一致 ✓

一个值得注意的细节：中文技术社区那篇转述里有几个数与本条目不同——它说「14,000+ 实验合成 MOF」「从 CoRE 筛选 42,349 个、剔除后保留 14,482 个」。这些数字与 v18 的 20,372 不符，可能对应 v5 时期（Matter 论文发表时）的口径。这说明「QMOF 有多少个结构」这个问题，答案取决于你问的是哪个版本。

§8 生态位与相邻资源

§8.1 QMOF 在网络里的位置

上游原料库                      QMOF                     下游分发/镜像
─────────────                ──────────                ──────────────
CSD MOF Subset  ─┐                                    ┌─ Figshare（主）
CoRE MOF 2019   ─┤                                    ├─ NOMAD（VASP 文件）
Pyrene MOFs     ─┤                                    ├─ Globus（电荷密度）
ToBaCCo         ─┼──→  20,372 结构 + 4 档 DFT 属性  ──┼─ MPContribs（MP 镜像）
Boyd & Woo      ─┤                                    └─ Hugging Face（HDF5 重打包）
GMOF            ─┤
Haranczyk       ─┘

这张图最该注意的一条：QMOF 既是「下游」（消费 CSD/CoRE 的结构），又是「上游」（被 Materials Project 的 MOF Explorer 消费）。 这种「中间层」位置决定了两件事：

它的结构质量继承自上游。CSD 的问题是 CSD 的，CoRE 的问题是 CoRE 的。QMOF 只做了「去溶剂 + 补原子 + 去重」这一层清洗。
它的属性质量决定了 MP 的 MOF 部分。MP 的 MOF Explorer 页面上的带隙、电荷，直接来自 QMOF。

§8.2 与本站已收条目的关系

本站条目	rid	与 QMOF 的关系
QM9	库内	分子（13 万小分子），QMOF 是晶体。对象不同
PCQM4Mv2	374	分子，374 万；QMOF 只有 2 万但每结构原子数大得多
GEOM	1078	分子构象；QMOF 无构象集（官方明言无轨迹）
MD17	最新收录	分子轨迹；QMOF 无轨迹。两者刚好互补缺的那一半
Tox21（93）	93	化合物体外毒性筛选，分子级；QMOF 是材料级电子结构
ToxCast（194）	194	同上
CompTox（1125）	1125	137 万化学品的毒理与性质，分子级
CPIC（1351）	1351	药物基因组，与材料无关

一个重要的观察：本站已收的化学类条目几乎全是「分子」，没有一个「周期性晶体」。 QMOF 补的正是这个形态级空缺——不是「又一个化学数据集」，而是「第一次把晶体材料纳进来」。这个空缺的另一半（无机晶体）由 Materials Project 一系覆盖，目前库内也还没有。

与本条构成最佳互补的三条：QM9（分子小）→ GEOM/PCQM4Mv2（分子多）→ QMOF（晶体），从分子到晶体的完整阶梯。而 MD17（分子轨迹） 与 QMOF（无轨迹）正好展示了「有轨迹」与「无轨迹」的差别。

§8.3 为什么一个「医学数据集站」要收它

三个理由：

第一，药物与材料在方法上是同一套。 本站大量条目是「分子图 → 性质」的预测任务（毒性、活性、溶解度）。QMOF 是「晶体图 → 性质」的同一范式，而且它的规模与属性完备度让它成为学习「图神经网络怎么处理周期边界」的最佳教材。周期性是分子数据集永远教不了的东西。

第二，它的泛函对照实验是「模型选择」的范本。 「同一批数据，换一个计算设置，结论翻转」——这件事在医学 AI 里同样存在（换标注标准、换测量设备、换医院）。QMOF 用 20,372 个结构和四种泛函把这件事量化了：双峰变单峰、每 1% 参数换 0.05–0.10 eV 的位移。这是一个可以在方法论课上直接用的案例。

第三，它的版本治理值得抄。 18 个版本、每版独立 DOI、逐版说明改了什么、提前公告要删什么。本站收录的 1300+ 条目里，版本治理做到这个程度的不超过五指之数。 对一个做数据集百科的站点来说，这份日志本身就是值得研究的一手材料。

§9 许可、伦理与合规

§9.1 许可：极简的一层

QMOF 的许可只有一句话（README.md「Licensing」段）：

The data underlying the QMOF Database is made publicly available under a CC BY 4.0 license. This means you can copy it, share it, adapt it, and do whatever you like with it provided that you give appropriate credit and indicate any changes.

没有第二层，没有「输入数据另归其主」，没有商用禁令。 这与本站刚收录的 HMD（自产 CC BY，Input Data 禁止商用）形成鲜明对比。

用途	允许？
商用训练	可以
再分发	可以
修改后发布	可以（需说明改动）
用于专利	可以
只需署名	是

唯一的条件是：give appropriate credit + indicate any changes。这比大多数「开放」数据集更彻底。

代码的许可是另一回事：GitHub 仓库标注 MIT（代码），与数据的 CC BY 4.0 分开。用它的脚本做工具是 MIT，用它的数据是 CC BY。

§9.2 但有一个隐性限制：CSD 的初始结构

QMOF 发布的是「DFT 优化后的结构」，不是「CSD 的原始结构」。 data_sources.md 原文：

Note: Only DFT-optimized structures are made available (no trajectories or initial structures). If you wish to obtain the initial structures, you must have an active CSD license and use the CCDC’s ConQuest program.

这句话的合规含义：

QMOF 的优化后结构是 QMOF 团队的工作产物，可 CC BY 4.0 发布。这部分没问题。
但「还原到 CSD 原始结构」需要 CSD 许可。如果你要做「优化前后对比」研究，你必须自己买 CSD 许可。
CoRE MOF 的结构来自 CoRE，CoRE 本身有自己的许可（Zenodo 上公开）。这一支通常不构成障碍。

这是一个典型的「衍生数据可开放、原始数据受限于第三方」的结构，与 HMD 的两层许可同构，只是 QMOF 把衍生部分做得更彻底（连初始结构都不发布，彻底规避了风险）。

§9.3 引用要求：两篇，有条件

README.md 原文：

If you use the QMOF Database, please refer to the following publications. Both should be cited if you are using the dataset with 20k+ structures.

情况	引哪篇
用 20k+ 结构（v6 之后的库）	两篇都引
用更早的小库	只引 Matter 2021
用 QMOF-Thermo（v18 新增）	另引 JACS 2026 那篇

两篇文献：

A.S. Rosen, S.M. Iyer, D. Ray, Z. Yao, A. Aspuru-Guzik, L. Gagliardi, J.M. Notestein, R.Q. Snurr. Machine Learning the Quantum-Chemical Properties of Metal–Organic Frameworks for Accelerated Materials Discovery, Matter 4, 1578–1597 (2021). DOI: 10.1016/j.matt.2021.02.015
A.S. Rosen, V. Fung, P. Huck, C.T. O’Donnell, M.K. Horton, D.G. Truhlar, K.A. Persson, J.M. Notestein, R.Q. Snurr. High-Throughput Predictions of Metal–Organic Framework Electronic Properties: Theoretical Challenges, Graph Neural Networks, and Data Exploration, npj Comput. Mater. 8, 195 (2022). DOI: 10.1038/s41524-022-00796-6

一个细节差异：README.md 写「8, 112 (2022)」，而 Figshare 页面写「8, 195 (2022)」。卷号 8 一致，文章号不一致（112 vs 195）。 我们查到 Nature 官网的 URL 是 s41524-022-00796-6，Springer 页面标注为 Article 112。以 DOI 为准，文章号差异可能是 Figshare 页面的笔误。

Thermo 库的引用：
B. Dallmann, A. Saha, A.S. Rosen. Predicting the Thermodynamic Limits of Metal–Organic Framework Metastability, J. Am. Chem. Soc. 148, 19 (2026). DOI: 10.1021/jacs.5c20253

§9.4 伦理与安全

伦理层面没有争议：QMOF 是计算材料数据，不含任何生物个体、人体样本或个人信息。

但有一个「双用途」角度值得提一句：MOF 的应用之一是气体分离与储存，包括有毒气体吸附与爆炸物检测。库里有孔径（pld/lcd）与电子结构，理论上可用于筛选特定气体吸附材料。这是公开的科学数据，不属于需要管控的范畴，但做数据站的合规说明时应知道这一层。

另一个角度是「环境与健康」：MOF 里含大量过渡金属与稀土（79 种元素到 Pu）。做「可合成性」筛选时，毒性金属的使用是一个现实约束，但 QMOF 不提供毒性数据——需转 Tox21 / ToxCast / CompTox（本站 rid 93 / 194 / 1125）。

§9.5 数据保护与隐私

完全不适用。QMOF 是材料数据，无个人信息、无患者数据、无人体样本。

唯一与「保护」沾边的是 CSD 的商业许可机制（见 §9.2）：CSD 是商业数据库，其原始结构不能自由再分发。QMOF 通过「只发布优化后结构」的方式规避了这个问题。这是一个值得学习的合规设计：不是「取得许可后开放」，而是「只开放自己加工出来的那一层」。

§10 一页速查与三条硬结论

10.1 一页速查卡

你要做的事	直接这么做
拿 MOF 带隙做预测	下 Figshare 主归档，读 `qmof.json` 的 `band_gap`
只要真实材料	`synthesized == 1`（CSD + CoRE + Pyrene）
要可容纳 CO2 的孔	`pld > 3.3`（用库里的列，别重算）
做泛函对比	取三档都有值的交集（约 1.07 万）
要原子电荷	用 `ddec6_charges`（覆盖最全）；Bader 只有约 3,000 条
要稳定性 / 形成能	QMOF 没有，转 Materials Project / OQMD
要轨迹或初始结构	QMOF 没有；初始结构需 CSD 许可 + ConQuest
要 VASP 文件	NOMAD 四套 DOI，按 `external_id` 查
要按材料名跨库找	用 `mofkey`（如 MOF-5 = `Zn.KKEYFWRCBNTPAC.MOFkey-v1.pcu`）
报指标	必须给 CGCNN 0.270 eV 与 Mean 0.940 eV 两个基线
商用	可以，CC BY 4.0，署名即可

10.2 三条硬结论

结论一：QMOF 最不可替代的不是「2 万个结构」，是「同一批结构、四种泛函」。

规模上 2 万不算大——hMOF 有 13.9 万，Alexandria 有 500 万。但只有 QMOF 把 PBE / HLE17 / HSE06* / HSE06 四档结果并排放在同一批结构上，让你能直接看到「换个泛函，双峰变单峰」。 这组对照的价值远大于多几万个结构——因为它回答的是「你的结论有多依赖计算设置」，而不是「你能算多少材料」。

结论二：这个库最该先看的一列是 synthesized。

20,372 个结构里混着「真的被合成过的」与「算法造出来从没合成过的」。这两类的分布不同，混在一起训练会得到一个不存在的「材料总体」。 而这一列在 v9 才加入（updates.md 明确记「Added ‘synthesized?’ flag」），说明早期使用者根本不知道有这个区分。这是本库最容易被踩、后果最隐蔽的一个坑。

结论三：它的版本治理值得作为模板抄。

18 个版本、每版独立 DOI、逐版说明改了什么、提前公告下版删什么、benchmarks.md 明确标注「在 v13 上做的」。这四件事凑齐，才叫「可复现」。 对比本站刚收录的 HMD（无版本号，只能靠下载日期）——同样是顶级数据库，版本治理的差距可以有这么大。

附录 A：九个来源与命名规则（原样整理）

`source`	名称特征	`synthesized`	说明
`CSD`	以 `_FSR` 结尾	1	CSD MOF Subset，去游离溶剂
`CoRE`	以 `core` 开头	1	CoRE MOF 2019 FSR
`Pyrene`	含 `pyrene`	1	含芘 MOF（Smit 组）
`ToBaCCo`	含 `tobacco`	0	Cu 三角 MOF
`Anderson`	含 `tobacco` 且含 `_SR_`	0	Zr/Hf MOF
`BoydWoo`	含 `boydwoo`	0	Boyd & Woo 假设库（经 QMOF 改造）
`GMOF`	含 `gmof`	0	Genomic MOF
`Haranczyk_MOF5`	含 `MOF-5`	0	假设 MOF-5 类似物
`Haranczyk_MOF74`	含 `mof74`	0	假设 MOF-74 类似物

附录 B：ML 基准表（`benchmarks.md` 原样，v13，80/20 切分）

方法	MAE (eV)
Mean of Dataset	0.940
Sine Matrix Eigenspectrum	0.539 ± 0.004
Stoichiometric-45	0.459 ± 0.005
Stoichiometric-120	0.454 ± 0.006
Orbital Field Matrix	0.410 ± 0.004
Average SOAP kernel	0.344 ± 0.004
CGCNN	0.270 ± 0.011

另：npj Comput Mater 2022 的 MEGNet 结果（10,720 结构子集）

模型	测试集 MAE
MEGNet 单任务（各泛函独立）	0.23 – 0.29 eV
其中 HSE06 单模型（最差）	0.29 eV
多任务学习（同时预测 4 种泛函）	略优（「perceptible but minor」）
多保真度模型（3–4 fidelity）	显著更低；最多 52,806 样本

附录 C：核对清单（拿到数据后按顺序跑）

□ 1. 确认版本号，记下 DOI 后缀（如 /18）
□ 2. 检查结构数 = 20,372（v18）
□ 3. 检查原子总数 = 2,312,743
□ 4. 检查 n_atoms 范围 = 17..500
□ 5. 检查原子序数最大值 = 94
□ 6. 检查 synthesized 只有 {0,1}
□ 7. 检查 source 有 9 个取值
□ 8. 检查 formation_energy_per_atom 全为 NaN   ← 若非全 NaN，说明混了别的库
□ 9. 检查 band_gap 无缺失（全库有值）
□ 10. 检查三档高精度带隙的覆盖数（约 1.07 万）
□ 11. 若做孔径筛选，用库内 pld/lcd，不要重算
□ 12. 若做电荷任务，确认用 DDEC6 且不与 Bader 混
□ 13. 若报指标，给出 CGCNN 0.270 与 Mean 0.940 两个基线
□ 14. 若按拓扑切分，说明与随机切分的差异