pythtb.Wannier.project

Wannier.project(tf_list=None, band_idxs=None, use_tilde=False)

Initialize or update Bloch-like states by projection onto trial functions.

This method performs the single-shot projection step used in Wannierization as desribed in [1] (Sec. II) and used in the disentanglement initialization of [2]. For each k-point, it builds the overlap matrix between selected states and the trial wavefunctions, computes its SVD, and applies the optimal unitary (or semi-unitary) alignment to produce projected states \(\tilde{\psi}_{n\mathbf{k}}\).

The projected states are passed to set_tilde_states(), which also updates derived quantities (Wannier functions, centers, and spreads).

Parameters:

tf_listlist of list of tuple, optional

Trial-wavefunction specification passed to set_trial_wfs(). If None, already stored trial wavefunctions are reused. Each trial wavefunction is a list of the form [(orb, amp), ...], for spinless models, or [(orb, spin, amp), ...] for spinful models, where orb is the orbital index, spin is the spin index, and amp is the complex amplitude. Trial wavefunctions are normalized internally, so only the relative amplitudes matter.

band_idxslist of int, optional

Indices of states to project.

• If use_tilde=False and band_idxs is None, defaults to the first half of Bloch eigenstates (half-filling assumption).

• If use_tilde=True and band_idxs is None, defaults to all current tilde-state indices.

use_tildebool, optional

If False (default), project from Bloch energy eigenstates. If True, re-project within the current tilde-state manifold.

Raises:

ValueError

If trial wavefunctions are unavailable.

See also

set_trial_wfs()

for setting trial wavefunctions.

set_tilde_states()

for setting the Bloch-like states directly.

Notes

• Specifically, for the overlap matrix

  \[A_{n j}(\mathbf{k}) \;=\; \langle \psi_{n\mathbf{k}} \mid t_j \rangle ,\]

  we compute \(A(\mathbf{k}) = V(\mathbf{k}) \Sigma(\mathbf{k}) W^\dagger(\mathbf{k})\) and rotate the selected energy eigenstates by \(U(\mathbf{k}) \equiv V(\mathbf{k}) W^\dagger(\mathbf{k})\):

  \[\tilde{\psi}_{n\mathbf{k}} \;=\; \sum_{m}^{\texttt{band_idxs}} U_{nm}(\mathbf{k}) \, \psi_{m\mathbf{k}} .\]

• Projection can produce at most len(band_idxs) independent states. For best stability, use no more trial functions than selected bands (n_trial <= len(band_idxs)).

References

[1]

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).