vasp-symmetry

VASP 结构对称性分析工具包 — 自动识别空间群、对称操作，支持 k 点小群分析、k·p 模型推导、压电与自旋霍尔张量

Python · spglib · 晶体学 · VASP

简介

vasp-symmetry 是一个专为 VASP 用户设计的 Python 工具包，用于分析 POSCAR 文件中的晶体对称性。 它基于 spglib 引擎，能够检测并分类所有对称操作，包括旋转轴、镜面、反演中心、滑移面和螺旋轴， 并以清晰的矩阵形式输出。此外，还支持对指定 k 点进行小群（Little Group）分析，是能带结构研究和 对称性分析的重要辅助工具。

安装

依赖

需要 Python 3.10+ 和以下包：

pip install numpy scipy spglib pymatgen

下载

git clone https://github.com/yingjwei/vasp-symmetry.git
cd vasp-symmetry

运行

# Windows
python run.py POSCAR

# Linux / macOS
python3 run.py POSCAR

使用指南

交互菜单模式（推荐）

运行后自动显示任务菜单，选择编号即可执行。

python run.py POSCAR

详细模式（含矩阵）

输出每个对称操作的 3x3 旋转矩阵和平移向量。

python run.py POSCAR --detail

高对称 k 点

自动列出该晶系的常见高对称 k 点及其小群。

python run.py POSCAR --high-sym

k 点小群分析

指定 k 点的分数坐标，分析其小群对称性。

python run.py POSCAR -k 0 0 0 --label G

k 路径分析

沿高对称路径追踪每个 k 点的点群变化。

python run.py POSCAR --path "G,0,0,0 X,0.5,0,0.5"

对称操作对 (k, σ) 作用

每个对称操作对 k 矢量和自旋 Pauli 矩阵的变换。

python run.py POSCAR --pauli-action

交互菜单

执行 run.py POSCAR（不指定任务参数）会自动进入交互菜单模式，从列表中选择任务编号即可：

============================================================
  vasp-symmetry 任务选择
============================================================
   1) 对称性分析 (空间群+对称操作分类)
   2) k 路径小群分析 (自动推荐路径)
   3) 指定 k 点小群分析
   4) 高对称 k 点列表
   5) k.p 模型
   6) 压电 & 自旋霍尔张量
   7) 对称操作对 (k,sigma) 作用
   8) 全部功能依次执行
   0) 退出
============================================================
  请选择 [0-8]:

菜单选项 2（k 路径分析）会根据晶系自动推荐标准高对称路径，直接选择编号即可，无需手动输入坐标。

功能详解

对称操作分类

工具将 spglib 检测到的对称操作自动分类为：

类型符号说明示例
恒等E不做任何变换所有结构
旋转轴Cn绕某轴旋转 360°/nC2, C3, C4, C6
镜面σ关于某平面的反射法向 [100]
反演i通过原点的中心反演—
滑移面a/b/c/n/d镜面 + 面内平移d-滑移 (金刚石)
螺旋轴nm旋转 + 轴向平移41, 21
非真旋转Sn旋转 + 垂直面反射S4, S6

小群（Little Group）

给定倒空间 k 点，小群是空间群中使该 k 点保持不变的对称操作子集 （模倒格矢）。小群决定了该 k 点的能带简并度和选择定则。 工具自动给出小群的点群符号和操作列表。

输出格式

摘要模式输出：空间群号、HM 符号、点群、各类型对称操作计数。

详细模式额外输出每个操作的 3×3 旋转矩阵和分数坐标平移向量。

对称操作对 (k, σ) 的作用

每个空间群对称操作 (R|τ) 作用于倒空间 k 矢量和自旋空间 Pauli 矩阵 σ 的方式为：

使用 --pauli-action 可以输出每个操作的这三种变换表达式。

k·p 模型（对称性约束）

给定 k 点的小群，k·p 方法将哈密顿量展开为 k 多项式的级数： 

H(k) = Σ fn(k) · Mn

其中 fn(k) 是 k 的齐次多项式，Mn 是自旋空间的 2×2 矩阵（Pauli 基）。 工具自动找出满足所有小群对称操作不变性的项，即： 

D(R)† H(R·k) D(R) = H(k)

使用 --kp（默认 Γ 点）和 --kp-order N 指定展开阶数。

