12. Reference — 全部命令、资源、flag 速查

把这一页当词典翻。

命令一览（顶层 command，不带 /）

命令	用途	例子
mat	0 参数 = 当前 context + 下一步建议	mat
mat --help	列全部 command 和 resource	mat --help
mat init	起 run 目录	mat init --label demo -q
mat materials	列内置 material 别名	mat materials
mat status	看 run 进度	mat status
mat build <kind|alias>	造结构	mat build mos2 strain=2%
mat get [target]	智能 get（file / mp-id / run-id 自动路由）	mat get mp-2815
mat show [target]	mat get 的别名	mat show foo.vasp
mat list <thing>	智能 list	mat list motifs
mat ls <thing>	mat list 的别名	mat ls runs
mat motifs [file]	列 motif（默认当前 context）	mat motifs center=Mo
mat sites [file]	列原子	mat sites element=S
mat strain <spec>	施应变	mat strain a:1%,b:-0.5%
mat vacuum <Å>	设真空	mat vacuum 20
mat recenter	slab 居中	mat recenter
mat perturb <ops...>	复合编辑	mat perturb vacancy=S:1 strain=2%
mat verify <structure> --rules <rules.yaml>	校验	mat verify mos2.vasp --rules rules.yaml
mat explain <structure> --profile <profile.yaml>	profile 解释	mat explain mos2.vasp --profile perovskite.yaml
mat reproduce <recipe.yaml>	跑 paper recipe	mat reproduce paper.recipe.yaml --continue

资源一览（mat /<path> <verb>）

路径	缩写	动词	典型用法
/structures	/s	get / create / update / delete	mat /s get foo.vasp
/motifs	/m	list / get	mat /m list center=Mo
/motifs/graph	—	get	mat /motifs/graph get
/lattice	/l	get / update	mat /l update strain=2% vacuum=20
/sites	/si	get / update / create	mat /si update set=0=z:7.5
/bilayers	/b	update	mat /b update shift=top:0.1,0 rotate=top:3
/defects	/d	create	mat /d create vacancy=S:1
/adsorbates/sites	—	list	mat /adsorbates/sites list positions=ontop,bridge
/adsorbates	/a	create	mat /a create molecule=O2 site=hollow
/vasp-inputs	/v	create	mat /v create profile=mp-relax-pbe (alias of set=mp-relax)
/runs	/r	list / create	mat /r list
/runs/<id>	—	get / delete	mat /r/001-demo get
/recipes	/rec	list / get / run	mat /rec run path=paper.recipe.yaml
/mp	—	list	mat /mp list elements=Mo,S
/mp/<id>	—	get	mat /mp/mp-2815 get -o mp2815.vasp

全局 IO flag（所有 verb 都支持）

flag	作用	例子
--json	输出 JSON	mat motifs --json
--jq EXPR	用 jq 表达式裁剪	mat motifs --json --jq '.[].label'
-o PATH	写文件	mat get --json -o snap.json
-q	单行 quiet	mat build mos2 -q

--jq 是 mini-jq（不依赖系统 jq），支持：

• .field、.a.b.c 字段链
• .[N] 数组索引
• .[] 数组扁平
• EXPR | EXPR 管道（左结果 → 右）
• {a:.x, b:.y, label} 对象重组（label 是 label:.label 简写）
• select(.x==V) 过滤，支持 == != > < >= <=
• length、keys、unique
• [EXPR] 包成数组

不支持：函数定义、map(...)、字符串处理、//、@csv 等高级特性。 高级需求建议 --json 输出再外接系统 jq。

全部环境变量

变量	默认	作用
MAT_STRUCTURE	—	强制当前结构（最高优先）
MAT_RUN_DIR	—	当前 run 目录（auto-out 落在这里）
MAT_NO_ARTIFACTS	unset	1 = 不出 PNG/summary
MP_API_KEY	—	Materials Project key

Material 别名

