Metadata-Version: 2.4
Name: zstar
Version: 0.0.7
Summary: Zstar: A code for calculations of Born effective charge and dielectric responses.
Author-email: Xudong Zhu <zhuxudong@ustc.edu.cn>
License: GPL-3.0
Project-URL: Homepage, https://github.com/xdzhu/zstar
Project-URL: Repository, https://github.com/xdzhu/zstar
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: PyYAML>=5.4
Requires-Dist: matplotlib>=3.3
Requires-Dist: spglib>=2.6.0
Requires-Dist: phonopy>=2.36
Requires-Dist: pymatgen>=2024.0.0
Dynamic: license-file

<p align="center">
  <img src="docs/logo-zstar.png" alt="Zstar" width="180"><br>
  <b>Zstar</b>
  <br>
  <sub>ZStar: A code for calculations of Born effective charge and dielectric responses</sub>
</p>

<p align="center">
  <a href="https://github.com/yourname/zstar/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/yourname/zstar/ci.yml?branch=main"></a>
  <a href="https://pypi.org/project/zstar/"><img alt="PyPI" src="https://img.shields.io/pypi/v/zstar"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-GPL3.0-green.svg"></a>
</p>

---

# 简介

**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）

---

# 安装

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

需要依赖：
- Python 3.8+
- numpy, scipy, spglib, phonopy
- 运行时工具：ABACUS、PyATB

---

# 快速上手

## 1) 生成极化位移任务

```bash
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

计算完成后：

```bash
# 从位移目录收集数据并求 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`。

---

# 命令行用法

```bash
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）
```bash
zstar bornsym --stru 0.no-move/STRU --reduced Z-BORN-reduced.out
# 产出：Z-BORN-symm.out（全原子）、Z-BORN-reduced-neutral.out（primitive reduced）
```

## 校验（有 all）
```bash
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）
```bash
zstar deal --solo --pyatb
```

## 完整 Born（reduced-only，自动重建）
```bash
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（层状或薄膜）
```bash
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 等相应工具）。
