View source for Constructing Wannier orbitals

[[:Category:Wannier_functions|Wannier orbitals]] are an important tool to study chemical bonding.
They also form the basis of various interpolation techniques.
As a quick summary, a Wannier orbital <math>|w_{m\mathbf{R}}\rangle</math> is a function obtained from a linear combination of the Bloch (Kohn-Sham) orbitals <math>|\psi_{n\mathbf{k}}\rangle</math>:
::<math>
|w_{m\mathbf{R}}\rangle =
\sum_{n\mathbf{k}}
e^{-i\mathbf{k}\cdot\mathbf{R}}
U_{mn\mathbf{k}}
|\psi_{n\mathbf{k}}\rangle,
</math>
where the unitary matrix <math>U_{mn\mathbf{k}}</math> is chosen such that the Wannier orbitals are localized in real space.
The process of finding a suitable Wannier transformation matrix <math>U_{mn\mathbf{k}}</math> is known as Wannierization.
This page guides you through the steps required to perform Wannierization using the approaches available in VASP.

== One-shot Wannierization using a singular-value decomposition ==

The two main Wannierization methods are projections onto local functions using the {{TAG|LOCPROJ}} tag and the Selected-Columns-of-the-Density-Matrix (SCDM) method using the {{TAG|LSCDM}} tag.
The {{TAG|LOCPROJ}} approach offers fine-grained control over the Wannierization process but is also more involved for electronically complex systems.
In this case, projection targets have to be chosen and placed manually using the {{TAG|LOCPROJ}} tag.
In contrast, the SCDM approach offers very little control and instead generates Wannier orbitals automatically from a small set of input parameters{{cite|damle:mms:2018}}.
This is convenient for systems where the electronic character of the band structure is complicated or unknown.

Both approaches produce as output a matrix <math>A_{mn \mathbf{k}}</math>.
In the case of the {{TAG|LOCPROJ}} tag, this is the projection matrix between the Bloch orbitals and the local functions, <math>\beta_m</math>:
::<math>
A_{mn, \bf{k}} \equiv \langle \beta_m | \tilde{S} | \Psi_{n \bf{k}} \rangle.
</math>
The operator <math>\tilde{S}</math> is the overlap operator in the [[Projector-augmented-wave formalism|projector-augmented-wave method]].
In the case of the SCDM method, the matrix <math>A_{mn \mathbf{k}}</math> is the result of an iterative process that extracts local functions from the information contained in the electronic one-particle density matrix.

In general, <math>A_{mn \mathbf{k}}</math> is not going to be a unitary matrix.
It could in principle be used to transform the Bloch orbitals into a set of non-orthogonal Wannier orbitals.
However, for many applications it is desirable to have orthonormal Wannier orbitals, such as for Wannier interpolation.
Therefore, <math>A_{mn \mathbf{k}}</math> needs to first be orthonormalized.

