nku-vasp-cli

面向 VASP/材料结构工作流的 motif-native CLI。它用 pymatgen 读取 POSCAR/CIF，构建 Material IR，识别 MnO6 等配位 motif、corner/edge/face-sharing connectivity，并支持结构构造、规则校验、论文 profile 解释和静态渲染。

安装

npm install -g nku-vasp-cli

或者直接使用：

npx nku-vasp-cli --help

注意：npm 包只是 Node 包装层，实际计算依赖本机 Python 运行环境。请确保可执行 python3，并安装 Python 依赖：pymatgen、pyyaml、numpy、matplotlib。可选 ASE 支持需要安装 ase。

基本用法

每次运行先创建编号目录：

RUN_DIR=$(nku-vasp-cli init-run --label escience-mno6-lattice --quiet)

构造 2D corner-sharing MnO6 晶格：

nku-vasp-cli build octahedron-lattice   --mode corner-sharing --nx 2 --ny 2   --center Mn --ligand O   --bond-length 2.05 --vacuum 16 --passivate   --output-structure "$RUN_DIR/MnO6-2d-corner-H.vasp"   --output-ir "$RUN_DIR/MnO6-2d-corner-H.ir.yaml"   --neighbor-strategy minimumdistance

识别 motif：

nku-vasp-cli motif summarize "$RUN_DIR/MnO6-2d-corner-H.vasp"   --center Mn --ligand O --geometry octahedral   --neighbor-strategy minimumdistance --quiet

渲染结构：

nku-vasp-cli render structure "$RUN_DIR/MnO6-2d-corner-H.vasp"   --center Mn --ligand O --geometry octahedral   --neighbor-strategy minimumdistance   --output "$RUN_DIR/MnO6-2d-corner-H.png"   --atom-labels none

Run Folder 规范

所有 CLI 生成产物都应该写入 runs/NNN-label/ 目录。每个运行目录必须包含自己的 README.md，说明本次运行目的、主要产物和复现命令。

主要命令

• init-run：创建编号运行目录。
• build octahedron：构造孤立八面体单元。
• build octahedron-pair：构造 corner/edge/face-sharing 双八面体。
• build octahedron-lattice：构造 2D corner-sharing 八面体晶格。
• motif find|summarize：识别配位 motif。
• graph export：导出 motif connectivity。
• export-ir：导出 Material IR。
• validate：按 YAML 规则校验结构。
• explain structure --profile：用论文 profile 解释结构语义。
• render structure：生成静态结构图。
• transform substitute：带规则守护的元素替换。