压电张量 eijk

压电效应描述应变 εjk 诱导的电极化 Pi = eijk εjk。 三阶压电张量 eijk 受 Neumann 原理约束。工具从 POSCAR 的 实际对称操作出发，对全秩张量施加变换约束 (e'ijk = RilRjmRkn elmn)， 自动过滤出所有对称允许的非零分量，并以 3×6 Voigt 矩阵（VASP 约定: xx yy zz xy yz zx）输出。

使用 --tensor 输出。工具基于 POSCAR 的实际对称操作进行推导，不依赖标准取向假设，结果始终正确。

自旋霍尔电导 σ^{s}_{ik}

自旋霍尔效应描述电场 Ek 诱导的自旋电流 Jis = σ^{s}_{ik} Ek。 上标 s 为自旋极化方向，下标 i,k 分别为电流和电场方向。 由于自旋极化方向是轴矢，变换规则多一个 det(R) 因子： 

σ^{s}_{ik} → det(R) · Rii' Rkk' Rss' σ^{s'}_{i'k'}

使用 --tensor 一并输出。

实例分析：金刚石硅 (Diamond Si)

POSCAR 文件：

Diamond Si
    5.4307
  0.0  0.5  0.5
  0.5  0.0  0.5
  0.5  0.5  0.0
  Si
  2
Direct
  0.000000  0.000000  0.000000
  0.250000  0.250000  0.250000

运行分析：

python run.py examples/POSCAR_Si
============================================================ 空间群 (国际号): #227 空间群 (HM 符号): Fd-3m 点群: m-3m 对称操作总数: 48 ============================================================ 恒等操作: E 反演中心: i C2 旋转轴: 3 个 C3 旋转轴: 8 个 镜面: 6 个 滑移面: 3 个 螺旋轴: 12 个

k 点小群分析

python run.py examples/POSCAR_Si --high-sym
高对称 k 点: Γ (0.0000, 0.0000, 0.0000) → 小群: Oh 对称操作: 48 X (0.5000, 0.0000, 0.5000) → 小群: D2h 对称操作: 8 R (0.5000, 0.5000, 0.5000) → 小群: Oh 对称操作: 48 M (0.5000, 0.5000, 0.0000) → 小群: D2h 对称操作: 8
python run.py examples/POSCAR_Si -k 0 0 0 --label G -k 0.5 0 0.5 --label X
k 点: Γ (0.0000, 0.0000, 0.0000) 小群点群: Oh 对称操作数: 48 k 点: X (0.5000, 0.0000, 0.5000) 小群点群: D2h 对称操作数: 8

k 路径分析

python run.py examples/POSCAR_Si --path "G,0,0,0 X,0.5,0,0.5 L,0.5,0.5,0.5 G,0,0,0"
Γ → Oh (48 ops) Γ→X#1 → Cs (2 ops) X → D2h (8 ops) X→L#1 → C2h (4 ops) L → Oh (48 ops) L→Γ#1 → C3v (6 ops) L→Γ#5 → Td (24 ops) L→Γ#6 → C3v (6 ops) Γ → Oh (48 ops)

k·p 模型

python run.py examples/POSCAR_Si --kp --kp-order 2
k·p 模型（对称性允许项，最高阶数 = 2） 第 0 阶 (1 项): 1 × I H(k) = + 1 * I

对于 Fd-3m (Oh 点群)，Γ 点仅有恒等项对称允许（所有 48 个对称操作严格约束）。 对于更低对称性的结构，允许项会显著增多，例如 C2v 在 Γ 点允许 Pauli 矩阵项：

# C2v (mm2) k·p 模型在 Γ 点的输出:
第 1 阶 (3 项):
  k_z    ×  I
  k_y    ×  σ_x      ← 对称操作变换互相抵消
  k_x    ×  σ_y      ← 导致 Pauli 项允许

第 2 阶 (6 项):
  k_z^2  ×  I
  k_y^2  ×  I
  k_x^2  ×  I
  k_y*k_z × σ_x
  k_x*k_z × σ_y
  k_x*k_y × σ_z

每个 f(k) × σ_i 项之所以被允许，是因为 k 多项式的变换恰好抵消了 Pauli 矩阵的变换（例如 ky → -ky 而 σx → -σx， 乘积不变）。这正是 k·p 模型的核心：找出所有满足 D(R)† H(R·k) D(R) = H(k) 的项。

