pythtb.Wannier.disentangle#

Wannier.disentangle(n_wfs=None, outer_window='all', frozen_window=None, max_iter=1000, tol=1e-10, mix=1.0, tf_speedup=False, verbose=True)[source]#

Disentanglement of a subspace that minimizes gauge-independent spread.

This procedure implements the Souza–Marzari–Vanderbilt (SMV) disentanglement algorithm [1]. The goal is to select an n_wfs-dimensional optimal subspace from a larger set of Bloch eigenstates in a specified “outer window,” such that the gauge-independent part of the Wannier spread \(\Omega_I\) is minimized. The procedure is iterative, updating the subspace at each k-point until self-consistency is achieved.

Parameters:
n_wfsint or None, optional

Number of states in the optimal subspace. If None, the number of trial wavefunctions is used.

outer_windowstr, tuple, list, or dict, optional

Defines the “disentanglement window,” i.e. the set of candidate states from which the optimal subspace is chosen. States outside this window are ignored. Options:

  • "occupied": All states below the Fermi level.

  • "all": All available states.

  • (Emin, Emax): Energy range in eV.

  • {"bands": [i1, i2, ...]}: Explicit band indices.

  • {"energy": (Emin, Emax)}: Energy window.

Defaults to "all".

frozen_windowstr, tuple, list, dict, or None, optional

Defines the “frozen window,” i.e. states that must be exactly included in the subspace. This ensures that, for example, the occupied manifold is preserved while disentangling higher states. Options follow the same conventions as outer_window. If None, no states are frozen. Defaults to None.

max_iterint, optional

Maximum number of optimization iterations. Defaults to 1000.

tolfloat, optional

Convergence tolerance for the optimization. Defaults to 1e-10.

mixfloat, optional

Mixing parameter for iterative updates. mix=1 uses the new step fully, while smaller values blend the new and old projectors. Defaults to 1.

tf_speedupbool, optional

If True, use the tensorflow package for accelerated linear algebra. Defaults to False.

verbosebool, optional

If True, print detailed iteration to the logger. Defaults to True.

Notes

  • The disentanglement algorithm iteratively refines the projectors onto the optimal subspace by solving the eigenvalue problem

    \[\left[\sum_{\mathbf{b}} w_b \,\hat{\mathcal{P}}_{\mathbf{k}+\mathbf{b}}^{(i)}\right] | u_{m\mathbf{k}}^{(i)} \rangle = \lambda_{m\mathbf{k}}^{(i)} | u_{m\mathbf{k}}^{(i)} \rangle,\]

    where \(\hat{\mathcal{P}}_{\mathbf{k}+\mathbf{b}}^{(i)}\) is the projector from the previous iteration. The states with the largest \(n_\text{wfs}\) eigenvalues are selected to form the new subspace.

  • The role of the outer window is to provide flexibility: states above or below the frozen region can be borrowed to reduce \(\Omega_I\). The frozen window ensures that crucial states (e.g. fully occupied bands) are exactly included regardless of the optimization outcome.

  • After convergence, the .tilde_states attribute stores the disentangled wavefunctions spanning the optimized subspace.

References

[1]

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

On this page