nku-vasp-cli

v0.4.1

Published

a month ago

Agent-first materials CLI — build, edit, and inspect 2D materials and catalytic interfaces with 1-4 token commands. Auto-renders PNG + Markdown summary for multimodal-agent self-verification.

0High
0Medium
0Low

aiden_novak_ai

agent ai-cli llm vasp materials pymatgen cli motif crystal-structure 2d-materials mos2 graphene hbn heterostructure supercell

mat — agent-first materials CLI

mat 是一个写给 AI agent 用的材料结构 CLI。它把构造、扰动、解释 2D 材料和催化界面所需的全部原子级操作，压缩到 1–4 个 token 的命令里，并且每次操作都自动产出 .png 渲染图 + .summary.md 摘要，方便多模态 agent 直接看图判断"这一步做对了没"。

设计灵感来自 GitHub gh：用 /resource verb 把长尾能力 RESTful 化，用顶层 command 表达高层意图，用 --json / --jq / -q 统一裁剪输出，避免污染 LLM 的 context。

30 秒上手

pip install -e .

mat init -q                              # 起一个 run 目录
mat build mos2 -q                        # 造一个 MoS2 单层
mat motifs                               # 看配位 motif
mat strain 2% -q                         # 施 2% 双轴应变
mat perturb vacancy=S:1 -q               # 抠掉 1 个 S 原子
mat                                      # 看当前 context + 下一步建议

每条会改/造结构的命令完成后，run 目录里自动多出三个文件：

runs/001-run/mos2.vasp           ← 结构
runs/001-run/mos2.png            ← 自动渲染
runs/001-run/mos2.summary.md     ← 摘要（formula / lattice / motifs / sites）

mos2

为什么是 agent-first

| 痛点（普通 CLI） | mat 的设计 | |---|---| | 命令爆炸，agent 要记 50+ 个子命令 | 顶层只 ~20 个高层命令 + /resource verb 路径覆盖长尾 | | 输出动辄上千 token，污染 context | 默认人类可读、--json --jq 精确裁剪 | | 每个命令都要重传文件路径 | 隐式 context：上一步的输出自动是下一步的输入 | | 操作完不知道做对没 | 每次自动出 .png 让多模态 agent 自检 | | 没有可复现的日志 | run 目录 + .summary.md 自动落盘 |

命令家族（一句话各自做什么）

| 命令 | 作用 | |---|---| | mat | 0 参数 = 当前 context 状态 + 下一步建议（像 git status） | | mat init | 起一个编号 run 目录 | | mat build <kind|alias> | 造结构（mos2 / graphene / hbn / bi / monolayer / bilayer / slab / ...） | | mat get [file] | 看结构信息（智能路由：file / mp-id / run-id 都行） | | mat list <thing> | 列资源（motifs / runs / recipes / ...） | | mat motifs | 列当前结构的配位 motif | | mat sites | 列当前结构的原子 (idx, element, cart, frac) | | mat strain <spec> | 对当前结构施应变（2% / a:1%,b:-0.5%） | | mat vacuum <Å> | 改 2D 真空层厚度 | | mat recenter | 把 slab 重新居中 | | mat perturb <ops...> | 复合编辑（vacancy / substitute / displace / shift / rotate / interlayer / strain / vacuum，可链式） | | mat verify rules.yaml | 按规则校验结构 | | mat explain profile.yaml | 按 profile 解释结构 | | mat reproduce x.recipe.yaml | 跑一篇论文的复现 recipe | | mat materials | 列内置 material 别名表 | | mat status | 看当前 run 的进度 |

资源（长尾能力）：mat /<path> <verb>，5 个动词收敛：list / get / create / update / delete（recipes 多一个 run）。

mat /motifs list center=Mo ligand=S
mat /lattice update strain=2%
mat /sites update set=0=z:7.5
mat /vasp-inputs create profile=mp-relax-pbe
mat /mp/mp-2815 get

单字母缩写：/m /s /l /r /a /d /b /si /v /rec。

自动产物（写给 agent 看）

每个会写结构的命令完成后，CLI 在结构文件旁边生成 2 个附属文件：

