Historical task source. The Eve task board holds current task state.
<!-- 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#
- 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) - 116.1.1.2 Create
project.jsonfor@kalika/electronic-structurewith Nx build (esbuild), test (vitest), and lint targets; add dependency edges to@kalika/core,@kalika/numerical-engine,@kalika/cas-engine,@kalika/algebra - 116.1.1.3 Create
package.jsonfor@kalika/electronic-structurewithcatalog:refs for vitest, typescript, tsup; add runtime dependencies on@kalika/core,@kalika/numerical-engine - 116.1.1.4 Create
tsconfig.jsonextending workspacetsconfig.base.jsonwith strict mode,composite: true, path references to dependency projects - 116.1.1.5 Add
@kalika/electronic-structurepath mapping totsconfig.base.json:"@kalika/electronic-structure": ["libs/kalika/electronic-structure/src/index.ts"] - 116.1.1.6 Create
libs/kalika/xc-functionals/directory structure withproject.json,package.json,tsconfig.jsonfor the standalone XC functional library@kalika/xc-functionals - 116.1.1.7 Create
libs/kalika/wannier/directory structure withproject.json,package.json,tsconfig.jsonfor the Wannier function library@kalika/wannier - 116.1.1.8 Add
@kalika/xc-functionalsand@kalika/wannierpath mappings totsconfig.base.json - 116.1.1.9 Initialize Rust workspace in
libs/kalika/electronic-structure/rust/withCargo.toml(workspace members:pw-engine,scf-solver,eigensolver,fft-kernel,xc-kernel), configurewasm-packandnapi-rsdual-target builds - 116.1.1.10 Create barrel exports in
src/index.tsfor all public types, classes, factories, and constants; ensure tree-shaking compatibility with explicit named exports - 116.1.1.11 Configure Rust-to-WASM build pipeline:
wasm-pack build --target nodejsfor each Rust crate; generate TypeScript type definitions from Rust structs viatsify; create npm-compatible WASM package with.wasmbinary, JS glue code, and.d.tstype definitions - 116.1.1.12 Configure Rust-to-native build pipeline via
napi-rs: create#[napi]bindings for all Rust compute kernels; build.nodenative addon for x86_64 and aarch64; implement feature-flag toggling between WASM and native at runtime based on environment detection - 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#
- 116.1.2.1 Implement
LatticeVectorstype: 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) - 116.1.2.2 Implement
UnitCelltype: lattice vectors, list ofAtompositions (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 - 116.1.2.3 Implement
Atomtype: 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) - 116.1.2.4 Implement
KPointtype: 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 - 116.1.2.5 Implement
KPointGridtype: 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 - 116.1.2.6 Implement
SpaceGrouptype: 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 - 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
- 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
- 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#
- 116.1.3.1 Implement
Wavefunctiontype: 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) - 116.1.3.2 Implement
ChargeDensitytype: 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 - 116.1.3.3 Implement
Potentialtype: 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 - 116.1.3.4 Implement
BandStructuretype: 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 - 116.1.3.5 Implement
DensityOfStatestype: 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 - 116.1.3.6 Implement
SCFStatetype: 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 - 116.1.3.7 Implement
DFTCalculationorchestrator 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#
- 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
- 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 - 116.1.4.3 Implement QE input/output parser:
pw.xinput file format (&CONTROL,&SYSTEM,&ELECTRONS,ATOMIC_SPECIES,ATOMIC_POSITIONS,K_POINTS,CELL_PARAMETERS), XML output data-file-schema.xml - 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)
- 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
- 116.1.4.6 Implement ABINIT input parser: parse
input.abiformat withacell,rprim,typat,xred/xcart,ecut,nkpt,kpt,occopt,tsmear,ixckeywords; output conversion from internal format to ABINIT input - 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#
- 116.2.1.1 Implement reciprocal lattice vector computation in Rust: given real-space lattice vectors a_i, compute b_i = 2pi(a_j x a_k)/V with exact double-precision arithmetic; verify b_i . a_j = 2pidelta_ij orthogonality to machine epsilon
- 116.2.1.2 Implement G-vector generation: enumerate all reciprocal lattice vectors G = n1b1 + n2b2 + 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
- 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
- 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)
- 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
- 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 4E_cut or 8E_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)#
- 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
- 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)
- 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
- 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)
- 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
- 116.2.2.6 Implement Hartree potential via FFT: solve Poisson equation V_H(G) = 4pirho(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
- 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
- 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#
- 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
- 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
- 116.2.3.3 Implement nonlocal potential application (Kleinman-Bylander form): VNL|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>
- 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>
- 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
- 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)#
- 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
- 116.2.4.2 Implement APW basis functions: inside muffin-tin sphere, expand in radial functions times spherical harmonics ul(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
- 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
- 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_lHu_l' and u_l*u_l' weighted by Gaunt coefficients for angular integration
116.3 Pseudopotential Infrastructure#
116.3.1 Norm-Conserving Pseudopotentials#
- 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
- 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
- 116.3.1.3 Implement Kleinman-Bylander (KB) separable form: transform the semi-local pseudopotential Vl(r) into fully nonlocal separable form V_NL = sum{l,m} |deltaV_l * phi{l,m}> <deltaV_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)
- 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)
- 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)
- 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#
- 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
- 116.3.2.2 Implement USPP augmentation charge: compute Qij(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
- 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)
- 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#
- 116.3.3.1 Implement PAW transformation theory (Blochl, Phys. Rev. B 50, 17953, 1994): linear transformation T mapping smooth pseudo-wavefunctions |tildepsi> 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
- 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
- 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
- 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
- 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)
- 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#
- 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)
- 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
- 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
- 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)
- 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#
- 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
- 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)
- 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
- 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#
- 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
- 116.3.6.2 Implement spin-orbit Hamiltonian: add the SOC contribution HSOC = 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)
- 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#
- 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
- 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
- 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
- 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
- 116.4.1.5 Implement SCF convergence monitoring: track total energy Etotal, 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#
- 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
- 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
- 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
- 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
- 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
- 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#
- 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, Hpsi_n - E_npsi_n}; expand subspace with preconditioned residuals; diagonalize the projected Hamiltonian in the subspace; extract improved eigenvectors; iterate until residual norms ||Hpsi_n - E_nS*psi_n|| < tol; block Davidson for multiple eigenvalues simultaneously
- 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)
- 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
- 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
- 116.4.3.5 Implement subspace diagonalization: given the filtered or iterated subspace {psin}, construct the projected Hamiltonian H{mn} = <psim|H|psi_n> and overlap S{mn} = <psim|S|psi_n>, solve the generalized eigenvalue problem Hc = epsilonSc using LAPACK dsygv/zhegv (via napi-rs binding or pure Rust), and rotate the wavefunctions psi_n <- sum_m psi_m _ c_{mn}
- 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
- 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
- 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#
- 116.4.4.1 Implement Gaussian smearing: f(x) = 0.5erfc(x/sigma) where x = (epsilon - E_F), sigma is the smearing width; entropy contribution -TS = -0.5sigmasum_{n,k} w_k * exp(-x^2/sigma^2) / sqrt(pi) for extrapolation to sigma->0
- 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
- 116.4.4.3 Implement Fermi-Dirac smearing: f(x) = 1/(exp(x/(kBT)) + 1) with electronic temperature T; physically motivated for finite-T DFT; entropy contribution -TS = -k_BT _ sum_{n,k} w_k * [f*ln(f) + (1-f)*ln(1-f)]
- 116.4.4.4 Implement cold smearing (Marzari-Vanderbilt, Phys. Rev. Lett. 82, 3296, 1999): f(x) = 0.5erfc(x/sigma) + (1/sqrt(2pi)) _ (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
- 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
- 116.4.4.6 Implement Fermi level determination: for each smearing method, solve Ne = sum{n,k} wk * 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#
- 116.4.5.1 Implement total energy computation: Etotal = 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 VHrho, 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
- 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
- 116.4.5.3 Implement Hellmann-Feynman forces: Fa = -dE/d(tau_a) = -integral rho(r) * dV_ion(r)/d(tau_a) - sum{n,k} f*{n,k} * <psi*{n,k}|dVNL/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
- 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)
- 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
- 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
- 116.4.5.7 Implement Harris-Foulkes energy functional: EHF = 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#
- 116.4.6.1 Implement collinear spin-polarized DFT: separate spin-up and spin-down channels with independent Kohn-Sham equations Hsigma|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
- 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'}
- 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)
- 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#
- 116.4.7.1 Implement Monkhorst-Pack k-point grid generation (Monkhorst & Pack, Phys. Rev. B 13, 5188, 1976): k_i = (2n_i - N_i - 1) / (2N_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
- 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
- 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
- 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
- 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)#
- 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/(4pirho))^{1/3}; separate parametrizations for r_s >= 1 (Pade approximant) and r_s < 1 (log series); implement both unpolarized and spin-polarized forms
- 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)
- 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
- 116.5.1.4 Implement LDA exchange: epsilon_x(rho) = -3/4 * (3rho/pi)^{1/3} (Dirac exchange); spin-polarized form using the spin-scaling relation epsilon_x[rho_up, rho_down] = (epsilon_x(2rho_up) + epsilon_x(2*rho_down))/2; compute both energy density and potential V_x = d(rho*epsilon_x)/d(rho)
- 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)#
- 116.5.2.1 Implement gradient computation: compute |grad(rho)|^2 on the FFT grid by transforming rho(G) -> iGrho(G) in each direction, then FFT to real space and compute the squared gradient; compute the reduced gradient s = |grad(rho)|/(2k_Frho) where k_F = (3pi^2rho)^{1/3}; handle the spin-polarized case with separate up/down gradients
- 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 + mus^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)|/(2phik_srho), phi = ((1+zeta)^{2/3} + (1-zeta)^{2/3})/2, k_s = sqrt(4*k_F/pi); the most widely used GGA
- 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
- 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
- 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
- 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 - betarho^{1/3}x^2 / (1 + 6betax*arcsinh(x)) where x = |grad(rho)|/rho^{4/3}; LYP correlation from the Colle-Salvetti formula reparametrized by Lee, Yang, and Parr
- 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
- 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
- 116.5.2.9 Implement GGA potential computation: V_xc,sigma(r) = d(rhoepsilon_xc)/d(rho_sigma) - div(d(rhoepsilon_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#
- 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/(8rho) 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
- 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.)
- 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
- 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
- 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
- 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#
- 116.5.4.1 Implement PBE0 (Adamo & Barone, J. Chem. Phys. 110, 6158, 1999): Exc = 0.25E_x^{EXX} + 0.75E_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 * psim(r) * integral psi_m*(r') * psi_n(r') / |r-r'| dr'
- 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.25E_x^{SR,EXX}(omega) + 0.75E_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
- 116.5.4.3 Implement HSE03 variant: same form as HSE06 but with omega = 0.15 Bohr^{-1}; provided for backward compatibility
- 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} + aE_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
- 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
- 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 Vx|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 * Nk * Npw) to O(N_e * Nproj * N_pw); critical for making hybrid functionals affordable in periodic systems
- 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#
- 116.5.5.1 Implement B2PLYP (Grimme, J. Chem. Phys. 124, 034108, 2006): Exc = a_xE_x^{EXX} + (1-a_x)E_x^{B88} + (1-a_c)E_c^{LYP} + a_cE_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#
- 116.5.6.1 Implement DFT-D2 (Grimme, J. Comput. Chem. 27, 1787, 2006): Edisp = -s_6 * sum{A<B} C6^{AB} / R{AB}^6 _ fdamp(R{AB}) with geometric-mean combining rule C_6^{AB} = sqrt(C_6^A _ C6^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
- 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): Edisp = -sum{n=6,8} sn * sum{A<B} Cn^{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
- 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
- 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
- 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
- 116.5.6.6 Implement vdW-DF (Dion et al., Phys. Rev. Lett. 92, 246401, 2004): non-local correlation functional Ec^{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(Nlog(N))
- 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
- 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#
- 116.5.7.1 Implement Dudarev (simplified rotationally-invariant) DFT+U (Dudarev et al., Phys. Rev. B 57, 1505, 1998): EU = (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
- 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; EU = 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
- 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
- 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
- 116.5.7.5 Implement occupation matrix projection: compute n*{mm'}^{I,sigma} = sum*{n,k} f*{n,k} * <psi*{n,k,sigma}|phim^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#
- 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
- 116.5.8.2 Implement functional combination framework: support linear combinations of exchange and correlation functionals with arbitrary weights; parse functional specifications like "0.25HF + 0.75PBE_X + PBE_C" into a composite functional; validate that exchange and correlation parts are both specified
- 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#
- 116.6.1.1 Implement non-self-consistent (NSCF) band structure calculation: read converged charge density from SCF, compute Veff, 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
- 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
- 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
- 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
- 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
- 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
- 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)
- 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#
- 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)
- 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
- 116.6.2.3 Implement projected DOS (PDOS): gl^a(E) = sum{n,k} wk * |<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
- 116.6.2.4 Implement site-projected and orbital-resolved DOS with symmetry decomposition: project onto symmetry-adapted orbitals (eg vs. t{2g} for octahedral sites, etc.); compute total, partial (atom-resolved), and orbital-resolved (l,m-resolved) DOS simultaneously
- 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
- 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
- 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
- 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#
- 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
- 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
- 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
- 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
- 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) = sumn 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)
- 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
- 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
- 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
- 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) = (4pi^2e^2)/(m^2omegacV) _ sum_{v,c,k} |p_{cv}|^2 * delta(epsilon_c - epsilon_v - hbaromega); output optical joint DOS and transition matrix elements
- 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) + hbarq.p/m + hbar^2q^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)#
- 116.7.1.1 Implement the Marzari-Vanderbilt spread functional (Marzari & Vanderbilt, Phys. Rev. B 56, 12847, 1997): Omega = sumn [<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)}
- 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
- 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
- 116.7.1.4 Implement Wannier function center and spread computation: <r>n = -(1/N_k) * sum{k,b} wb * b _ Im(ln(M_{nn}^{(k,b)})) and <r^2>n = (1/N_k) * sum{k,b} wb * [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
- 116.7.1.5 Implement Wannier function real-space evaluation: wn(r) = (1/N_k) * sum_k exp(-ik.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#
- 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 Nwan-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
- 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
- 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
- 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#
- 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
- 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
- 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 iR * exp(ik.R) * H^{(R)}
- 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)
- 116.7.3.5 Implement Wannier-interpolated matrix elements: beyond eigenvalues, interpolate arbitrary operators O*{mn}^{(k)} = sum_R exp(ik.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#
- 116.7.4.1 Implement Berry connection from Wannier functions: A*{mn}^{alpha}(k) = <u*{m,k}|d/dkalpha|u{n,k}> = sumR iR_alpha * exp(ik.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}
- 116.7.4.2 Implement the Berry phase for electric polarization: Palpha = -(e/(2pi)^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
- 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
- 116.7.4.4 Implement dielectric tensor from Wannier interpolation: epsilon*{alpha,beta}(omega) = delta*{alpha,beta} + (4pie^2)/(V) _ sum_{v,c,k} |<psi*{c,k}|ralpha|psi{v,k}>|^2 / (epsilon*{c,k} - epsilon*{v,k} - omega - ieta) * (f{v,k} - f*{c,k}); compute optical matrix elements from the Wannier position operator
116.7.5 WANNIER90 Format Compatibility#
- 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
- 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))
- 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)
- 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
- 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#
- 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)
- 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
- 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
- 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
- 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#
- 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
- 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
- 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#
- 116.8.3.1 Implement Birch-Murnaghan equation of state (3rd order): E(V) = E_0 + (9/16)B_0V_0*{[(V_0/V)^{2/3}-1]^3B_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
- 116.8.3.2 Implement Vinet equation of state (Vinet et al., J. Phys.: Condens. Matter 1, 1941, 1989): E(V) = E0 + (4B_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
- 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
- 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#
- 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
- 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
- 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 = 9BG/(3B+G) and Poisson's ratio nu = (3B-2G)/(6B+2*G); check mechanical stability conditions (Born criteria for the crystal system)
- 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#
- 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
- 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
- 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
- 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
- 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#
- 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
- 116.9.1.2 Implement Mulliken population analysis: Pmu = 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)
- 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
- 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
- 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
- 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
- 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)
- 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#
- 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)
- 116.9.2.2 Implement Crystal Orbital Overlap Population (COOP) analysis: COOP*{ij}(E) = sum*{n,k} wk * 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
- 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
- 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#
- 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/(8rho) 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
- 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)(3pi^2)^{2/3}*rho^{5/3} is the Thomas-Fermi KED; related to ELF but with different physical interpretation (kinetic energy excess)
- 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#
- 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
- 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
- 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
- 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#
- 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
- 116.10.2.2 Implement GPU-accelerated matrix operations: the subspace diagonalization step involves dense matrix-matrix multiplications (GEMM) of size Nbands 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
- 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
- 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#
- 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
- 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
- 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
- 116.10.3.4 Implement memory usage estimation: before starting a calculation, estimate the total memory required (wavefunctions: Nbands * Nkpts * Npw * 16 bytes, charge density: Ngrid * 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#
- 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)
- 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
- 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
- 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
- 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)
- 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 -->