# pyfplo.wanniertools

- WanDefCreator
- SingleOrbitalWandef
- MultipleOrbitalWandef
- Wandef
- Contrib

This module provides some simple functions, which can be used to create `=.wandef` files. It is convenient in the context of `pyfplo.slabify`, where one usually needs to construct minimum basis models. For multi-contrib Wannier functions consult `Wandef` and `Contrib` and the example MgB2 in `DOC/WannierFunctions/examples/MgB2/bond-centered`. Example for simple Wannier functions:

    wdc=wt.WanDefCreator(rcutoff=25,wftol=0.001,coeffformat='bin',
                         wfgriddirections=[[2,0,0],[0,2,0],[0,0,2]],
                         wfgridsubdiv=[1,1,1],savespininfo=True,
                         savebfield=True,savepositionoperator=True,
                         gradorder=1,
                         keeprunning=True,opendxinterface=False,
                         wfinrealspace=False,wfcoeffstats=True,
                         hamtstats=True,printT=True)

    emin=-5
    emax= 3
    delower=1
    deupper=1

    # Add all wandefs for all 3d orbitals for both spins
    # for Fe site 1 and 2.

    wdc.add(wt.MultipleOrbitalWandef('Fe',[1,2],['3db'],
                                  emin=emin,emax=emax,
                                  delower=delower,deupper=deupper))

    # Add all wandefs for all 2p orbitals for both spins
    # for O site 7, 8 and 9.

    wdc.add(wt.MultipleOrbitalWandef('O',[7,8,9],['2pb'],
                                  emin=emin,emax=emax,
                                  delower=delower,deupper=deupper))

    wdc.writeFile('=.wandef')

## WanDefCreator

class `WanDefCreator`(rcutoff=20, wftol=0.01, coeffformat='bin', wfgridbasis='conv', wfgridsubdiv=[1, 1, 1], wfgriddirections=[[1, 0, 0], [0, 1, 0], [0, 0, 1]], wfgridorigin=None, savespininfo=False, savebfield=False, savepositionoperator=False, gradorder=1, keeprunning=True, opendxinterface=False, wfinrealspace=True, wfcoeffstats=True, hamtstats=True, printT=True, automode=None)

  The WanDefCreator object defines the content of the file `=.wandef`. You can add a single-contrib wandef via `SingleOrbitalWandef` and several such wandefs via `MultipleOrbitalWandef`. More complex mulit-contrib wandefs are added via `Wandef` which in turn uses `Contrib` to add single contribs to it.

  Parameters: | rcutoff (float) – Where in Bohr radii do we cutoff the hopping matrix elements to construct the tight-binding representation. wftol (float) – Hoppings below this threshold are not used. coeffformat (str) – Can be ‘bin’ or something else. If set to ‘bin’ the binary `+wancoeffbin` will be created and used. wfgridbasis (str) – Can be `'conv'`, `'prim'` or `'cart'` wfgridsubdiv (list or numpy.ndarray of 3 int) – The subdivision of the real-space grid on which to plot the Wannier functions. wfgriddirections (list or numpy.ndarray of 3 vectors) – The three directions, which span the real-space grid. wfgridorigin (list or numpy.ndarray of 3 float or None) – The origin of the real-space grid. Please consult `FPLO../DOC/WannierFunctions/wan_user.pdf` for more information. savespininfo (bool) – If `True` additional matrices (spin operators) are saved into `+wancoeff` for use by `slabify`. This option only works with full-relativistic calculations. savebfield (bool) – If `True` additional matrices (exchange field) are saved into `+wancoeff` for use by `slabify`. This option only works with full-relativistic calculations. savepositionoperator (bool) – If `True` additional matrices (position operator) are saved into `+wancoeff` for use by `slabify`. gradorder (int) – For the position operator a numerical gradient in k-space is needed. The gradient formula can have order 1,3,5 and 7. 1 or 3 are most likely best. The position operator converges very slowly with the number of SCF k-points. Often, gradorder=3 helps to improve the accuracy. opendxinterface (bool) – If `True` additionally the old-style opendx interface files will be written (`WF.net`, `WF.cfg`, `opendxWF.dx`). keeprunning (bool) – If `True` fplo waits after the Wannier function calculation to make a quick re-run possible. If `False` fplo stops. wfinrealspace (bool) – If `True` the real space representation of the WFs will be calculated and written to the files wfdata001 …. These files can be loaded by xfplo: `xfplo =.in wfdata002 wfdata005`. Additionally the WF statistics files `+WF...` are written if wfcoeffstats is `True`. wfcoeffstats (bool) – Triggers the output of the files `+WFstat...`, which contain the size of the orbital contributions to a WF as a function of distance between WF and orbital, which serves as a measure a for localiaztion. This option is inactive if wfinrealspace is `False`. It also triggers the ouptut of `+WF_coefficients`, which gives a detailed account of the orbital contributions to the WFs. hamtstats (bool) – Triggers the output of the files `+T_...`, which contain the size of the hoppings around a WF as a function of distance, which serves as a measure for localiaztion. printT (bool) – Triggers the output of `T=...` lines on standard output. Nowadays `+hamdata` is much more usefull. automode (`None` or ‘valence’ or ‘all’) – If this is ‘valence’ (or ‘all’) no wandefs need to be specified. Instead the code creates wandefs for all valence (or really all) orbitals. If some semi core states overlap the valence energy region semi cores are added to the wandefs until we get a clear gap below the lowest band considered. This options leads to a slow down, but it is usefull for automatic situations. Note, that a larger rcutoff might be needed in this case. For convenience the file `makewandeffromauto.py` is created after the file `+wancoff` was processed in the WF creation run. This file is overwritten. To modify it copy it.

  An example with automatic creation is:

      import pyfplo.wanniertools as wt

      if __name__ == '__main__':
          wdc=wt.WanDefCreator(rcutoff=25,wftol=0.001,coeffformat='bin',
                       wfgriddirections=[[2,0,0],[0,2,0],[0,0,2]],
                       wfgridsubdiv=[1,1,1],savespininfo=True,
                       savebfield=True,savepositionoperator=True,
                       gradorder=1,
                       wfinrealspace=True,wfcoeffstats=True,hamtstats=True,
                       printT=True,automode='val')

          wdc.writeFile('=.wandef')

  `add`(wandef)

    Add a `SingleOrbitalWandef`, `MultipleOrbitalWandef` or `Wandef` to the defintitions:

        import pyfplo.wanniertools as wt
        wdc=wt.WanDefCreator(rcutoff=30,wftol=0.001)
        wdc.add(MultipleOrbitalWandef('Al',[1,4],['3s','3p'],
                              emin=-13,emax=-5,
                              delower=1,deupper=10))
        wdc.writeFile()

  `writeFile`(filename='=.wandef')

    Write the content into the file called filename.

