
.. This is a raw version of the Example documentation. This file
   was compiled into a pdf file and html pages.
   Please consult :file:`../FPLO../DOC/pyfplo/pyfplo.doc`
   or open :file:`../FPLO../DOC/pyfplo/html/index.html`

.. |refcalculateZ2Invariant| replace:: `~pyfplo.slabify.Slabify.calculateZ2Invariant`
.. |refkscale| replace:: `~pyfplo.slabify.Slabify.kscale`


.. _Sec2dTI:

                         
2D topological insulator
========================

.. Contents::
   :local:
   :backlinks: top

.. note:: You need to use the newer **xfbp**\ /\ **xfplo** version,
   which comes with `pyfplo` in order for the ``cmd`` scripts to work
   properly.



This example tries to explain how to calculate the :math:`Z_2` invariant of the
2d time reversal invariant topological insulator BHZ model (Bernevig,
Hughes and Zhang).  The tutorial files are in
:file:`FPLO.../DOC/pyfplo/Examples/slabify/BHZmodel` where `FPLO...`
stands for your version's FPLO directory, e.g. `FPLO22.00-62`.

The method can be applied to any plane spanned by time reversal
invariant points also in 3d lattices, e.g. in Weyl semi metals, where
the :math:`Z_2` invariant tells us how many pairs of surface states are to be
expected to cross a given line -- the projection of the plane onto the
surface. (All assuming that the corresponding plane is gapped.)


We use a Hamiltonian file (:file:`+hamdata`) containing the model
data, which was created by :file:`bhz.py`.  Usually :file:`+hamdata`
is created by the Wannier function module of **fplo**. The model data
are taken from [Yu2011]_ and modified a bit (a=5, M_TI=-6).  The model
defines a four orbital tight binding model. Depending on the parameter
choice the model is either a trivial insulator or a topological
insulator.  The two cases are in subdiretories called :file:`I` and
:file:`TI`.

.. [Yu2011] Rui Yu et.al. Phys. Rev. B **84**, 075119 (2011).
   https://doi.org/10.1103/PhysRevB.84.075119

The topological phase
^^^^^^^^^^^^^^^^^^^^^

In python script for the 2d band structure and the :math:`Z_2` calculation is
:file:`TI/2d/Z2.py`

      
.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/BHZmodel/TI/2d/Z2.py
   :linenos:

      
Line 8 can be uncommented and edited to make python search for
pyfplo in a particular location (also see :ref:`Setup
<install_setup>`).
Line 14 shows which `pyfplo` version was loaded and from where.
If you uncomment line 16, the script is showing an error message if the
`pyfplo` version does not match a particular version.



