SPECTRAL_LOCALIZER
References: Dixon2023, Wong2026, Doll2025, Loring2015
Spectral localizer for isolated or two- and three-dimensionally periodic GPW/GAPW systems. Uses the full converged AO Hamiltonian, overlap, and analytic position or Berry integrals. Independent of KUBO_TRANSPORT and WANNIER90 Wilson/Z2/Chern or inversion-TQC analysis. Reports a finite-basis local index and protection gap, not a bulk-gap certificate. Requires convergence with basis, system size, and position/energy scale. [Edit on GitHub]
Keywords
Keyword descriptions
SECTION_PARAMETERS
Type: logical
Default: F
Lone keyword: T
Description: Activate post-SCF spectral localizer analysis. [Edit on GitHub]
DIMENSION
Type: integer
Default: 2
Description: Number of localizer position directions, 2 or 3. DIMENSION 3 uses all Cartesian moments (FINITE) or all three torus directions (PERIODIC). It requires Z2 and SOLVER DENSE; PERIODIC also requires CELL and POISSON PERIODIC XYZ. Its strong local Z2 index is not a tuple of weak indices or a 2D slice index. [Edit on GitHub]
ENERGY
Type: real[ ]
Default: 0.00000000E+000 [hartree]
Description: Absolute query energies, without a Fermi-level shift. All combinations of POSITION, ENERGY and KAPPA (FINITE) or ETA (PERIODIC) are evaluated. [Edit on GitHub]
EPS_ELECTRONIC_GAP
Type: real
Default: 1.00000000E-008 [hartree]
Description: Minimum resolved distance from ENERGY to the original generalized Hamiltonian spectrum before SPECTRAL_FLATTENING. Additional roundoff bounds apply. Separate from EPS_GAP, which applies to the final localizer. [Edit on GitHub]
EPS_FLATTENING
Type: real
Default: 1.00000000E-009
Description: Tolerance for the inverse and sign-square Frobenius residuals and relative complex-structure/Hermiticity residuals of the DBCSR matrix iterations. For the periodic Bloch path, checks translation covariance, metric orthonormality, eigenproblem residuals and final Hermiticity instead. An unconverged result is rejected, not used to report an index. [Edit on GitHub]
EPS_GAP
Type: real
Default: 1.00000000E-008 [hartree]
Description: Absolute localizer-gap threshold below which the index is unresolved. An additional roundoff threshold is always applied. [Edit on GitHub]
EPS_METRIC
Type: real
Default: 1.00000000E-010
Description: Minimum smallest/largest AO-overlap eigenvalue ratio. Ill-conditioned bases are rejected, not silently truncated. [Edit on GitHub]
ETA
Type: real[ ]
Default: 1.00000000E+000 [hartree]
Description: Positive energy scales for FORMULATION PERIODIC, multiplying the dimensionless trigonometric coordinates. Choose on the scale of H-ENERGY and check size/basis/ETA convergence. Replaces KAPPA for this formulation. The localizer and reported gaps retain energy units. [Edit on GitHub]
FLATTENING_SCALE
Type: real
Default: 1.00000000E+000 [hartree]
Description: Positive energy assigned to the positive bands by SPECTRAL_FLATTENING; negative bands receive its negative. ETA or KAPPA and output gaps retain their normal units but refer to this flattened Hamiltonian, not to the original band dispersion. [Edit on GitHub]
FORMULATION
Type: enum
Default: FINITE
Description: FINITE uses Cartesian first moments for PERIODIC NONE. PERIODIC uses analytic cos(G.r)/sin(G.r) integrals on a two- or three-dimensional Born-von-Karman torus. MP_GRID controls its size; this is not an independent localizer at each k. [Edit on GitHub]
Valid values:
FINITEPERIODIC
INVARIANT
Type: enum
Default: CHERN
Description: CHERN evaluates the 2D class A half-signature. Z2 evaluates the class AII Pfaffian sign (2D) or chiral-block determinant sign (3D); requires SOC and TIME_REVERSAL. [Edit on GitHub]
Valid values:
CHERNZ2
KAPPA
Type: real[ ]
Default: 1.00000000E-002 [bohr^-1*hartree]
Description: Positive energy/length scales. The default is not a converged choice; check a plateau under changes of KAPPA and system size. [Edit on GitHub]
MATRIX_TOLERANCE
Type: real
Default: 1.00000000E-009
Description: Relative Hermiticity and time-reversal residual tolerance. [Edit on GitHub]
MAX_AO
Type: integer
Default: 512
Description: Safety limit on scalar AO dimension for the dense solver. DENSE uses replicated localizers and source-rank diagonalization, quadratic memory and cubic runtime; the SOC Hermitian localizer has dimension 4NAO (DIMENSION 2) or 8NAO (DIMENSION 3). [Edit on GitHub]
MP_GRID
Type: integer[3]
Default: 1 1 1
Description: Full Gamma-centered analysis mesh for FORMULATION PERIODIC. Equivalent to a Gamma supercell with these replication factors, at the frozen SCF potential. Independent of the SCF KPOINTS scheme or symmetry reduction. Nonperiodic directions must have size one. MAX_AO applies to the entire torus, not the primitive cell. [Edit on GitHub]
PLANE
Type: enum
Default: XY
Description: Ordered Cartesian directions for FINITE; ordered lattice-vector directions for PERIODIC, which must match the two periodic CELL directions. Only valid for DIMENSION 2. [Edit on GitHub]
Valid values:
XYXZYZ
POSITION
Type: real[3]
Default: 0.00000000E+000 0.00000000E+000 0.00000000E+000 [bohr]
Repeatable: yes
Description: Cartesian query position in the coordinate frame of SUBSYS/COORD. For FINITE with DIMENSION 2 the component perpendicular to PLANE is ignored. For PERIODIC the reciprocal-cell phase G.r0 is used, including for oblique cells. Repeat for scans. [Edit on GitHub]
SOC
Type: logical
Default: F
Description: Add the GTH pseudopotential SOC operator to the restricted SCF Hamiltonian in the complete AO spinor space. Requires SOC parameters in the potentials; does not perform a self-consistent noncollinear calculation. [Edit on GitHub]
SOLVER
Type: enum
Default: DENSE
Description: Dense LAPACK reference calculation in the AO overlap metric. [Edit on GitHub]
Valid values:
DENSE
SPECTRAL_FLATTENING
Type: logical
Default: F
Description: Replace H-ENERGYS by FLATTENING_SCALESsign(S^-1(H-ENERGY*S)). Retains the full occupied and empty AO subspaces and leaves position operators unchanged. Requires a positive metric and a resolved electronic gap, checked before flattening. The resulting finite localizer can have a different index and gap from the unflattened one. No bulk-index or convergence certificate is implied. Computed once per ENERGY, using complete Bloch blocks for periodic tori or DBCSR matrix iterations for finite systems. Both retain the original AO basis and can increase fill-in. [Edit on GitHub]
SPIN_CHANNEL
Type: integer
Default: 1
Description: Scalar collinear spin channel, as in WANNIER90. SOC requires restricted channel 1. [Edit on GitHub]
TIME_REVERSAL
Type: logical
Default: F
Description: Assert physical spinful time reversal for Z2, as in WANNIER90. The Hamiltonian, metric and position operators are also checked numerically. [Edit on GitHub]