## SingleOrbitalWandef

class `SingleOrbitalWandef`(el, site=1, orb='1s+0', emin=-1, emax=1, de=1, delower=1, deupper=1, fewind=[-100, 100, 1, 1, 0], lbands=None, ubands=None, xaxis=[1, 0, 0], zaxis=[0, 0, 1], fac=1.0, onoff=1, sxaxis='qua', szaxis=None)

  This class defines a single wandef entry with a single contrib. To collect multiple wandefs into a single python statment use `MultipleOrbitalWandef`.

  Ignore fewind for now. The rest should be clear. Read the Wannier function documentation.

  Parameters: | el (str) – An element name. site (int) – The site number. fac (float or complex) – The factor of the contrib. Makes no sense in this context, but is needed if you use `Wandef` and `Contrib`. emin,emax,de,delower,deupper (float) – The energy window settings; all values can be single numbers or a list of two numbers (for spin up and spin down). lbands,ubands (int or list or None) – Optional. Either a single int (for both spins) or list of two int (spin up and down), specifying the lower and upper most band index to take into the projector. This narrows the energy window to a definite set of bands. which might be usefull if there is a separation of bands. orb (str) – can be something like 5d : all 5d+m orbitals 5d-1: only 5d-1 For full relativistic a `'u'`, `'d'` or `'b'` can follow the orbital name, specifying spin up,down or both. 5d b : all 5d+m orbitals for both spins 5d-1 b: only 5d-1, both spins Alternatively, a spherical spinor basis can be chosen. 5d5/2: all 5d5/2+mu/2 orbitals 5d5/2-3/2: only this orbital xaxis,zaxis (list or numpy.ndarray of 3 float) – The local coordinate system in which the orbital is defined sxaxis,szaxis (str or list or numpy.ndarray of 3 float) – For full relativistic: the local coordinate system in which the spin eigenstates are defined. If it is a `str` is must be ‘global’ ,’local’, or ‘quant’, which can be abbreviated as ‘glo’ ,’loc’, or ‘qua’. If it is vector szaxis must also be given. ’glo’: uses the global cartesian system ’loc’: uses the system defined by xaxis and zaxis ’qua’: uses the spin-quantization axis as defined in fedit.

## MultipleOrbitalWandef

class `MultipleOrbitalWandef`(el, sites, orbs, emin=-1, emax=1, de=1, delower=1, deupper=1, fewind=[-100, 100, 1, 1, 0], lbands=None, ubands=None, xaxis=[1, 0, 0], zaxis=[0, 0, 1], fac=1.0, onoff=1, sxaxis='qua', szaxis=None)

  Define multiple single-contrib wandefs.

  Parameters: | sites (list) – a list of sites orbs (list) – a list of orbitals (see `SingleOrbitalWandef`)

  For other parameters consult `SingleOrbitalWandef`.

## Wandef

class `Wandef`(name, emin=-1, emax=1, de=1, delower=1, deupper=1, fewind=[-100, 100, 1, 1, 0], lbands=None, ubands=None, onoff=1, contribs=None)

  This class defines a single wandef which can have multiple `Contrib`.

  Example:

      #! /usr/bin/env python

      import sys
      import numpy as np
      import pyfplo.wanniertools as wt

      # ===================================================================
      def work():

          # operations
          s=np.sqrt(3.)/2.
          C6=np.matrix([[0.5,-s,0],[s,0.5,0,],[0,0,1]],dtype='float')
          C3=C6.dot(C6)

          emin=-13
          emax=-10
          delower=1
          deupper=20

          xaxiss=np.matrix([1,0,0],dtype='float')

          wdc=wt.WanDefCreator(rcutoff=15,wftol=0.001,coeffformat='bin',
                       wfgridbasis='conv',wfgridsubdiv=[30,30,30],
                       wfgriddirections=[[2,0,0],[0,2,0],[0,0,2]],
                       wfgridorigin=None,savespininfo=False,
                       savebfield=False,savepositionoperator=False,
                       gradorder=1,
                       keeprunning=True,opendxinterface=False,
                       wfinrealspace=True,wfcoeffstats=True,
                       hamtstats=True,printT=False)

          for isa in range(2,4):
              xaxisp=xaxiss
              if isa == 3:
                  xaxisp=-xaxiss
              for i in range(1,4):
                  wdc.add(wt.Wandef(
                      name='Bs sp{0} at {1}'.format(i,isa),
                      emin=emin,emax=emax,de=1.0,delower=delower,deupper=deupper)
                      .addContrib(site=isa,orb='2s+0',fac=1.,xaxis=xaxiss)
                      .addContrib(site=isa,orb='2p+1',fac=np.sqrt(2),xaxis=xaxisp)
                  )
                  xaxisp=xaxisp.dot(C3)

          wdc.writeFile()
          return

      # ===================================================================
      #
      # ===================================================================
      if __name__ == '__main__':
          work()

  Parameters: | name (str) – The name of the Wannier function. emin,emax,de,delower,deupper (float) – The energy window settings; all values can be single numbers or a list of two numbers (for spin up and spin down). lbands,ubands (int or list or None) – Optional. Either a single int (for both spins) or list of two int (spin up and down), specifying the lower and upper most band index to take into the projector. This narrows the energy window to a definite set of bands. which might be usefull if there is a separation of bands. contribs (list of Contrib) – A list of instances of `Contrib`. Alternatively, `Contribs` can be added via `addContrib`.

  Ignore fewind for now.

  `addContrib`(site, orb='1s+0', fac=1.0, difvec=[0.0, 0.0, 0.0], xaxis=[1.0, 0.0, 0.0], zaxis=[0.0, 0.0, 1.0], sxaxis='qua', szaxis=None)

    Add a single contrib. For meaning of the parameters consult `SingleOrbitalWandef`.

    Returns: | self for call chaining as in:
        Wandef(...)\
          .addContrib(...)\
          .addContrib(...)
    Return type: | `Wandef`

## Contrib

class `Contrib`(site, orb='1s+0', fac=1.0, difvec=[0.0, 0.0, 0.0], xaxis=[1.0, 0.0, 0.0], zaxis=[0.0, 0.0, 1.0], sxaxis='qua', szaxis=None)

  A contrib for a `Wandef`.

  Parameters: | site (int) – The site number. orb (str) – can be something like 5d+2: real harmonics 5d+2 up: real harmonics spin up (full relativistic) 5d+2 dn: real harmonics spins down (full relativistic) Alternatively, a spherical spinor basis can be chosen. 5d5/2-3/2: j=5/2 mu=-3/2 fac (float or complex) – can be complex as in 0.577+0.5j difvec (list or numpy.ndarray of 3 float) – The connection vector from the Wannier center to this constrib’s site. xaxis,zaxis (list or numpy.ndarray of 3 float) – The local coordinate system in which the orbital is defined sxaxis,szaxis (str or list or numpy.ndarray of 3 float) – For full relativistic: the local coordinate system in which the spin eigenstates are defined. If it is a `str` is must be ‘global’ ,’local’, or ‘quant’, which can be abbreviated as ‘glo’ ,’loc’, or ‘qua’. If it is vector szaxis must also be given. ’glo’: uses the global cartesian system ’loc’: uses the system defined by xaxis and zaxis ’qua’: uses the spin-quantization axis as defined in fedit.