← 交互预演 Markdown 原稿(课程仓库,需权限) · 样本索引

MatterGen 怎样读入、生成和写回一块晶体?

对 MatterGen 而言,一块周期性晶体可以用三组数描述:每个站点放什么元素、站点在晶胞内的相对位置,以及晶胞的三条边向量。一次生成先确定位点数,再反复更新这三组数。神经网络在每次更新时看见的是当前带噪的晶体,最终交给材料组的是一个可以独立计算的结构文件。论文图 1 与方法 · 固定版本 base 配置

本说明对应项目固定的微软官方代码 92423660a8bd70e83679086e88f88596d484dc16。以真实生成的三原子 Cu₂Pd 为例,同一个候选分别沿两条路径追踪:从 CIF 重新读入可检查网络的输入,从生成器导出的原始文件可检查交给队友的坐标。另用本地 base 权重做了一次单步前向核对。条件生成部分解释官方实现,原有 8 个 CUDA base 样本均为无性质条件生成。模型配置 · Cu₂Pd 运行记录(课程仓库,需权限)

1. 两种入口:从已有 CIF 学习,从随机状态生成

训练或检查已有结构。 官方 CSV 转换器解析每条记录的 CIF,读取元素、分数坐标与晶格,关联 material_id 和支持的性质列;随后取原胞,作 Niggli 晶胞约化并缓存数组。数据集把分数坐标取模 1,把晶格与位置转为 float32。base 的数据变换再对晶格作极分解,保留等价的对称矩阵。若原来的行向量晶格为 LL,该矩阵是 (LL𝖳)1/2(L L^\mathsf{T})^{1/2},保留晶胞的边长、夹角和体积。由此,CIF 和网络中的同一个结构可以有不同的坐标数字。化学体系字符串可从元素集生成,空间群标签在读取时可由符号转编号。CIF 与缓存 · 数据变换 · 极分解实现

无条件生成。 官方 loader 根据 ALEX_MP_20 经验分布先抽取每个晶胞的站点数 nn,构造相应大小的占位张量;采样器再用三个扩散过程的先验值填入元素、坐标与晶胞。nn 在一次生成内保持固定。seed48 最终有 3 个站点,模型要逐步决定这些站点的元素和位置。该运行没有以某个 Cu₂Pd CIF 作为起点。站点数 loader · 占位样本与采样分布 · 先验初始化

输入张量是什么?

令 BB 为晶胞数,N=∑bnbN=\sum_b n_b 为一个批次的总站点数。数据按站点拼接,每个晶胞可以有不同的 nbn_b。ChemGraph 定义 · PyG 批处理

批处理字段 形状与类型 值的含义
atomic_numbers [N][N],整数,常规路径为 int64 干净样本存一基原子序数,如 Cu=29、Pd=46。带噪输入还可取 101,表示待确定的元素。
pos [N,3][N,3],float32 无量纲分数坐标 FF,按三个方向取模 1,等价位置相差整数平移。
cell [B,3,3][B,3,3],float32 三行分别是晶格向量,单位 Å。单个样本保留前导维 [1,3,3][1,3,3]。
num_atoms [B][B],整数 每个晶胞的站点数。单图还设置 PyG 的 num_nodes 以便批处理。
batch、ptr [N][N]、[B+1][B+1],int64 站点到晶胞的归属和切片边界。若两晶胞各有 3、2 个站点,归属为 [0,0,0,1,1][0,0,0,1,1],边界为 [0,3,5][0,3,5]。
t [B][B],浮点 每个晶胞本次前向计算的扩散噪声时刻,由调用者单独传入模型。默认反向采样在 1 到 0.001 之间取 1000 个时刻。
性质与标识 按晶胞 选定的标量性质可成为批次张量,化学体系可成为字符串列表。原始 material_id 存在数组缓存,课程项目的 candidate_id 来自交接清单;两者用于追踪来源。base 的两个性质嵌入字典均为空。

原胞中每个站点的笛卡尔坐标为 ri=fiLr_i=f_i L。例如 f=(0.99,0.2,0.5)f=(0.99,0.2,0.5) 与 (1.01,0.2,0.5)(1.01,0.2,0.5) 相差第一条晶格向量的 2%,后者折回晶胞后第一分量是 0.01。这解释了为什么动画中一个站点经过晶胞表面时可以出现在另一面。网络保留周期性,但交接包的 frames[].positions 已是以 Å 为单位的笛卡尔坐标,读入前端时可直接画。坐标换算 · 网页数据接口(课程仓库,需权限)

2. 为什么三组数使用不同的加噪方式?

