dft_tools/doc/guide/conv_elk.rst

.. _convElk:

Interface with Elk
=====================

This is the first iteration of the Elk-TRIQS interface, so certain inputs may change in later updates. The Elk part of the interface is not currently in the main distribution, but it can be found `here <https://github.com/UoB-Compton-scattering-group/elk-8.4.21-TRIQS>`_.

We assume that the user has obtained a self-consistent solution of the
Kohn-Sham equations with Elk (a full tutorial can be found here :ref:`Elk SVO tutorial <SrVO3_elk>`). Also, the user needs to be familiar with the main in/output files of Elk, and how to run
the DFT code. Further information about Elk can be found on the `official Elk website <http://elk.sourceforge.net/>`_.

Conversion for the DMFT self-consistency cycle
----------------------------------------------

Once the user has obtained the groundstate calculation, they will have to rerun Elk but with some small changes to the inputs in the elk.in file which will be explained below. The Elk part of the interface calculates and outputs the Wannier projectors. All downfolding related flags are set in the elk input file, and Elk determines automatically by symmetry equivalent sites. The TRIQS Elk converter then reads in these projectors along with the other Elk ascii files which would have been generated in the Elk ground state calculation. This information is then packed into the HDF5 file.

In the following, we use SrVO3 as an example to explain the flags required in the elk.in input file. An example elk.in of SrVO3 is available in the :ref:`SrVO3 tutorial <SrVO3_elk>`:

.. literalinclude:: ../tutorials/svo_elk/elk.in


The projectors are generated in Elk using these alterations in the elk.in file::
  
  task
   805

  wanproj
   1            !1) number of projector species
   2 2 3        !2) species number, l value and lm submatrix size
   7 8 9        !3) cubic harmonic lm indices 
   -0.055 0.07  !4) Correlated energy window in Hartrees (this is [-1.5, 1.9] in eV)

The first flag "task" specifies Elk to do the Wannier projector calculation in the Elk input convention. The "wanproj" flag specifies the information needed to generate the desired projectors (the exclamation marks are comment flags in Fortran). Below gives the meaning of each line:

#. The number of different species to generate the projectors for. If the material has multiple atoms of the same species, then the projectors will be generated for all of these atoms. Information about whether these atoms are symmetrically equivalent is written to the PROJ.OUT file. Generating projectors for multiple species requires lines 2) and 3) to be repeated for each projector species. 
#. The desired species index (relative to the order of the "atoms" input in elk.in), the l value and the number of wanted lm orbitals for the projectors. 
#. The lm indices (in the cubic harmonics by default) where lm = 1 refers to the s orbital, lm = 2,3,4 refers to the p orbitals, lm = 5,6,7,8,9 refers to the d orbitals and finally lm = 10,11,12,13,14,15,16 refers to the f orbitals. In the example above, this specifies that we want the t2g orbitals which has size 3 [last number in line 2)] and the lm indices are 7, 8 and 9 as specified in line 3). If, on the other hand, the user wishes to use all of the d-orbitals then all 5 orbital indices need to be included along with specifying that all 5 orbitals will be used [at the end of line 2)].
#. The correlated energy window (in Hartree) to generate the projectors within.

It should be noted that the indices in line 3) will change if another lm basis is used. 
The default is the cubic harmonic basis. The flags in elk.in required to change the spherical harmonic basis are::

  cubic
   .true.

  lmirep
   .true.

Above are the default inputs. If both of these flags are set to .false., the projectors will be generated in the complex spherical harmonic basis. It is possible to generate the projectors in Elk's irreducible basis by setting cubic to .false., but this is experimental and the TRIQS side of the interface is 
currently unable to convert the projectors in that basis. Finally, these projectors are written to file in the complex spherical harmonic basis.

Also, the input flag called "wanind", when set to .true. in elk.in, enables the user to input the lower and upper band indices (respectively) in line 4) of "wanproj" instead of the correlated energy window energies. An example of the inputs in the elk.in file::

  wanind
   .true.

  wanproj
   1      !No. of projector species
   2 2 3  !species, l, lm submatrix size
   7 8 9  !lm indices
   21 25  !correlated energy window band indices.

Note that for magnetic systems (spin uncoupled calculations), only the indices of the majority spin bands are used as inputs. The code calculates the indices for the minority spin automatically.


.. _Elk_files:

The rest of the elk.in file can remain unchanged. This 805 task calculates the projectors which are written into the WANPROJ_L**_S**_A****.OUT file(s). Note that the projectors will be written in the complex spherical harmonic basis. Along with this, the other written file (PROJ.OUT) specficies some information about the projectors (like atom equivalency, lm indices and so on) needed for reading the files into the TRIQS library. The PROJ.OUT file contains comments about its outputs. Here's a list of all of the input files needed for this part of the TRIQS converter:

#. WANPROJ_L**_S**_A****.OUT - file containing the projectors and band window indices.
#. PROJ.OUT -  specficies some information about the projectors.
   (like atom equivalency, lm indices and so on) needed for reading into the TRIQS library.
#. EIGVAL.OUT - contains the energies and latice vector coordinates for each k-point.
#. EFERMI.OUT - contains the Fermi energy.
#. KPOINTS.OUT - contains the k-point weights and lattice vectors.
#. SYMCRYS.OUT - has the crystal symmetries used for symmetries observables.
#. LATTICE.OUT - has lattice-Cartesian basis transformation matrices.
#. GEOMETRY.OUT - file with the lattice positions of every atom of each species.

Moreover, the Wannier charge density matrix (in WANCHARGE.OUT) and the Wannier spectral function (in WANSF_L**_S**_A****_0*.OUT) are calculated. These files are not used in the interface. 

As a side note, there are two other tasks which also generate the Wannier projectors. Task 804 generates the same outputs as 805 except it doesn't calculate the Wannier charge and spectral function. Task 806 outputs the same information as 805, but it generates the projectors (and other k-dependent variables) on a different user defined ngridk mesh. These tasks are parallelized with both OpenMP and MPI.

The Elk outputs are read into the TRIQS library using the following lines::

  from triqs_dft_tools.converters.elk import *
  Converter = ElkConverter(filename=filename, repacking=True)
  Converter.convert_dft_input()

The first two lines import and load the Elk converter module and the last line executes the conversion into the filename.h5 HDF5 file.


Data for post-processing - Correlated Spectral functions
--------------------------------------------------------

In case you want to do post-processing of your data using the module :class:`SumkDFTTools <dft.sumk_dft_tools.SumkDFTTools>`, some more files have to be converted to the HDF5 archive. Some of this has been laid out in :ref:`analysis`, but the Elk specific functions are described in the following sections. Below, we will discuss how to input the information for correlated spectral functions (band structures) and which is then calculated using "spaghettis" in :ref:`analysis`. However, band character band structure plots have not yet been implemented.

In Elk, the elk.in requires the altered flag::

  task
   820

As well as the wanproj flag (which has be discussed previously) and the plot1d flag (refer to the Elk manual). The new output files of this task required for the interface are:

#. BAND.OUT - the energy eigenvalues along the user specified path.
#. PROJ_WANBAND.OUT - same as PROJ.OUT but for band structure projectors
#. WANPROJ_L**_S**_A****_WANBAND.OUT - same as WANPROJ_L**_S**_A****.OUT
    but for band structure projectors.

(The ascii output files which have the new extension of _WANBAND.OUT are specific for this post processing calculation.)

The band structure information is converted into TRIQS by using::

  Converter.convert_bands_input()


Spectral function Energy Contour Plots (Fermi Surfaces) from Elk inputs
-----------------------------------------------------------------------

Here, we will discuss how to plot the Fermi surface contour or any other non-zero omega spectral function contour plot. The energy eigenvalues, projectors and so on required for the contour plot needs to be outputed from Elk. This is done by using::

  task 
  807 
  
