5. Motifs — 配位环境抽象 + connectivity graph

什么是 motif

晶体里没几个人在意"第 47 号原子坐标 (3.21, 1.85, 7.30)"。大家真正描述结构时用的是局部图案：

例子	内容
MoS6_octahedral	1 个 Mo 被 6 个 S 包围成八面体
MnO6_octahedral	1 个 Mn 被 6 个 O 包围（钙钛矿就是 BO6 拼出来的）
SMo3_trigonal	1 个 S 被 3 个 Mo 包围（MoS2 单层里 S 看 Mo 的视角）
CC3_trigonal	1 个 C 被 3 个 C 包围（石墨烯）

一个 motif = 中心 + 配体 + 配位数 + 几何分类（octahedral / trigonal / tetrahedral / square_pyramidal ...）。

mat 把 motif 当成一等公民——任何结构进来，CLI 第一步先抽 motif，后续 verify / explain / perturb 全部基于 motif 思考。

mat motifs：列当前结构的全部 motif

mat motifs

输出（MoS2 单层）：

✓ 2 motif(s)
  smo3_trigonal_0001       SMo3_trigonal          S[1]   cn=3  trigonal
  smo3_trigonal_0002       SMo3_trigonal          S[2]   cn=3  trigonal
  mos6_octahedral_0001     MoS6_octahedral        Mo[0]  cn=6  octahedral

每行 = 一个 motif 实例：实例 id / 标签 / 中心位点 / 配位数 / 几何分类。

过滤

mat motifs center=Mo                      # 只看以 Mo 为中心
mat motifs center=Mo ligand=S             # 只看 Mo–S
mat motifs geometry=octahedral            # 只看八面体

JSON + jq

mat motifs --json --jq '.[].label'

["SMo3_trigonal", "SMo3_trigonal", "MoS6_octahedral"]

mat motifs --json --jq '.[]|select(.cn==6).label'

只列出 cn=6 的 motif 名。

mat /motifs/graph — motif 之间怎么连

motifs 列点，motifs/graph 给点之间的连接（corner / edge / face-sharing）。这是钙钛矿、TMD、MOF 等结构的本质拓扑。

mat /motifs/graph get

输出（钙钛矿样本）：

✓ 6 edge(s)
  MnO6_octahedral_0001 ─[corner]─ MnO6_octahedral_0002
  MnO6_octahedral_0001 ─[corner]─ MnO6_octahedral_0003
  ...

JSON 形式：

mat /motifs/graph get --json --jq '.[]|{from,to,mode}'

三个高频场景

场景 A：建出来的结构对不对

mat build mos2 -q
mat motifs                                # 应该是 MoS6_octahedral

如果出来是别的几何（比如 prismatic 误造成 octahedral，或 cn=4 而不是 6），立即知道建错了。

场景 B：扰动后结构还稳不稳

mat strain 10% -q                         # 重度施压
mat motifs                                # 八面体还在不在？

施压太大时配位会重排，motif label 直接变。

场景 C：数 motif 多样性

mat motifs --json --jq '[.[].label]|unique'   # 全部不同 motif 名
mat motifs --json --jq 'length'                # motif 总数

motif 也是 verify / explain 的基础

mat verify  <structure.vasp>  --rules rules.yaml
mat explain <structure.vasp>  --profile profile.yaml

rules.yaml 里可以写：

require_motifs:
  - label: MoS6_octahedral
    count: 1
  - cn: 6
forbid_motifs:
  - geometry: tetrahedral

mat verify 会按 motif 检查，pass / fail。

motif 引擎细节

• 默认用 pymatgen 的 CrystalNN 找近邻；可以 neighbor=brunner / voronoi 换。
• 几何分类用 LocalGeometryFinder（与 ChemEnv 一致）。
• motif label = <center><n><ligand><n>_<geometry> 形式，跨结构一致。

相关命令速查

命令	作用
mat motifs	列当前 motif（顶层快捷）
mat /motifs list	等价（资源形式）
mat /m list	等价（缩写）
mat /motifs/graph get	列 motif 间连接
mat /motifs get <label>	取某 motif 详情
mat verify rules.yaml	按 motif 规则校验

---

下一步： Lattice ops → strain / vacuum / recenter