变量 训练时怎样破坏干净样本 无条件生成从什么状态开始
元素 AA D3PM 对每个站点的元素标签做离散掩码。网络学习从带噪晶体预测干净标签分布。 从吸收态 MASK 开始。内部类别索引为 0–100,外部元素编号偏移 1,故内部 100 对应文件中的 101。官方 CLI 的采样白名单共有 76 个实际元素。
分数坐标 FF Wrapped VE 在三个分数维度加高斯噪声,再取模 1。标准差为 0.01(5/0.01)tn−1/30.01(5/0.01)^t n^{-1/3},按晶胞站点数调整,可减弱不同晶胞尺度对位置扰动的影响。 采样高方差高斯并按 n−1/3n^{-1/3} 缩放后取模,得到分布在周期晶胞中的起始站点。
行向量晶格 LL 对称矩阵上的 VP 扩散。随着噪声增大,其均值趋于 (n/ρ)1/3I(n/\rho)^{1/3}I,其中 ρ=0.0577145\rho=0.0577145 个站点/ų。非对角项成对加噪以保持对称。 极限分布围绕这个立方晶胞取样,各矩阵分量的极限方差为 0.25n2/30.25n^{2/3},得到有大小与形状波动的初始晶胞。

给定同一个干净晶体和 tt,前向过程分别扰动这三个字段。反向时一个共享网络看见所有字段,当前位置及近邻格局会影响元素预测,元素和晶格又会影响下一次建图。训练目标包含元素 D3PM 损失、周期位置的去噪目标与晶格的去噪目标。base 的字段权重依次为元素 1、位置 0.1、晶格 1。多字段扰动 · 晶体专用扩散 · 训练目标 · base 超参数

3. 一次去噪前向在 GemNet-T 里发生了什么?

  1. 从当前晶体建邻居图。 先由 R=FLR=FL 得到站点,再搜索周期近邻。考虑整数像平移 kk 后,从站点 ii 看站点 jj 的位移可写成 (fj+k−fi)L(f_j+k-f_i)L。边存源和目标索引 edge_index[2,E],以及对应的晶胞像偏移 to_jimages[E,3]。base 的半径是 7 Å,构图时近邻数阈值为 50,各方向搜索的平移级数上限为 5。网络进一步整理成正反向配对的边,同一对原子编号可能因周期像不同而出现多次。周期构图 · 近邻筛选与边对称化
  2. 把元素和时刻变成节点特征。 元素通过可学习查表得到 512 维向量,查表索引是 Z-1,MASK 也有自己的嵌入。每个晶胞的 tt 经 256 对不同频率的正弦与余弦编码为 512 维。广播到各站点后,两个向量拼接为 1024 维,经线性层得到 512 维节点特征 hih_i。同一晶胞的所有节点接收相同的时间编码。时间编码 · 节点嵌入 · 去噪器入口
  3. 给边加入距离、方向和角度。 边长按 7 Å 缩放,用 128 个高斯径向基与平滑截断包络编码,结合两端节点特征得到 512 维边特征 mjim_{ji}。边方向与三个晶格向量的夹角余弦也进入边嵌入。对共享中心 aa 的两条不同边 b→a←cb\to a\leftarrow c,再计算两方向的夹角。默认使用 7 个角向基函数,与径向基一起调制三元组消息。即使只有三个原胞内站点,周期像仍可提供多条边和多个夹角。基函数和三元组 · 角基函数实现
  4. 用四个交互块交换信息。 每个块从三元组聚合方向相关的边信息,更新边,再按目标站点汇聚信号更新节点,更新后的节点也反馈到边。模型据此区分“距离相似、周围夹角不同”的环境。进入第一个交互块前及每个块后均有读出,位置与晶格分支会累加这些层的贡献。交互块 · 顺序与读出

输出头与采样器怎样配合?

字段 形状 怎样影响下一次更新
元素 [N,101][N,101] logits 最后一层的 512 维节点特征通过线性层,为每个站点给出干净标签分数。CLI 对不允许的元素类别施加 logit 屏蔽。默认 predict_x0=True 的 D3PM predictor 将预测的干净标签概率和当前 AtA_t 结合,构建上一个时刻的类别分布并抽样。
位置 [N,3][N,3] 每条有向边得到一个标量,乘以边的笛卡尔单位方向,累加到目标站点,得到三维输出。代码以列向量写成 $L^{-\mathsf T}v_{\rm cart}$ 转到分数坐标分支。该输出对应训练定义的 score_times_std,采样前除以当前边际标准差得到 score。
晶格 [B,3,3][B,3,3] 边标量乘以方向外积 uu𝖳uu^\mathsf{T},按晶胞聚合并作边数归一化,各层贡献相加形成对称输出。该分支同样按标准差换算为采样用的 score。
骨干辅助输出 [B,1][B,1] GemNet-T 还会聚合名为 energy 的标量。外层去噪器只取 node_embeddings、forces 和 stress 构造上述三个预测。生成训练赋予后两项位置、晶格去噪语义。要给项目报告填入物理能量、原子力或应力,需要另用 MLIP 或第一性原理计算。

