pythtb.Wannier#

class Wannier(bloch_states)[source]#

Construct Wannier functions using the projection method.

This class provides methods to build Wannier functions from Bloch eigenstates and to evaluate their quadratic spreads. It realizes the Marzari-Vanderbilt maximal localization program on a toroidal k-mesh without endpoints by combining

Single-shot projection via SVD alignment to user-specified trial orbitals, producing Bloch-like states \(\tilde{\psi}_{n\mathbf{k}}\).
Disentanglement of entangled bands following the Souza-Marzari-Vanderbilt [2] scheme, where disentangle() optimizes projectors within user-defined outer and inner windows to minimize the gauge-invariant spread \(\Omega_I\).
Maximal localization thorugh the Marzari-Vanderbilt scheme [1] using maxloc(), which iteratively rotates the disentangled subspace to minimize the gauge-dependent spread \(\widetilde{\Omega}=\Omega_{\mathrm{OD}}+\Omega_{\mathrm{D}}\).

Together these steps construct Wannier functions from Bloch energy eigenstates and minimize their spreads through disentanglement and maximal localization.

Parameters:

bloch_statesWFArray: The Bloch wavefunctions to be Wannierized. This should be initialiazed on a toroidal k-mesh without endpoints (open k-axes). They should also have their values filled, either by setting manually or by calling WFArray.solve_model(). These can be energy eigenstates or any other set of Bloch-like states on the mesh.

Notes

The k-mesh must be a torus (no endpoints included).
tilde_states must be set before calling routines that compute Wannier functions or spreads.
Disentanglement workflow: disentangle() uses outer (candidate) and inner (frozen) windows to optimize projectors that define a smooth subspace with minimal gauge-invariant spread.
Maximal localization: maxloc() performs a steepest-descent update of the unitary gauge to reduce the gauge-dependent spread and produce maximally localized Wannier functions.
Wannier construction: We form Wannier functions by discrete inverse Fourier transform of the Bloch-like states,

\[w_{n\mathbf{R}} = \frac{1}{\sqrt{N_k}} \sum_{\mathbf{k}} e^{i\mathbf{k}\cdot\mathbf{R}}\,\tilde{\psi}_{n\mathbf{k}} .\]

In code this is done by np.fft.ifftn over the k-axes.
Overlap matrices: For nearest-neighbor k-shell displacements \(\{\mathbf{b}\}\) with weights \(\{w_b\}\), the code constructs the discrete overlaps

\[M_{mn}^{(\mathbf{b})}(\mathbf{k}) \equiv \langle u_{m\mathbf{k}} \mid u_{n,\mathbf{k}+\mathbf{b}}\rangle ,\]

using the cell-periodic parts of the Bloch-like states stored in tilde_states.
Spread decomposition (MV97): The total spread \(\Omega=\Omega_I+\widetilde{\Omega}\) is decomposed into the gauge-invariant part \(\Omega_I\) and the gauge-dependent part \(\widetilde{\Omega}=\Omega_{\mathrm{OD}}+\Omega_{\mathrm{D}}\). The code computes these using the diagonal and full elements of \(M^{(\mathbf{b})}\) as in [1].
Centers and phases: The Wannier-center vector for band \(n\) is obtained from the phases of the diagonal overlaps,

\[\mathbf{r}_n \;=\; -\frac{w_b}{N_k} \sum_{\mathbf{k}} \operatorname{Im}\!\left[\ln M_{nn}^{(\mathbf{b})}(\mathbf{k})\right] \, \mathbf{b} ,\]

References

[1] (1,2)

Marzari, N., & Vanderbilt, D. Maximally localized generalized Wannier functions for composite energy bands. Phys. Rev. B 56, 12847 (1997).

[2]

Souza, I., Marzari, N., & Vanderbilt, D. Maximally localized Wannier functions for entangled energy bands. Phys. Rev. B 65, 035109 (2001).

Examples

Initialize the Bloch WFArray on a toroidal k-mesh without endpoints

>>> from pythtb import TBModel, Lattice, Mesh, WFArray, Wannier
>>> lat_vecs = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
>>> orb_vecs = [[0, 0, 0]]
>>> lat = Lattice(lat_vecs, orb_vecs, periodic_dirs=[0, 1, 2])
>>> model = TBModel(lattice=lat, spinful=False)
>>> model.set_onsite(0.0)
>>> model.set_hop(-1.0, 0, 0, [1, 0, 0]) # along with other hops...
>>> mesh = Mesh(dim_k=3, axis_types=['k', 'k', 'k'])
>>> mesh.build_grid(shape=(8, 8, 8), k_endpoints=False)
>>> wfa = WFArray(lattice=lat, mesh=mesh, nstates=model.nbands, spinful=False)
>>> wfa.solve_model(model)
>>> wan = Wannier(bloch_states=wfa)

Set trial wavefunctions and perform single-shot projection

>>> twf_list = [[(0, 1.0)]]  # single trial wf on orbital 0
>>> wan.project(twf_list)

Perform maximal localization

>>> wan.maxloc(num_iter=100, conv_tol=1e-6)

Compute and print Wannier centers and spreads

>>> wan.info(precision=6)

Plot Wannier centers

>>> wan.plot_centers(wan_idx=0)

Methods#

`pythtb.Wannier.disentangle`	Disentanglement of a subspace that minimizes gauge-independent spread.
`pythtb.Wannier.get_centers`	Get the centers of the Wannier functions.
`pythtb.Wannier.info`	Report of Wannier centers and spreads.
`pythtb.Wannier.interp_bands`	Wannier interpolate the band structure along a k-path.
`pythtb.Wannier.maxloc`	Unitary transformation to minimize the gauge-dependent spread.
`pythtb.Wannier.min_spread`	Find the maximally localized Wannier functions using the projection method.
`pythtb.Wannier.plot_centers`	Plot the Wannier function centers in the supercell.
`pythtb.Wannier.plot_decay`	Plot the Wannier function density as a function of distance from center.
`pythtb.Wannier.plot_density`	Plot the Wannier function density on the lattice in 2D.
`pythtb.Wannier.project`	Perform Wannierization via optimal alignment with trial functions (single-shot SVD).
`pythtb.Wannier.set_tilde_states`	Set the Bloch-like states for the Wannier functions.
`pythtb.Wannier.set_trial_wfs`	Set trial wavefunctions for Wannierization.

Attributes#

`pythtb.Wannier.Amn`	Overlap matrix between energy eigenstates and trial wavefunctions.
`pythtb.Wannier.Omega_D`	Off-diagonal part of gauge-dependent spread.
`pythtb.Wannier.Omega_I`	Gauge-independent quadratic spread.
`pythtb.Wannier.Omega_OD`	Off-diagonal part of gauge-dependent spread.
`pythtb.Wannier.bloch_states`	WFArray object associated with the Bloch states.
`pythtb.Wannier.centers`	Centers of the Wannier functions in Cartesian coordinates.
`pythtb.Wannier.lattice`	Lattice object associated with the Wannier functions.
`pythtb.Wannier.mesh`	Mesh object associated with the Wannier functions.
`pythtb.Wannier.nks`	Number of k-points in each dimension.
`pythtb.Wannier.num_twfs`	Number of trial wavefunctions.
`pythtb.Wannier.spread`	Quadratic spread for each Wannier function.
`pythtb.Wannier.tilde_states`	WFArray corresponding to the Bloch-like (tilde) states.
`pythtb.Wannier.trial_wfs`	Trial wavefunctions to project onto.
`pythtb.Wannier.wannier`	Wannier functions.