构型搜索¶
mliport confsearch 用来找周期性 slab 一侧单个吸附分子的低能构型。需要先装好对应后端
并准备模型,见后端和安装。程序会从多个起点各跑
一条 MD 链,把途中的结构做局部优化,去掉重复的极小值,最后导出一份候选结构,留给 DFT
复核。
它只做构型筛选:吸附能、自由能和 Boltzmann 分布都不在它的计算范围内,晶胞也保持不变。 结果里给出的是"这次搜索找到的能量最低的几个结构",同时附上判断搜索是否充分的统计数据。 有限次数的搜索没法证明找到的就是全局最小。
.venv-mace/bin/mliport confsearch run starts/*.extxyz \
--adsorbate-indices 300-341 \
--model mace-omat-0-medium.model --model-type mace --task bulk \
--cycles 5 --output runs/lds-on-lpsc
上面是模式 A,用你自己准备的结构作起点。模式 B 让程序把分子随机摆到 slab 上方:
.venv-mace/bin/mliport confsearch run \
--slab slab.vasp --molecule conformers.xyz --n-starts 20 \
--model mace-omat-0-medium.model --model-type mace --task bulk \
--output runs/placed
cs_adsorbate_indices 和 ASE 一样从 0 开始编号,CP2K 和 VMD 是从 1 开始的。编号填错是最
常见的问题,所以程序会检查:选中的原子必须能连成一个完整的共价分子,否则直接报错退出。
搜索过程¶
每个起点先做一次结构优化,这一步的结果就是"只做多起点优化"的对照组。然后每条 replica
重复 --cycles 轮"升温、保温、降温":
- 用 Langevin 热浴升到
CS_TEMPERATURE_HIGH并保温; - 保温期间定时取几帧,然后线性降温到
CS_TEMPERATURE_LOW; - 每个取出的帧和本轮最后一帧都在固定晶胞下用 FIRE 做局部优化;
- 对得到的每个极小值做分类和去重;
- 用
CS_ACCEPT_TEMPERATURE下的 Metropolis 判据,决定是否把本轮最后的极小值作为下一轮的 起点。
各条 replica 互不影响。程序轮流推进它们(先每条跑第 1 轮,再每条跑第 2 轮),所以任何时候
停下来都有一份可用的结果。默认 MD 期间 slab 原子全部固定(CS_MD_MOBILE = adsorbate)。
设成 adsorbate_and_top 会把表面以下 CS_TOP_DEPTH Å 内的原子也放开,设成 all_free 则放开
所有没被固定的原子。局部优化时,输入里没有固定的原子都会参与优化。
开始前的检查¶
只有当力等于能量的负梯度时,按能量排序才有意义。所以在跑任何 MD 之前,程序会先记录模型 信息,并在第一个起点上检查能量和力是否一致:
- 模型信息(后端、版本、task、head、精度、推理模式、设备、是否加了 DFT-D3)写进
run_context.json; - 如果模型声明自己的力是直接预测的(
direct_forces = true),程序拒绝运行。确实要用的话加--allow-direct-forces,这时每条结果都会附上"排序不可靠"的警告; - 其余模型用有限差分抽查:沿几个方向比较
-F·u和能量的数值导数,结果存为gradient_preflight。
步长也会检查:可动原子里有氢时,步长不能超过 1.0 fs,默认是 0.5 fs。
自动摆放¶
模式 B 下,每个起点的生成步骤是:随机选一个构象,以几何中心为原点做一次随机旋转,在面内 随机选一个位置,再用二分法调整高度,直到分子和 slab 之间最近的一对原子距离达到设定值。距离 用"两原子共价半径之和"的倍数来表示:
| 选项 | 默认值 | 含义 |
|---|---|---|
CS_PLACE_CONTACT_SCALE |
1.5 | 普通摆放:最近原子对贴近但不成键 |
CS_PLACE_ANCHOR |
不设置 | 分子文件里的锚点原子编号(从 0 开始) |
CS_PLACE_ANCHOR_SCALE |
1.1 | 设了锚点时,锚点和表面原子直接以成键距离摆放 |
CS_PLACE_OTHER_MIN_SCALE |
1.3 | 锚点以外的原子离表面都要大于这个倍数 |
CS_PLACE_ANCHOR_TARGETS |
不设置 | 限定锚点只和这几种表面元素成键 |
锚点摆放用于优先考虑化学吸附。程序会旋转分子,直到锚点原子处在最下方,再把它放到
CS_PLACE_ANCHOR_SCALE 倍共价半径和的位置。这个距离已经满足分类时的成键判据,所以起点
本身就是成键的。默认情况下锚点只和非离子原子成键,Li 这类离子不算。
去重¶
两个极小值的能量差不超过 CS_DEDUP_ENERGY_TOL,并且满足下面任意一条,就算作同一个结构:
G,几何直接比对:slab 有固定原子作锚定,原子顺序也不变,所以可以逐个原子比较吸附物的 位置,每个原子的位移都不超过CS_DEDUP_GEOM_TOL就算相同。平缓势能面上优化留下的微小 差别由这一条处理;D,指纹比对:吸附物周围环境的 Oganov–Valle 指纹距离不超过CS_DEDUP_FP_TOL。这一条用来 识别对称等价的吸附位点,以及甲基转了一下这种本质相同的构象。
指纹的离散方式和 ASE 完全一致,可以逐个 bin 和 OFPComparator 对照。(它和
NEB 里检查能量和力是否一致的预检是两回事。)容差按照"宁可多留一个重复,也不错删
一个结构"来设定:错把两个不同结构合并,可能正好删掉 DFT 复核后排第一的那个;多留一个重复,
代价只是多算一次 DFT。
标定的局限。 默认的 CS_DEDUP_FP_TOL 来自
tests/mliport/mliport/confsearch/test_fingerprint_calibration.py 里的标定。标定用的是
LGPS 体相晶胞里的甲醇;"同一个极小值"那一类样本是随机扰动出来的,没有真正做优化;
"对称等价"那一类是严格的刚性对称拷贝,D 几乎为 0。所以这个容差能保证不会错误合并,但对
"带一点噪声的等价结构"还没有实测数据。实际使用中,D 基本只会合并完全对称的拷贝,同一
个极小值的合并主要靠 G 和 CS_DEDUP_ENERGY_TOL。这样做的后果是可能多出一些重复结构,不会
丢掉候选。在真实 slab 和真实模型上重新标定,是验证脚本
validation/science/scripts/confsearch_suite.py 要做的事。
输出¶
一次运行会写出 resolved_config.json、run_context.json、run.log、
search_results.json、artifacts.json、starts/、raw/、minima/、
diagnostics/discovery.csv、top/rank_NNN/ 和 checkpoints/。各文件的通用约定见
输出文件。
每个导出的结构目录里有 POSCAR(分数坐标,固定原子带 selective dynamics)、
structure.extxyz、cp2k_coord.xyz、cp2k_cell.inc、cp2k_fixed_atoms.inc 和
minimum.json。CP2K 的固定原子文件按 &MOTION/&CONSTRAINT/&FIXED_ATOMS 的 LIST 格式写,
原子编号从 1 开始,连续编号写成 a..b。导出时 slab 原子会放回晶胞内,吸附分子按最近镜像
拼成完整的分子,和原始极小值只差一个晶格平移。
search_results.json 里有排序结果、发现曲线、饱和程度的统计(最低结构被找到几次、被几条
replica 找到、第一次出现在搜索的什么阶段),以及和"只做多起点优化"对照组的比较。相关验证
记录见验证。
续算¶
起点优化完成后、以及每条 replica 每跑完一轮,都会写一次检查点。续算时程序会核对模型、输入
结构、原子分区、随机种子和各项参数(输出相关的设置除外),有任何一项变了就拒绝续算。核对
通过后,程序从中断前保存的随机数状态重跑被打断的那一轮。在 CPU 上,中断后续算的结果和一口
气跑完的结果逐位相同。被打断那一轮留下的原始文件会移到 incomplete_attempt_N/,不会删除。
风险和注意事项¶
- 基础模型大多只用体相无机材料训练,描述硫化物表面上的有机分子可能很差,温度越高问题越
明显。
reacted(分子骨架断键)的比例偏高就是信号。导出的候选一定要用 DFT 复核。 - 烷基链是平躺还是竖立,取决于色散作用。如果模型的训练数据不含色散,请加
--d3。D3 会记 入模型信息,加 D3 和不加 D3 的搜索不能合并。 - MD 期间固定 slab,会让搜索偏向初始的表面结构。
adsorbate_and_top可以缓解,但能量会更 嘈杂,注意诊断里的far_field_slab_changed。 - 晶胞必须已经用同一个模型优化过。confsearch 不检查这一点,也不会改变晶胞。
- 分子与自身周期像的距离、真空层厚度的检查只是几何上的保护,不能说明模型在周期像之间完全 没有相互作用。
- 短程 MLIP 不含长程静电。对单侧吸附的 slab 做 DFT 单点或优化时,记得加偶极修正。
- 模型没见过的表面上形成的化学吸附键,是整个结果里最不可靠的部分。每个标为
chemisorbed的候选都要用 DFT 确认。
Python API 和命令行一一对应,返回值就是 search_results.json 的内容:
from mliport import run_confsearch
results = run_confsearch(
starts=["starts/start_000.extxyz"],
adsorbate_indices="300-341",
model_path="mace-omat-0-medium.model",
model_type="mace",
task="bulk",
cycles=5,
output_dir="runs/lds-on-lpsc",
verbose=False,
)
print(results["ranking"]["best_energy_eV"])
终端界面(TUI)的配置页也支持这两种起点方式,可以设置锚点原子、锚点目标元素和随机种子;
resume、extend 和 merge 只能在命令行里用。各个入口
分别支持哪些功能,记录在能力矩阵里。mliport confsearch place 只做摆放、不加载模型,可以在
花 GPU 时间之前先看看起点是否合理: