Interface with Wannier90

This interface allows to convert the output of wannier90 Maximally Localized Wannier Functions (MLWF) and create a HDF5 archive suitable for DMFT calculations with the SumkDFT class. The tasks are parallelized with MPI.

The converter can be run in two different modes, which are specified with the keyword bloch_basis in the call:

from triqs_dft_tools.converters import Wannier90Converter
Converter = Wannier90Converter(seedname='seedname', bloch_basis=False, rot_mat_type='hloc_diag', add_lambda=None)

Here and in the following, the keyword seedname should always be intended as a placeholder for the actual prefix chosen by the user when creating the input for wannier90.

Orbital mode

In the default mode (bloch_basis = False), the Converter writes the Hamiltonian in orbital basis, in which case the projector functions are trivial identity matrices. The user must supply two files:

  1. The file seedname_hr.dat, which contains the DFT Hamiltonian in the MLWF basis calculated through wannier90 with write_hr = true (please refer to the wannier90 documentation).

  2. A file named seedname.inp, which contains the required information about the \(\mathbf{k}\)-point mesh, the electron density, the correlated shell structure, … (see below).

Once these two files are available, one can use the converter as follows:

Converter.convert_dft_input()

The converter input seedname.inp is a simple text file with the following format:

 0  6 4 6               # specification of the k-mesh
8.0                     # electron density
 4                      # number of atoms
 0  0  2  3  0  0       # atom, sort, l, dim, SO, irep
 1  0  2  3  0  0       # atom, sort, l, dim, SO, irep
 2  0  2  3  0  0       # atom, sort, l, dim, SO, irep
 3  0  2  3  0  0       # atom, sort, l, dim, SO, irep
0.0                     # DFT Fermi Energy (optional)

The example shows the input for the perovskite crystal of LaVO3 in the room-temperature Pnma symmetry. The unit cell contains four symmetry-equivalent correlated sites (the V atoms) and the total number of electrons per unit cell is 8 (see second line). The first line specifies how to generate the \(\mathbf{k}\)-point mesh that will be used to obtain \(H(\mathbf{k})\) by Fourier transforming \(H(\mathbf{R})\). Currently implemented options are:

  • \(\Gamma\)-centered uniform grid with dimensions \(n_{k_x} \times n_{k_y} \times n_{k_z}\); specify 0 followed by the three grid dimensions, like in the example above

  • \(\Gamma\)-centered uniform grid with dimensions automatically determined by the converter (from the number of \(\mathbf{R}\) vectors found in seedname_hr.dat); just specify -1

Inside seedname.inp, it is crucial to correctly specify the correlated shell structure, which depends on the contents of the wannier90 output seedname_hr.dat and on the order of the MLWFs contained in it. In this example we have four lines for the four V atoms. The MLWFs were constructed for the t2g subspace, and thus we set l to 2 and dim to 3 for all V atoms. Further the spin-orbit coupling (SO) is set to 0 and irep to 0. As in this example all 4 V atoms are equivalent we set sort to 0. We note that, e.g., for a magnetic DMFT calculation the correlated atoms can be made inequivalent at this point by using different values for sort.

The number of MLWFs must be equal to, or greater than the total number of correlated orbitals (i.e., the sum of all dim in seedname.inp). If the converter finds fewer MLWFs inside seedname_hr.dat, then it stops with an error; if it finds more MLWFs, then it assumes that the additional MLWFs correspond to uncorrelated orbitals (e.g., the O-2p shells). When reading the hoppings \(\langle w_i | H(\mathbf{R}) | w_j \rangle\) (where \(w_i\) is the \(i\)-th MLWF), the converter also assumes that the first indices correspond to the correlated shells (in our example, the V-t2g shells). Therefore, the MLWFs corresponding to the uncorrelated shells (if present) must be listed after those of the correlated shells. With the wannier90 code, this can be achieved by listing the projections for the uncorrelated shells after those for the correlated shells. In our Pnma-LaVO3 example, for instance, we could use:

Begin Projections
 V:l=2,mr=2,3,5:z=0,0,1:x=-1,1,0
 O:l=1:mr=1,2,3:z=0,0,1:x=-1,1,0
End Projections

where the x=-1,1,0 option indicates that the V–O bonds in the octahedra are rotated by (approximatively) 45 degrees with respect to the axes of the Pbnm cell.

The last line of seedname.inp is the DFT Fermi energy (in eV), which is subtracted from the onsite terms in the seedname_hr.dat file. This is recommended since some functions in DFTTools implicitly assume a Fermi energy of 0 eV.