压电与自旋霍尔张量

python run.py examples/POSCAR_Si --tensor
压电张量 (P_i = e_ijk ε_jk) 点群 Oh: 所有分量为 0（有反演中心或对称性禁止） 自旋霍尔电导张量 (J_i^s = σ^{s}_{ik} E_k) 点群 Oh: 所有分量为 0（有反演中心或对称性禁止）

金刚石硅具有反演中心（Oh 点群），因此压电效应和自旋霍尔效应均为零。对于无中心对称的晶体（如 GaAs，Td 点群），则允许非零分量。

输出解读

输出项含义
空间群 (国际号)Hermann-Mauguin 空间群编号（1–230）
空间群 (HM 符号)如 Fd-3m, Fm-3m, P4/mmm 等
点群如 m-3m (Oh), 4/mmm (D4h) 等
旋转矩阵 R3×3 整数矩阵，作用在分数坐标上
平移向量 τ分数坐标下的平移分量
C2 [1 1 -1]绕 [111] 方向的 180° 旋转轴
σ 法向: [100]法向量为 [100] 的镜面
d-滑移对角滑移面（金刚石型滑移），滑移分量 (a±b)/4
4₁ 螺旋四次螺旋轴，螺距为 1/4 晶格常数
k → R·k对称操作对 k 矢量的变换（分数坐标）
σi → det(R)·Rij σj对称操作对 Pauli 矩阵的变换
H(k) = Σ fn(k) Mnk·p 哈密顿量展开（对称性允许项）
eijk压电张量（Neumann 原理约束）
σ^{s}_{ik}自旋霍尔电导张量（轴矢变换，上标 s=自旋方向）
提示: 旋转矩阵和平移向量完整定义了对称操作 (R|τ)： 空间中的点 x 经过操作后变为 x' = R·x + τ。

程序调用（Python API）

在 Python 脚本或 Jupyter Notebook 中调用：

from vasp_symmetry import (
    read_poscar, SymmetryAnalyzer, LittleGroupAnalyzer,
    KpModel, PiezoelectricTensor, SpinHallTensor,
    analyze_operation_action, full_tensor_report,
)

# 1. 读取 POSCAR
struct = read_poscar("POSCAR")

# 2. 对称性分析
analyzer = SymmetryAnalyzer(struct)
result = analyzer.analyze()
print(f"空间群: #{result.spacegroup_number} {result.spacegroup_symbol}")
print(f"对称操作数: {len(result.operations)}")

# 3. 小群分析 (Gamma 点)
lg = LittleGroupAnalyzer(analyzer)
r = lg.analyze_kpoint([0, 0, 0], label="Gamma")
print(f"{r.kpoint_label}: {r.pointgroup}, {r.num_operations} ops")

# 4. 对称操作对 (k, sigma) 作用
info = analyze_operation_action(result.operations[0], result.lattice)
print(info.report())

# 5. k.p 模型 (基于 Gamma 点小群)
kp = KpModel(r.operations, result.lattice)
print(kp.report(max_order=2))

# 6. 压电张量 (基于实际对称操作推导)
pe = PiezoelectricTensor(ops=result.operations, lattice=result.lattice)
print(pe.report())

# 7. 自旋霍尔电导 (基于实际对称操作推导)
sh = SpinHallTensor(ops=result.operations, lattice=result.lattice)
print(sh.report())

# 8. 综合报告 (基于实际对称操作推导)
print(full_tensor_report(analyzer))

自旋霍尔电导 σ^{s}_{ik}

轴矢张量变换（额外 det(R) 因子）。从对称操作直接推导，不依赖标准取向假设。 输出格式为 σ^{s}_{i,k}，上标 s 为自旋极化方向，下标 i,k 分别为电流和电场方向。

from vasp_symmetry import SpinHallTensor
sh = SpinHallTensor(ops=result.operations, lattice=result.lattice)
print(sh.report())

综合报告

一键输出 (k,σ) 作用、k·p 模型、压电和自旋霍尔张量（基于实际对称操作推导）。

from vasp_symmetry import full_tensor_report
print(full_tensor_report(analyzer))