别名	实际
mos2, tmd	monolayer prototype=MoS2-2H
graphene, gr	honeycomb element=C a=2.46
hbn, h-bn	honeycomb element=B element-b=N a=2.504
bi	honeycomb element=Bi a=4.337 buckling=1.74
sb	honeycomb element=Sb a=4.025 buckling=1.65
as	honeycomb element=As a=3.607 buckling=1.40

Build kind 一览

kind	关键参数
monolayer	prototype=
honeycomb	element= element-b= a= buckling=
square	element= a=
bilayer	两个 .vasp 文件 + interlayer= shift-xy=
slab	metal= miller=h,k,l layers= vacuum=
octahedron	center= ligand=
octa-pair	center= ligand= mode=corner/edge/face
octa-lattice	center= ligand= nx= ny= nz=

Perturb 操作一览

键	形式	例子
shift=	<layer-sel>:dx,dy	shift=top:0.1,0
rotate=	<layer-sel>:deg	rotate=top:5
interlayer=	<Å>	interlayer=6.5
vacancy=	<el>:k 或 index:i,j	vacancy=S:1, vacancy=index:7,12
substitute=<i>:<el>	按 index	substitute=5:Se
seed=<int>	随机种子（vacancy/substitute）	seed=42
substitute=<species>:<el>	全替换	substitute=Mo:W
substitute=<species>:<k>:<el>	随机 k 个	substitute=S:2:Se
displace=	<index>:dx,dy,dz	displace=12:0,0,0.2
strain=	同 mat strain	strain=2%, strain=a:1%,b:-0.5%
vacuum=	<Å>	vacuum=20
recenter=	z	recenter=z
set=	<index>=<axis>:val	set=0=z:7.5
add=	<el>:x,y,z	add=O:2.5,1.4,9.0
remove=	<i>,<j>,...	remove=7,12

Layer 选择器

写法	含义
top	z 最大的层
bottom	z 最小的层
z>5.0	所有 z > 5.0
z<3.0	所有 z < 3.0
0,3,7-12	显式 index 集合

VASP profile 一览

profile	描述
mp-relax-pbe	MP 风格 PBE 弛豫
mp-static-pbe	单点
scan	SCAN
hse06	HSE06
2d-relax	2D 材料弛豫
surface-relax	slab 弛豫

自动 artifacts

每个写结构的命令完成后产出：

<stem>.vasp        ← 主结构
<stem>.png         ← VESTA 风格 3D 渲染
<stem>.summary.md  ← 文本摘要 (formula / lattice / motifs / sites)

详见 Auto-artifacts。

配套文件

文件	用途
./.mat-context.json	当前 context + 操作 history
runs/NNN-label/	编号 run 目录
runs/NNN-label/provenance.json	recipe 跑过后的完整日志

Builder kinds（mat build <kind> 全参数表）

kind	必需参数	可选参数	说明
monolayer	prototype=<id>	a= c= vacuum=	通用 2D 单层
honeycomb	element= a=	vacuum=	蜂窝单元素层（graphene 等）
square	element= a=	vacuum=	正方晶格单层
bilayer	<bottom> <top> interlayer=	shift-xy=dx,dy vacuum= cell-from=bottom|top	两个结构叠成双层
octahedron	—	center= ligand= bond= box= passivate=	单个八面体团簇
octa-pair	mode=corner|edge|face-sharing	center= ligand= bond= box=	两个八面体共享
octa-lattice	—	mode= nx= ny= center= ligand= bond= vacuum=	周期八面体阵列（钙钛矿）
slab	metal= miller=h,k,l	layers= vacuum= supercell=nx,ny fix-bottom-layers= prototype=	金属表面 slab

材料别名

mat build <alias> 会自动选 builder + 默认参数。完整列表：

alias	→ builder + 默认
mos2, tmd	monolayer prototype=MoS2-2H
graphene, gr	honeycomb element=C a=2.46
hbn, h-bn	honeycomb element=B-N a=2.504
bi, sb, as	monolayer prototype=<elem>-2D

退出码

code	含义
0	成功
2	用户错误（参数错 / 结构不存在 / 物理约束失败）
3	系统错误（IO / 依赖缺失）
4	内部 bug（请报告）

---

回到 文档首页