z2-invariant

---
name: z2-invariant
description: Use when computing a Z2 topological invariant for a time-reversal-invariant insulator in 2D or 3D. Triggers on Z2, Z2 不变量, 拓扑不变量, 时间反演不变量, 量子自旋霍尔, 宇称判据, Fu-Kane, Kane-Mele, parity invariant, parity criterion, TRIM, time-reversal polarization, partner switching, quantum spin Hall, QSH, strong/weak topological insulator, ν0, "compute Z2".
license: MIT
---

# Z2 Invariant

## Repository contract
Repository-local instructions and explicit user constraints override this skill's defaults where they apply. Otherwise, follow this skill's default workflow and artifacts. Do not import rules from a different workflow category. Never commit, tag, or push unless that specific Git action is authorized by the user or repository policy.

## Overview
The ℤ₂ invariant classifies TRS insulators (class AII): ν=1 topological (odd), ν=0 trivial. In 2D one
ν; in 3D four (ν₀; ν₁ν₂ν₃). Requires TRS with T²=−1 (verify with `symmetry-analysis` first).

## Three routes (prefer 1)
1. **WCC / Wilson-loop partner switching** — general, needs no extra symmetry. Compute WCC flow over
   half the BZ (see `wilson-loop-wcc`); ν = number of times Kramers partners switch, mod 2. Robust and
   gauge-invariant; the default.
2. **Fu–Kane parity** — *only if inversion symmetry is present*: ν = ∏ over TRIM of the product of
   parity eigenvalues of occupied Kramers pairs. Cheap, but inversion-only.
3. **Direct integral of A/Ω over half BZ** — gauge-dependent, fragile; avoid unless you enforce a smooth
   gauge.

## Common mistakes
- Using Fu–Kane parity when the model has no inversion symmetry (invalid).
- Computing ℤ₂ on a model whose T²=−1 you never verified (wrong class).
- Miscounting partner switches from too few k-points (converge the WCC flow).

Verifies against edge counting via `edge-states-bulk-boundary` (an odd ν ⇒ odd number of Kramers edge
pairs).