跳转至

配置

简单的计算把参数都写在命令行上就行。参数多了以后,可以写进 settings.ini、模型别名或 INCAR 风格的输入文件。这些来源由同一个解析器处理,按下面的顺序叠加,后面的覆盖前面的:

built-in defaults
  < settings.ini
  < model alias ([model:NAME])
  < profile ([profile:NAME])
  < INCAR / job file
  < CLI flags / API arguments

同一个选项在多层里都出现时,只取优先级最高的那个值,不做合并。每个选项的最终值和它的来源 都写在 resolved_config.json 里(见输出文件)。想知道某次计算为什么用了某个 参数,查这个文件即可。

必需的输入

需要什么 从哪里来
计算类型 子命令(sp、opt、md、neb、batch、confsearch),或 CALC_TYPE / CALCULATION
后端 --model-type / MODEL_TYPE,或声明了 engine 的模型别名
模型路径 --model / MODEL_PATH,或别名里的 path
结构 位置参数;run 命令下用 --structure 或 INCAR 的结构键
DPA 分支 多任务模型用 --head / HEAD
NEB 端点 --initial / --final,或 NEB_INITIAL / NEB_FINAL
confsearch 起点 CS_STARTS + CS_ADSORBATE_INDICES,或 --slab / --molecule / --n-starts

后端没有默认值。所有层里都没有指定后端时,程序会报错:

Error: No MLIP backend was selected.

Choose one of:
  --model-type mace
  --model-type dpa
  --model-type grace
  --model-type uma

or use a configured model alias/profile.

默认使用严格模式

拼错的参数名,或者属于别的后端的参数,都会直接报错。如果只给个警告然后继续跑,很容易算出 错误结果却没人发现。

mliport sp structure.cif --model m.model --model-type mace --inference-mode turbo
# Error: Option 'inference_mode' is not applicable to engine 'mace' ...

做探索性计算时,可以手动切换成"只警告、继续运行":

mliport sp ... --lenient-config
[general]
strict_config = false

几个查看配置的命令:mliport config validate settings.ini 检查文件; mliport config explain <KEY> 显示某个值的来源;mliport config paths 列出 settings.ini 的查找位置;mliport config init 生成一个模板文件;mliport config show 打印最终生效的配置; mliport config schema 列出所有参数名。

settings.ini

mliport config paths 会按优先级从高到低列出查找位置。环境变量 MLIPORT_SETTINGS 可以 指定一个文件,命令行的 --settings PATH 优先级更高。

[general]
strict_config = true

[model:mace_omat]
engine = mace
path = /models/mace-omat-0-medium.model
task = bulk

[md]
ensemble = NVT
temperature = 300

[profile:quick]
calc_type = sp
device = cuda
  • [model:NAME] 段必须写 engine(uma、mace、dpa 或 grace;fairchem 等同于 uma)。
  • [profile:NAME] 段把一组计算参数打包在一起,不包含模型。
  • 以计算类型命名的段([sp]、[md]、[neb] 等)只对该类型生效;[general]、 [resources]、[output]、[safety] 对所有类型生效。

INCAR 风格的输入文件

mliport run --incar INCAR.mliport 读取一个仿照 VASP INCAR 写法的参数文件。只是格式像, 内容和 DFT 无关。所有可以写的键,连同类型、默认值、取值范围和适用条件,都列在 INCAR 键参考 里。

CALC_TYPE = SP
MODEL_TYPE = MACE
MODEL_PATH = /models/mace-omat-0-medium.model
DEVICE = cpu                        # explicit cuda / cuda:0 for GPU runs

可以让 mliport 生成模板,后端自己填:

mliport template sp --engine mace --output INCAR.mace
mliport template sp --output INCAR.neutral   # backend-neutral, MODEL_TYPE=REQUIRED

任务文件夹

推荐的日常用法是一个任务一个文件夹:INCAR.mliport 和结构文件(POSCAR、CONTCAR、 structure.cif 或 structure.xyz)放在一起。这样 mliport run 不需要任何参数:

cd LiDS-on-LPSC
mliport run

mliport run 的默认输出目录是 INCAR 所在文件夹下的 results/。这个默认值只在 run 里生效:--output 和 OUTPUT_DIR 仍然优先;OUTPUT_DIR 写相对路径时相对 INCAR 所在 文件夹解析,而不是相对当前目录;OUTPUT_DIR = . 可以恢复以前写进当前目录的行为(settings.ini 或命令行里写的相对 OUTPUT_DIR 一直就是相对当前目录解析,这一点没有变)。 和以前一样,results/ 里已经有计算结果的目录会被拒绝写入,除非加 --overwrite。

mliport run 支持 CALC_TYPE = CONFSEARCH,走的是和 mliport confsearch run 完全相同的 代码路径。CALC_TYPE = BATCH 不支持,批处理要用 mliport batch,它需要自己的输入目录。

后端专用的选项

选项 后端 作用
TASK / --task UMA 任务族(omat、omol、oc20 等)
TASK / --task MACE、DPA、GRACE 明确的 PBC 语义(bulk / molecule)
HEAD / --head DPA、MACE 模型的分支或 head(许多 MACE 模型用 default)
INFERENCE_MODE UMA default、turbo 或 trained 推理预设
ACTIVATION_CHECKPOINTING UMA 节省 GPU 显存
DEFAULT_DTYPE MACE 模型精度
GPU_MEMORY_GROWTH、GPU_MEMORY_LIMIT_MB GRACE TensorFlow 的 GPU 显存策略
NEIGHBOR_CACHE、NEIGHBOR_SKIN GRACE 近邻列表缓存策略
TORCH_NUM_THREADS UMA、MACE、DPA CPU 算子内线程数

严格模式下,把这些选项用在别的后端上会报错。