In the orbital mode the Converter supports the addition of a local spin-orbit term, if the Wannier Hamiltonian describes a t2g manifold. Currently, the correct interaction term is only implemented if the default orbital order of wannier90 is maintained, i.e. it is assumed to be \(d_{xz,\uparrow}, d_{yz,\uparrow}, d_{xy,\uparrow}, d_{xz,\downarrow}, d_{yz,\downarrow}, d_{xy,\downarrow}\). The coupling strength can be specified as add_lambda = [lambda_x, lambda_y, lambda_z], representative of the orbital coupling terms perpendicular to \([x, y, z]\) i.e. \([d_{yz}, d_{xz}, d_{xy}]\), respectively. Note that it is required to have SO=0 and SP=1.

For spin-orbit coupled systems (from DFT or with the add_lambda parameter), the orbitals are resorted internally by the converter to the triqs order so, e.g., the order from above would become \(d_{xz,\uparrow}, d_{xz,\downarrow}, d_{yz,\uparrow}, d_{yz,\downarrow}, d_{xy,\uparrow}, d_{xy,\downarrow}\).

Band mode

If bloch_basis = True, the Converter writes the Hamiltonian in the Kohn-Sham basis that was used to construct the Wannier functions. The projector functions are then given by the transformation from Kohn-Sham to orbital basis. Note that to do so wannier90 must be run with write_u_matrices = true. Additionally to the files described above, the Converter will require the following files:

  1. seedname_u.mat (and seedname_u_dis.mat if disentanglement was used to construct the Wannier functions.) is read to construct the projector functions.

  2. seedname.eig is read to get the Kohn-Sham band eigenvalues

  3. seedname.nnkp is read to obtain the band indices of the orbitals selected for the Wannier Hamiltonian

  4. seedname.wout is read to get the outer energy window to ensure the correct mapping of the disentanglement

Note that in case of disentanglement the user must set the outer energy window (dis_win_min and dis_win_max) explicitly in wannier90 with an energy separation of at least \(10^{-4}\) to the band energies. This means in particular that one should not use the default energy window to avoid subtle bugs.

Additionally, to keep the dimension of the lattice Green’s function reasonable, it is recommendable to use the exclude_bands tag for bands completely outside of the energy window.

The Converter currently works with Quantum Espresso and VASP. Additional files are required for each case to obtain the Fermi weights:

  1. seedname.nscf.out for Quantum Espresso (the NSCF run must contain the flag verbosity = 'high')

  2. OUTCAR and LOCPROJ for VASP

Note that in the band mode the user input of the \(k\)-mesh and the Fermi energy in seedname.inp are ignored, since both quantities are automatically read from the wannier90 and DFT output. However, the \(k\)-mesh parameter still has to be specified to comply with the file format.

Rotation matrix

The converter will analyse the matrix elements of the local Hamiltonian to find the symmetry matrices rot_mat needed for the global-to-local transformation of the basis set for correlated orbitals (see section standardized hdf5 structure). If rot_mat_type='hloc_diag', the matrices are obtained by finding the unitary transformations that diagonalize \(\langle w_i | H_I(\mathbf{R}=0,0,0) | w_j \rangle\), where \(I\) runs over the correlated shells and i,j belong to the same shell (more details elsewhere…). If rot_mat_type='wannier', the matrix for the first correlated shell per impurity will be identity, defining the reference frame, while the rotation matrices of all other equivalent shells contain the correct mapping into this reference frame. If two correlated shells are defined as equivalent in seedname.inp, then the corresponding eigenvalues have to match within a threshold of 10-5, otherwise the converter will produce an error/warning. If this happens, please carefully check your data in seedname_hr.dat. This method might fail in non-trivial cases (i.e., more than one correlated shell is present) when there are some degenerate eigenvalues: so far tests have not shown any issue, but one must be careful in those cases (the converter will print a warning message and turns off the use of rotation matrices, which leads to an incorrect mapping between equivalent correlated shells).

Note that in the case of spin-orbit coupling, these rotation matrices in general mix spin and orbital components.

Current limitations

The current implementation of the Wannier90 Converter has some limitations:

  • Since wannier90 does not make use of symmetries (symmetry-reduction of the \(\mathbf{k}\)-point grid is not possible), the converter always sets symm_op=0 (see the standardized hdf5 structure section).

  • The spin-polarized case (SP=1) is neither completely implemented nor tested.

  • proj_mat_all are not used, so there are no projectors onto the uncorrelated orbitals for now.