zstar 0.0.2

Zstar: A code for calculations of Born effective charge and dielectric responses.

Zstar
_{Version 0.0.1 · A Python Kit for Ab-initio Polarization & Phonon Analysis}

---

简介

zstar 是面向极化与声子流程的轻量工具集，围绕 ABACUS / PyATB 生态做了高通量与易用性增强。核心能力：

• 一键生成极化/声子输入、批量位移计算与后处理；
• 统一极化单位为 C/m²，透明支持 ABACUS 与 PyATB 两套 nscf 框架；
• 基于空间群与 Wyckoff 对称性，最小计算集（reduced/加星号原子）重建全原子 BORN 有效电荷，并强制满足电荷中性；
• 产物自动组织（Z-BORN-reduced.out, Z-BORN-symm.out, BORN-for-phonopy.out 等），与 phonopy 兼容。

若你只看两个文件：
Z-BORN-symm.out（全原子、对称性+中性修正）
Z-BORN-reduced-neutral.out（仅 reduced 原子、对称性+中性修正，喂给 Phonopy）

---

安装

pip install zstar-*.whl
# 或 cd 到源码目录
pip install .

需要依赖：

• Python 3.8+
• numpy, scipy, spglib, phonopy
• 运行时工具：ABACUS、PyATB

---

快速上手

1) 生成极化位移任务

zstar gen
# 或者定义参数
zstar gen --stru STRU --kspacing 0.1 --force --all

基于有限差分法，生成 0.no-move 与每个位移目录。 参数要点：

• --abacus / --pyatb：选择 NSCF 框架（默认 PyATB，已全部支持PyATB）。
• --input-mode {abacus|pyatb|hamgnn|custom}：输入准备模式（支持拷贝自定义脚本与模板）。
• --input_sets "abacus.sh hamgnn.yaml"：自定义需要拷贝的文件或目录（支持空格分隔）。

2) 计算 → 处理 BORN

计算完成后：

# 从位移目录收集数据并求 BORN（默认 PyATB；ABACUS 用 --abacus）
zstar deal

# 仅提取极化/极化向量（与 zstar polar 等价）
zstar deal --solo

得到的关键文件：

• Z-BORN-reduced.out：reduced 原子的原始张量（未中性修正）
• Z-BORN-symm.out：全原子，对称性映射 + 中性修正
• Z-BORN-reduced-neutral.out：reduced 原子，对称性映射 + 中性修正
• BORN-for-phonopy.out：第 2 行是介电张量，后续每行为一个 reduced Born（供 Phonopy）

注意：不再生成 Z-BORN-all-neutral.out。仅当目录中确实计算了所有原子时才写 Z-BORN-all.out。
reduced-only 场景会用对称性自动重建 Z-BORN-symm.out 与 Z-BORN-reduced-neutral.out。

---

命令行用法

zstar -h
zstar gen   [--pyatb|--abacus] [--input-mode MODE] [--input_sets FILES] [--move "x y z"] ...
zstar deal  [--solo] [--pyatb|--abacus] [--dim 2|3] ...
zstar polar [同 deal，默认 --solo]
zstar ph    --stru STRU --dim "1 1 1" ...
zstar postph [--nac] ...
zstar wyckoff --stru STRU
zstar vasp   --stru STRU
zstar symcheck --stru STRU --reduced Z-BORN-reduced.out --all Z-BORN-all.out
zstar bornsym --stru STRU --reduced Z-BORN-reduced.out

• symcheck：校验模式（必须有 --all），生成详细报告与对比。
• bornsym：生成模式（无 --all），基于对称性从 reduced 重建全原子与 reduced-neutral。

---

新特性（v1.2.0）

• ✅ 极化单位统一为 C/m²：自动识别 ABACUS 的三种输出（(e/Ω).bohr, e/bohr^2, C/m^2），统一转换。
• ✅ NSCF 框架默认 PyATB：--pyatb/--abacus 即时切换。
• ✅ reduced-only → 全原子 BORN 重建：基于空间群与 Wyckoff 对称性，把最小计算集扩展为全原子，外加电荷中性修正。
• ✅ BORN-for-phonopy.out 正规化：第 2 行为介电张量，后面仅写 primitive reduced-neutral 的 3×3。
• ✅ 输入准备：--input-mode {abacus|pyatb|hamgnn|custom} 与 --input_sets 支持批量拷贝脚本/模板。
• ✅ 更好的日志：gen_polar.out 打印入参；对关键步骤给出提示与警告。
• ✅ 2D/3D 统一：--dim 2 时按 2D 流程解析与计算（含 PyATB/ABACUS）。

BREAKING：

• ❌ 移除 Z-BORN-all-neutral.out（无对称性约束，不具物理意义）；
• ✅ 统一使用 Z-BORN-symm.out 与 Z-BORN-reduced-neutral.out。

