Wannierization Workflows
Wannierization constructs localized orbitals from Bloch states. These orbitals can turn a large band calculation into a compact Hamiltonian that is cheap to evaluate at new momenta. The central practical question is what the compact representation preserves. Reproducing a band plot does not by itself ensure that the retained states, spin matrix elements, or optical response are accurate. This guide separates subspace selection, localization, interpolation, and tests of the resulting operators, including a small exact model.
Required background. Wannier functions introduces Bloch projectors, basis freedom, and the Bloch–Wannier transform. Band structure workflows explains how to obtain a converged source Hamiltonian and sample the full Brillouin zone.
Bloch subspaces and their bases
Section titled “Bloch subspaces and their bases”A subspace specifies which states are retained. A basis specifies how those states are described. Changing an orthonormal basis within one subspace changes matrices but preserves predictions when all states and operators are transformed together. Changing the subspace can change the predictions themselves.
Let the columns of be orthonormal source Bloch states, with . Choose combinations through a rectangular matrix , then rotate their basis with :
Here is an orthonormal frame: an ordered basis varying with momentum. The projector depends on but not on . A momentum-dependent can change individual orbital centers, spreads, and hoppings while leaving the represented subspace unchanged.
For an isolated band family, its spectral projector is separated from excluded bands at every momentum. Crossings within the family are allowed. One may take the source frame to contain exactly these states, so that no subspace selection is needed. Direct isolation does not require an indirect insulating gap or a completely occupied family.
For entangled bands, the desired states must instead be selected from a larger space. Changing changes the retained projector. The disentanglement method of Souza, Marzari, and Vanderbilt (2001) selects a subspace that varies smoothly across momentum, before optimizing its internal basis. Smoothness is useful, but the resulting states must still describe the physics of interest.
Choose the intended use before choosing tolerances. Energy interpolation for a density of states, spin matrix elements, and optical transitions require different comparisons. A small energy error cannot replace an operator test.
Source states and the physical inner product
Section titled “Source states and the physical inner product”Hold the source Hamiltonian fixed while studying Wannierization errors. Changing the crystal structure, density, magnetic state, functional, or relativistic treatment changes the physical calculation. Increasing the Wannier mesh or hopping range addresses a different question.
Retain the eigenvalues and states, lattice and reciprocal vectors, orbital positions, spinor conventions, neighbor overlaps, and physical matrices of the operators you will use. Eigenvalues alone contain no information about relative phases or orbital character. Keep the input parameters and software versions so another calculation can reproduce these quantities.
In a nonorthogonal coefficient basis, normalization uses its positive overlap matrix :
Euclidean normalization of the coefficient columns generally gives the wrong inner product. Likewise, a neighbor overlap involves two different bases:
The cross-momentum matrix includes the physical overlap and the reciprocal boundary identification when the neighbor lies outside the chosen zone. Replacing it by is not generally valid. Boundary phases, spin rotations, and orbital positions must be consistent across all links.
If contains physical operator matrix elements in the coefficient basis, its source-state matrix is . The alternative expression applies only when is explicitly the coefficient-action matrix. Distinguishing these conventions prevents an extra or missing factor of .
An isolated family needs a direct separation from its complement throughout the zone. An entangled calculation needs enough source states everywhere to support its chosen rank and mandatory states. A plotting path tests neither condition over the full zone.
Trial orbitals, windows, and frozen states
Section titled “Trial orbitals, windows, and frozen states”Trial orbitals provide an initial guess. First remove their linear dependencies and normalize their span in the physical inner product. For independent physical trial columns , an orthonormal choice is
In a nonorthogonal coefficient basis replace by . Project the normalized trials into the source space:
The last expression requires full column rank. For normalized frames, the singular values of measure how well the source space contains the trial directions. A small positive value means that one projected direction has a small norm and can be sensitive to perturbations; zero means rank loss. Arbitrarily rescaling an unnormalized trial changes these values without changing its span. Thus a numerical threshold needs a fixed normalization and a relevant error scale. Check conditioning throughout the mesh.
The outer window supplies available source states. The frozen window specifies source eigenstates that the selected subspace must contain exactly, up to numerical tolerance. These meanings are described in the Wannier90 parameter documentation. Necessary pointwise conditions are
For an orthonormal frozen-state matrix expressed in the outer frame, test
These counts alone do not guarantee a smooth or symmetry-compatible solution. An impossible state count makes the requested construction infeasible. A residual above tolerance means the computed subspace does not contain the required states; it can also reveal a convergence or implementation problem in an otherwise feasible calculation. Do not confuse these diagnoses.
Try physically plausible alternatives in windows and orbital character. For spinors, specify whether trials represent actual spin orbitals or an effective pseudospin, and include the correct local axes and site positions. Changing rank or windows changes the selected model; additional optimizer iterations alone cannot establish stability under those changes.
Localization and symmetry
Section titled “Localization and symmetry”Localization is controlled by the variation of the selected cell-periodic frame across momentum. Its neighbor overlaps are
Use the boundary identification before taking the inner product. Naively wrapping stored components can create a discontinuity that is absent from the physical states.
The quadratic spread separates as . At fixed projector, is independent of the internal basis, whereas changes with it. A standard discrete expression is
with finite-difference weights appropriate to the mesh. Marzari and Vanderbilt (1997) develop the spread minimization; the review by Marzari et al. (2012) explains its relation to disentanglement. Comparing spreads across different projectors mixes subspace selection with basis optimization. The smaller spread need not give more accurate observables.
Compare several starting guesses, residuals, individual spreads, and orbital centers as the mesh is refined. If symmetry is imposed, check its action on the frame as well. For a unitary source symmetry and desired orbital representation ,
An antiunitary action conjugates on the left. Include spin, fractional translations, and reciprocal boundary phases. Symmetry constraints can increase the smallest attainable spread; Sakuma (2013) describes a symmetry-adapted construction.
Failure to converge does not establish a topological obstruction. A nonzero Chern number does obstruct exponentially localized orthonormal translated Wannier functions for that isolated projector. The existence assumptions are developed in Wannier functions and Chern numbers. Requirements on a symmetry-preserving basis are additional conditions; use symmetry of Bloch states when deciding which symmetry constraints are appropriate.
Equal energies can hide different subspaces
Section titled “Equal energies can hide different subspaces”Consider three orthonormal internal states and the one-dimensional source Hamiltonian
Take and . The exact middle band has state and energy . Suppose instead that we retain the normalized candidate
where . The energy shifts of states 1 and 3 cancel in the expectation value:
Every compressed one-band Hamiltonian therefore reproduces the middle-band energy at every momentum. This equality survives arbitrarily fine energy sampling, but the states differ. With and , direct calculation gives
The observable measures the weight in the middle internal state. Its exact value in is 1, while the candidate gives
At , the projector distance is and the observable is , an absolute error of . The candidate also fails to form an invariant subspace:
This norm measures the part of the Hamiltonian action that leaves the retained space. It equals at the highlighted angle. A frozen constraint containing the exact middle state would reject every nonzero angle in this example.
The energy curves agree for every candidate, while the projector distance and observable error grow as and . At , they are and . These are deliberately chosen subspaces, not outputs of a localization algorithm.
The example isolates a limitation of energy-only comparisons. It does not claim that these candidates are equivalent minima of a spread functional.
Finite Fourier transforms and hopping range
Section titled “Finite Fourier transforms and hopping range”On a uniform mesh of momenta, the chosen frame defines
This finite transform changes basis within the discrete retained space. Its continuum interpretation and localization conditions are explained in Wannier functions. In a source eigenbasis with energy matrix , compute
The raw coefficients repeat on the Born–von Karman superlattice for an unshifted mesh. A shift introduces a phase for every superlattice vector :
Consequently, these repeated coefficients are not an infinite decaying hopping series. Select a finite set of real-space representatives . Equivalent representatives on a boundary may share a weight; orbital centers can also affect which separation is shortest. The Wannier90 interpolation notes explain this distinction. Preserve the shift phases and absorb all weights and representative mappings into final matrices . Check the file conventions before applying a weight: applying it twice changes the Hamiltonian.
For retained representatives , reconstruct
The full finite set must reproduce the construction samples. Keep Hermitian partners together, with . Off-mesh accuracy still requires testing: many continuous functions share the same finite samples. Exercise 8 gives an explicit aliasing example.
Dropping terms from this finite interpolation produces the bound
The triangle inequality proves it because each Fourier phase has unit modulus. For Hermitian reconstructions, corresponding ordered eigenvalues differ by at most . This bounds the deliberate truncation of the represented interpolation, not its sampling error, subspace error, or underlying electronic approximation. Even says nothing about unsampled Fourier components. Refine both the construction mesh and hopping range when testing a compact tight-binding model.
Operators and velocities in a moving basis
Section titled “Operators and velocities in a moving basis”For a translation-invariant one-body operator with source matrix , project consistently:
Fourier transform it using the Hamiltonian convention. Position, dipole, current, and interaction calculations may require derivative, nonlocal, augmentation, or multi-momentum terms. They are not determined by the interpolated energies alone.
Velocity illustrates the issue. When the physical Bloch Hamiltonian is differentiated in a fixed physical representation, the source matrix is
It is not generally the derivative of the diagonal eigenvalue matrix: the eigenvectors also vary with momentum. Project this physical matrix to obtain . For an invariant selected subspace, define the frame connection . Then
The commutator accounts for the moving basis. In an energy eigenbasis it does not change the diagonal group velocities, but it can change interband matrix elements. Wang et al. (2006) demonstrate the importance of geometric and interband information in Wannier interpolation of Hall response.
A generic disentangled subspace need not be invariant. Hamiltonian action into the discarded space then adds terms to the displayed identity. Project and test the full source velocity instead of inferring it from and its internal connection alone. Nonlocal and augmentation contributions must be included in the source operator when applicable.
Comparing energies, subspaces, and observables
Section titled “Comparing energies, subspaces, and observables”Evaluate source quantities at additional momenta across the full zone. Check that the test points are distinct from the construction points modulo reciprocal vectors: a shifted grid can still share points with the original. Refine locally around small gaps, avoided crossings, and Fermi pockets. A conventional path can miss the largest error.
Compare eigenvalue sets near degeneracies, where band labels can swap. Report maximum and weighted root-mean-square energy errors over the energy range of interest. The maximum reveals localized failures that an average can hide. Also check orthonormality, Hermiticity, frozen containment, and the chosen symmetries before interpreting a successful energy comparison.
For two orthonormal frames of the same rank, let the singular values of be . The angles measure the difference between their subspaces:
Internal basis rotations leave these angles unchanged. Unequal-rank orthogonal projectors have distance 1, so comparisons after increasing rank need a different question, such as containment of the smaller space. The overlap must use physical frames even when the two source windows contain different numbers of states.
Operator matrices require a basis alignment before subtraction. When the overlap is nonsingular, use its unitary polar factor
and compare with . This removes a basis rotation; it cannot remove a change of subspace. If an overlap singular value is too small for a stable correspondence, report the subspace mismatch rather than forcing an operator comparison.
For normalized test-point weights , define the absolute RMS difference and reference scale separately:
The Frobenius norm sums squared matrix elements. A dimensionless comparison can use , with a physically chosen floor and the absolute difference reported too. This avoids meaningless pointwise percentages at zeros. For a vector operator, sum over components in both squared norms and use for components.
Finally vary mesh, hopping range, starts, and plausible windows or trials separately. A stable optimization at fixed projector does not establish that another sensible subspace gives the same observables. Conversely, agreement among these numerical checks does not correct missing physics in the source Hamiltonian. In particular, a precise Kohn–Sham representation does not automatically give quasiparticle energies or the screened interactions needed for Hubbard physics in materials.
Exercises
Section titled “Exercises”Exercise 1: Classify the operations
Section titled “Exercise 1: Classify the operations”Distinguish exact basis changes, subspace choices, numerical approximations, and physical reductions for: a rotation; a complete finite Bloch–Wannier transform; selecting an isolated band family; entangled subspace selection; finite momentum sampling; hopping truncation; and projecting a Coulomb interaction.
Solution
A rotation and the complete finite transform are exact basis changes inside the selected discrete space. An isolated family defines an exact spectral projector, but discarding its complement is a physical reduction whose usefulness depends on the observable and energy scale. Entangled selection changes the retained subspace.
Finite sampling approximates a continuous momentum problem; truncation approximates its finite interpolation. Computing the matrix of a specified operator is exact for a given projector. Replacing full many-body dynamics by a projected Hamiltonian is generally an additional approximation. Eliminating complementary states can generate new interactions and energy dependence. Keeping all bare projected Coulomb matrix elements does not automatically include those effects.
Exercise 2: Test a normalized trial projection
Section titled “Exercise 2: Test a normalized trial projection”Two orthonormal physical trials, projected into a three-state outer space, give
Compute its singular values, , , and . If a chosen numerical requirement is , what does a refined-mesh value establish?
Solution
The singular values are 1 and . Therefore
Both values are nonzero, and
The value fails the stated requirement but remains nonzero: it does not prove rank loss. Normalization amplifies absolute perturbations in a projected direction whose norm is small. Assess that sensitivity relative to the actual numerical errors, and reconsider the trials or available source space if necessary. Arbitrarily rescaling a trial could change the unnormalized singular value without improving its physical overlap; that is why the normalization in the question matters.
Exercise 3: Repair impossible windows
Section titled “Exercise 3: Repair impossible windows”A calculation requests . At one momentum the outer window contains five states; at another the frozen window contains seven. Explain the failures and possible repairs. Does a failed containment residual always prove this same kind of infeasibility?
Solution
Five states cannot span six independent retained directions. Widen the outer window or compute more source bands. Seven independent frozen states cannot fit inside rank six. Narrow the frozen window or increase the rank, recognizing that the latter changes the reduced model.
Containment is a separate test of the computed subspace. For example, with two available states and , freezing is feasible. The incorrect candidate has containment residual 1, whereas has residual 0. Thus failed containment can reflect a bad result rather than an impossible count.
Exercise 4: Reconstruct and truncate a Hamiltonian
Section titled “Exercise 4: Reconstruct and truncate a Hamiltonian”On the dimensionless mesh , a scalar Hamiltonian has values . Use
Choose the symmetric lift , dividing the self-inverse boundary class equally between . Find the coefficients. What goes wrong if only are retained?
Solution
The raw boundary coefficient vanishes, so the final nonzero values are
They reconstruct and satisfy Hermitian pairing. Discarding alone gives , generally complex. The omitted-term norm is , but the truncated scalar function is no longer a Hermitian Hamiltonian. Retain both members of each pair. Keeping leaves zero tail within this finite model.
Exercise 5: Test the full zone
Section titled “Exercise 5: Test the full zone”Three construction meshes give maximum path errors . Distinct full-zone test points instead give maximum errors and RMS errors . Which meets a maximum-error target of ? What should be refined?
Solution
None meets the target. The decreasing RMS error shows improvement, but the finest full-zone maximum still exceeds . Inspect the momenta with the largest errors, including nearby gaps and orbital character. Refine the construction mesh and the test sampling in those regions while keeping the physical source Hamiltonian fixed. A small path error cannot substitute for the failed full-zone comparison.
Exercise 6: Include the velocity connection
Section titled “Exercise 6: Include the velocity connection”At one momentum in an invariant two-band subspace, let
Find . Which entries are group velocities, and what assumption prevents direct application to an arbitrary disentangled subspace?
Solution
The connection contribution is
so
At this momentum is diagonal, so the diagonal entries divided by are group velocities. The off-diagonal entry is an interband matrix element. Differentiating only eigenvalues would miss it. The identity assumes an invariant subspace. A generic disentangled projector permits Hamiltonian action into discarded states, so the full source velocity must be projected instead.
Exercise 7: Compare projectors
Section titled “Exercise 7: Compare projectors”Two equal-rank orthonormal frames at the same momentum have overlap singular values , , and . Find their projector distance. Can an internal unitary rotation reduce it below ?
Solution
The smallest singular value gives the largest principal angle:
Internal rotations preserve the two projectors and all their principal angles, so they cannot reduce this difference. Even identical energy curves would not establish that the subspaces describe the same states. The windows or trials must be reconsidered if this mismatch matters for the intended observable.
Exercise 8: Find an invisible Fourier component
Section titled “Exercise 8: Find an invisible Fourier component”A scalar source band is
Sample and fit the symmetric four-point interpolation. Show that it gives . Compare the two at . Does retaining every fitted coefficient bound the remaining sampling error by zero?
Solution
On these four samples, , so . The fifth harmonic is indistinguishable from the first. The fitted coefficients are , with the other independent coefficients zero. At the new momentum,
Their difference is . Keeping every fitted term gives because nothing in that finite interpolation was discarded. It does not bound the aliasing error between the interpolation and the source band. Additional source samples are needed to distinguish the two functions.
References
Section titled “References”- N. Marzari and D. Vanderbilt, “Maximally Localized Generalized Wannier Functions for Composite Energy Bands,” Physical Review B 56, 12847–12865 (1997), doi:10.1103/PhysRevB.56.12847.
- N. Marzari, A. A. Mostofi, J. R. Yates, I. Souza, and D. Vanderbilt, “Maximally Localized Wannier Functions: Theory and Applications,” Reviews of Modern Physics 84, 1419–1475 (2012), doi:10.1103/RevModPhys.84.1419.
- R. Sakuma, “Symmetry-Adapted Wannier Functions in the Maximal Localization Procedure,” Physical Review B 87, 235109 (2013), doi:10.1103/PhysRevB.87.235109.
- I. Souza, N. Marzari, and D. Vanderbilt, “Maximally Localized Wannier Functions for Entangled Energy Bands,” Physical Review B 65, 035109 (2001), doi:10.1103/PhysRevB.65.035109.
- X. Wang, J. R. Yates, I. Souza, and D. Vanderbilt, “Ab Initio Calculation of the Anomalous Hall Conductivity by Wannier Interpolation,” Physical Review B 74, 195118 (2006), doi:10.1103/PhysRevB.74.195118; erratum, Physical Review B 76, 169902 (2007), doi:10.1103/PhysRevB.76.169902.
- Wannier90 developers, “Files,” “Parameters,” and “Some Notes on the Interpolation,” Wannier90 User Guide, accessed 15 October 2026: file formats, frozen windows, finite-mesh interpolation.