这里的 score 指带噪数据对数密度对相应变量的梯度。采样器使用学到的方向和本步噪声尺度更新状态。默认每个时刻先用一次 Langevin corrector 修正位置和晶格,再由三个 predictor 更新元素、位置和晶格。两次更新前各保存一条当前状态,所以 1000 个时刻对应 2000 条记录。课程轨迹导出器从中保留 120 条作为显示帧。原始 extxyz 没有单列每帧的时刻或阶段,网页用原始记录索引标注进度。输出转换 · 晶格方向外积 · 分数缩放 · 离散反向步 · 更新顺序 · 采样参数

4. 如何把一个要求送进模型?

例如希望候选属于 Li–O 化学体系且目标凸包上方能量为 0.05 eV/atom。官方示例选用 chemical_system_energy_above_hull 联合条件权重,同一批样本携带两个结构级字段 chemical_system="Li-O" 与 energy_above_hull=0.05。生成器先检查权重支持的字段。这条路径可以用化学体系、空间群编号或有标注的标量性质控制生成方向,字段由所选择的模型定义。联合条件权重配置 · 官方生成示例 · 权重模型卡

条件 输入及编码方式 输出可以检验什么
化学体系 元素名串拆为集合,构造长度 101 的 multi-hot 向量,索引取元素原子序数;Li–O 的索引 3、8 置 1。再通过可学习线性层变成 512 维。 对官方 CLI 的条件分支,允许集合以外的元素 logits 加上约 −1010-10^{10} 的屏蔽。该操作限制可选集合,但两个元素是否都出现、出现几次,仍需读取最终化学式。
空间群 输入 1–230 的国际空间群编号,减 1 后查 230×512230\times512 的可学习表。 生成后的空间群应在给定容差下用对称性分析复核。嵌入本身没有把坐标投影到特定空间群的 Wyckoff 位置。
连续性质 如能带间隙、凸包上方能量,使用训练统计量标准化,再做 512 维正弦/余弦编码。官方 ml_bulk_modulus 权重对体模量先取 log⁡10\log_{10} 再标准化。 标量是请求值。要得到样本的偏差,须独立预测或计算实现值,并报告单位和参考方法。
固定化学计量(CSP 路径) 由各元素的整数个数直接构造固定的 atomic_numbers 列表,使用只扩散位置与晶格的 CSP 模型和采样配置。例如 Cu:2、Pd:1 给定三个站点及各自元素。 该路径固定各元素的数目。官方生成器会检查模型的元素去噪损失权重与离散扰动配置,通常用于自由元素生成的 mattergen_base 无法直接接受这个固定计量入口。

以上编码可分别在化学体系适配器、标量适配器和 CSP 配置中核对。性质编码器 · 体模量权重配置 · 固定组成的模型兼容性检查 · CSP 采样配置

条件如何进入主干。 条件权重使用 GemNetTAdapter 和 GemNetTCtrl。每个新增条件有独立的小网络,在四个交互块的入口,把该条件向量广播给所属晶胞的站点,与当前 hih_i 拼接;经 1024→512→5121024\to512\to512 的 MLP,再经零初始化的线性混合层,最后残差加回 hih_i。多个条件的增量相加。训练可丢弃条件,让网络也学会无条件分支;运行时未启用的条件在 adapter 路径贡献为零。是否冻结预训练参数由 full_finetuning 配置决定,固定版本的默认值为 true,即允许更新原模型参数。性质编码 · 逐层注入 · adapter 的无条件分支 · 微调程序 · 微调默认值

引导强度如何改变采样。 在同一个带噪状态上,分别计算有条件与无条件的输出,官方实现按 sγ=su+γ(sc−su)s_\gamma=s_u+\gamma(s_c-s_u) 合并。γ=0\gamma=0 只走无条件分支,γ=1\gamma=1 只走条件分支,γ=2\gamma=2 对差异作线性外推。连续变量混合 score,元素分支混合 logits 后再做离散反向步。上表的化学体系屏蔽仅在带条件的推理分支启用;标准正向引导能强烈排除体系外元素,显式设置 γ=0\gamma=0 则跳过该分支。能量等标量条件采取学习式引导,每个候选的独立计算结果才是检验条件响应的观测值。CFG 混合实现 · CLI 启用元素屏蔽 · 允许元素掩码

5. 从网络输出回到能交接的晶体