---

对称性重建/校验

生成（无 all）

zstar bornsym --stru 0.no-move/STRU --reduced Z-BORN-reduced.out
# 产出：Z-BORN-symm.out（全原子）、Z-BORN-reduced-neutral.out（primitive reduced）

校验（有 all）

zstar symcheck --stru 0.no-move/STRU --reduced Z-BORN-reduced.out --all Z-BORN-all.out
# 产出：born_symmetry_report.txt / .json / .csv（可选）

屏幕会展示：

Born tensor symmetry verification
Structure : 0.no-move/STRU
Symprec   : 0.001
Natoms    : 6
SpaceGroup: P4_2/nmc (No.137)
...

并对每个等价类按变换矩阵 R 预测 Z_pred = R · Z_ref · R^T，与参考逐元素比较。

---

文件与输出说明

• Z-BORN-reduced.out

• 在计算完成后直接生成的不可约原子的原始BORN有效电荷，此时未进行电中性处理。

  No. Atom      xx      xy      xz      yx      yy      yz      zx      zy      zz
  *   1 Zr    5.822   0.000   0.000   0.000   5.822   0.000   0.000   0.000   4.985
  *   3 O    -2.122   0.000   0.000   0.000  -3.700   0.000   0.000   0.000  -2.498
  

  仅 reduced/加星号原子，未中性修正。

• Z-BORN-symm.out
  全原子，按对称性扩展 + 电中性修正。

  No. Atom    xx      xy      xz      yx      yy      yz      zx      zy      zz
  *  1 Zr   5.822   0.000   0.000   0.000   5.822   0.000   0.000   0.000   4.982
     2 Zr   5.822   0.000   0.000   0.000   5.822   0.000   0.000   0.000   4.982
  *  3 O   -2.122   0.000   0.000   0.000  -3.700   0.000   0.000   0.000  -2.491
     4 O   -3.700   0.000   0.000   0.000  -2.122   0.000   0.000   0.000  -2.491
     5 O   -2.122   0.000   0.000   0.000  -3.700   0.000   0.000   0.000  -2.491
     6 O   -3.700   0.000   0.000   0.000  -2.122   0.000   0.000   0.000  -2.491
  

• Z-BORN-reduced-neutral.out
  仅 reduced/加星号原子，已经对称性扩展+中性修正（用于 Phonopy）。

  No. Atom    xx      xy      xz      yx      yy      yz      zx      zy      zz
  *   1 Zr  5.822   0.000   0.000   0.000   5.822   0.000   0.000   0.000   4.982
  *   3 O  -2.122   0.000   0.000   0.000  -3.700   0.000   0.000   0.000  -2.491
  

• BORN-for-phonopy.out 与 BORN 文件

  #   xx      xy      xz      yx      yy      yz      zx      zy      zz      
    5.166   0.000   0.000   0.000   5.166   0.000   0.000   0.000   4.548  <-电子介电张量
    5.822   0.000   0.000   0.000   5.822   0.000   0.000   0.000   4.982  <-reduced #1
   -2.122   0.000   0.000   0.000  -3.700   0.000   0.000   0.000  -2.491  <-reduced #3
  

---

例子

仅做极化（solo）

zstar deal --solo --pyatb

完整 Born（reduced-only，自动重建）

zstar gen --pyatb --move "x y z" --force
# …跑完子任务后：
zstar deal --pyatb    # 得到 Z-BORN-reduced.out
# 自动调用对称性重建 → Z-BORN-symm.out & Z-BORN-reduced-neutral.out

2D（层状或薄膜）

zstar gen --dim 2 --pyatb
zstar deal --dim 2 --pyatb

---

常见问题

Q: 为什么不再生成 Z-BORN-all-neutral.out？
A: 因其不满足对称性约束，物理意义弱。统一用 Z-BORN-symm.out（全原子、含中性与群对称）与 Z-BORN-reduced-neutral.out（给 Phonopy）。

Q: 默认 NSCF 框架是？
A: PyATB。用 --abacus 切回 ABACUS。

---

变更摘要

• 1.2.0

  • 统一极化单位到 C/m²（自动转换 ABACUS 三种格式）
  • 支持 PyATB/ABACUS；默认 PyATB
  • 对称性重建全原子 Born + 电中性修正
  • 新增 symcheck / bornsym
  • 重构 BORN-for-phonopy.out 格式
  • 输入准备模式：--input-mode 与 --input_sets
  • 移除 Z-BORN-all-neutral.out

• 1.0.0

  • 初始发布

---

许可证

GPL-3.0 © Xudong Zhu

---

引用

若本项目对你的研究工作有帮助，请在论文中引用 zstar（以及 ABACUS/PyATB/Phonopy 等相应工具）。