In VASP, we employ a one-shot orthonormalization procedure that uses the [https://en.wikipedia.org/wiki/Singular_value_decomposition singular-value decomposition] (SVD) of <math>A_{mn \mathbf{k}}</math>:
::<math>
A_{mn\mathbf{k}} = [D \Sigma V^\dagger]_{mn\mathbf{k}},
</math>
which is then used to construct the unitary matrix <math>U_{mn \mathbf{k}}</math>:
::<math>
U_{mn\mathbf{k}} = [DV^\dagger]_{mn\mathbf{k}}.
</math>
The SVD orthogonalization operates simultaneously on all local functions, in contrast to iterative methods (e.g. Gram-Schmidt orthogonalization).
This ensures that the symmetry properties of the local functions encoded in <math>A_{mn \mathbf{k}}</math> are preserved during the orthonormalization procedure.

== LOCPROJ method ==
To generate Wannier orbitals using local projections, it is sufficient to specify the {{TAG|LOCPROJ}} tag with suitable projection targets.
VASP will then apply the [[#One-shot Wannierization using a singular-value decomposition|one-shot orthonormalization]] internally to obtain the Wannier transformation matrix <math>U_{mn\mathbf{k}}</math>.
The number of Wannier orbitals is the same as the total number of local functions.
{{NB|tip|You can write the Wannier transformation matrix to disk by setting {{TAGO|LWRITE_WANPROJ|true}}.}}
This information can then be used to perform Wannier interpolation of the electronic band structure (for example, using the [[KPOINTS_WAN]] file).
It can also be passed to [http://www.wannier.org Wannier90] (more on that [[#SCDM and Wannier90|later]]).

To find a good representation of the electronic band structure in terms of Wannier orbitals, it is important to choose suitable projection targets.
In general, this can be a difficult task as some bands hybridize and disperse, changing electronic character as a function of the Bloch vector <math>\mathbf{k}</math>.
It is thus expedient to have a good understanding of the relevant electronic bands before attempting a Wannierization using {{TAG|LOCPROJ}}.

To gain insight into the electronic character of certain bands, you can use the {{TAG|LORBIT}} tag.
This decomposes the bands into local contributions either in terms of spherical harmonics ({{TAGO|LORBIT|10|op=<}}) or in terms of PAW projector functions ({{TAGO|LORBIT|10|op=≥}}).
The relevant information is written to the [[PROCAR]] file and can be used to determine suitable projection targets for {{TAG|LOCPROJ}}.

=== Example - diamond ===
Let us examine a small example to highlight the procedure of determining projection targets.
Here, we aim to Wannierize the four highest-lying valence bands of diamond.
This is a group of bands that is energetically isolated (they are surrounded by band gaps).
Since there is no mixing with any other states, the Wannierization process of these four bands is relatively simple.
With the standard C POTCAR distributed with VASP, we can conveniently set {{TAGO|NBANDS|4}} to only consider those states.

First, let us run a calculation with {{TAGO|LORBIT|1}} and {{TAGO|RWIGS|1.1}}.
This decomposes the bands into <math>l</math> and <math>m</math> quantum numbers in terms of spherical harmonics.
We get information on each k-point in the [[PROCAR]] file.
Here is the start of the file which contains information about the Γ-point:
<pre>
PROCAR lm decomposed
# of k-points:    8         # of bands:    4         # of ions:    2

 k-point     1 :    0.00000000 0.00000000 0.00000000     weight = 0.01562500

band     1 # energy  -11.73066124 # occ.  2.00000000

ion      s     py     pz     px    dxy    dyz    dz2    dxz  x2-y2    tot
    1  0.508  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.508
    2  0.508  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.508
tot    1.016  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  1.016

band     2 # energy    9.78016466 # occ.  2.00000000

ion      s     py     pz     px    dxy    dyz    dz2    dxz  x2-y2    tot
    1  0.000  0.173  0.173  0.173  0.032  0.032  0.000  0.032  0.000  0.613
    2  0.000  0.173  0.173  0.173  0.032  0.032  0.000  0.032  0.000  0.613
tot    0.000  0.346  0.345  0.346  0.063  0.063  0.000  0.063  0.000  1.226

band     3 # energy    9.78126079 # occ.  2.00000000

ion      s     py     pz     px    dxy    dyz    dz2    dxz  x2-y2    tot
    1  0.000  0.305  0.011  0.202  0.002  0.037  0.000  0.056  0.000  0.613
    2  0.000  0.305  0.011  0.202  0.002  0.037  0.000  0.056  0.000  0.613
tot    0.000  0.610  0.023  0.404  0.004  0.074  0.000  0.112  0.000  1.226

band     4 # energy    9.78126093 # occ.  2.00000000

ion      s     py     pz     px    dxy    dyz    dz2    dxz  x2-y2    tot
    1  0.000  0.041  0.334  0.143  0.061  0.026  0.000  0.007  0.000  0.613
    2  0.000  0.041  0.334  0.143  0.061  0.026  0.000  0.007  0.000  0.613
tot    0.000  0.081  0.668  0.287  0.122  0.052  0.000  0.015  0.000  1.226
</pre>
From this, we learn that the four valence bands are predominantly s-like and p-like (make sure that this is true also at the other k-points).
This was to be expected since carbon forms hybridized sp-3 bonds in diamond.

With this information, we can now specify projection targets.
We seek to map the four bands in the simulation to four Wannier orbitals, so we choose to setup four sp-3 hybrids on one atom.
The minimal INCAR file used in this example looks like this:
<pre>
ismear = 0                   ! use Gaussian smearing for insulator
sigma = 0.01                 ! use small smearing
nbands = 4                   ! use only 4 bands
locproj = 1 : sp3 : Hy 1 4.  ! ... to map onto 4 sp-3 functions
</pre>
The last part of the {{TAG|LOCPROJ}} setting (<tt>Hy 1 4.</tt>) specifies that we want Hyrdogen-like atomic orbitals (spherical harmonics) with main quantum number <math>n = 1</math> and a diffusivity of <math>\alpha = 4</math>.
The diffusivity influences the spread of the local function.
A higher value generally results in a higher degree of localization.
This is beneficial for Wannier interpolation and yields Wannier orbitals of higher quality in that regard.
{{NB:tip:You may also choose to use the PAW information to specify local orbitals with {{TAG|LOCPROJ}}. In this case, you should use {{TAGO|LORBIT|11}} to extract the relevant information from the basis.}}

For this example calculation, we use a relatively course Γ-centered regular mesh of <tt>4x4x4</tt> k-points.

To gauge the quality of the generated Wannier orbitals, we can plot the electronic band structure using Wannier interpolation and compare it against the ab-initio data.
As of VASP 6.3.0, this can conveniently be done all in one run by providing the [[KPOINTS_OPT]] and the [[KPOINTS_WAN]] file.
These files are automatically read from disk and provide a way to calculate the electronic eigenvalues at specific k-points.
* [[KPOINTS_OPT]]: Charge density is kept fixed and the Hamiltonian is diagonalized at each provided k-point.
* [[KPOINTS_WAN]]: Hamiltonian is constructed, interpolated and diagonalized using the Wannier orbitals.
Importantly, these k-points can be different from those specified in the [[KPOINTS]] file.

Here, we specify a k-point path through the first Brillouin zone using the [[KPOINTS#Band-structure calculations|line mode]] for both files.
The results can then be read from the [[vaspout.h5]] at the following locations:
<pre>
results/electron_eigenvalues_kpoints_opt/
results/electron_eigenvalues_kpoints_wan/
</pre>
The results can be seen in the following band-structure plot:
[[Image:Locproj-c-4.png|center|600px|frame|Electronic band structure of diamond. Comparison between ab-initio data and Wannier interpolation using LOCPROJ method.]]
The agreement between both methods is already very good.
The splitting of otherwise degenerate electronic bands in some parts of the plot is most likely an artifact of an improper treatment of the boundary conditions when performing Wannier interpolation.
This could be improved in future versions of VASP.
The remaining differences can be systematically decreased by increasing the k-point density in the initial [[KPOINTS]] file or by choosing a more suitable local basis.

== SCDM method ==
To activate the SCDM method, set {{TAGO|LSCDM|true}}.
This will use the information contained in the electronic one-particle density matrix to construct localized functions from the original Bloch (Kohn-Sham) orbitals.
These localized functions are then orthonormalized using a [[:Category:Wannier functions#One-shot single value decomposition (SVD)|one-shot approach]] based on the singular-value decomposition (SVD) to obtain orthonormal Wannier orbitals.

The number of Wannier orbitals obtained is controlled via the {{TAG|NUM_WANN}} tag.
{{NB|mind|You must ensure that {{TAGO|NUM_WANN|{{TAG|NBANDS}}|op=≤}} in order to have enough information to construct the Wannier orbitals.}}

=== Example - diamond ===
Let us run an example calculation to obtain Wannier orbitals in diamond using the SCDM method.
We choose {{TAGO|NUM_WANN|4}} as well as {{TAGO|NBANDS|4}}.
Using the standard C POTCAR that is distributed with VASP, the four bands in our calculation are the highest-lying valence states below the fundamental band gap of diamond.
This is a group of bands that is energetically isolated (they are surrounded by band gaps).
Since there is no mixing with any other states, the Wannierization process of these four bands is relatively simple.
Here is the minimal [[INCAR]] file for this example:
<pre>
ismear = 0      ! use Gaussian smearing for insulator
sigma = 0.01    ! use small smearing
nbands = 4      ! use only 4 bands
num_wann = 4    ! ... to map to 4 Wannier orbitals
lscdm = true    ! ... using the SCDM method
</pre>
For this example calculation, we use a relatively course Γ-centered regular mesh of <tt>4x4x4</tt> k-points.

To gauge the quality of the generated Wannier orbitals, we can plot the electronic band structure using Wannier interpolation and compare it against the ab-initio data.
As of VASP 6.3.0, this can conveniently be done all in one run by providing the [[KPOINTS_OPT]] and the [[KPOINTS_WAN]] file.
These files are automatically read from disk and provide a way to calculate the electronic eigenvalues at specific k-points.
* [[KPOINTS_OPT]]: Charge density is kept fixed and the Hamiltonian is diagonalized at each provided k-point.
* [[KPOINTS_WAN]]: Hamiltonian is constructed, interpolated and diagonalized using the Wannier orbitals.
Importantly, these k-points can be different from those specified in the [[KPOINTS]] file.

Here, we specify a k-point path through the first Brillouin zone using the [[KPOINTS#Band-structure calculations|line mode]] for both files.
The results can then be read from the [[vaspout.h5]] at the following locations:
<pre>
results/electron_eigenvalues_kpoints_opt/
results/electron_eigenvalues_kpoints_wan/
</pre>
The results can be seen in the following band-structure plot:
[[Image:Scdm-bands-c-4.png|center|600px|frame|Electronic band structure of diamond. Comparison between ab-initio data and Wannier interpolation using SCDM method.]]
The agreement between both methods is already very good.
The remaining differences can be systematically decreased by increasing the k-point density in the initial [[KPOINTS]] file.

== Comparison with LOCPROJ ==
It is worth noting that in the case of [[#Example - diamond|diamond]], a Wannier interpolation of similar quality can be achieved using the {{TAG|LOCPROJ}} tag.
The bands considered in that example have predominantly <tt>sp-3</tt> character.
Therefore, we can set:
<pre>
locproj = 1 - 2 : sp3 : Hy
</pre>
This places hydrogen-like atomic orbitals with <tt>sp-3</tt> character on atoms 1 and 2 (all atoms in the primitive cell).
These orbitals are then orthonormalized using the one-shot SVD approach and used for Wannier interpolation.
The resulting interpolated band structure is of good quality because the chemical character of the bands is well known.

In general, finding suitable projection targets can be a difficult and arduous task.
This is where the more automatic SCDM method has a clear advantage over the {{TAG|LOCPROJ}} approach.
The SCDM method extracts the electronic character of the bands directly from the density matrix.
On the other hand, the {{TAG|LOCPROJ}} approach requires the user to have a good understanding of the band structure of the material.

However, specifying local functions via {{TAG|LOCPROJ}} also has advantages over the SCDM method.
First, there is very little control over the orbitals that the SCDM method generates because the number of calculational parameters is so small.
This can be undesirable if the location, shape or symmetry of the Wannier orbital is important.
With {{TAG|LOCPROJ}}, you can choose the kind of orbital much more freely, for example, to study chemical bonding.
Second, SCDM orbitals do not generally obey the same symmetries as the crystal or as molecular bonds.
This is because the SCDM procedure employs an iterative scheme for choosing "optimal" localized functions one after the other (this is based on a rank-revealing QR decomposition).
As such, orbitals that should be symmetrically equivalent such as the hybridized <tt>sp-3</tt> orbitals in the case of diamond end up being slightly different from each other.
Consequently, the Wannier interpolation of the electronic band structure using SCDM orbitals will not be able to perfectly reproduce degeneracies since the underlying symmetries are broken.
Usually, this difference is comparatively small but it is something to keep in mind.

== Disentanglement ==
When {{TAGO|NBANDS|{{TAG|NUM_WANN}}|op=>}} or when the bands are not energetically isolated, Wannierization becomes more involved.
The difficulty lies in determining which electronic states to select when transforming the initial Bloch orbitals to the Wannier orbitals.
This process is known as disentanglement.

When using the SCDM method, disentanglement can be achieved by applying a smooth cutoff or weight function to the electronic states during the Wannierization process.
Loosely speaking, electronic states with a larger weight will be fitted more accurately.
In VASP, we currently support three types of cutoff functions that can be selected via {{TAG|CUTOFF_TYPE}}, <code>erfc</code>, <code>gaussian</code> and <code>fermi</code>.
The tags {{TAG|CUTOFF_MU}} and {{TAG|CUTOFF_SIGMA}} control the position, <math>\mu</math>, and width, <math>\sigma</math>, of these cutoff functions, respectively.

The complementary error function and Fermi function are particularly useful in scenarios where the band structure does not have a gap above the relevant energies, such as in metals.
The Gaussian function is useful for extracting a Wannier representation from a group of bands that is not surrounded by any gaps, below or above.

=== Example - LiF ===
[[File:Scdm-bands-lif-disentangle.png|right|300px|frame|Electronic band structure of LiF. Comparison between ab-initio data and Wannier interpolation using SCDM method.]]
LiF is an insulator with a wide band gap.
The Wannierization of the valence states in isolation is as simple as shown [[#Example - diamond|earlier]].
However, the lowest-lying conduction states are relatively dispersive and hybridize with higher-lying states.
This renders the Wannierization of these conduction bands difficult without disentanglement.

To obtain the lowest lying conduction bands of LiF, we choose the <code>erfc</code> cutoff function with an appropriate <math>\mu</math> and <math>\sigma</math>.
By default, VASP chooses reasonable default values for these parameters.
However, in order to get a good Wannier fit of the band structure, both <math>\mu</math> and <math>\sigma</math> should be chosen carefully by the user through trial and error.
As a rule of thumb, the smooth edge of the complementary error function should be positioned such that states below it are to be fitted more accurately.
For this example, we have chosen <math>\mu = 10 \text{eV}</math> and <math>\sigma = 0.1 \text{eV}</math>, which places the edge of the cutoff function amidst the lowest-lying conduction bands with a relatively sharp edge.

The minimal [[INCAR]] file for this example is provided below:
<pre>
ismear = 0           ! use Gaussian smearing for insulator
sigma = 0.01         ! use small smearing
nbands = 16          ! use 16 bands, including unoccupied states
num_wann = 9         ! ... to map to 9 Wannier orbitals
lscdm = true         ! ... using the SCDM method
cutoff_type = erfc   ! choose erfc cutoff function
scdm_mu = 10         ! ... and place it at 10 eV
scdm_sigma = 0.1     ! ... with a width of 0.1 eV
</pre>
The initial k-point mesh is chosen to be <tt>8x8x8</tt> Γ-centered.

The Wannier-interpolated band structure compares favorably against the ab-initio data below <math>\mu</math> and starts to diverge from it more and more above <math>\mu</math>.
This is a general trend with these kinds of calculations and is an unavoidable side effect of the disentanglement procedure.
The alternative would be a much higher and sharper cutoff that requires more Wannier states to be constructed.
This is however not generally advisable as it can negatively affect the quality of the Wannierization.

== SCDM and Wannier90 ==
Wannier orbitals obtained inside VASP via the SCDM method can be passed to [http://www.wannier.org Wannier90] for further processing.
Wannier90 employs an iterative algorithm that generates so-called maximally-localized Wannier functions (MLWF).
MLWFs are usually superior in terms of quality for band structure calculations.
However, even though they are generated from an iterative procedure, Wannier90 still relies on good first guesses for the localized functions.
This is where the SCDM method can provide a suitable set of initial functions for the MLWF procedure.

To generate MLWFs from SCDM orbitals, you can add the following lines to your [[INCAR]] file:
<pre>
lwannier90 = true   # or lwannier90_run = true
wannier90_win = "
  dis_num_iter = 0
  num_iter = 100
"
</pre>
{{NB|important|Make sure that VASP is compiled with the [[Precompiler options#-DVASP2WANNIER90|VASP2WANNIER90]] precompiler option.}}
{{TAG|LWANNIER90}} activates the interface between VASP and Wannier90 and writes a <tt>wannier90.win</tt> input file that can then be read by Wannier90.
In addition to the basic input parameters, VASP also writes the overlap matrices <math>M_{mn}</math> and <math>A_{mn}</math> to the corresponding files, <tt>wannier90.mmn</tt> and <tt>wannier90.amn</tt>.
<math>M_{mn}</math> contains the overlaps between all pairs of Bloch orbitals.
Meanwhile, <math>A_{mn}</math> contains the overlaps between the Bloch orbitals and the projection targets (in this case, the SCDM orbitals obtained from VASP).
{{NB|tip|The <tt>wannier90.mmn</tt> and <tt>wannier90.amn</tt> files can be explicitly written via {{TAGO|LWRITE_MMN_AMN|true}}. This is switched on by default when {{TAGO|LWANNIER90|true}}. It is unnecessary to write these files when {{TAGO|LWANNIER90_RUN|true}} as they are directly passed to Wannier90.}}
{{NB|important|When using the SCDM method together with Wannier90, it is recommended to set <code>dis_num_iter {{=}} 0</code> via {{TAG|WANNIER90_WIN}} or in the Wannier90 input file.}}


Run VASP with the above [[INCAR]] file to generate Wannier orbitals via SCDM and to generate the required Wannier90 input files.
Afterwards, run Wannier90 to generate MLWFs (all of this can be done in one run when setting {{TAGO|LWANNIER90_RUN|true}}).
At this point, you can use the functionality available in Wannier90 to plot the band structure, the orbitals, etc.
{{NB|warning|The <code>exclude_bands</code> parameter in the <tt>wannier90.win</tt> input file is currently not properly supported in VASP when using the SCDM method. Use with caution!||Bug:}}

== Related tags and articles==
{{TAG|LSCDM}},
{{TAG|CUTOFF_TYPE}},
{{TAG|CUTOFF_MU}},
{{TAG|CUTOFF_SIGMA}}

== References ==
<references/>