| 文件 | 给谁看 | 内容 | |---|---|---| | *.vasp | 下游 DFT 计算 | 标准 POSCAR | | *.png | 多模态 agent / 人 | 3D 科学渲染（Blender 优先，自动回退 matplotlib），含原子球、键、晶胞线框 | | *.summary.md | 文本 agent | formula / lattice / 2D slab+vacuum / motifs / sites 表 |

*.summary.md 长这样（示例为 mos2.summary.md）：

# mos2.vasp

*Produced by* `build.monolayer` *at* `2026-05-25 07:06:10`

![structure](mos2.png)

## Composition
- formula: **MoS2**
- sites: 3  (2 species)
- elements: Mo S

## Lattice
- a, b, c: `3.1600  3.1600  15.0000` Å
- angles : α=`90.00` β=`90.00` γ=`120.00`°
- volume : `129.7167` Å³

## 2D layer (along c)
- slab z range: `[5.94, 9.06]` Å
- slab thickness: `3.12` Å
- vacuum (c − slab): `11.88` Å

## Motifs
- `SMo3_trigonal` × 2
- `MoS6_octahedral` × 1

## Sites (first 20) ...

CI / 批处理中关闭：export MAT_NO_ARTIFACTS=1。

渲染后端

PNG 渲染默认优先使用 Blender（publisher-grade 科学渲染：Eevee 引擎、emission-only 材质、正交投影、Jmol 元素配色）。若 Blender 不可用则自动回退 matplotlib。

安装 Blender（可选，强烈推荐）：

# macOS（推荐）
brew install --cask blender

# macOS（手动）
# 从 https://www.blender.org/download/ 下载 DMG，双击挂载后拖入 /Applications

# Linux
sudo snap install blender --classic

安装后运行一次配置脚本：

bash setup_blender.sh

该脚本自动检测 Blender 路径并写入 ~/.zshenv（MAT_BLENDER_BIN）。后续所有 mat 命令的 PNG 产物即自动使用 Blender 渲染。

文档

详细文档在 docs/site/（12 页，每页配示意图）：

安装

git clone <repo> vasp-cli
cd vasp-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
mat --help

依赖：Python ≥ 3.10、pymatgen、numpy、matplotlib（渲染图用）、PyYAML。

环境变量

| 变量 | 作用 | |---|---| | MAT_STRUCTURE | 强制覆盖"当前结构"（任何命令都优先用它） | | MAT_RUN_DIR | 覆盖"当前 run 目录"（auto-out 路径会落在这里） | | MAT_NO_ARTIFACTS=1 | 跳过 PNG + summary.md 生成（CI 用） | | MP_API_KEY | Materials Project API key（/mp 资源用） |

License

nku-vasp-cli is dual-licensed:

AGPL-3.0-or-later for academic, personal, research, non-profit, and open-source use — see LICENSE.
Commercial license for closed-source / SaaS / proprietary integration — see COMMERCIAL.md or email [email protected].

If you use nku-vasp-cli in any way (including AGPL community use), you must preserve the NOTICE file and the citation block below.

Citation

If nku-vasp-cli contributed to a paper, preprint, thesis, technical report, or any other published work, please cite it:

@software{novak2026nkuvaspcli,
  author       = {Novak, Aiden},
  title        = {nku-vasp-cli: agent-first materials CLI},
  year         = {2026},
  version      = {0.3.3},
  url          = {https://github.com/AidenNovak/nku-vasp-cli},
  note         = {Agent-first command-line tool for 2D materials and
                  catalytic interfaces with auto-rendered PNG / Markdown
                  artifacts for multimodal-agent self-verification.}
}

GitHub also surfaces a "Cite this repository" button driven by CITATION.cff — click it for APA / BibTeX / RIS exports.

Commercial use

The AGPL-3.0 license requires that any derivative work, including software offering nku-vasp-cli functionality over a network (SaaS), be released under the AGPL with full source available.

If that does not fit your business — e.g. you want to embed nku-vasp-cli in a closed-source product, internal commercial pipeline, or hosted service without open-sourcing your own code — please get a commercial license by emailing [email protected] with subject [nku-vasp-cli] commercial license inquiry. Details and what to include in the email: COMMERCIAL.md.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme