<!-- prettier-ignore-start -->

## Phase 116: Kalika Electronic Structure Foundation — Kohn-Sham DFT, Exchange-Correlation Functionals, Pseudopotentials, Band Structure & Wannier Functions

Density Functional Theory (DFT) is the single most widely used method in
computational materials science and condensed matter physics. Founded on the
Hohenberg-Kohn theorems (1964) and the Kohn-Sham ansatz (1965), DFT maps the
intractable many-electron Schrodinger equation to a set of single-particle
equations in an effective potential determined self-consistently from the
electron density. This reformulation reduces the computational cost from
exponential (wavefunction-based methods) to O(N^3) or better, enabling
first-principles calculations of systems with hundreds to thousands of atoms.
DFT predicts crystal structures, electronic band structures, formation energies,
elastic properties, phonon spectra, magnetic ordering, surface chemistry, defect
energetics, and countless other materials properties with no empirical fitting
parameters. It is the workhorse behind materials databases (Materials Project,
AFLOW, OQMD, NOMAD), high-throughput screening, and computational materials
discovery.

This phase implements a complete, production-quality DFT engine within Kalika
targeting feature parity with and algorithmic improvements over the leading
codes: VASP (plane-wave PAW, industry standard), Quantum ESPRESSO (open-source
plane-wave, norm-conserving and ultrasoft pseudopotentials), ABINIT (plane-wave,
PAW, response functions), and FHI-aims (numeric atom-centered orbitals,
all-electron). The engine uses Rust for all performance-critical compute kernels
(SCF loop, FFT, eigensolvers, plane-wave operations) compiled to both WASM (via
wasm-pack for browser/Node.js) and native (via napi-rs for server-side HPC),
TypeScript for workflow orchestration, job management, input/output parsing, and
API surfaces, and Python for ML-accelerated functionals and interoperability
with existing DFT ecosystem tools. Every algorithm references the original paper
or authoritative implementation to ensure correctness and reproducibility.

---

### 116.1 Project Scaffolding & Core Types (`@kalika/electronic-structure`)

#### 116.1.1 Monorepo Integration

- [x] **116.1.1.1** Create `libs/kalika/electronic-structure/` directory
      structure with subdirectories: `src/`, `src/types/`, `src/plane-wave/`,
      `src/pseudopotential/`, `src/scf/`, `src/xc/`, `src/band-structure/`,
      `src/wannier/`, `src/optimization/`, `src/charge-analysis/`,
      `src/parallel/`, `tests/`, `rust/` (Cargo workspace for Rust kernels)
- [x] **116.1.1.2** Create `project.json` for `@kalika/electronic-structure`
      with Nx build (esbuild), test (vitest), and lint targets; add dependency
      edges to `@kalika/core`, `@kalika/numerical-engine`, `@kalika/cas-engine`,
      `@kalika/algebra`
- [x] **116.1.1.3** Create `package.json` for `@kalika/electronic-structure`
      with `catalog:` refs for vitest, typescript, tsup; add runtime
      dependencies on `@kalika/core`, `@kalika/numerical-engine`
- [x] **116.1.1.4** Create `tsconfig.json` extending workspace
      `tsconfig.base.json` with strict mode, `composite: true`, path references
      to dependency projects
- [x] **116.1.1.5** Add `@kalika/electronic-structure` path mapping to
      `tsconfig.base.json`:
      `"@kalika/electronic-structure": ["libs/kalika/electronic-structure/src/index.ts"]`
- [x] **116.1.1.6** Create `libs/kalika/xc-functionals/` directory structure
      with `project.json`, `package.json`, `tsconfig.json` for the standalone XC
      functional library `@kalika/xc-functionals`
- [x] **116.1.1.7** Create `libs/kalika/wannier/` directory structure with
      `project.json`, `package.json`, `tsconfig.json` for the Wannier function
      library `@kalika/wannier`
- [x] **116.1.1.8** Add `@kalika/xc-functionals` and `@kalika/wannier` path
      mappings to `tsconfig.base.json`
- [x] **116.1.1.9** Initialize Rust workspace in
      `libs/kalika/electronic-structure/rust/` with `Cargo.toml` (workspace
      members: `pw-engine`, `scf-solver`, `eigensolver`, `fft-kernel`,
      `xc-kernel`), configure `wasm-pack` and `napi-rs` dual-target builds
- [x] **116.1.1.10** Create barrel exports in `src/index.ts` for all public
      types, classes, factories, and constants; ensure tree-shaking
      compatibility with explicit named exports
- [x] **116.1.1.11** Configure Rust-to-WASM build pipeline:
      `wasm-pack build --target nodejs` for each Rust crate; generate TypeScript
      type definitions from Rust structs via `tsify`; create npm-compatible WASM
      package with `.wasm` binary, JS glue code, and `.d.ts` type definitions
- [x] **116.1.1.12** Configure Rust-to-native build pipeline via `napi-rs`:
      create `#[napi]` bindings for all Rust compute kernels; build `.node`
      native addon for x86_64 and aarch64; implement feature-flag toggling
      between WASM and native at runtime based on environment detection
- [x] **116.1.1.13** Create shared constants module: physical constants (Bohr
      radius a_0 = 0.529177 Angstrom, Hartree = 27.2114 eV, Rydberg = 13.6057
      eV, hbar, electron mass, Boltzmann constant k_B), conversion factors
      (Angstrom <-> Bohr, eV <-> Hartree <-> Ry <-> kcal/mol <-> kJ/mol, GPa <->
      kbar <-> eV/Angstrom^3), and numerical tolerances for convergence checks

#### 116.1.2 Core Crystallographic Types

- [x] **116.1.2.1** Implement `LatticeVectors` type: 3x3 matrix of real-space
      lattice vectors (a1, a2, a3) in Angstroms; methods for volume computation
      (a1 . (a2 x a3)), reciprocal lattice construction (b_i = 2pi (a_j x a_k) /
      V), metric tensor (g_ij = a_i . a_j), and lattice parameter extraction (a,
      b, c, alpha, beta, gamma)
- [x] **116.1.2.2** Implement `UnitCell` type: lattice vectors, list of `Atom`
      positions (Cartesian and fractional coordinates with bidirectional
      conversion), space group symmetry operations (rotation matrix +
      translation vector in fractional coords), cell volume, and methods for
      supercell construction, primitive cell reduction (Niggli reduction,
      Delaunay reduction), and conventional cell determination
- [x] **116.1.2.3** Implement `Atom` type: atomic number Z, element symbol, mass
      (AMU), position (Vec3), pseudopotential assignment, magnetic moment
      (initial), Hubbard U/J parameters, force vector, velocity (for MD),
      constraint flags (selective dynamics), and species label (for distinct
      sites of same element)
- [x] **116.1.2.4** Implement `KPoint` type: k-vector in fractional reciprocal
      coordinates, weight (for BZ integration), label (for high-symmetry points:
      Gamma, X, M, K, L, W, etc.), and index in the k-point grid
- [x] **116.1.2.5** Implement `KPointGrid` type: Monkhorst-Pack grid generation
      given (n1, n2, n3) subdivisions and shift vector; Gamma-centered variant;
      symmetry reduction to irreducible Brillouin zone (IBZ) using space group
      operations; tetrahedron connectivity for tetrahedron integration method
- [x] **116.1.2.6** Implement `SpaceGroup` type: Hermann-Mauguin symbol,
      international number (1-230), point group, Bravais lattice type (14
      types), list of symmetry operations {R|t}, Wyckoff positions, and methods
      for symmetry-equivalent position generation and site symmetry
      determination
- [x] **116.1.2.7** Implement symmetry finder: given atomic positions and
      lattice vectors, determine the space group using Spglib-equivalent
      algorithm (tolerance-based comparison of symmetry-mapped structures),
      returning standardized cell, primitive cell, and symmetry operations
- [x] **116.1.2.8** Implement lattice type classifier: from lattice vectors,
      determine the centering type (P, I, F, C, R) and crystal system
      (triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal,
      cubic); compute the conventional cell from the primitive cell and vice
      versa using the standard transformation matrices
- [x] **116.1.2.9** Implement atomic distance and neighbor computation: given a
      unit cell, compute all interatomic distances up to a cutoff radius
      accounting for periodic boundary conditions; build neighbor lists using
      Verlet cell lists for O(N) scaling; identify coordination number and
      coordination polyhedron for each atom

#### 116.1.3 Electronic Structure Types

- [x] **116.1.3.1** Implement `Wavefunction` type: complex coefficients in
      plane-wave basis (c\_{n,k}(G) for each band n, k-point k, and G-vector),
      with methods for real-space evaluation via FFT, norm computation,
      orthogonality check, and spin component (up/down for collinear, spinor for
      non-collinear)
- [x] **116.1.3.2** Implement `ChargeDensity` type: electron density rho(r) on
      real-space FFT grid, with methods for integration (total electron count),
      symmetrization, spin-density (rho_up - rho_down), magnetization density
      vector m(r) for non-collinear, and augmentation charge for PAW
- [x] **116.1.3.3** Implement `Potential` type: effective potential V_eff(r) on
      real-space grid, decomposed into ionic V_ion(r), Hartree V_H(r), and
      exchange-correlation V_xc(r) components; both local (real-space grid) and
      nonlocal (projector-based) parts
- [x] **116.1.3.4** Implement `BandStructure` type: eigenvalues epsilon*{n,k}
      and occupations f*{n,k} for all bands n at all k-points k, with methods
      for Fermi level determination, band gap extraction (direct and indirect
      with k-point locations), bandwidth, band character (orbital projections),
      and serialization to JSON/HDF5
- [x] **116.1.3.5** Implement `DensityOfStates` type: total DOS g(E), projected
      DOS g_l^a(E) (atom a, angular momentum l), integrated DOS N(E), with
      Gaussian/Lorentzian broadening and tetrahedron method; energy grid
      specification and Fermi level alignment
- [x] **116.1.3.6** Implement `SCFState` type: mutable state container for the
      self-consistent field loop — current iteration number, total energy,
      eigenvalues, wavefunctions, charge density, potentials, mixing history,
      convergence metrics (delta_E, delta_rho, max_force), wall time per
      iteration, and restart checkpoint data
- [x] **116.1.3.7** Implement `DFTCalculation` orchestrator type: input
      parameters (unit cell, k-grid, energy cutoff, XC functional,
      pseudopotentials, convergence criteria, smearing), output results (total
      energy, forces, stress, band structure, DOS, charge density), calculation
      status (initialized, running, converged, failed), and methods for setup,
      execution, and post-processing

#### 116.1.4 File Format I/O

- [x] **116.1.4.1** Implement POSCAR/CONTCAR parser and writer (VASP structure
      format): lattice vectors, atomic species, positions (Direct/Cartesian),
      selective dynamics flags, velocities; support VASP 5 format with species
      names
- [x] **116.1.4.2** Implement CIF (Crystallographic Information File) parser:
      parse `_cell_length_a/b/c`, `_cell_angle_alpha/beta/gamma`,
      `_atom_site_fract_x/y/z`, `_symmetry_equiv_pos_as_xyz`; handle
      symmetry-generated positions
- [x] **116.1.4.3** Implement QE input/output parser: `pw.x` input file format
      (`&CONTROL`, `&SYSTEM`, `&ELECTRONS`, `ATOMIC_SPECIES`,
      `ATOMIC_POSITIONS`, `K_POINTS`, `CELL_PARAMETERS`), XML output
      data-file-schema.xml
- [x] **116.1.4.4** Implement XYZ/extXYZ format parser and writer for molecular
      and periodic structures (with lattice vectors in comment line for periodic
      systems, per-atom properties)
- [x] **116.1.4.5** Implement structure conversion utilities: POSCAR <-> CIF <->
      QE input <-> XYZ <-> internal UnitCell, with consistent handling of
      coordinate systems, units (Angstrom/Bohr), and symmetry information
- [x] **116.1.4.6** Implement ABINIT input parser: parse `input.abi` format with
      `acell`, `rprim`, `typat`, `xred`/`xcart`, `ecut`, `nkpt`, `kpt`,
      `occopt`, `tsmear`, `ixc` keywords; output conversion from internal format
      to ABINIT input
- [x] **116.1.4.7** Implement Materials Project / pymatgen JSON structure format
      parser and writer: support the `Structure.as_dict()` format with lattice
      matrix, species, fractional coordinates, and properties; enable
      interoperability with the Materials Project ecosystem

---

### 116.2 Plane-Wave Basis Set Engine (Rust + WASM)

#### 116.2.1 Reciprocal Space Infrastructure

- [x] **116.2.1.1** Implement reciprocal lattice vector computation in Rust:
      given real-space lattice vectors a_i, compute b_i = 2*pi*(a_j x a_k)/V
      with exact double-precision arithmetic; verify b_i . a_j = 2*pi*delta_ij
      orthogonality to machine epsilon
- [x] **116.2.1.2** Implement G-vector generation: enumerate all reciprocal
      lattice vectors G = n1*b1 + n2*b2 + n3\*b3 satisfying the kinetic energy
      cutoff |k+G|^2/2 <= E_cut (in Rydberg or Hartree units,
      user-configurable); store as sorted list with Miller indices (n1, n2, n3)
      and |k+G|^2 values
- [x] **116.2.1.3** Implement sphere truncation with proper k-point dependence:
      for each k-point, determine the set of G-vectors satisfying the cutoff
      |k+G|^2/2 <= E_cut; manage variable-size G-vector lists per k-point with
      efficient indexing via hash map from (n1,n2,n3) to linear index
- [x] **116.2.1.4** Implement G-vector shell structure: group G-vectors by |G|^2
      into shells for symmetry analysis; compute structure factor S(G) = sum_a
      f_a * exp(-i*G.tau_a) for each shell (f_a = atomic form factor, tau_a =
      atomic position)
- [x] **116.2.1.5** Implement dual-basis representation: maintain both G-space
      (plane-wave coefficients) and r-space (real-space grid values) for
      wavefunctions and potentials; track which representation is current to
      avoid redundant FFTs
- [x] **116.2.1.6** Implement augmentation charge G-vectors: for ultrasoft
      pseudopotentials and PAW, maintain a separate G-vector set with a higher
      cutoff (typically 4*E_cut or 8*E_cut for the augmented charge density
      Q_ij(G)) and the corresponding FFT grid (the "hard" grid vs. "smooth"
      grid)

#### 116.2.2 FFT Engine (Rust)

- [x] **116.2.2.1** Implement mixed-radix 3D FFT in Rust: Cooley-Tukey algorithm
      supporting composite sizes N = 2^a _ 3^b _ 5^c \* 7^d (matching FFTW's
      supported radices); in-place computation with twiddle factor
      precomputation and bit-reversal permutation; complex-to-complex and
      real-to-complex variants
- [x] **116.2.2.2** Implement FFT grid determination: given E_cut and lattice
      vectors, compute the minimum real-space grid dimensions (N1, N2, N3)
      satisfying Nyquist sampling (N_i >= 2\*G_max_i + 1) and round up to
      FFT-friendly sizes (products of small primes 2,3,5,7); optionally add
      padding for anti-aliasing of XC potential (typically 1.5x or 2x the
      wavefunction grid)
- [x] **116.2.2.3** Implement scatter/gather operations: distribute plane-wave
      coefficients c(G) from the 1D coefficient array to the 3D FFT grid
      (scatter), and collect back after inverse FFT (gather); handle the mapping
      between linear G-vector index and 3D grid coordinates (n1, n2, n3) with
      negative index wrapping
- [x] **116.2.2.4** Implement wavefunction FFT: transform psi*{n,k}(G) ->
      psi*{n,k}(r) via scatter + 3D inverse FFT, and psi*{n,k}(r) ->
      psi*{n,k}(G) via 3D forward FFT + gather; handle normalization (1/sqrt(V)
      for Bloch states)
- [x] **116.2.2.5** Implement charge density computation via FFT: rho(r) =
      sum*{n,k} f*{n,k} |psi*{n,k}(r)|^2 — for each band and k-point, FFT
      wavefunction to real space, accumulate |psi|^2 weighted by occupation
      f*{n,k} and k-point weight w_k; symmetrize the resulting density using
      space group operations
- [x] **116.2.2.6** Implement Hartree potential via FFT: solve Poisson equation
      V_H(G) = 4*pi*rho(G)/|G|^2 for G != 0 (G=0 component set by charge
      neutrality); handle the G=0 divergence via compensating background charge
      for charged cells
- [x] **116.2.2.7** Implement convolution via FFT for XC potential: compute
      V_xc(r) = d(E_xc[rho])/d(rho) in real space on the fine grid, then FFT to
      G-space for application to wavefunctions; handle the double-grid technique
      where XC is evaluated on a finer grid than wavefunctions
- [x] **116.2.2.8** Implement batched FFT operations: transform multiple
      wavefunctions simultaneously using batched 3D FFT to improve cache
      utilization and amortize twiddle factor computation; configurable batch
      size based on available memory

#### 116.2.3 Plane-Wave Operations

- [x] **116.2.3.1** Implement kinetic energy application: T|psi> in G-space is
      simply |k+G|^2/2 \* c(G) — diagonal in reciprocal space; precompute and
      store the kinetic energy array for each k-point
- [x] **116.2.3.2** Implement local potential application: V_loc(r)\*psi(r) in
      real space — FFT psi to real space, multiply pointwise by V_loc(r), FFT
      back to G-space; this is the standard approach for ionic, Hartree, and XC
      local potentials
- [x] **116.2.3.3** Implement nonlocal potential application (Kleinman-Bylander
      form): V*NL|psi> = sum*{a,l,m} |beta*{a,lm}> D*{lm,l'm'}^a
      <beta\_{a,l'm'}|psi> where beta are projector functions and D is the
      pseudopotential D-matrix; compute <beta|psi> projections in G-space, form
      D*<beta|psi>, and accumulate |beta>*D\*<beta|psi>
- [x] **116.2.3.4** Implement overlap matrix (S-matrix) for ultrasoft/PAW:
      S|psi> = |psi> + sum*{a,i,j} |beta*{a,i}> q*{ij}^a <beta*{a,j}|psi> where
      q_ij are the augmentation overlap integrals; required for generalized
      eigenvalue problem H|psi> = epsilon\*S|psi>
- [x] **116.2.3.5** Implement Hamiltonian application H|psi> = (T + V_loc +
      V_NL)|psi> as a single composite operation: apply kinetic energy in
      G-space, local potential via FFT round-trip, and nonlocal potential via
      projectors; this is the central operation of the SCF loop, called
      thousands of times
- [x] **116.2.3.6** Implement subspace Hamiltonian and overlap matrix
      construction: H*{mn} = <psi_m|H|psi_n> and S*{mn} = <psi_m|S|psi_n> for a
      set of trial wavefunctions {psi_n}; used by iterative diagonalizers for
      subspace rotation; compute via batched H|psi> application followed by dot
      products

#### 116.2.4 Augmented Plane Waves (APW+lo)

- [x] **116.2.4.1** Implement muffin-tin sphere partitioning: divide the unit
      cell into non-overlapping atomic spheres (muffin-tin radius R_MT for each
      species) and an interstitial region; determine optimal R_MT values by
      touching-sphere algorithm with configurable reduction factor
- [x] **116.2.4.2** Implement APW basis functions: inside muffin-tin sphere,
      expand in radial functions times spherical harmonics
      u*l(r,E)\*Y*{lm}(r_hat) matched to plane waves at sphere boundary; solve
      radial Schrodinger equation for u_l(r,E) at linearization energies E_l
- [x] **116.2.4.3** Implement local orbitals (lo): additional basis functions
      confined to muffin-tin spheres, constructed from radial functions at two
      different energies to remove linearization error; lo functions vanish at
      sphere boundary and have zero derivative
- [x] **116.2.4.4** Implement APW+lo Hamiltonian and overlap matrix elements:
      interstitial contributions via plane-wave integrals, muffin-tin
      contributions via radial integrals of u_l*H*u_l' and u_l\*u_l' weighted by
      Gaunt coefficients for angular integration

---

### 116.3 Pseudopotential Infrastructure

#### 116.3.1 Norm-Conserving Pseudopotentials

- [x] **116.3.1.1** Implement Troullier-Martins (TM) norm-conserving
      pseudopotential construction (Phys. Rev. B 43, 1993, 1991): given
      all-electron atomic calculation, construct smooth pseudo-wavefunction
      matching the all-electron wavefunction outside cutoff radius r_c with the
      same norm, logarithmic derivative, and first four energy derivatives of
      the logarithmic derivative at r_c; pseudo-wavefunction is r^{l+1} \*
      exp(p(r)) with p(r) a degree-6 polynomial
- [x] **116.3.1.2** Implement Optimized Norm-Conserving Vanderbilt (ONCV)
      pseudopotential construction (Hamann, Phys. Rev. B 88, 085117, 2013):
      two-projector norm-conserving pseudopotentials with improved
      transferability and hardness; construct by optimizing the projector
      functions to minimize the kinetic energy of the pseudo-wavefunctions while
      maintaining norm conservation
- [x] **116.3.1.3** Implement Kleinman-Bylander (KB) separable form: transform
      the semi-local pseudopotential V*l(r) into fully nonlocal separable form
      V_NL = sum*{l,m} |delta*V_l \* phi*{l,m}> <delta*V_l \* phi*{l,m}| /
      <phi*{l,m}|delta_V_l|phi*{l,m}> where delta_V_l = V_l - V_loc; choose
      V_loc to avoid ghost states (Gonze-Stumpf-Scheffler criterion)
- [x] **116.3.1.4** Implement ghost state detection: check for states below the
      reference energy with wrong number of nodes in the pseudo-wavefunction;
      compute the logarithmic derivative as a function of energy and verify
      monotonic behavior (ghost states appear as anomalous poles)
- [x] **116.3.1.5** Implement non-linear core correction (Louie, Froyen, Cohen,
      Phys. Rev. B 26, 1738, 1982): include partial core charge rho_core(r) in
      the XC energy evaluation to improve transferability for systems where the
      valence and core charge densities overlap significantly (e.g., alkali
      metals, transition metals)
- [x] **116.3.1.6** Implement scalar-relativistic corrections for
      pseudopotential generation: solve the radial Dirac equation in the
      Koelling-Harmon scalar-relativistic approximation to obtain reference
      wavefunctions and eigenvalues that include mass-velocity and Darwin terms
      but not spin-orbit coupling

#### 116.3.2 Ultrasoft Pseudopotentials

- [x] **116.3.2.1** Implement Vanderbilt ultrasoft pseudopotential (USPP) theory
      (Phys. Rev. B 41, 7892, 1990): relaxed norm-conservation constraint
      allowing softer pseudopotentials with lower plane-wave cutoffs; construct
      multiple projector functions beta_i per angular momentum channel with
      augmentation functions Q_ij(r) = phi_i*(r)*phi_j(r) -
      tilde_phi_i*(r)*tilde_phi_j(r) that restore the correct charge in the
      augmentation region
- [x] **116.3.2.2** Implement USPP augmentation charge: compute Q*ij(G) by
      Fourier transforming the augmentation functions; handle the augmentation
      charge contribution to the total density rho(r) = sum
      f*{nk}|psi*{nk}(r)|^2 + sum*{a,ij} rho_ij^a \* Q_ij^a(r) where rho_ij is
      the density matrix in the projector basis
- [x] **116.3.2.3** Implement USPP force and stress contributions: the Hellmann-
      Feynman forces for USPP include additional terms from the augmentation
      charge gradient d(Q_ij)/d(tau_a) and from the non-local D-matrix
      derivative; implement all six USPP force contributions (Laasonen et al.,
      Phys. Rev. B 47, 10142, 1993)
- [x] **116.3.2.4** Implement generalized eigenvalue problem solver interface:
      USPP leads to H|psi> = epsilon\*S|psi> with S != I; adapt all eigensolvers
      (Davidson, LOBPCG, CheFSI) to handle the S-matrix via preconditioned
      iterations with S^{-1} approximation or Cholesky factorization

#### 116.3.3 Projector Augmented Wave (PAW) Method

- [x] **116.3.3.1** Implement PAW transformation theory (Blochl, Phys. Rev. B
      50, 17953, 1994): linear transformation T mapping smooth
      pseudo-wavefunctions |tilde*psi> to all-electron wavefunctions |psi> =
      T|tilde_psi> = |tilde_psi> + sum*{a,i} (|phi_i^a> - |tilde_phi_i^a>)
      <tilde_p_i^a|tilde_psi> where phi_i are all-electron partial waves,
      tilde_phi_i are pseudo partial waves, and tilde_p_i are projector
      functions
- [x] **116.3.3.2** Implement PAW partial waves and projectors: solve the radial
      Schrodinger equation for the all-electron atom to get phi_i(r); construct
      smooth pseudo partial waves tilde_phi_i(r) matching phi_i outside r_c;
      construct projector functions tilde_p_i satisfying biorthogonality
      <tilde_p_i|tilde_phi_j> = delta_ij
- [x] **116.3.3.3** Implement PAW one-center quantities: compute the PAW
      compensation charge density rho_hat(r) that makes the multipole moments of
      pseudo-density + rho_hat equal to those of the all-electron density in
      each augmentation sphere; compute one-center Hamiltonian matrix D_ij^1
      from all-electron and pseudo partial wave matrix elements
- [x] **116.3.3.4** Implement PAW total energy: E = tilde_E} + sum_a (E_1^a -
      tilde_E_1^a) where tilde_E is the pseudo energy (kinetic + Hartree + XC +
      ion of smooth quantities) and E_1^a - tilde_E_1^a are one-center
      corrections for each atom a computed from partial wave matrix elements;
      handle the PAW double-counting corrections correctly
- [x] **116.3.3.5** Implement PAW forces: Hellmann-Feynman forces with PAW
      corrections — include the gradient of one-center energies with respect to
      atomic positions, the force from the compensation charge, and the
      non-local force from the D-matrix derivative (Kresse & Joubert, Phys. Rev.
      B 59, 1758, 1999)
- [x] **116.3.3.6** Implement PAW stress tensor: generalization of the
      Parrinello-Rahman stress tensor to the PAW formalism — include one-center
      correction terms, compensation charge contributions, and the shape
      derivative of the augmentation sphere with respect to strain