Please run the script (from :file:`TI/2d/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/BHZmodel/TI/2d/README.rst

In line 27 we set the proper :file:`+hamdata` and in line 30 we set
the object to `'3d'`, which in the case of a 2d lattice means 2d-bulk.
In lines 35-48 the band structure is calculated
(:ref:`FigBHZModelTI2d`).  Note that there is a small gap close to the
:math:`\Gamma`-point where the orbital weight is inverted across the
gap which already indicates the possibility of a topological phase.

.. _FigBHZModelTI2d:
.. figure:: pics/BHZmodel/TI/2d/bands2d.png
   :figwidth: 10cm
   :width: 10cm
   :align: center
        
   2d bulk bands for the topological phase.

In line 52 the Wannier centers are calculated. Consult
|refcalculateZ2Invariant| for more information. Note, that we have to
chose three time reversal invariant points (TRIM) in the Brillouin
zone in units of |refkscale|. At the end of the output you will see
the primitive reciprocal cell and the kscale factor (code lines
57-58). The TRIM points are always in the middle between two
reciprocal cell vectors. This should explain our choice.

The output contains
quite a lot of information. Please consider it all.  For each homo
which was specified a file containing the Wannier centers
:file:`slabifyres/+Z2_homo...` and a file containing a reference line
:file:`+zgap_homo...` are created. The reference line usually follows
the largest gap between Wannier centers [Sol2011]_. In our
modification a number of such lines for some of the largest WC-gaps is
created. Each yields a topological index. The majority result will
win. The percentage of such lines with the majority result is called
reliability in the output. The table of invariants for all homos in
the output looks like

.. [Sol2011] A. A. Soluyanov, D. Vanderbilt Phys. Rev. B **83**,
   235401 (2011)

   https://doi.org/10.1103/PhysRevB.83.235401

::
   
   Invariants:
    homo      Z2 (reliability)   smallest gap [eV]
        2     1  (100%)          0.20353
        4     0  (100%)              >10

If the reliability is 100% all WC-gap-following curves gave the same
result. This does however not mean it is a save result.  The exactness
of this algorithm depends on the actual system.  If the Berry
curvature is strongly fluctuating a finer grid is needed. This often
happens e.g. if the energy gaps are small or zero. In such cases the
degeneracies at :math:`ky=0` and :math:`ky=\pi` can be broken. Also
discontinuities can occur and the results can depend on the
evenness/oddness of *Nint*. All these are warning signs that the
:math:`Z_2` invariant might be nonsensical.

Additionally, the smallest energy gap for each homo on the grid
defined by the parameters *Nint* and *Nky* is printed. This helps you
decide, if the time reversal invariant plane is really gaped. Also
this information is not fool proof, since the grid is discrete.

If *efhomo* is given to |refcalculateZ2Invariant| a * is printed after
this homo number, usually ment to be the Fermi level. If the
reliability is less then 99% a question mark is printed before the :math:`Z_2`
invariant, as in in the following example::

   Invariants:
    homo      Z2 (reliability)   smallest gap [eV]
        12  ?  1  (90%)            0.4
        14 *?  0  (67%)            0.13
        16     1  (100%)           0.56
  


Let's have a look at the corresponding Wannier center files
(:ref:`FigBHZModelTIhomo2` and :ref:`FigBHZModelTIhomo4`) created by
loading :file:`Z2_homo...cmd` into **xfbp**.

.. _FigBHZModelTIhomo2:
.. figure:: pics/BHZmodel/TI/2d/Z2_homo2.png
   :figwidth: 5cm
   :width: 5cm
   :align: center
        
   Wannier centers for homo 2 in the topological phase.

.. _FigBHZModelTIhomo4:
.. figure:: pics/BHZmodel/TI/2d/Z2_homo4.png
   :figwidth: 5cm
   :width: 5cm
   :align: center
        
   Wannier centers for homo 4 in the topological phase.

The Soluyanov algorithm draws a curve through all wannier centers,
such that it always stays in the largest gap between Wannier centers
(which we modified to give more competing solutions). If the number of
centers crossed so far at a certain ky-value is even a blue symbol is
plotted if the number is odd a red symbol is plotted. If the last
symbol (:math:`ky=\pi`) is red the :math:`Z_2` invariant is odd. Of course the
WC-curves are discrete and hence we cannot a priori decide about their
connectedness, which leaves an uncertainty. Ultimately, the user has
to look at these pictures and decide for himself, how many WCs a
chosen reference line crosses. In **xfbp** a right mouse click close
to a curve tells you how many sets there are, which helps to verify
the number of crossed Wannier centers. Any reference curve (also a
straight horizontal line) is OK. The one shown in the plots is just
the automatically determined one. Since we modified the algorithm, the
automatic curve does not necessarily follow the largest WC-gaps.  The
two figures tell us that homo 2 has a non trivial :math:`Z_2` invariant in the
plane spanned by the TRIM points given to |refcalculateZ2Invariant|.


Now, we make a calculation of the 1d surface states. Go into
:file:`TI/semi` and run the script (from :file:`TI/semi/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/BHZmodel/TI/semi/README.rst


The script looks like this:
   
.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/BHZmodel/TI/semi/calcedc.py
   :linenos:

Lines 30-32 setup a ``semislab`` with [010] surface and two layers in
the primary layer. Since the bulk is 2d with a [001] surface this
results in a semi infinite ribbon. (Actually, in the moment the 2d
bulk is a 3d repeated monolayer slab.)  After setup, the former [010]
direction is the new c-direction (surface of the semi infinite ribbon)
but still the cartesian y-axis (remember we use rotations internally
to keep the original orientation). The global x-axis is now the
(periodic) b-direction, while the global z-axis (as for the 2d bulk)
is the direction perpendicular to the ribbon. If we chose the high
symmetry points along the cartesian x-axis (lines 40-42, 52-54) we
sample k-points in the periodic b-direction.



In lines 37-46 we set up a bandplot path and an energy contour and
calculate the energy resolved Bloch spectral density.  In line 50-59 a
zoomed in version is calculated and placed into a different directory
(line 50), because the :file:`+points` file is different for both
calculations. 

.. _FigBHZModelTIedc:
.. figure:: pics/BHZmodel/TI/semi/edc.png
   :figwidth: 10cm
   :width: 10cm
   :align: center
        
   Surface states in the topological phase.


The result looks like :ref:`this Figure<FigBHZModelTIedc>` and clearly shows a
Dirac cone at the edge of the surface.


The trivial insulator phase
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In python script for the 2d band structure and the :math:`Z_2` calculation is
:file:`I/2d/Z2.py` and is identical to the one for the topological
phase.

Please run the script (from :file:`I/2d/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/BHZmodel/TI/2d/README.rst

Have a look at the :ref:`FigBHZModelI2d`


.. _FigBHZModelI2d:
.. figure:: pics/BHZmodel/I/2d/bands2d.png
   :figwidth: 10cm
   :width: 10cm
   :align: center
        
   2d bulk bands for the trivial phase.

It looks pretty much like the :ref:`FigBHZModelTI2d` except that the
band inversion across the gap is missing. Consequently,
:ref:`FigBHZModelIhomo2` (created by ``xfbp Z2_homo2.cmd``) clearly
indicates a trivial phase as is also seen by the output::
  
   Invariants:
    homo      Z2 (reliability)   smallest gap [eV]
        2     0  (100%)          0.46419
        4     0  (100%)              >10


.. _FigBHZModelIhomo2:
.. figure:: pics/BHZmodel/I/2d/Z2_homo2.png
   :figwidth: 5cm
   :width: 5cm
   :align: center
        
   Wannier centers for homo 2 in the trivial phase.

.. _FigBHZModelIhomo4:
.. figure:: pics/BHZmodel/I/2d/Z2_homo4.png
   :figwidth: 5cm
   :width: 5cm
   :align: center
        
   Wannier centers for homo 4 in the trivial phase.
        
As a final confirmation let's have a look at the :ref:`FigBHZModelIedc`.


.. _FigBHZModelIedc:
.. figure:: pics/BHZmodel/I/semi/edc.png
   :figwidth: 10cm
   :width: 10cm
   :align: center
        
   Surface states in the trivial phase.

Run the script (from :file:`TI/semi/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/BHZmodel/I/semi/README.rst

The python script is the same as for the topological phase.