色散校正(DFT-D3)

MLIP 模型本身不含色散校正。用 PBE 数据训练的模型(MACE 的 omat、UMA 的 omat 和大多数 材料模型)学到的是 PBE 势能面,PBE 不含长程色散。--d3 会在模型结果上加上 Grimme DFT-D3 的 能量、力和应力,所有后端都能用,实现来自 torch-dftd:

选项 默认值 作用
D3 / --d3 关闭 在模型之上叠加 DFT-D3
D3_XC / --d3-xc pbe 模型训练数据的参考泛函,决定 D3 参数
D3_DAMPING / --d3-damping bj 阻尼函数:zero、bj、zerom 或 bjm
uv pip install --python .venv-mace/bin/python torch-dftd
mliport opt slab.vasp --model model.model --model-type mace --task bulk --d3

只有训练数据不含色散的模型才能加 D3,并且要用 --d3-xc 写明训练数据的泛函,因为 mliport 没法从 MACE、DPA、GRACE 的模型文件里读出这个信息。UMA 各 task 的参考泛函是已知的:只有 omat(PBE)和 oc20(RPBE)可以加 D3;omol、omc、odac、oc25 的参考已经含色散或 无法确认不含,加 D3 会报错。只写了 D3_XC 或 D3_DAMPING 却没开 D3,也会报错,避免记录 一个实际没生效的设置。NEB 暂不支持 D3。TUI 配置页里的 DFT-D3 开关对应同样的三个选项(NEB 的配置页不显示这个开关)。

是否加了 D3 会记录下来:JSON 结果的模型信息里有 dispersion 字段,OUTCAR 文件头里有一行 Dispersion:。torch-dftd 依赖 PyTorch,MACE、DPA 和 UMA 的环境里都已经有了。

模型文件:models/

模型权重不属于 mliport,也不会进仓库。把权重放在 mliport 仓库根目录的 models/ 下(这个 目录已在 .gitignore 里),在 MODEL_PATH 里只写文件名即可:

MODEL_TYPE = MACE
MODEL_PATH = mace-omat-0-medium.model

不含路径分隔符的 MODEL_PATH 按文件名处理,查找顺序是:

  1. INCAR 旁边的同名文件(显式路径本来就是这么解析的),
  2. <MLIPORT_ROOT>/models/<文件名>,
  3. <MLIPORT_ROOT>/models/*/<文件名>,只找一层子目录。

第 3 步如果撞到两个同名文件,程序报错而不是替你挑一个:不同的 checkpoint 是不同的模型身份, 这个选择必须由人来做。含路径分隔符的值就是路径,相对声明它的文件解析,不会再去 models/ 里找。

MLIPORT_ROOT 就是 mliport 仓库根目录。它取自环境变量 MLIPORT_ROOT;没有设置时,如果当前 解释器跑在安装器创建的 .venv-<engine> 环境里,就取 sys.prefix 的父目录——安装器生成的 bin/mliport-<engine> 启动脚本会替你导出这个变量。确定不了根目录时,只写文件名的取值会直接 报错并说明怎么设置,不会去猜。找不到模型时,错误信息会列出所有搜索过的位置,以及 models/ 里现有的文件。

mliport doctor 会打印它使用的根目录、models/ 路径和其中的模型文件清单。每次运行实际 解析出的绝对模型路径都记录在 resolved_config.json 里。

科学参数的默认值

温度、步长、步数、恒温器、优化器、fmax、NEB 参数等都有内置默认值,按计算类型区分,每次 运行实际用的值都记录在 resolved_config.json 里。完整列表可以这样查看:

mliport config schema
mliport config show --settings settings.ini

输出控制

键 含义
DEVICE / --device cpu、cuda 或 cuda:N;请求的设备和实际使用的设备分开记录
OUTPUT_DIR / --output 运行目录
WRITE_OUTCAR、WRITE_XDATCAR、WRITE_TRAJECTORY 写出哪些文件
WRITE_FORCES、WRITE_STRESS 写出哪些数组和列

NEB 的必需输出不能关闭,关闭会报错。

环境变量

变量 作用
MLIPORT_SETTINGS 明确指定 settings.ini 路径
MLIPORT_ROOT mliport 仓库根目录;只写文件名的 MODEL_PATH 在其中的 models/ 下查找
MLIPORT_JOBS_DIR 队列与作业注册表目录
MLIPORT_CANCEL_GRACE_SECONDS 取消作业时的宽限时间
MLIPORT_LEASED_GPU_UUID 分配给队列 worker 的 GPU
CUDA_VISIBLE_DEVICES 可见的 GPU;队列分配 GPU 时会设置它,不要在运行中的作业里修改

TUI

mliport tui 打开后先是“新建任务”向导,因为这是最常见的用法:选计算类型、结构文件和模型 (先选后端,再从 models/ 的文件清单里选),它会建好一个任务文件夹,里面有 INCAR.mliport 和结构文件的逐字节副本,并提示 cd <文件夹> && mliport run。“创建并运行”走的就是 mliport run 本身,不是另一套运行逻辑。向导会把 TASK(多分支 checkpoint 还有 HEAD)留成 REQUIRED 占位符:UMA 的任务族和其他后端的 bulk/molecule 语义属于模型层面的决定,所以它 只提示还差什么,不会用模板默认值直接开跑。

其余功能都在“高级”里:SP、OPT、MD、NEB、CONFSEARCH 的手工配置页、模板生成(和 mliport template 用同一个生成器)、后台作业和结果分析。它们提供同样的配置项,同样要求先选定 后端和模型才能运行,并且和命令行通过同一套代码提交作业,两边行为一致。分析页包含所有 analyze 任务和常用参数;不常用的参数(例如 GEMDAT 自动识别位点)只能在命令行里设置。