pythtb.Wannier.min_spread#

Wannier.min_spread(outer_window='all', inner_window=None, twfs_2=None, n_wfs=None, max_iter=1000, max_iter_dis=1000, alpha=0.5, tol_max_loc=1e-05, tol_dis=1e-10, grad_min=0.001, mix=1, verbose=False)[source]#

Run disentanglement + projection + maximal-localization workflow.

This method performs three steps:

  1. Calls disentangle() to find the optimal subspace that minimizes the gauge-independent spread.

  2. Applies a second projection using twfs_2 if provided, or the original trial wavefunctions otherwise, to refine the states within the optimal subspace. This step ensures that the states are well-aligned with the desired chemical character before localization. It uses the project() method for this projection.

  3. Calls maxloc() to find the unitary transformation that minimizes the gauge-dependent spread, resulting in maximally localized Wannier functions.

Parameters:
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".

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

twfs_2list of list of tuple or None, optional

A second set of trial wavefunctions for the projection step after disentanglement. If None, the original trial wavefunctions are used. Defaults to None.

n_wfsint or None, optional

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

max_iterint, optional

Maximum number of iterations for the maximal localization step. Default is 1000.

max_iter_disint, optional

Maximum number of iterations for the disentanglement step. Default is 1000.

alphafloat, optional

Step size for gradient descent in the maximal localization step. Typical values are between 0 and 1. Default is 1/2.

tol_max_locfloat, optional

Convergence tolerance for the change in spread in the maximal localization step. Default is 1e-5.

tol_disfloat, optional

Convergence tolerance for the disentanglement step. Default is 1e-10.

grad_minfloat, optional

Minimum gradient magnitude for convergence in the maximal localization step. Default is 1e-3.

mixfloat, optional

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

verbosebool, optional

If True, print detailed iteration information to the logger. Default is False.

Notes

  • This method combines disentanglement and maximal localization to produce maximally localized Wannier functions from a set of Bloch states. It first identifies an optimal subspace, then refines the states via projection, and finally minimizes the gauge-dependent spread.

  • The resulting Wannier functions are stored in the .tilde_states attribute after the procedure completes.

On this page