#### 116.3.4 Pseudopotential File Format Parsers

- [x] **116.3.4.1** Implement UPF (Unified Pseudopotential Format) parser: parse
      UPF v2 XML format used by Quantum ESPRESSO — extract header (element,
      pseudo_type, relativistic, is_ultrasoft, is_paw, core_correction), radial
      mesh, local potential V_loc(r), beta projectors beta_i(r), D_ij^0 matrix,
      Q_ij augmentation (for USPP/PAW), rho_atom(r), PAW-specific data (ae_wfc,
      ps_wfc, occupations)
- [x] **116.3.4.2** Implement POTCAR parser (VASP format): parse the
      concatenated POTCAR format with multiple species — extract ENMAX
      (recommended E_cut), ZVAL (valence electrons), radial grid, local
      potential, projectors, augmentation charge Q_ij, PAW data (ae partial
      waves, ps partial waves), and hash/title for version tracking
- [x] **116.3.4.3** Implement PSP8 parser (ABINIT format): parse the PSP8 text
      format for norm-conserving pseudopotentials — header (Z, Z_ion, pspcod=8,
      pspxc, lmax, lloc), Kleinman-Bylander projectors on the radial grid,
      non-linear core correction charge density
- [x] **116.3.4.4** Implement JTH PAW dataset parser: parse the JTH (Jollet,
      Torrent, Holzwarth) PAW dataset format used by ABINIT — XML format with
      PAW-specific data (partial waves, projectors, shape functions,
      compensation charge parameters)
- [x] **116.3.4.5** Implement pseudopotential format conversion: UPF <-> POTCAR
      <-> PSP8 <-> internal format, preserving all physically relevant data;
      handle the different conventions for units (Rydberg vs. Hartree),
      normalization, and radial grid definitions (linear vs. logarithmic)

#### 116.3.5 Pseudopotential Library Management

- [x] **116.3.5.1** Implement pseudopotential library registry: maintain a
      searchable catalog of available pseudopotentials indexed by element, XC
      functional, type (NC/USPP/PAW), and source library (PseudoDojo, SSSP,
      GBRV, PSLibrary, JTH); store metadata (recommended cutoffs, delta-factor,
      phonon errors) for each entry
- [x] **116.3.5.2** Implement automatic pseudopotential selection: given a
      structure and XC functional, select the optimal pseudopotential for each
      element from the library based on accuracy-efficiency tradeoff; use SSSP
      (Standard Solid-State Pseudopotentials) protocol rankings as default
      (Prandini et al., npj Comput. Mater. 4, 72, 2018)
- [x] **116.3.5.3** Implement delta-factor validation test: compute the equation
      of state for elemental crystals and compare with all-electron reference
      values using the delta-factor metric (Lejaeghere et al., Science 351,
      aad3000, 2016); use this as the standard transferability test for any
      pseudopotential
- [x] **116.3.5.4** Implement pseudopotential cutoff convergence test: for a
      given pseudopotential and reference structure, compute total energy as a
      function of E_cut and identify the cutoff required for convergence to
      within 1 meV/atom; report recommended and strict cutoffs

#### 116.3.6 Spin-Orbit Coupling

- [x] **116.3.6.1** Implement fully relativistic pseudopotentials: j-dependent
      pseudopotentials V*{l,j=l+1/2}(r) and V*{l,j=l-1/2}(r) from solving the
      full Dirac equation for the atom; construct SOC-capable Kleinman-Bylander
      projectors for each (l,j) channel
- [x] **116.3.6.2** Implement spin-orbit Hamiltonian: add the SOC contribution
      H*SOC = sum*{a,l} sum*{j=l-1/2,l+1/2} sum_m |beta*{a,l,j,m}> (D*{lj} -
      D*{l,loc}) <beta\_{a,l,j,m}| to the Kohn-Sham Hamiltonian; requires
      2-component spinor wavefunctions psi = (psi_up, psi_down)