最后一步返回采样状态 sample 和 mean。官方生成器单独取最终 mean 作为交付结构,离散字段由反向预测器取对应分布的最大概率类别。程序把晶格矩阵转成三边长度和三个夹角,按 num_atoms 切分各晶体的分数坐标和原子序数,用 pymatgen 重建周期结构,最后由 ASE 写出 CIF 与 extxyz。晶胞在文件里可能具有新的整体取向,可以用晶格度量 LL𝖳LL^\mathsf T、组成和周期距离比较等价结构。课程网页读取单独的 final_structure,材料计算读取匹配的 final.cif。生成与记录 · 结构构造和文件导出 · 本组接口(课程仓库,需权限)

实例:同一个 Cu₂Pd 的三种读法

① 看输出文件。 原始 extxyz 中,第一个 Cu 的笛卡尔位置是 (1.594332,2.724094,−0.227476)(1.594332,2.724094,-0.227476) Å。CIF 中对应的分数坐标为 (0.662126,0.969702,0.250248)(0.662126,0.969702,0.250248)。以下为 extxyz 的晶格行向量(Å),将这行分数坐标右乘晶格,即可还原上述笛卡尔位置。晶胞体积为 39.01445 ų。Cu₂Pd CIF · 原始 extxyz(课程仓库,需权限)

 2.824153   0.000000  -0.897811
-0.284226   2.809208  -0.890616
 0.000000   0.000000   4.917601

② 看周期关系。 在这份输出里,第一个 Cu 与 Pd 的晶胞内直线距离为 4.1330 Å。给 Pd 加上晶格平移 (−1,0,−1)(-1,0,-1) 后,距离是 2.6117 Å。两者对应不同的周期像。这个差异说明仅把中央晶胞中的三个点连起来会漏掉重要近邻。这里给出的是距离,化学键与相稳定性需要其他证据。原始结构(课程仓库,需权限)

③ 看实际输入与输出形状。 将上面的 CIF 按官方数据流程重新取原胞、约化及对称化,得到如下真实单样本批次。变换改选了晶胞基底,所以这里的分数坐标随之改变。再用本地 base 权重对这份输入在 t=0.4t=0.4 独立加噪并执行一次前向,实测得到元素 logits [3,101]、位置 [3,3] 与晶格 [1,3,3];骨干还返回 node_embeddings[3,512] 和 energy[1,1]。这次检查验证张量链路,原 seed48 轨迹另有独立的运行记录。固定配置 · seed48 原始运行(课程仓库,需权限)

atomic_numbers = [29, 29, 46]       num_atoms = [3]
batch          = [0, 0, 0]          ptr       = [0, 3]

pos (fractional)                     cell (Å, symmetric)
[[0.0303, 0.4119, 0.2502],            [[[ 2.9049, -0.0550, 0.5694],
 [0.3815, 0.7624, 0.5477],              [-0.0550,  2.9081, 0.5672],
 [0.7059, 0.0871, 0.8989]]              [ 0.5694,  0.5672, 4.8465]]]

以下代码可在 members/tk/ 中用已安装的 MatterGen 环境执行,CPU 即可。前半段从 CIF 读图,无需权重。后半段读取本地固定 checkpoint,只执行一个噪声时刻的前向,无需重新生成候选。安装与本地权重路径(课程仓库,需权限)

from pathlib import Path

import torch
from pymatgen.io.cif import CifParser
from mattergen.common.data.collate import collate
from mattergen.common.data.dataset import CrystalDataset, structures_to_numpy
from mattergen.common.data.transform import set_chemical_system_string, symmetrize_lattice
from mattergen.common.utils.data_classes import MatterGenCheckpointInfo
from mattergen.common.utils.eval_utils import load_model_diffusion

candidate = "tk-cuda-seed48"
structure = CifParser(f"deliverables/{candidate}/final.cif").parse_structures(primitive=True)[0]
structure.properties["material_id"] = candidate
arrays, labels = structures_to_numpy([structure])
dataset = CrystalDataset(**arrays, properties=labels,
                         transforms=[symmetrize_lattice, set_chemical_system_string])
graph = collate([dataset[0]])
print(graph.atomic_numbers, graph.pos, graph.cell, graph.batch, graph.ptr)

checkpoint = MatterGenCheckpointInfo(
    model_path=Path("external/models/checkpoints/mattergen_base").resolve()
)
model = load_model_diffusion(checkpoint).cpu().eval().diffusion_module
with torch.inference_mode():
    torch.manual_seed(17)
    t = torch.tensor([0.4])
    noisy = model.corruption.sample_marginal(graph, t)
    out = model.model(noisy, t)
    print(out.atomic_numbers.shape, out.pos.shape, out.cell.shape)

这段演示可以用一段话讲完:“在这个样本里,AI 要决定三个站点放什么元素、放在哪里、晶胞应有多大。每次迭代,它都重新查看跨晶胞的邻居和夹角,更新三组数。最后我们拿到了 Cu₂Pd 的结构文件。接下来可以用同一份文件检验,当原子受到轻微扰动时,这个候选能否保持稳定。”