in Elk, but unlike the previous Elk interface tasks, the k-mesh grid needs to be specified. This is done by using the same inputs as the Fermi surface calculations in Elk. In Elk, The user needs to specify the "plot3d" input flag used to generate the k-mesh which the interface variables are evaluated on. A simple example is for SrVO3 where plot3d would look something like::
  
  plot3d
  0.0 0.0 0.0 !1) origin
  1.0 0.0 0.0 !2) vertex 1
  0.0 1.0 0.0 !3) vertex 2
  0.0 0.0 1.0 !4) vertex 3
  32 32 32    !5) k-mesh grid size

Lines 1) to 4) specifies the corners (in lattice coordinates) of the k-grid box and line 5) is the grid size in each direction (see the Elk manual). If the user desires to plot a 2D plane, then the user should define the plane using lines 2) and 3) [relative to line 1)] and define line 4) to be the cross-product of lines 2) and 3) [i.e. the vector in line 4) is normal to the 2D plane]. The outputs will be in terms of the k-dependent quantities in the irreducible Brillouin zone (IBZ). The files needed for this converter routine are:

#. EIGVAL_FS.OUT - same as EIGVAL.OUT but with the corresponding plot3d user defined k-mesh instead.
#. KPOINT_FS.OUT - same as KPOINT.OUT but with the corresponding plot3d user defined k-mesh instead.
#. PROJ_FS.OUT - same as PROJ.OUT but with the corresponding plot3d user defined k-mesh instead.   
#. WANPROJ_L**_S**_A****_FS.OUT - same as WANPROJ_L**_S**_A****.OUT but with the corresponding plot3d user defined k-mesh instead.   
#. EFERMI.OUT - contains the Fermi energy.
#. SYMCRYS.OUT - has the crystal symmetries used for symmetries observables.
#. LATTICE.OUT - has lattice-Cartesian basis transformation matrices.

(The ascii output files which have the extension of _FS.OUT are specific for this post processing calculation.)

These outputs are converted to the HDF5 file by::

  from triqs_dft_tools.converters.elk import *
  Converter = ElkConverter(filename=filename, repacking=True)
  Converter.convert_contours_input(kgrid,ngrid)

The kgrid and ngrid are user-defined numpy array inputs containing the plot3d inputs described above. 
These inputs are needed to generate the reciprocal lattice coordinates for the output files. 
The default for both of these variables is None, which in this case the converter automatically generates the 
full Brillouin zone by applying all of the symmetry operators to the read IBZ coordinates. However,
if the plot3d input is a k-mesh not centered around the origin and/or a k-mesh which only requires
a subset of the symmetry operators (say a 2D k-mesh) then the plot3d input needs to be an input to 
the converter. Here, kgrid would be a double numpy array of size (4,3) specifying the k-mesh corner, 
i.e, which contains lines 1) to 4) of the plot3d input described. The ngrid is an integer numpy 
array of size (3) containing the k-mesh grid size - line 5) in plot3d input above.


DFT+DMFT wavefunction dependent quantities
------------------------------------------

The DFT+DMFT wavefunctions and occupations are generated in Elk by diagonalizing the full DFT+DMFT density matrix at each k-point during task 808. These are used to update the electron density which is then used to solve the Kohn-Sham equations once to complete a FCSC DFT+DMFT cycle. It is possible to calculate quantities which are solely dependent on the wavefunctions and occupations by using the aforementioned diagonalized set. After generating the DMATDMFT.OUT file, these diagonalized wavefunctions and occupations are calculated by amending elk.in with the new task::

  task
   809

This will write the new second variational eigenvectors and occupations in the EVECSV.OUT and OCCSV.OUT binary files respectively. Then the wavefunction dependent quantities implemented within Elk can be calculated using these DFT+DMFT wavefunctions and occupations. Note that this only works for energy independent quantities. Also, the user has to ensure that the second variational eigenvectors will be used in determining the wavefunction dependent quantities. This is done by looking for the variable "tevecsv" in init0.f90 of Elk's source code and making sure that this is set to .true. for the task number the user wishes to use.