- [x] **116.3.6.3** Implement non-collinear spin framework: generalize the
      charge density to a 2x2 density matrix rho\_{ss'}(r), the XC potential to
      V_xc^{ss'}(r), and the Hamiltonian to a 2x2 matrix in spin space; support
      both collinear and non-collinear magnetism within the same framework

---

### 116.4 Self-Consistent Field (SCF) Solver (Rust)

#### 116.4.1 Kohn-Sham Equation Solver

- [x] **116.4.1.1** Implement the SCF loop in Rust: (1) construct initial charge
      density from superposition of atomic densities; (2) compute V_eff =
      V_ion + V_H[rho] + V_xc[rho]; (3) solve Kohn-Sham equations to get new
      wavefunctions and eigenvalues; (4) compute new charge density from
      wavefunctions; (5) mix old and new densities; (6) check convergence; (7)
      iterate until self-consistent
- [x] **116.4.1.2** Implement initial density construction: superpose atomic
      charge densities rho_init(r) = sum_a rho_atom^a(|r - tau_a|) on the FFT
      grid; obtain atomic densities from pseudopotential files or free-atom
      calculations; apply symmetrization to respect crystal symmetry
- [x] **116.4.1.3** Implement initial wavefunction generation: option 1 — random
      initialization with orthogonalization (Gram-Schmidt or Cholesky); option 2
      — diagonalize the initial Hamiltonian in a subspace of atomic orbitals
      (LCAO start); the LCAO start typically converges in fewer SCF iterations
- [x] **116.4.1.4** Implement occupation number computation: given eigenvalues
      epsilon*{n,k} and total number of electrons N_e, determine the Fermi
      energy E_F and occupations f*{n,k} = f(epsilon\_{n,k} - E_F) using the
      chosen smearing function; handle insulating (integer occupations) and
      metallic (fractional occupations) cases
- [x] **116.4.1.5** Implement SCF convergence monitoring: track total energy
      E*total, band energy E_band = sum f*{n,k}\*epsilon\_{n,k}, charge density
      residual ||rho_new - rho_old||, maximum force component, and Harris-
      Foulkes energy estimate; declare convergence when delta_E < E_tol AND
      delta_rho < rho_tol (user-configurable, defaults: 1e-6 eV and 1e-6 e/A^3)

#### 116.4.2 Charge Density Mixing

- [x] **116.4.2.1** Implement linear (simple) mixing: rho*{in}^{new} =
      alpha\*rho*{out} + (1-alpha)\*rho\_{in} with mixing parameter alpha
      (typically 0.1-0.3 for metals, 0.3-0.7 for insulators); implement adaptive
      alpha adjustment based on convergence rate
- [x] **116.4.2.2** Implement Pulay mixing (DIIS — Direct Inversion in the
      Iterative Subspace, Pulay, Chem. Phys. Lett. 73, 393, 1980): store history
      of input densities {rho_in^i} and residuals {R^i = rho_out^i - rho_in^i};
      construct the optimal linear combination by minimizing ||sum_i c_i R_i||^2
      subject to sum_i c_i = 1; solve the (n+1)x(n+1) linear system via Lagrange
      multiplier; history length typically 4-8
- [x] **116.4.2.3** Implement Broyden mixing (Broyden's second method, Johnson,
      Phys. Rev. B 38, 12807, 1988): quasi-Newton method that builds an
      approximate inverse Jacobian from the mixing history using rank-1 updates;
      more robust than Pulay for difficult cases (surfaces, molecules in
      vacuum); implement both Broyden-1 and Broyden-2 variants
- [x] **116.4.2.4** Implement Kerker preconditioning (Kerker, Phys. Rev. B 23,
      3082, 1981): precondition the density residual in G-space with the factor
      G^2/(G^2 + q_0^2) to damp long-wavelength charge sloshing; q_0 is a
      screening parameter (typically ~1.0 Bohr^{-1} for metals); critical for
      metallic systems to prevent SCF divergence
- [x] **116.4.2.5** Implement combined Kerker-preconditioned Pulay mixing: apply
      Kerker preconditioning to the residual before feeding into the Pulay
      minimization; this combination is the default in most modern codes (VASP,
      QE) for metallic systems
- [x] **116.4.2.6** Implement metric-based mixing (Singh, Phys. Rev. B 40, 5428,
      1989): generalize the Pulay overlap matrix to use a physically motivated
      metric <R_i|K|R_j> where K is the Kerker preconditioner or the dielectric
      function; improves mixing for heterogeneous systems (surfaces, interfaces)

#### 116.4.3 Eigenvalue Solvers

- [x] **116.4.3.1** Implement Davidson iterative diagonalization (Davidson, J.
      Comput. Phys. 17, 87, 1975; adapted for plane-waves by Ihm, Zunger,
      Cohen): maintain a subspace of trial vectors {psi_n, H*psi_n - E_n*psi_n};
      expand subspace with preconditioned residuals; diagonalize the projected
      Hamiltonian in the subspace; extract improved eigenvectors; iterate until
      residual norms ||H*psi_n - E_n*S\*psi_n|| < tol; block Davidson for
      multiple eigenvalues simultaneously
- [x] **116.4.3.2** Implement RMM-DIIS (Residual Minimization Method — Direct
      Inversion in the Iterative Subspace, Wood & Zunger, J. Phys. A 18, 1343,
      1985; Kresse & Furthmuller): for each band independently, minimize the
      residual norm in the subspace spanned by current and previous trial
      vectors using DIIS; bands are processed independently then orthogonalized;
      faster per-step than Davidson but may converge to wrong eigenvalues (needs
      occasional reorthogonalization)
- [x] **116.4.3.3** Implement LOBPCG (Locally Optimal Block Preconditioned
      Conjugate Gradient, Knyazev, SIAM J. Sci. Comput. 23, 517, 2001):
      three-term recurrence X*{i+1} = span{X_i, H\*X_i, X*{i-1}} with block
      structure and preconditioning; solve the Rayleigh-Ritz problem in this
      3\*n_bands subspace at each iteration; hard-lock converged eigenpairs;
      robust for ill-conditioned problems
- [x] **116.4.3.4** Implement Chebyshev-filtered subspace iteration (CheFSI,
      Zhou et al., J. Comput. Phys. 219, 172, 2006): apply a Chebyshev
      polynomial filter T_m(H) to the subspace to amplify the desired
      eigencomponents and damp unwanted ones; filter degree m = 10-30 depending
      on spectral gap; avoids explicit diagonalization during filtering, only
      Rayleigh-Ritz at the end; excellent for large systems and GPU acceleration
- [x] **116.4.3.5** Implement subspace diagonalization: given the filtered or
      iterated subspace {psi*n}, construct the projected Hamiltonian H*{mn} =
      <psi*m|H|psi_n> and overlap S*{mn} = <psi*m|S|psi_n>, solve the
      generalized eigenvalue problem H*c = epsilon*S*c using LAPACK dsygv/zhegv
      (via napi-rs binding or pure Rust), and rotate the wavefunctions psi_n <-
      sum_m psi_m _ c_{mn}
- [x] **116.4.3.6** Implement preconditioning for iterative eigensolvers: the
      Teter-Payne-Allan (TPA) preconditioner K(G) = (27 + 18x + 12x^2 + 8x^3) /
      (27 + 18x + 12x^2 + 8x^3 + 16x^4) where x = |k+G|^2 / (2\*E_kin_avg),
      approximating the inverse of the kinetic energy operator; apply to
      residuals before subspace expansion
- [x] **116.4.3.7** Implement conjugate gradient direct minimization (Payne,
      Teter, Allan, Arias, Joannopoulos, Rev. Mod. Phys. 64, 1045, 1992):
      minimize the total energy functional directly with respect to wavefunction
      coefficients using CG with orthogonality constraints; suitable as a backup
      solver when iterative diagonalization has convergence difficulties
- [x] **116.4.3.8** Implement Projected Preconditioned Conjugate Gradient (PPCG,
      Duersch et al., J. Comput. Phys. 338, 114, 2017): block CG method with
      projection to maintain orthogonality and preconditioning for acceleration;
      competitive with CheFSI and more robust for clustered eigenvalues

#### 116.4.4 Smearing Methods

- [x] **116.4.4.1** Implement Gaussian smearing: f(x) = 0.5*erfc(x/sigma) where
      x = (epsilon - E_F), sigma is the smearing width; entropy contribution
      -T*S = -0.5*sigma*sum\_{n,k} w_k \* exp(-x^2/sigma^2) / sqrt(pi) for
      extrapolation to sigma->0
- [x] **116.4.4.2** Implement Methfessel-Paxton smearing (orders 1-3, Methfessel
      & Paxton, Phys. Rev. B 40, 3616, 1989): f_N(x) = S_N(-x/sigma) using
      Hermite polynomial expansion of the step function; order-1 is the most
      commonly used; provides O(sigma^{2N+2}) accuracy in the total energy,
      reducing the need for very small sigma
- [x] **116.4.4.3** Implement Fermi-Dirac smearing: f(x) =
      1/(exp(x/(k*B*T)) + 1) with electronic temperature T; physically motivated
      for finite-T DFT; entropy contribution -T*S = -k_B*T _ sum_{n,k} w_k *
      [f*ln(f) + (1-f)\*ln(1-f)]
- [x] **116.4.4.4** Implement cold smearing (Marzari-Vanderbilt, Phys. Rev.
      Lett. 82, 3296, 1999): f(x) = 0.5*erfc(x/sigma) + (1/sqrt(2*pi)) _
      (x/sigma + sqrt(2)) _ exp(-(x/sigma + sqrt(2))^2 / 2); optimal for density
      of states with van Hove singularities; provides zero entropy term at the
      Fermi level
- [x] **116.4.4.5** Implement tetrahedron method with Blochl corrections (Blochl
      et al., Phys. Rev. B 49, 16223, 1994): decompose the BZ into tetrahedra,
      interpolate eigenvalues linearly within each tetrahedron, integrate
      analytically; add Blochl corrections to restore the correct k-point limit;
      required for accurate DOS and insulating systems
- [x] **116.4.4.6** Implement Fermi level determination: for each smearing
      method, solve N*e = sum*{n,k} w*k \* f((epsilon*{n,k} - E_F)/sigma) for
      E_F using bisection or Newton's method; handle the case of an insulator
      (gap between occupied and unoccupied) and metal (no gap) uniformly

#### 116.4.5 Total Energy & Forces

- [x] **116.4.5.1** Implement total energy computation: E*total = E_kin + E_H +
      E_xc + E_ion + E_loc + E_NL + E_Ewald where E_kin = sum f*{n,k} _
      <psi_{n,k}|T|psi*{n,k}>, E_H = (1/2)*integral V*H*rho, E_xc = integral
      epsilon_xc(rho)_rho, E_loc = integral V_loc\*rho, E_NL = sum
      f_{n,k}\*<psi*{n,k}|V_NL|psi*{n,k}>, and E_Ewald = Ewald sum for ion-ion
      interaction; track each component separately for debugging
- [x] **116.4.5.2** Implement Ewald summation for ion-ion energy: split the
      Coulomb sum into real-space (short-range, erfc-screened), reciprocal-
      space (long-range), and self-energy terms; optimize the Ewald parameter
      eta for balanced convergence of both sums; implement O(N\*log(N)) PME
      (Particle Mesh Ewald) for large cells via FFT
- [x] **116.4.5.3** Implement Hellmann-Feynman forces: F*a = -dE/d(tau_a) =
      -integral rho(r) \* dV_ion(r)/d(tau_a) - sum*{n,k} f*{n,k} \*
      <psi*{n,k}|dV*NL/d(tau_a)|psi*{n,k}> - dE_Ewald/d(tau_a); the
      Hellmann-Feynman theorem ensures that only the ionic potential derivatives
      appear (no wavefunction derivatives) at self-consistency
- [x] **116.4.5.4** Implement Pulay force correction: for finite basis sets
      (especially APW+lo), the force has an additional term from the basis set
      dependence on atomic positions; for plane waves with pseudopotentials this
      is primarily the Pulay stress (see 116.4.5.6)
- [x] **116.4.5.5** Implement stress tensor computation: sigma*{alpha,beta} =
      (1/V) \* dE/d(epsilon*{alpha,beta}) where epsilon is the strain tensor;
      includes kinetic, Hartree, XC, local pseudopotential, nonlocal
      pseudopotential, and Ewald contributions; handle PAW-specific correction
      terms
- [x] **116.4.5.6** Implement Pulay stress correction: for finite plane-wave
      basis (E_cut < infinity), the total stress has a Pulay correction from the
      incomplete basis — estimate via E_total(V) at nearby volumes or via the
      explicit basis-set derivative; report the corrected stress for
      variable-cell relaxation
- [x] **116.4.5.7** Implement Harris-Foulkes energy functional: E*HF = sum
      f*{n,k}*epsilon\_{n,k} - E_H[rho_in] + E_xc[rho_in] - integral
      V_xc[rho_in]*rho_in + E_Ewald; this is variational in the density and
      equals the Kohn-Sham energy at self-consistency; use as a better energy
      estimate than the band energy during early SCF iterations

#### 116.4.6 Spin-Polarized DFT

- [x] **116.4.6.1** Implement collinear spin-polarized DFT: separate spin-up and
      spin-down channels with independent Kohn-Sham equations
      H*sigma|psi*{n,k,sigma}> = epsilon*{n,k,sigma}|psi*{n,k,sigma}> and
      separate charge densities rho_up(r), rho_down(r); the XC potential is
      spin-dependent V_xc,sigma = delta E_xc[rho_up, rho_down]/delta rho_sigma
- [x] **116.4.6.2** Implement non-collinear spin DFT: use 2-component spinor
      wavefunctions psi*{n,k} = (psi_up, psi_down); compute 2x2 spin density
      matrix n*{ss'}(r) = sum f*{n,k} psi*{n,k,s}_(r) _ psi\_{n,k,s'}(r);
      magnetization density m(r) = Tr[n * sigma] (sigma = Pauli matrices); the
      XC potential becomes a 2x2 matrix V_xc^{ss'}
- [x] **116.4.6.3** Implement constrained magnetization: fix the magnetic moment
      direction on specific atoms using penalty energy E_penalty = lambda \*
      sum_a (M_a - M_a^target)^2 where M_a = integral_sphere m(r) dr; required
      for calculating magnetic anisotropy energies and non-trivial magnetic
      structures (spirals, skyrmions)
- [x] **116.4.6.4** Implement initial magnetic moment configuration: assign
      initial spin polarization to atoms based on user input or chemical
      intuition (e.g., Fe: +/-2.5 mu_B); support ferromagnetic,
      antiferromagnetic, and ferrimagnetic initial configurations; handle
      magnetic symmetry operations (time-reversal combined with spatial
      symmetry)

#### 116.4.7 Brillouin Zone Integration

- [x] **116.4.7.1** Implement Monkhorst-Pack k-point grid generation (Monkhorst
      & Pack, Phys. Rev. B 13, 5188, 1976): k_i = (2*n_i - N_i - 1) / (2*N_i) \*
      b_i for n_i = 1,...,N_i; support both unshifted (includes Gamma for odd N)
      and shifted (excludes Gamma, better for metals) variants
- [x] **116.4.7.2** Implement Gamma-centered k-point grid: k_i = n_i/N_i \* b_i
      for n_i = 0,...,N_i-1; always includes the Gamma point; preferred for
      hexagonal systems and when Gamma-point symmetry is needed
- [x] **116.4.7.3** Implement irreducible Brillouin zone (IBZ) reduction: given
      the full k-point grid and space group operations, find the irreducible
      k-points and their weights by identifying symmetry-equivalent k-points;
      for time-reversal symmetry (k <-> -k), further reduce by a factor of ~2
- [x] **116.4.7.4** Implement k-point path generation for band structures: given
      the Bravais lattice type, generate the standard high-symmetry k-point path
      following Setyawan-Curtarolo conventions (Comput. Mater. Sci. 49,
      299, 2010) or Hinuma-Pizzi-Kumagai-Oba-Tanaka conventions (Comput. Mater.
      Sci. 128, 140, 2017); interpolate N points between each pair of
      high-symmetry points
- [x] **116.4.7.5** Implement automatic k-point density selection: given a
      target k-point density (e.g., 30 k-points per reciprocal Angstrom or 1000
      k-points per reciprocal atom), compute the grid dimensions (N1, N2, N3)
      proportional to the reciprocal lattice vector lengths to ensure
      approximately isotropic sampling

---

### 116.5 Exchange-Correlation Functional Library (`@kalika/xc-functionals`)

#### 116.5.1 Local Density Approximation (LDA)

- [x] **116.5.1.1** Implement Perdew-Zunger (PZ81) LDA parametrization (Phys.
      Rev. B 23, 5048, 1981): parametrize the correlation energy per electron
      epsilon_c(r_s) using the Ceperley-Alder QMC data; use the Wigner-Seitz
      radius r_s = (3/(4*pi*rho))^{1/3}; separate parametrizations for r_s >= 1
      (Pade approximant) and r_s < 1 (log series); implement both unpolarized
      and spin-polarized forms
- [x] **116.5.1.2** Implement Vosko-Wilk-Nusair (VWN) LDA parametrization (Can.
      J. Phys. 58, 1200, 1980): Pade approximant fit to the Ceperley- Alder data
      with three variants (VWN3, VWN5, VWN-RPA); implement the
      spin-interpolation formula using the relative spin polarization zeta =
      (rho_up - rho_down)/rho and the spin-scaling function f(zeta)
- [x] **116.5.1.3** Implement Perdew-Wang (PW92) LDA parametrization (Phys. Rev.
      B 45, 13244, 1992): improved parametrization of the uniform electron gas
      correlation energy using a single analytic expression valid for all r_s;
      implement the three spin channels (paramagnetic, ferromagnetic, and
      spin-stiffness alpha_c); this is the recommended LDA parametrization for
      modern calculations
- [x] **116.5.1.4** Implement LDA exchange: epsilon_x(rho) = -3/4 *
      (3*rho/pi)^{1/3} (Dirac exchange); spin-polarized form using the
      spin-scaling relation epsilon_x[rho_up, rho_down] = (epsilon_x(2*rho_up) +
      epsilon_x(2*rho_down))/2; compute both energy density and potential V_x =
      d(rho\*epsilon_x)/d(rho)
- [x] **116.5.1.5** Implement XC energy and potential evaluation on real-space
      grid: for each grid point, compute rho, rho_up, rho_down (from density
      arrays), evaluate epsilon_xc(rho, zeta) and V_xc,sigma =
      d(rho\*epsilon_xc)/d(rho_sigma); handle the low-density limit (rho <
      rho_min ~ 1e-12) to avoid numerical instabilities

#### 116.5.2 Generalized Gradient Approximation (GGA)

- [x] **116.5.2.1** Implement gradient computation: compute |grad(rho)|^2 on the
      FFT grid by transforming rho(G) -> i*G*rho(G) in each direction, then FFT
      to real space and compute the squared gradient; compute the reduced
      gradient s = |grad(rho)|/(2*k_F*rho) where k_F = (3*pi^2*rho)^{1/3};
      handle the spin-polarized case with separate up/down gradients
- [x] **116.5.2.2** Implement PBE exchange-correlation (Perdew, Burke,
      Ernzerhof, Phys. Rev. Lett. 77, 3865, 1996): exchange enhancement factor
      F_x(s) = 1 + kappa - kappa/(1 + mu*s^2/kappa) with kappa = 0.804, mu =
      0.21951; correlation based on H(r_s, zeta, t) gradient correction to PW92
      with t = |grad(rho)|/(2*phi*k_s*rho), phi = ((1+zeta)^{2/3} +
      (1-zeta)^{2/3})/2, k_s = sqrt(4\*k_F/pi); the most widely used GGA
- [x] **116.5.2.3** Implement PBEsol (Perdew et al., Phys. Rev. Lett. 100,
      136406, 2008): modified PBE with mu = 10/81 (exact second-order gradient
      expansion coefficient) and adjusted beta for correlation; optimized for
      solids and surfaces rather than molecules; improves lattice constants and
      surface energies relative to PBE
- [x] **116.5.2.4** Implement RPBE (Hammer, Hansen, Norskov, Phys. Rev. B 59,
      7413, 1999): F_x(s) = 1 + kappa*(1 - exp(-mu*s^2/kappa)) — satisfies the
      Lieb-Oxford bound locally; better for chemisorption energies than PBE
- [x] **116.5.2.5** Implement revPBE (Zhang & Yang, Phys. Rev. Lett. 80, 890,
      1998): PBE form with kappa = 1.245 (fitted to exact exchange energies of
      atoms); improves atomization energies; used in vdW-DF as the exchange
      component
- [x] **116.5.2.6** Implement BLYP: Becke88 exchange (B88, Phys. Rev. A 38,
      3098, 1988) with Lee-Yang-Parr correlation (LYP, Phys. Rev. B 37, 785,
      1988); B88 exchange: epsilon_x^B88 = epsilon_x^LDA - beta*rho^{1/3}*x^2 /
      (1 + 6*beta*x\*arcsinh(x)) where x = |grad(rho)|/rho^{4/3}; LYP
      correlation from the Colle-Salvetti formula reparametrized by Lee, Yang,
      and Parr
- [x] **116.5.2.7** Implement PW91 (Perdew & Wang, Phys. Rev. B 46, 6671, 1992):
      predecessor to PBE with more complex parametrization; implement for
      backward compatibility with older calculations
- [x] **116.5.2.8** Implement Wu-Cohen (WC) GGA (Phys. Rev. B 73, 235116, 2006):
      exchange enhancement factor interpolating between the exact second-order
      gradient expansion at small s and PBE at large s; good for ferroelectric
      perovskites
- [x] **116.5.2.9** Implement GGA potential computation: V_xc,sigma(r) =
      d(rho*epsilon_xc)/d(rho_sigma) -
      div(d(rho*epsilon_xc)/d(grad(rho_sigma))); the divergence term is computed
      in G-space by FFTing the gradient of epsilon_xc with respect to grad(rho),
      multiplying by i\*G, and FFTing back

#### 116.5.3 Meta-GGA Functionals

- [x] **116.5.3.1** Implement kinetic energy density computation: tau(r) = (1/2)
      _ sum*{n,k} f*{n,k} _ |grad(psi\_{n,k}(r))|^2 — the positive- definite KS
      kinetic energy density; compute psi gradients on the FFT grid via G-space
      differentiation; also compute the von Weizsacker KED tau_W =
      |grad(rho)|^2/(8*rho) and the Thomas-Fermi KED tau_TF =
      (3/10)*(3*pi^2)^{2/3}*rho^{5/3} used to define the dimensionless variable
      alpha = (tau - tau_W)/tau_TF
- [x] **116.5.3.2** Implement SCAN (Strongly Constrained and Appropriately
      Normed, Sun, Ruzsinszky, Perdew, Phys. Rev. Lett. 115, 036402, 2015):
      meta-GGA satisfying all 17 known exact constraints; exchange: F_x(s,
      alpha) with switching function h_1(alpha) interpolating between alpha=0
      (single-bond), alpha=1 (slowly-varying density), and alpha>>1 (weak-bond)
      regimes; correlation: separate slowly-varying and iso-orbital terms with
      smooth interpolation; implement the full functional form with all
      parameters (c1x, c2x, dx, k1, etc.)
- [x] **116.5.3.3** Implement r2SCAN (Furness, Kaplan, Ning, Perdew, Sun, J.
      Phys. Chem. Lett. 11, 8208, 2020): regularized SCAN with improved
      numerical stability — replace the alpha switching function with a smoother
      regularized version; eliminate numerical issues in the exchange
      enhancement factor near alpha=0 and alpha=1; same accuracy as SCAN but
      orders of magnitude better numerical behavior
- [x] **116.5.3.4** Implement TPSS (Tao, Perdew, Staroverov, Scuseria, Phys.
      Rev. Lett. 91, 146401, 2003): non-empirical meta-GGA based on the exchange
      hole model; and revTPSS (Perdew et al., Phys. Rev. Lett. 103, 026403,
      2009): revised TPSS with improved lattice constants for solids
- [x] **116.5.3.5** Implement MS0/MS1/MS2 (Made Simple, Sun et al., J. Chem.
      Phys. 138, 044113, 2013): meta-GGA functionals built from a simple
      interpolation between the uniform density limit and the single-orbital
      limit using the alpha variable
- [x] **116.5.3.6** Implement meta-GGA potential: the XC potential for meta-GGAs
      includes a term involving the functional derivative with respect to tau,
      delta E_xc/delta tau(r); in the generalized Kohn-Sham framework, this
      contributes a non-multiplicative potential operator
      -div(d(epsilon_xc)/d(grad(psi))) that must be applied to wavefunctions
      during the Hamiltonian application

#### 116.5.4 Hybrid Functionals

- [x] **116.5.4.1** Implement PBE0 (Adamo & Barone, J. Chem. Phys. 110, 6158,
      1999): E*xc = 0.25*E_x^{EXX} + 0.75*E_x^{PBE} + E_c^{PBE} with exact
      exchange fraction alpha = 0.25; implement the exact exchange operator
      (Fock exchange) K|psi_n> = -sum_m f_m * psi*m(r) * integral psi_m*(r') *
      psi_n(r') / |r-r'| dr'
- [x] **116.5.4.2** Implement HSE06 (Heyd, Scuseria, Ernzerhof, J. Chem. Phys.
      118, 8207, 2003; Krukau et al., J. Chem. Phys. 125, 224106, 2006):
      range-separated hybrid with E_xc = 0.25*E_x^{SR,EXX}(omega) +
      0.75*E_x^{SR,PBE}(omega) + E_x^{LR,PBE}(omega) + E_c^{PBE} with screening
      parameter omega = 0.11 Bohr^{-1} (HSE06); the short-range exact exchange
      decays exponentially, making it feasible for periodic systems; implement
      the range-separated Coulomb kernel erfc(omega\*r)/r for the short-range
      part
- [x] **116.5.4.3** Implement HSE03 variant: same form as HSE06 but with omega =
      0.15 Bohr^{-1}; provided for backward compatibility
- [x] **116.5.4.4** Implement B3LYP (Becke, J. Chem. Phys. 98, 5648, 1993;
      Stephens et al., J. Phys. Chem. 98, 11623, 1994): E_xc = (1-a)*E_x^{LDA} +
      a*E_x^{EXX} + b*Delta_E_x^{B88} + (1-c)*E_c^{VWN} + c\*E_c^{LYP} with
      a=0.20, b=0.72, c=0.81; most popular functional in molecular chemistry but
      less suitable for solids
- [x] **116.5.4.5** Implement dielectric-dependent hybrid (DDH, Skone et al.,
      Phys. Rev. B 89, 195112, 2014): self-consistently determine the exact
      exchange fraction alpha = 1/epsilon_inf where epsilon_inf is the
      electronic (optical) dielectric constant computed from DFPT; iterate alpha
      until self-consistency; improves band gaps for semiconductors and
      insulators without empirical parameters
- [x] **116.5.4.6** Implement Adaptively Compressed Exchange (ACE, Lin, J. Chem.
      Theory Comput. 12, 2242, 2016): accelerate exact exchange computation by
      compressing the exchange operator into a low-rank representation
      V*x|psi_i> ≈ sum_j |xi_j> <xi_j|psi_i> where {xi_j} are adaptively chosen
      projection vectors; reduces scaling from O(N_e^2 * N*k * N*pw) to O(N_e *
      N*proj * N_pw); critical for making hybrid functionals affordable in
      periodic systems
- [x] **116.5.4.7** Implement exact exchange for k-point sampling: compute Fock
      exchange K*{k}|psi*{n,k}> = -sum*{m,q} f*{m,q} _ integral psi\_{m,q}(r') _
      psi\_{n,k}(r') \* v(r-r',k-q) / V dr' where v is the Coulomb kernel (or
      screened kernel for HSE); the q-sum runs over the k-point grid; handle the
      q=k divergent head term via auxiliary function method or Gygi-Baldereschi
      approach

#### 116.5.5 Double-Hybrid Functionals

- [x] **116.5.5.1** Implement B2PLYP (Grimme, J. Chem. Phys. 124, 034108, 2006):
      E*xc = a_x*E_x^{EXX} + (1-a_x)*E_x^{B88} + (1-a_c)*E_c^{LYP} +
      a_c*E_c^{PT2} with a_x=0.53, a_c=0.27; the PT2 correlation term is
      second-order Moller-Plesset perturbation theory E_c^{PT2} = sum*{ia,jb}
      |<ij||ab>|^2 / (epsilon_i + epsilon_j - epsilon_a - epsilon_b); compute
      the two-electron integrals <ij||ab> in the plane-wave basis using the
      resolution-of-identity (RI) or density fitting approximation

#### 116.5.6 van der Waals Corrections

- [x] **116.5.6.1** Implement DFT-D2 (Grimme, J. Comput. Chem. 27, 1787, 2006):
      E*disp = -s_6 \* sum*{A<B} C*6^{AB} / R*{AB}^6 _ f*damp(R*{AB}) with
      geometric-mean combining rule C_6^{AB} = sqrt(C_6^A _ C*6^B) and
      Fermi-type damping function f_damp = 1/(1 + exp(-d\*(R*{AB}/R_0^{AB} -
      1))); implement the C_6 coefficient database and R_0 values for all
      elements
- [x] **116.5.6.2** Implement DFT-D3(BJ) (Grimme et al., J. Chem. Phys. 132,
      154104, 2010; Grimme et al., J. Comput. Chem. 32, 1456, 2011): E*disp =
      -sum*{n=6,8} s*n \* sum*{A<B} C*n^{AB} / (R*{AB}^n + f_n(R_0^{AB})^n) with
      Becke-Johnson (BJ) damping; coordination-number-dependent C_6 coefficients
      C_6^{AB}(CN_A, CN_B) interpolated from reference data; compute
      coordination numbers from the geometry using a counting function
- [x] **116.5.6.3** Implement DFT-D4 (Caldeweyher et al., J. Chem. Phys. 150,
      154122, 2019): electronegativity-equilibration scheme for atomic charges;
      charge-dependent C_6 coefficients; three-body ATM (Axilrod- Teller-Muto)
      dispersion term; implement the atomic polarizability model and the
      charge-equilibration (EEQ) scheme
- [x] **116.5.6.4** Implement Tkatchenko-Scheffler (TS) method (Phys. Rev. Lett.
      102, 073005, 2009): atom-in-molecule C_6 coefficients obtained by scaling
      free-atom C_6 values using Hirshfeld volume ratios C_6^eff =
      (V_eff/V_free)^2 \* C_6^free; implement the Hirshfeld partitioning of the
      electron density to obtain effective atomic volumes
- [x] **116.5.6.5** Implement many-body dispersion (MBD, Tkatchenko et al.,
      Phys. Rev. Lett. 108, 236402, 2012; Ambrosetti et al., J. Chem. Phys. 140,
      18A508, 2014): self-consistently screen the atomic polarizabilities using
      the dipole interaction tensor; solve the coupled fluctuating dipole model
      as an eigenvalue problem to obtain the MBD energy; captures many-body
      contributions beyond pairwise including screening and collective effects
- [x] **116.5.6.6** Implement vdW-DF (Dion et al., Phys. Rev. Lett. 92, 246401,
      2004): non-local correlation functional E*c^{nl} = (1/2)\_integral
      integral rho(r) * phi(r,r') * rho(r') dr dr' where the kernel phi depends
      on |r-r'| and on the local density and gradient at r and r'; implement the
      efficient Roman-Perez-Soler algorithm (Phys. Rev. Lett. 103, 096102, 2009)
      using FFT-based interpolation to reduce O(N^2) to O(N*log(N))
- [x] **116.5.6.7** Implement vdW-DF2 (Lee et al., Phys. Rev. B 82,
      081101, 2010) and rev-vdW-DF2 (Hamada, Phys. Rev. B 89, 121103, 2014):
      improved kernels with better short-range and exchange components; use
      rPW86 exchange for vdW-DF2
- [x] **116.5.6.8** Implement SCAN+rVV10 (Peng, Yang, Perdew, Phys. Rev. X 6,
      041005, 2016): combine SCAN meta-GGA with the revised VV10 non-local
      correlation (Vydrov & Van Voorhis, J. Chem. Phys. 133, 244103, 2010); a
      single parameter b is fitted; provides accurate lattice constants and
      binding energies for layered materials (graphite, h-BN, MoS2)

#### 116.5.7 DFT+U Methods

- [x] **116.5.7.1** Implement Dudarev (simplified rotationally-invariant) DFT+U
      (Dudarev et al., Phys. Rev. B 57, 1505, 1998): E*U = (U_eff/2) \*
      sum*{I,sigma} Tr[n_{I,sigma} - n_{I,sigma}^2] where n\_{I,sigma} is the
      occupation matrix of the localized orbitals on atom I with spin sigma and
      U_eff = U - J; compute occupation matrices by projecting Kohn-Sham
      wavefunctions onto atomic orbitals
- [x] **116.5.7.2** Implement Liechtenstein DFT+U (Liechtenstein et al., Phys.
      Rev. B 52, R5467, 1995): full rotationally-invariant form with separate U
      and J parameters; E*U = sum*{I} sum*{m,m',sigma} (U/2) \* n*{m,sigma}^I _
      n\_{m',-sigma}^I + ((U-J)/2) _ n*{m,sigma}^I \* n*{m',sigma}^I (m != m');
      properly handles the exchange interaction J between localized electrons
- [x] **116.5.7.3** Implement linear-response U calculation (Cococcioni & de
      Gironcoli, Phys. Rev. B 71, 035105, 2005): compute the Hubbard U parameter
      from first principles by applying a small perturbation alpha to the
      potential on the target site and computing the response chi = dn/d(alpha);
      U = chi_0^{-1} - chi^{-1} where chi_0 is the non-interacting response;
      implement the supercell approach for periodic systems
- [x] **116.5.7.4** Implement DFT+U+V (extended Hubbard, Campo & Cococcioni, J.
      Phys.: Condens. Matter 22, 055602, 2010; Timrov, Marzari, Cococcioni,
      Phys. Rev. B 103, 045141, 2021): include inter-site Hubbard V parameters
      to capture hybridization between neighboring sites; E\_{U,V} includes
      cross-site occupation matrix terms; compute V from linear response using
      DFPT (density-functional perturbation theory) with the HP code approach
- [x] **116.5.7.5** Implement occupation matrix projection: compute
      n*{mm'}^{I,sigma} = sum*{n,k} f*{n,k} \* <psi*{n,k,sigma}|phi*m^I> \*
      <phi_m'^I|psi*{n,k,sigma}> where |phi_m^I> are the localized (atomic)
      orbitals on site I; handle the choice of projector orbitals (atomic,
      ortho-atomic, PAW projectors) and the double-counting scheme (AMF vs. FLL)

#### 116.5.8 Libxc Compatibility & Validation

- [x] **116.5.8.1** Implement Libxc-compatible interface: define the standard
      functional interface matching the Libxc API — input: rho,
      sigma=|grad(rho)|^2, lapl_rho, tau; output: exc, vrho, vsigma, vlapl, vtau
      (energy density and potentials); support LDA, GGA, meta-GGA, and hybrid
      classes; enable any of the ~600 Libxc functionals to be used as a backend
      via FFI binding to the C Libxc library
- [x] **116.5.8.2** Implement functional combination framework: support linear
      combinations of exchange and correlation functionals with arbitrary
      weights; parse functional specifications like "0.25*HF + 0.75*PBE_X +
      PBE_C" into a composite functional; validate that exchange and correlation
      parts are both specified
- [x] **116.5.8.3** Implement functional validation test suite: compute
      atomization energies for the G2/97 test set (148 molecules), lattice
      constants for 60 elemental solids, and bulk moduli for 20 test cases;
      compare with reference values from the literature and report mean absolute
      errors; regression test against Libxc reference output values for
      numerical precision validation

---

### 116.6 Band Structure & Density of States

#### 116.6.1 Band Structure Computation

- [x] **116.6.1.1** Implement non-self-consistent (NSCF) band structure
      calculation: read converged charge density from SCF, compute V*eff, and
      diagonalize the Hamiltonian at k-points along the high-symmetry path
      without updating the density; compute eigenvalues epsilon*{n,k} for all
      requested bands at each k-point on the path
- [x] **116.6.1.2** Implement high-symmetry k-path generation using Setyawan-
      Curtarolo conventions (Comput. Mater. Sci. 49, 299, 2010): automatic
      detection of Bravais lattice type from lattice vectors and space group;
      look up the standard high-symmetry points and path for each of the 14
      Bravais lattices; generate N interpolated k-points between each pair of
      high-symmetry points
- [x] **116.6.1.3** Implement Hinuma-Pizzi-Kumagai-Oba-Tanaka k-path conventions
      (Comput. Mater. Sci. 128, 140, 2017): alternative conventions compatible
      with SeeK-path; handle the monoclinic and triclinic special cases that
      differ from Setyawan-Curtarolo
- [x] **116.6.1.4** Implement band structure plotting data generation: compute
      the k-distance along the path (cumulative |Delta_k| between consecutive
      points), mark high-symmetry point positions, output (k_distance,
      epsilon_n) data for all bands; support multiple spin channels and
      spin-orbit split bands
- [x] **116.6.1.5** Implement band structure interpolation: given eigenvalues
      computed on a coarse k-grid along the path, interpolate to a finer grid
      using Fourier interpolation (Pickett, Krakauer, Allen, Phys. Rev. B 38,
      2721, 1988) or spline interpolation; verify smoothness and continuity at
      high-symmetry points where band crossings occur
- [x] **116.6.1.6** Implement band ordering and connectivity: track band indices
      across k-points by maximizing the overlap <psi*{n,k}|psi*{m,k+dk}> between
      neighboring k-points; handle band crossings and avoided crossings;
      essential for correct fat band and orbital character tracking
- [x] **116.6.1.7** Implement spin-orbit split band structure: for SOC
      calculations, output bands labeled by total angular momentum j and m_j
      quantum numbers where applicable; compute the spin-orbit splitting at
      high-symmetry points (e.g., Delta_SO at Gamma for semiconductors)
- [x] **116.6.1.8** Implement high-symmetry point table: database of
      high-symmetry k-points and their labels for all 14 Bravais lattice types —
      Gamma (0,0,0), X, M, K, L, W, U, etc. with fractional coordinates in
      reciprocal space; support both time-reversal-invariant momenta (TRIM) and
      general high-symmetry points

#### 116.6.2 Density of States

- [x] **116.6.2.1** Implement total DOS via histogram method with Gaussian
      broadening: g(E) = sum*{n,k} w_k \* delta_sigma(E - epsilon*{n,k}) where
      delta_sigma is a Gaussian of width sigma; energy grid from E_min - margin
      to E_max + margin with configurable resolution (default 0.01 eV)
- [x] **116.6.2.2** Implement tetrahedron method DOS (Blochl-corrected): divide
      the BZ into tetrahedra, interpolate eigenvalues linearly within each
      tetrahedron, compute the DOS analytically from the tetrahedron
      contributions; apply Blochl corrections for improved accuracy; produces
      sharp van Hove singularities without artificial broadening
- [x] **116.6.2.3** Implement projected DOS (PDOS): g*l^a(E) = sum*{n,k} w*k \*
      |<phi*{a,l,m}|psi*{n,k}>|^2 \* delta_sigma(E - epsilon*{n,k}) where the
      projections are onto atomic orbitals phi*{a,l,m} (s, p_x/p_y/p_z,
      d*{xy}/d*{xz}/d*{yz}/d*{x^2-y^2}/d*{z^2}, f orbitals) centered on atom a;
      resolve by atom AND by angular momentum channel
- [x] **116.6.2.4** Implement site-projected and orbital-resolved DOS with
      symmetry decomposition: project onto symmetry-adapted orbitals (e*g vs.
      t*{2g} for octahedral sites, etc.); compute total, partial
      (atom-resolved), and orbital-resolved (l,m-resolved) DOS simultaneously
- [x] **116.6.2.5** Implement integrated DOS N(E) = integral\_{-inf}^{E} g(E')
      dE' and verify N(E_F) = N_electrons as a consistency check; compute the
      inverse participation ratio to identify localized vs. delocalized states
- [x] **116.6.2.6** Implement Lorentzian broadening for DOS: alternative to
      Gaussian, delta_sigma(E) = (sigma/pi)/(E^2 + sigma^2), producing
      Lorentzian lineshapes that better approximate experimental spectroscopy
      (XPS, UPS) line shapes; support user-selectable broadening type
- [x] **116.6.2.7** Implement adaptive broadening DOS (Yates, Wang, Vanderbilt,
      Souza, Phys. Rev. B 75, 195121, 2007): use band-velocity-dependent
      broadening sigma*{n,k} = |v*{n,k}| \* Delta_k to adapt the broadening to
      the local band dispersion; produces sharper features near band edges and
      smoother regions in dispersive bands
- [x] **116.6.2.8** Implement spin-resolved DOS for magnetic systems: separate
      spin-up and spin-down DOS for collinear calculations; for non-collinear,
      decompose into majority/minority channels projected along the local
      magnetization axis; compute the spin polarization P(E) = (g_up(E) -
      g_down(E))/(g_up(E) + g_down(E)) at each energy

#### 116.6.3 Band Gap & Fermi Surface Analysis

- [x] **116.6.3.1** Implement band gap detection: search for the VBM (valence
      band maximum) and CBM (conduction band minimum) across all k-points;
      classify as direct (VBM and CBM at same k-point) or indirect (different
      k-points); report the gap value, k-point locations, and band indices;
      handle metallic systems (no gap) and zero-gap semiconductors
- [x] **116.6.3.2** Implement fat band computation: at each k-point, decompose
      each eigenstate into orbital contributions |<phi*{a,l,m}|psi*{n,k}>|^2 and
      represent as a band structure where the linewidth/color encodes the
      orbital character — e.g., red for d-character, blue for p-character;
      output projection weights for visualization
- [x] **116.6.3.3** Implement Fermi surface computation: evaluate eigenvalues on
      a dense 3D k-point grid, identify bands crossing the Fermi level, and
      extract the Fermi surface isosurface using marching cubes algorithm;
      output triangulated surface mesh with velocity/orbital-character coloring
      for visualization
- [x] **116.6.3.4** Implement effective mass tensor computation: at the VBM and
      CBM, compute the effective mass tensor (m*)\_{ij}^{-1} = (1/hbar^2) *
      d^2(epsilon_n)/d(k_i)\*d(k_j) by finite-difference second derivatives of
      eigenvalues on a fine k-grid around the extremum; diagonalize to get
      principal effective masses and directions; handle degenerate bands using
      k.p perturbation theory
- [x] **116.6.3.5** Implement band unfolding for supercell calculations: given a
      supercell calculation (e.g., with defects, disorder, or surface), unfold
      the bands back to the primitive cell Brillouin zone by computing the
      spectral function A(k,E) = sum*n sum_K |<k+K|psi*{n,K_super}>|^2 \*
      delta(E - epsilon_n) where k is the primitive cell k-point and K_super are
      supercell reciprocal lattice vectors (Popescu & Zunger, Phys. Rev. B 85,
      085201, 2012)
- [x] **116.6.3.6** Implement joint density of states: JDOS(E) = sum*{v,c,k}
      w_k \* delta(E - epsilon*{c,k} + epsilon\_{v,k}) where v and c run over
      valence and conduction bands; used to identify optical transition energies
      and van Hove singularities relevant for optical properties
- [x] **116.6.3.7** Implement Fermi surface nesting function: chi(q) = sum*{n,k}
      delta(epsilon*{n,k}) \* delta(epsilon\_{n,k+q}) computed on the Fermi
      surface; peaks in chi(q) indicate strong electron-phonon coupling and
      potential charge density wave instabilities; compute on a q-grid using
      tetrahedron method
- [x] **116.6.3.8** Implement Fermi velocity computation: v*{n,k} = (1/hbar) \*
      grad_k(epsilon*{n,k}) computed by finite differences or from the
      Hellmann-Feynman relation v = <psi|dH/dk|psi>/hbar; compute the Fermi
      velocity distribution and average Fermi velocity for transport property
      estimates
- [x] **116.6.3.9** Implement optical matrix elements: compute the momentum
      matrix elements p*{cv}(k) = <psi*{c,k}|p|psi*{v,k}> between valence and
      conduction states; used for optical absorption coefficient alpha(omega) =
      (4*pi^2*e^2)/(m^2*omega*c*V) _ sum_{v,c,k} |p\_{cv}|^2 * delta(epsilon_c -
      epsilon_v - hbar*omega); output optical joint DOS and transition matrix
      elements
- [x] **116.6.3.10** Implement k.p perturbation theory at band extrema: expand
      the Hamiltonian to second order around a high-symmetry point k_0: H(k_0+q)
      = H(k_0) + hbar*q.p/m + hbar^2*q^2/(2m); diagonalize in the degenerate
      subspace to obtain effective mass parameters, Luttinger parameters
      (gamma_1, gamma_2, gamma_3 for valence bands), and Kane energy E_P for the
      semiconductor k.p Hamiltonian

---

### 116.7 Wannier Functions (`@kalika/wannier`)

#### 116.7.1 Maximally Localized Wannier Functions (MLWF)

- [x] **116.7.1.1** Implement the Marzari-Vanderbilt spread functional (Marzari
      & Vanderbilt, Phys. Rev. B 56, 12847, 1997): Omega = sum*n [<r^2>_n -
      <r>_n^2] decomposed into gauge-invariant part Omega_I = sum_n [<r^2>\_n -
      sum_b w_b |<u*{n,k}|u*{n,k+b}>|^2] and gauge-dependent part Omega_tilde =
      Omega_D + Omega_OD; the goal is to minimize Omega_tilde over all unitary
      mixing matrices U*{mn}^{(k)}
- [x] **116.7.1.2** Implement overlap matrix computation: M*{mn}^{(k,b)} =
      <u*{m,k}|u*{n,k+b}> where |u*{n,k}> is the periodic part of the Bloch
      state; compute on the plane-wave basis as a dot product of wavefunction
      coefficients with a phase shift; handle the finite- difference b-vectors
      connecting neighboring k-points with appropriate weights w_b from the
      Marzari-Vanderbilt b-vector shell condition
- [x] **116.7.1.3** Implement the spread minimization algorithm: steepest
      descent or conjugate gradient on the unitary group — compute the gradient
      of Omega with respect to anti-Hermitian perturbations dW = dOmega/dU _
      U^dagger; update U^{(k)} -> U^{(k)} _ exp(dW); ensure unitarity is
      maintained at each step; implement both the one-shot (steepest descent
      with line search) and CG variants
- [x] **116.7.1.4** Implement Wannier function center and spread computation:
      <r>_n = -(1/N_k) \* sum_{k,b} w*b * b _ Im(ln(M_{nn}^{(k,b)})) and <r^2>_n
      = (1/N_k) \* sum_{k,b} w*b \* [1 - |M*{nn}^{(k,b)}|^2 +
      (Im(ln(M\_{nn}^{(k,b)})))^2]; track the total spread Omega and its
      decomposition during minimization as convergence diagnostics
- [x] **116.7.1.5** Implement Wannier function real-space evaluation: w*n(r) =
      (1/N_k) * sum_k exp(-i*k.R) \* sum_m U*{mn}^{(k)} \* psi\_{m,k}(r);
      evaluate on a real-space grid by summing the rotated Bloch states; output
      the Wannier function amplitude for visualization (cube file format or
      XCRYSDEN xsf format)

#### 116.7.2 Disentanglement

- [x] **116.7.2.1** Implement the Souza-Marzari-Vanderbilt (SMV) disentanglement
      procedure (Phys. Rev. B 65, 035109, 2001): for entangled bands (where the
      target bands overlap with other bands in energy), select an optimal
      N*wan-dimensional subspace from the N_band-dimensional Hilbert space at
      each k-point by minimizing the gauge-invariant spread Omega_I; maintain a
      rectangular matrix V*{mn}^{(k)} (N_band x N_wan) whose columns are the
      selected subspace vectors
- [x] **116.7.2.2** Implement the disentanglement iteration: compute the
      Z-matrix Z\_{mn}^{(k)} = sum*b w_b * (V^{(k+b)})^dagger \_ M^{(k,b)} \*
      V^{(k)}; at each k, take the N_wan eigenvectors of Z^{(k)} with largest
      eigenvalues; iterate to self-consistency; then proceed with MLWF
      minimization within the selected subspace
- [x] **116.7.2.3** Implement frozen window and outer window: allow the user to
      specify an energy window [E_min_outer, E_max_outer] for the
      disentanglement space and a frozen window [E_min_frozen, E_max_frozen]
      where bands are kept unchanged; bands inside the frozen window are forced
      into the selected subspace without modification
- [x] **116.7.2.4** Implement automatic window selection: given a target orbital
      set (e.g., "Fe 3d + O 2p"), automatically determine appropriate inner and
      outer energy windows based on the orbital projections of the bands;
      compute the band character ("fatness") to identify which bands belong to
      the target set

#### 116.7.3 Wannier Interpolation

- [x] **116.7.3.1** Implement Wannier-interpolated band structure: compute the
      Hamiltonian in the Wannier basis H*{mn}^{(R)} = <w*{m,0}|H|w*{n,R}> by
      inverse Fourier transform of the rotated Bloch Hamiltonian H*{mn}^{(k)} =
      U^dagger _ diag(epsilon\_{n,k}) _ U; then interpolate to arbitrary
      k-points via H*{mn}^{(k)} = sum_R exp(i*k.R) _ H_{mn}^{(R)}; diagonalize
      the small N_wan x N_wan matrix to get the interpolated eigenvalues —
      orders of magnitude cheaper than recomputing from DFT
- [x] **116.7.3.2** Implement Wannier-interpolated DOS: evaluate eigenvalues on
      an ultra-dense k-grid (e.g., 100x100x100) using Wannier interpolation;
      compute the DOS from these eigenvalues using the tetrahedron method or
      adaptive Gaussian broadening; this is far more efficient than DFT NSCF on
      such a dense grid
- [x] **116.7.3.3** Implement Wannier-interpolated Fermi surface: evaluate
      eigenvalues on a dense 3D k-grid via Wannier interpolation; extract Fermi
      surface using marching cubes; compute Fermi velocity v_n(k) = (1/hbar) *
      grad_k(epsilon_n(k)) from the interpolated Hamiltonian gradient
      dH^{(k)}/dk = sum_R i*R * exp(i*k.R) \* H^{(R)}
- [x] **116.7.3.4** Implement Wannier tight-binding Hamiltonian export: output
      the real-space Hamiltonian matrix H\_{mn}^{(R)} and lattice vectors R in a
      standard format (hr.dat matching WANNIER90); this tight-binding model can
      be used for transport calculations (Landauer, Boltzmann), topological
      invariant computation, or as input to many-body methods (DMFT)
- [x] **116.7.3.5** Implement Wannier-interpolated matrix elements: beyond
      eigenvalues, interpolate arbitrary operators O*{mn}^{(k)} = sum_R
      exp(i*k.R) _ <w_{m,0}|O|w*{n,R}>; specifically implement the position
      operator r*{mn}^{(k)} (needed for Berry phase), velocity operator
      v*{mn}^{(k)} (needed for optical conductivity), and spin operator
      s*{mn}^{(k)} (needed for spin Hall effect)

#### 116.7.4 Berry Phase & Topological Properties

- [x] **116.7.4.1** Implement Berry connection from Wannier functions:
      A*{mn}^{alpha}(k) = <u*{m,k}|d/dk*alpha|u*{n,k}> = sum*R i*R_alpha *
      exp(i*k.R) _ H_{mn}^{(R)} (computed from the Wannier Hamiltonian
      gradient); and Berry curvature Omega*{mn}^{alpha,beta}(k) =
      d(A_m^beta)/d(k_alpha) - d(A_m^alpha)/d(k_beta) + i\*[A^alpha,
      A^beta]*{mn}
- [x] **116.7.4.2** Implement the Berry phase for electric polarization: P*alpha
      = -(e/(2*pi)^3) _ integral_BZ dk _ sum_n f_n _ A_{nn}^alpha(k); compute
      using the King-Smith-Vanderbilt discrete formula phi_alpha = sum_k
      Im(ln(det(M^{(k,k+b_alpha)}))) over the k-point string in direction alpha;
      correctly handle the quantum of polarization (e\*R/V) ambiguity
- [x] **116.7.4.3** Implement Born effective charges from Wannier functions:
      Z\*_{kappa,alpha,beta} = d(P_beta)/d(tau_{kappa,alpha}) computed as the
      change in Wannier center positions with respect to atomic displacements;
      the Born effective charges are essential for computing LO-TO splitting in
      polar materials
- [x] **116.7.4.4** Implement dielectric tensor from Wannier interpolation:
      epsilon*{alpha,beta}(omega) = delta*{alpha,beta} + (4*pi*e^2)/(V) _
      sum_{v,c,k} |<psi*{c,k}|r*alpha|psi*{v,k}>|^2 / (epsilon*{c,k} -
      epsilon*{v,k} - omega - i*eta) \* (f*{v,k} - f*{c,k}); compute optical
      matrix elements from the Wannier position operator

#### 116.7.5 WANNIER90 Format Compatibility

- [x] **116.7.5.1** Implement .win file parser/writer: parse the WANNIER90
      master input file — num_wann, num_bands, mp_grid, unit_cell_cart,
      atoms_frac, projections, dis_win_min/max, dis_froz_min/max, num_iter, and
      all keyword parameters; write the corresponding file from internal data
- [x] **116.7.5.2** Implement .amn file parser/writer: initial projection matrix
      A*{mn}^{(k)} = <psi*{m,k}|g_n> where g_n are the initial guess projection
      functions (atomic orbitals or Gaussian-type orbitals); format: n_bands,
      n_wann, n_kpts, followed by (m, n, ik, Re(A), Im(A))
- [x] **116.7.5.3** Implement .mmn file parser/writer: overlap matrix
      M*{mn}^{(k,b)} = <u*{m,k}|u\_{n,k+b}> for all k-point pairs connected by
      b-vectors; format: n_bands, n_kpts, n_bvec, followed by blocks of (ik,
      ik+b, G_shift, M_matrix)
- [x] **116.7.5.4** Implement .eig file parser/writer: eigenvalues
      epsilon\_{n,k} for all bands and k-points; format: (n, ik, epsilon) per
      line
- [x] **116.7.5.5** Implement _hr.dat file parser/writer: real-space Hamiltonian
      H_{mn}^{(R)} with degeneracy weights; format: n_wann, n_rpts,
      degeneracy_list, then (R1, R2, R3, m, n, Re(H), Im(H)) per line

---

### 116.8 Structural Optimization & Cell Relaxation

#### 116.8.1 Ionic Relaxation Algorithms

- [x] **116.8.1.1** Implement BFGS quasi-Newton optimizer (Broyden-Fletcher-
      Goldfarb-Shanno): maintain approximate inverse Hessian H^{-1}; update with
      rank-2 formula using position and force differences between steps; line
      search along the BFGS direction with Wolfe conditions; reset H^{-1} to
      identity if step fails; convergence when max|F| < F_tol (default 0.01
      eV/Angstrom)
- [x] **116.8.1.2** Implement L-BFGS (limited-memory BFGS): store only the last
      m (typically 5-20) position/gradient pairs instead of the full N x N
      Hessian; two-loop recursion to compute the search direction; essential for
      large systems where the full Hessian is too expensive to store
- [x] **116.8.1.3** Implement conjugate gradient optimizer: Fletcher-Reeves or
      Polak-Ribiere beta formula; reset to steepest descent every N steps or
      when the CG direction ceases to be a descent direction; line search with
      cubic interpolation
- [x] **116.8.1.4** Implement FIRE algorithm (Fast Inertial Relaxation Engine,
      Bitzek et al., Phys. Rev. Lett. 97, 170201, 2006): velocity Verlet
      integration with adaptive time step; mix velocity with force direction v =
      (1-alpha)_v + alpha_|v|\*F_hat; if P = F.v > 0, increase dt and decrease
      alpha; if P <= 0, stop, reduce dt, increase alpha; robust for pathological
      energy landscapes and no line search needed
- [x] **116.8.1.5** Implement constraint handling: fix specific atoms (selective
      dynamics), fix specific Cartesian directions, constrain bond lengths or
      angles using SHAKE/RATTLE constraints or Lagrange multipliers; project
      forces onto the constraint manifold before optimization step

#### 116.8.2 Variable-Cell Relaxation

- [x] **116.8.2.1** Implement variable-cell relaxation: simultaneously optimize
      atomic positions and cell shape/volume; use the stress tensor to compute
      the generalized force on the lattice vectors; combine ionic forces and
      stress into a unified force vector and optimize using BFGS or L-BFGS in
      the extended (positions + cell) space; handle the coupling between cell
      change and fractional coordinate change correctly
- [x] **116.8.2.2** Implement the extended Lagrangian approach (Wentzcovitch,
      Phys. Rev. B 44, 2358, 1991): use damped dynamics simultaneously for ionic
      positions and cell parameters with a modified Parrinello-Rahman
      Lagrangian; the cell degrees of freedom evolve under the stress tensor
      while ions evolve under forces
- [x] **116.8.2.3** Implement cell-only optimization: fix atomic fractional
      coordinates and optimize only the cell parameters (a, b, c, alpha, beta,
      gamma) using the stress tensor; useful for equation of state calculations
      where only volume/shape changes

#### 116.8.3 Equation of State Fitting

- [x] **116.8.3.1** Implement Birch-Murnaghan equation of state (3rd order):
      E(V) = E_0 + (9/16)*B_0*V_0*{[(V_0/V)^{2/3}-1]^3*B_0' +
      [(V_0/V)^{2/3}-1]^2*[6-4*(V_0/V)^{2/3}]} fitting parameters E_0, V_0, B_0,
      B_0'; and 4th order with additional B_0'' parameter; non-linear least
      squares fit to E(V) data from multiple volume calculations
- [x] **116.8.3.2** Implement Vinet equation of state (Vinet et al., J. Phys.:
      Condens. Matter 1, 1941, 1989): E(V) = E*0 + (4*B_0*V_0/(B_0'-1)^2) * {1 -
      [1-eta_(B_0'-1)] _ exp(-eta_(B_0'-1))} where eta = (V/V_0)^{1/3} - 1;
      better for highly compressed materials
- [x] **116.8.3.3** Implement Rose equation of state (Rose et al., Phys. Rev. B
      29, 2963, 1984): universal binding energy relation; implement the fit and
      compare with Birch-Murnaghan and Vinet for consistency check
- [x] **116.8.3.4** Implement EOS fitting workflow: automated calculation runner
      that performs SCF at 7-11 volumes (V_0 \* [0.94, 0.96, ..., 1.06]), fits
      all EOS forms, reports E_0, V_0, B_0, B_0' with error bars from the fit
      covariance matrix, and generates E(V) and P(V) plots

#### 116.8.4 Elastic Properties

- [x] **116.8.4.1** Implement elastic constants via stress-strain method: apply
      6 independent strain modes (3 normal + 3 shear: epsilon*{xx},
      epsilon*{yy}, epsilon*{zz}, epsilon*{yz}, epsilon*{xz}, epsilon*{xy}) at
      small magnitudes (+/- delta, delta ~ 0.005-0.01), compute stress at each
      strained configuration, and extract the 6x6 elastic constants tensor
      C\_{ij} = d(sigma_i)/d(epsilon_j) via central finite differences
- [x] **116.8.4.2** Implement elastic constants via energy-strain method:
      alternative approach computing E(epsilon) for each strain mode and
      extracting C\_{ij} from the curvature d^2E/d(epsilon_i)\*d(epsilon_j);
      more robust for systems with numerical noise in the stress tensor
- [x] **116.8.4.3** Implement Voigt-Reuss-Hill elastic moduli: from C\_{ij},
      compute the Voigt (upper bound) and Reuss (lower bound) estimates of the
      isotropic bulk modulus B and shear modulus G; Hill average as (B_V +
      B_R)/2; compute Young's modulus E = 9*B*G/(3*B+G) and Poisson's ratio nu =
      (3*B-2*G)/(6*B+2\*G); check mechanical stability conditions (Born criteria
      for the crystal system)
- [x] **116.8.4.4** Implement elastic anisotropy measures: Zener anisotropy
      ratio A = 2\*C_44/(C_11-C_12) for cubic systems; universal anisotropy
      index A^U (Ranganathan & Ostoja-Starzewski, Phys. Rev. Lett. 101, 055504,
      2008); directional Young's modulus and Poisson ratio for visualization as
      3D surfaces

#### 116.8.5 Transition State Search

- [x] **116.8.5.1** Implement Nudged Elastic Band (NEB, Jonsson et al.):
      discretize the reaction path into N images connected by spring forces;
      compute the tangent at each image using the improved tangent estimate
      (Henkelman & Jonsson, J. Chem. Phys. 113, 9978, 2000); project out the
      parallel component of the true force and the perpendicular component of
      the spring force to get the NEB force; optimize all images simultaneously
- [x] **116.8.5.2** Implement climbing-image NEB (CI-NEB, Henkelman, Uberuaga,
      Jonsson, J. Chem. Phys. 113, 9901, 2000): after initial NEB convergence,
      the highest-energy image is driven uphill along the path by inverting the
      parallel force component; this image converges to the exact saddle point,
      giving a rigorous transition state energy
- [x] **116.8.5.3** Implement variable-spring NEB: use stronger springs near the
      transition state and weaker springs away from it to improve resolution at
      the barrier; spring constant k_i proportional to the energy of image i
      relative to the endpoints
- [x] **116.8.5.4** Implement growing string method (Peters et al., J. Chem.
      Phys. 120, 7877, 2004): grow the reaction path from both endpoints toward
      the transition state by adding images one at a time; avoids the need for
      an initial path guess spanning the entire reaction coordinate; more
      efficient than NEB when the endpoints are far apart
- [x] **116.8.5.5** Implement dimer method (Henkelman & Jonsson, J. Chem. Phys.
      111, 7010, 1999): find saddle points without knowing the final state; a
      "dimer" of two configurations separated by a small distance delta_R is
      rotated to align with the lowest curvature mode and then translated uphill
      along this mode; converges to the nearest saddle point from any starting
      configuration

---

### 116.9 Charge Density Analysis

#### 116.9.1 Population Analysis Methods

- [x] **116.9.1.1** Implement Bader charge analysis (Henkelman algorithm,
      Henkelman, Arnaldsson, Jonsson, Comput. Mater. Sci. 36, 354, 2006):
      partition the charge density into atomic basins bounded by zero-flux
      surfaces (grad(rho) . n = 0); assign each FFT grid point to the basin
      whose attractor (density maximum) it flows to via steepest ascent;
      integrate the charge within each basin; use the efficient grid-based
      algorithm with weight assignment for boundary points
- [x] **116.9.1.2** Implement Mulliken population analysis: P*mu = sum*{nu}
      (D\*S)\_{mu,nu} where D is the density matrix and S is the overlap matrix
      in the atomic orbital basis; partition electrons among atoms and orbitals;
      requires projection onto a localized basis set (for plane-wave codes,
      project onto pseudoatomic orbitals)
- [x] **116.9.1.3** Implement Lowdin population analysis: orthogonalize the
      atomic orbital basis using S^{-1/2} (symmetric orthogonalization) before
      computing populations; P*mu^Lowdin = (S^{1/2} * D _ S^{1/2})_{mu,mu}; less
      basis-set dependent than Mulliken but still requires a localized basis
      projection
- [x] **116.9.1.4** Implement Hirshfeld charge analysis (Hirshfeld, Theor. Chim.
      Acta 44, 129, 1977): partition the charge using atomic weight functions
      w_a(r) = rho_a^free(r) / sum_b rho_b^free(r) where rho_a^free is the
      free-atom density; charge on atom a = integral w_a(r) \* rho(r) dr;
      requires pre-computed free-atom densities; less basis-dependent than
      Mulliken/Lowdin
- [x] **116.9.1.5** Implement iterative Hirshfeld (Hirshfeld-I, Bultinck et al.,
      J. Chem. Phys. 126, 144111, 2007): iteratively update the reference atomic
      densities rho_a^ref using the partial charges from the previous iteration
      until self-consistency; produces charges that satisfy the exact sum rule
      and are less sensitive to the choice of reference state
- [x] **116.9.1.6** Implement Voronoi deformation density (VDD) analysis:
      partition space into Voronoi cells around each atom; compute the
      deformation density integral within each cell q_a^VDD =
      -integral_Voronoi(a) [rho(r) - sum_b rho_b^free(r)] dr; provides a
      complementary charge partitioning to Bader and Hirshfeld
- [x] **116.9.1.7** Implement charge density topological analysis: compute
      critical points of rho(r) (maxima = nuclei, saddle points = bond critical
      points, ring critical points, cage critical points); compute rho,
      grad(rho), Laplacian(rho) at each critical point; classify bonds by the
      sign of the Laplacian at the bond critical point (negative =
      shared/covalent, positive = closed-shell/ionic)
- [x] **116.9.1.8** Implement free-atom density database: precompute and store
      spherically-averaged all-electron atomic charge densities for all elements
      Z=1-103 using self-consistent atomic DFT calculations for each XC
      functional (LDA, PBE, SCAN); these reference densities are needed by
      Hirshfeld, VDD, and charge density difference analyses

#### 116.9.2 Bonding Analysis

- [x] **116.9.2.1** Implement Crystal Orbital Hamilton Population (COHP)
      analysis (Dronskowski & Blochl, J. Phys. Chem. 97, 8617, 1993):
      COHP*{ij}(E) = H*{ij} \* COOP*{ij}(E) where H*{ij} is the Hamiltonian
      matrix element between atomic orbitals i and j; integrated COHP (ICOHP)
      measures the covalent bond strength; positive COHP = bonding, negative =
      antibonding; implementation requires projection onto a local orbital basis
      matching LOBSTER (Maintz et al., J. Comput. Chem. 37, 1030, 2016)
- [x] **116.9.2.2** Implement Crystal Orbital Overlap Population (COOP)
      analysis: COOP*{ij}(E) = sum*{n,k} w*k \* c*{i,n,k}\* _ S\_{ij} _
      c*{j,n,k} \* delta(E - epsilon*{n,k}) where c are LCAO coefficients and S
      is the overlap matrix; COOP > 0 indicates bonding character, COOP < 0
      antibonding; integrate to get bond order
- [x] **116.9.2.3** Implement PAW-based local orbital projection for COHP/COOP:
      project the plane-wave wavefunctions onto the PAW partial waves to obtain
      LCAO-like coefficients; use the PAW transformation to ensure the
      all-electron character is captured; this is the approach used by LOBSTER
      for VASP compatibility
- [x] **116.9.2.4** Implement charge density difference computation:
      Delta_rho(r) = rho_total(r) - sum_a rho_a^isolated(r) for deformation
      density (bonding), or rho_AB(r) - rho_A(r) - rho_B(r) for interaction
      density between fragments A and B; output on the FFT grid for
      visualization

#### 116.9.3 Electron Localization Functions

- [x] **116.9.3.1** Implement Electron Localization Function (ELF, Becke &
      Edgecombe, J. Chem. Phys. 92, 5397, 1990): ELF(r) = 1/(1 + (D/D_h)^2)
      where D = tau - |grad(rho)|^2/(8*rho) is the Pauli kinetic energy density
      (excess KED beyond the bosonic ground state) and D_h =
      (3/5)*(6*pi^2)^{2/3} * rho^{5/3} is the homogeneous electron gas
      reference; ELF = 1 for perfect localization, ELF = 0.5 for electron-
      gas-like, ELF = 0 for perfect delocalization; requires the kinetic energy
      density tau(r) from the KS orbitals
- [x] **116.9.3.2** Implement Localized Orbital Locator (LOL, Schmider & Becke,
      J. Mol. Struct. (THEOCHEM) 527, 51, 2000): LOL(r) = tau_TF(r) /
      (tau_TF(r) + tau(r)) where tau_TF = (3/10)*(3*pi^2)^{2/3}\*rho^{5/3} is
      the Thomas-Fermi KED; related to ELF but with different physical
      interpretation (kinetic energy excess)
- [x] **116.9.3.3** Implement charge density output: write the charge density,
      spin density, ELF, LOL, and other scalar fields on the real-space grid in
      standard formats — CHGCAR (VASP-compatible), Gaussian cube format, and
      XCRYSDEN xsf format; include proper header information (lattice vectors,
      atomic positions, grid dimensions)

---

### 116.10 Parallelization & Performance

#### 116.10.1 Distributed Computation

- [x] **116.10.1.1** Implement k-point parallelization: distribute k-points
      across worker threads/processes; each worker handles a subset of k-points
      independently (embarrassingly parallel); reduce eigenvalues, forces, and
      total energy contributions across workers; use Rayon (Rust) for shared-
      memory parallelism and message passing for distributed parallelism
- [x] **116.10.1.2** Implement band parallelization: within each k-point,
      distribute bands across threads; relevant for the Davidson eigensolver
      where multiple trial vectors can be expanded independently; implement
      parallel matrix-vector products for the Hamiltonian application
- [x] **116.10.1.3** Implement plane-wave (G-vector) parallelization: distribute
      the G-vectors across processes; each process stores only its share of the
      wavefunction coefficients; the FFT requires an all-to-all communication
      step (slab decomposition or pencil decomposition); implement using Rayon
      for threads and optional MPI binding for multi-node
- [x] **116.10.1.4** Implement FFT parallelization with slab decomposition: for
      3D FFT of size N1 x N2 x N3, distribute along one dimension (slabs of size
      N1 x N2 x (N3/P)); perform local 2D FFTs, transpose data across processes
      (all-to-all), perform final 1D FFTs locally; this is the standard approach
      for parallel 3D FFT in DFT codes

#### 116.10.2 GPU Acceleration

- [x] **116.10.2.1** Implement GPU-accelerated FFT kernels via wgpu: compute 3D
      FFTs on the GPU for the charge density and wavefunction transforms;
      implement the Bluestein/chirp-z algorithm for arbitrary FFT sizes on GPU;
      batch multiple wavefunction FFTs into a single GPU dispatch
- [x] **116.10.2.2** Implement GPU-accelerated matrix operations: the subspace
      diagonalization step involves dense matrix-matrix multiplications (GEMM)
      of size N*bands x N_bands; implement these on GPU via wgpu compute
      shaders; also GPU-accelerate the construction of the subspace Hamiltonian
      H*{mn} = <psi_m|H|psi_n> via batched dot products
- [x] **116.10.2.3** Implement GPU-accelerated Davidson eigensolver: the main
      bottleneck is the Hamiltonian application H|psi>; offload the kinetic
      energy (pointwise multiply in G-space), local potential application (FFT
      -> pointwise multiply -> FFT), and nonlocal potential application
      (projector dot products + accumulation) to the GPU; keep the subspace
      diagonalization and mixing on CPU/GPU depending on size
- [x] **116.10.2.4** Implement GPU memory management: for large systems, the
      wavefunctions may not fit in GPU memory; implement streaming of bands
      to/from GPU with overlap of computation and data transfer; track GPU
      memory usage and fall back to CPU for operations that exceed GPU memory

#### 116.10.3 Memory & I/O Optimization

- [x] **116.10.3.1** Implement out-of-core wavefunction storage: for large
      systems where all wavefunctions cannot fit in RAM, store wavefunctions on
      disk (memory-mapped files or explicit I/O) and read/write as needed during
      the SCF loop; implement an LRU cache for the most-accessed bands/k-points
- [x] **116.10.3.2** Implement restart file (checkpoint) I/O: save the full SCF
      state (charge density, wavefunctions, mixing history, iteration count,
      cell geometry) to a binary checkpoint file at configurable intervals; read
      the checkpoint to resume an interrupted calculation without restarting
      from scratch; use a versioned binary format with checksums for data
      integrity
- [x] **116.10.3.3** Implement wavefunction compression: store wavefunctions
      using only the significant plane-wave coefficients (those above a
      magnitude threshold) to reduce memory/disk usage; for checkpoint files,
      use lz4 or zstd compression; benchmark the accuracy vs. compression
      tradeoff
- [x] **116.10.3.4** Implement memory usage estimation: before starting a
      calculation, estimate the total memory required (wavefunctions: N*bands *
      N*kpts * N*pw * 16 bytes, charge density: N*grid * 8 bytes, potentials:
      N_grid \* 8 bytes, projectors, etc.) and warn the user if it exceeds
      available RAM; suggest parallelization or out-of-core strategies

#### 116.10.4 Performance Benchmarking

- [x] **116.10.4.1** Implement silicon diamond benchmark: 2-atom cell, PBE, PAW,
      E_cut = 400 eV, 8x8x8 k-grid; measure SCF convergence (iterations to 1e-6
      eV), wall time per SCF step, total time, and compare band structure with
      known results (indirect gap ~0.6 eV at PBE level, experimental 1.17 eV)
- [x] **116.10.4.2** Implement diamond carbon benchmark: 2-atom cell with high
      E_cut (800 eV for hard pseudopotential), testing the FFT performance and
      plane-wave engine at large basis set sizes
- [x] **116.10.4.3** Implement BCC iron benchmark: 1-atom cell, spin-polarized
      PBE+U (or plain PBE), testing the spin-polarized SCF convergence and
      magnetic moment (expected ~2.2 mu_B); verify equation of state and elastic
      constants against literature values
- [x] **116.10.4.4** Implement GaAs benchmark: 2-atom cell, testing band
      structure (direct gap at Gamma, expected ~0.5 eV at PBE level vs.
      experimental 1.52 eV), effective masses, and Born effective charges if
      Wannier interpolation is used
- [x] **116.10.4.5** Implement perovskite (SrTiO3/BaTiO3) benchmark: 5-atom
      cell, testing structural optimization (lattice constant, tetragonal
      distortion for BaTiO3), Born effective charges, and the sensitivity to XC
      functional choice (PBE vs. PBEsol vs. SCAN)
- [x] **116.10.4.6** Implement scaling benchmark: measure wall time vs. system
      size for silicon supercells (2, 8, 16, 64, 128, 256 atoms) to verify
      O(N^3) scaling; measure parallel efficiency for k-point and band
      parallelization; report GFLOPS and bandwidth utilization

<!-- prettier-ignore-end -->
