
.. 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`

.. |refSlabify| replace:: `slabify.Slabify <pyfplo.slabify.Slabify>`
.. |refenlarge| replace:: `enlarge <pyfplo.slabify.Slabify.enlarge>`
   
A basic tutorial
================

.. 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 `pyfplo.slabify` works in detail.
The tutorial files are in
:file:`FPLO.../DOC/pyfplo/Examples/slabify/model` where `FPLO...`
stands for your version's FPLO directory, e.g. `FPLO22.00-62`.
      
We use a hand written Hamiltonian file (:file:`+hamdata`) containing
some model data.  Usually this is created by the Wannier function
module of **fplo**.
The model defines a single orbital tight binding model on a cubic
lattice.

.. _SecBulkBands:

The bulk band structure
^^^^^^^^^^^^^^^^^^^^^^^

In a first step we plot the 3d bulk band structure. The python script
:file:`3d/slabify.py` is shown in the following

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/3d/slabify.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:`3d/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/3d/README.rst 



Now for the actual script. Line 25 defines a convenient variable
pointing to the Hamiltonian file. Line 27 makes ``s`` an instance of
|refSlabify|. In line 30 we tell it that we want a 3d
object and since we dont set any other options it will be the simple
cubic cell as defined in :file:`+hamdata`. Line 33 now reads the
Hamiltonian data and sets up the structure. After this step there will
be several files in the output directory :file:`slabifyres/` called
:file:`=.in_...`:

   =.in_step_1_3d_enlarged:
      This is the cell after the first structure manipulation step,
      which is the application of the |refenlarge| matrix.
   =.in_final_PLlayer:
      I the final result.

Of course in our case the two are identical, since we did not give any
structure options except for ``s.object=3d``. Furthremore, there are
bandstructure files. Ignore :file:`+sweights_sf_my_suffix` for now.

On with the code: Line 35 make ``bp`` an instance of `common.BandPlot
<pyfplo.common.BandPlot>` while lines 36.. set the high symmetry
points.  Note, that the units are `slabify.Slabify.kscale
<pyfplo.slabify.Slabify.kscale>`. One can set ``kscale`` to something
else after the call to ``s.prepare(hamdata)``.  Line 46 sets up ``bp``
and writes the file :file:`+points` to the directory defined in
`slabify.Slabify.dirname <pyfplo.slabify.Slabify.dirname>`. If this
variable is set by the user, it must be before the call to
`slabify.Slabify.prepare <pyfplo.slabify.Slabify.prepare>`.  Finally, in line
48 the band structure and band weights are calculated. The `suffix`
argument helps to give the files custom made names.

Finally, if you sucesfully installed **xfbp** and executed ``xfbp
bands.cmd`` you saw the simple bulk band structure (:ref:`That is what
you should see. <FigModel3d>`).


.. _FigModel3d:
.. figure:: pics/model/3d/bands3d.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

      
   The 3d band structure of the model.

It is strongly encouraged to also study the :file:`.cmd` scripts to
learn tricks.  If you want to use other software for plotting you can
use the `pyfplo.common.BandPlot.readBands` and
`pyfplo.common.BandWeights.readBandWeights` methods to deal with the
data as you please.


The bulk Fermi surface
^^^^^^^^^^^^^^^^^^^^^^

Next we create a bulk Fermi surface of the model. We created an
appropriate :file:`=.in` with symmetry P1 and a simple cubic lattice
with correct lattice constants (as in :file:`+hamdata`). Next, we
opened **xfplo** in fermi surface mode, defined a mesh, exported it,
saved the settings in :file:`=.xef`, stopped before the automatic
**fplo** run and quit the program. Now, we got :file:`=.kp` and
:file:`=.xef`.

Please change into :file:`FS/` and run the script (from :file:`FS/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/FS/README.rst 

:ref:`You should see something like this. <FigModelFS3d>`
                      
.. _FigModelFS3d:
.. figure:: pics/model/FS/FS3d.jpg
   :figwidth: 10cm
   :width: 10cm
   :align: center

   The 3d Fermi surface extracted via slabify.
           

Let's explain the script :file:`FS/slabify.py` now.     

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/FS/slabify.py
   :linenos:

In line 31 we explicitely set `slabify.Slabify.dirname
<pyfplo.slabify.Slabify.dirname>` to the local directory. This will
put everything into the same directory where :file:`slabify.py` was
executed. The setup continues as in :ref:`SecBulkBands` until line 42
where instead of setting a path through high symmetry points the
k-point file from **xfplo** is used.


Fermi surface cuts
^^^^^^^^^^^^^^^^^^

There is an option to create Fermi surface cuts.

Please change into :file:`cuts/` and run the script (from
:file:`cuts/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/cuts/README.rst 


:ref:`You should see something like this. <FigModelcuts3d>`
                      
.. _FigModelcuts3d:
.. figure:: pics/model/cuts/cuts.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Cuts through the 3d Fermi surface of the model.
           

Let's explain the script :file:`cuts/slabify.py` now.     

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/cuts/slabify.py
   :linenos:
   
In lines 35-36 we set up a `slabify.FermiSurfaceOptions
<pyfplo.slabify.FermiSurfaceOptions>` instance with default axes and
define a 100x100 2d mesh which stretches from ``-0.5`` to ``0.5`` in
units of `slabify.Slabify.kscale <pyfplo.slabify.Slabify.kscale>`
which happens to be ``2*pi/a`` by default.

Next a loop is done over various ``kz``-values. In line 41 the plane
(axes and origin) is specified explicitely. The origin ``[0,0,kz]``
puts this plane parallel to ``kx``, ``ky`` through the ``kz``-value.
Line 42 sets the Fermi energy and line 43 a filename suffix.  In line
46 `Slabify.calculateFermiSurfaceCuts
<pyfplo.slabify.Slabify.calculateFermiSurfaceCuts>` is called with the
flag ``forcerecalculation=True``, which is explained under the link
above. After this line the files

  :file:`+cut_band_sf`,
      
  :file:`+cut_bweights_sf` and

  :file:`+cuts_kz=00.00.spin1_kz=...` 

are created in :file:`slabifyres/`.

Line 49 sets a different Fermi energy and line 54 recalculates the
files :file:`+cuts_kz=00.00.spin1_kz=...` (iso lines) but not the
other files because of ``forcerecalculation=False``. In a real example
with lots of orbitals this avoids the expensive diagonalization step.
There are also :file:`+cutswithweights` files if the *wds* option is
specified.

Bulk projected bands
^^^^^^^^^^^^^^^^^^^^

On can calculate the bulk projected bands (BPB) as energy distribution
curves (EDC) or Fermi surface projections.

Please change into :file:`bpb/` and run the script (from
:file:`bpb/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/bpb/README.rst 

:ref:`You should see something like this. <FigModelbpb>` 
                      
.. _FigModelbpb:
.. figure:: pics/model/bpb/bpb.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   The bulk projected bands of the model.
           
                      

                      
Let's explain the script :file:`bpb/slabify.py` now.     

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/bpb/slabify.py
   :linenos:

In line 34-42 we define a path through the 2d BZ and set the maximum
number of subdivisions for the path segments to 150. In line 47 we
define an `EnergyContour <pyfplo.slabify.EnergyContour>` for the EDC.
In line 49 the bulk projected EDC is calculated
(`Slabify.calculateBulkProjectedEDC
<pyfplo.slabify.Slabify.calculateBulkProjectedEDC>`) by defining a
projection axis *zaxis* and setting the number of integration
intervals for the projetion. The code finds out which is the shortest
period in the projection direction and integrates over this period via
linear interpolation. A complex representation of the delta functions
is used, which necessitates an imaginary part in `EnergyContour`
(automatic in our case). The result is written to
:file:`slabifyres/+bpb_fs.spin1`.

In lines 52-59 we set up a 2d mesh in a plane perpendicular to the
projection axis, set an imaginary energy part (needs some
experimenting for good results) and do the calculation
(`Slabify.calculateBulkProjectedFS
<pyfplo.slabify.Slabify.calculateBulkProjectedFS>`). The result is
written to 'slabifyres/+bpfs_sf.spin1'.
      

Finite slab with 10 unit cells
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We construct a finite slab with 10 unit cells. 
Please change into :file:`slab10/` and run the script (from
:file:`slab10/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/slab10/README.rst 


:ref:`You should see something like this. <FigModelslab10>`
                      
.. _FigModelslab10:
.. figure:: pics/model/slab10/weislab10.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   The 10-cell finite slab band structure.
  
Let's explain the script :file:`slab10/slabify.py` now.     

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/slab10/slabify.py
   :linenos:

This time we make a slab structure (free standing x,y-periodic slab)
in line 30. The `zaxis <pyfplo.slabify.Slabify.zaxis>` is not set and
hence has its default value ``[0,0,1]``. Line 32 sets `numberoflayers
<pyfplo.slabify.Slabify.numberoflayers>`.  We set the `anchor
<pyfplo.slabify.Slabify.anchor>` to slightly below 0 in line 31. What
happens now:

.. _structurecreationalgo:

  * The default 3d unit cell is enlarged to produce the "enlarged 3d" unit
    cell in :file:`=.in_step_1_3d_enlarged` (identical to the default
    here).
    
  * The enlarged 3d unit cell will be transformed into a 3d unit cell
    which has the ``a`` and ``b`` axis perpendicular to the
    `zaxis`. (the ``c`` axis it not necessarily parallel to the ``z``
    axis) This creates the elementary building block for ``'slabs'``\ /\
    ``'semislabs'``.
  
  * Then this block is repeated ``numberoflayers`` of times in
    ``c``-direction to get the 3d "layered cell"
    (:file:`=.in_step_2_3d_layered`).
  
  * Next, the "layered cell" will be anchored, which means that the
    ``z``-periodic 3d "layered cell" will be shifted such that `anchor
    <pyfplo.slabify.Slabify.anchor>` becomes the ``z=0``-plane. After
    this the cell is cut at ``z=0`` and ``z=1``, which results in a free
    standing slab of the length of one "layered cell" unit cell. The
    result is found in :file:`=.in_step_3_slab_anchored`
    For ``'semislab'``\ s the resulting cell is used as surface
    block (layer) such that the upper boundary (largest ``z``) represents
    the surface to the vaccum. Internally this block is repeated
    indefinitely at the lower boundary of the unit cell to form a
    semi-infinite slab.

The next option is only needed for ``'slab'``\ s.

  * (Not used here) After this, `cutlayersat
    <pyfplo.slabify.Slabify.cutlayersat>` is applied to cut away some
    layers at the top and bottom of the slab.

The next option is currently only used for ``'slab'``\ s, which means
that we cannot remove selected atoms for ``'semislab'``\ s yet.
    
  * (Not used here) Finally, all atoms in the list `cutatoms
    <pyfplo.slabify.Slabify.cutatoms>` are removed from the slab.  The
    number in this list must be taken from the site numbers in
    :file:`=.in_step_4_slab_cutlayers`. Use **xfplo** and point the
    mouse at the atoms: the status bar will show the site number as in
    ``Al(S3,W3,T3)...``. ``S3`` means site 3. The result after this step is
    :file:`=.in_final_PLlayer`


We setup the high symmetry points an calculate bands and weights up to
line 46.

What comes next is adding all orbitals at the two sides and in the
middle to get band weights to color the band structure with. In the
current slab this is not very interesting. But it becomes interesting
later. Line 51 defines a list of orbitals which sit up to 10 length
units (usually Bohr radii) deep at the upper side of the slab. Note
the ``-1`` in the first argument. This is explained in
`orbitalNamesByDepth <pyfplo.slabify.Slabify.orbitalNamesByDepth>` and
`orbitalIndicesByDepth <pyfplo.slabify.Slabify.orbitalIndicesByDepth>`. 
It just takes orbitals at the lower side which lie below the lower
vaccum boundary, which is no orbitals.
The same is done for the ``lower`` variable. The line 55 shows a neat
trick to calculate the rest (which is not orbitals in the upper or
lower set of orbitals).

Line 58-61 defines three added weights named ``'bulk'``, ``'lower'``
and ``'upper'`` and line 63-64 read the bandweights file and write the
added weights to :file:`+bwsum_sf`.

Now, we can color the band weights according to their "surface
character" which is shown in :ref:`FigModelslab10`. Nothing interesting
to see here. (But later!)

Finite slab with 10 unit cells (doubled in-plane cell)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We construct a finite slab with 10 unit cells, doubled in the ``a``,
``b``\ -plane.

Please change into :file:`slab10x2/` and run the script
(from :file:`slab10x2/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/slab10x2/README.rst 


:ref:`You should see something like this. <FigModelslab10x2>`
                      
.. _FigModelslab10x2:
.. figure:: pics/model/slab10x2/weislab10x2.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   The 10-cell slab with doubled in-plane unit cell.
  
Let's explain the script :file:`slab10x2/slabify.py` now.     

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/slab10x2/slabify.py
   :linenos:

We now used an |refenlarge| matrix to double the 3d unit cell (Line
31). In contrast to the previous example we now use another route to
get the neede orbital sets (Line 52-60). This also alters the line
66-68. Whatever method you use depends on what you want to do. The
orbital-name based approach allows specific filtering, which was shown
elsewhere.

This example was not very interesting either. Let's go on.


Finite slab with 10 unit cells (doubled in-plane cell), one atom removed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We construct a finite slab with 10 unit cells, doubled in the ``a``,
``b``\ -plane with one atom removed at the upper side.

Please change into :file:`slab10x2mod1/` and run the script
(from :file:`slab10x2mod1/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/slab10x2mod1/README.rst 


:ref:`You should see something like this. <FigModelslab10x2mod1>`
                      
.. _FigModelslab10x2mod1:
.. figure:: pics/model/slab10x2mod1/weislab10x2mod1.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   10-cell slab, double in-plane cell, one atom removed.

Now, that is interesting. We see a surface state steming from the
removed atom at the upper boundary.
           
Let's explain the script :file:`slab10x2mod1/slabify.py` now.

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/slab10x2mod1/slabify.py
   :linenos:

Now, we remove atom 20 in line 34. Have a look at
:file:`=.in_final_PLlayer`, you will see that an atom at the top is
missing.

In lines 72-84 we do something new.  We define added band weights for
the file :file:`+sweights_sf`, which contains fatband data of
layer-coordinate versus k-path. The band weights are refering to the
bands not orbitals. This file tells us in which layer a particular
bands has what weight. By defining added weights for band 10 and the
rest we can see in :ref:`this Figure <FigModelslab10x2mod1swei>` that the surface
state in :ref:`FigModelslab10x2mod1` really lives in the first layer
and the rest of the bands does not.

                      
.. _FigModelslab10x2mod1swei:
.. figure:: pics/model/slab10x2mod1/sweislab10x2mod1.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Layer resolved weights of the bands.


Finite slab with 10 unit cells (doubled in-plane cell), 3 atoms removed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   

We construct a finite slab with 10 unit cells, doubled in the ``a``,
``b``\ -plane with one atom removed at the upper side and two at the
lower side.

Please change into :file:`slab10x2mod2/` and run the script
(from :file:`slab10x2mod2/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/slab10x2mod2/README.rst 


:ref:`You should see something like this. <FigModelslab10x2mod2>`
                      
.. _FigModelslab10x2mod2:
.. figure:: pics/model/slab10x2mod2/weislab10x2mod2.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   10-cell slab, doubled in-plane, 3 atoms removed.

Now, that is even more interesting. We see a surface state steming from the
removed atom at the upper surface and two surface states from the
atom removal at the lower boundary.

Let's explain the script :file:`slab10x2mod2/slabify.py` now.

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/slab10x2mod2/slabify.py
   :linenos:

Line 34 now removes sites 2, 4 and 20. In lines 80-88 we use a
different technique to extract the layer-wise fatbands for 3 bands and
the rest resulting in :ref:`this Figure <FigModelslab10x2mod2swei>`.

                      
.. _FigModelslab10x2mod2swei:
.. figure:: pics/model/slab10x2mod2/sweislab10x2mod2.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Layer resolved weights of the bands.

The second script in this example is
:file:`slab10x2mod2/cuts.py`:

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/slab10x2mod2/cuts.py
   :linenos:

      
Here we first define the addweights in lines 40-51. Then we give *wds*
as argument to `Slabify.calculateFermiSurfaceCuts
<pyfplo.slabify.Slabify.calculateFermiSurfaceCuts>` which triggers the
creation of the files :file:`+cutswithweights...`. Note, that the flag
``forcerecalculation=False`` is used in the second call to
`Slabify.calculateFermiSurfaceCuts
<pyfplo.slabify.Slabify.calculateFermiSurfaceCuts>`.  The resulting
files are plottet via `xfbp wcuts.cmd` and produce
:ref:`this Figure. <FigModelslab10x2mod2cuts>`.

.. _FigModelslab10x2mod2cuts:
.. figure:: pics/model/slab10x2mod2/wcuts.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Fermi surface cuts colored by bulk, lower and upper weights.

You can see that there are a lots of tiny wiggles in the bulk band
region.  This is so because we backfolded the planar unit cell. The
only changes to the Hamiltonian are the cut-out atoms, which do not
influence the bulk much. Together with the finit number of layers this
is what you get. For infinite layers these bulk regions would fill up
completely. What you also see however are the blue upper-surface
surface-band for :math:`E=0` and additionally one green lower-surface
surface-band for :math:`E=-1`. Compare to :ref:`the band weights
<FigModelslab10x2mod2>`.

Semi infinite slab
^^^^^^^^^^^^^^^^^^

Finally we create spectral density plots for a semi infinite slab. In
this case not much interesing is seen, since the surface states where
a consequence of cutting out and atom, which currently is not yet
implemented for ``'semislab'``\ s yet.


Please change into :file:`semi/` and run the script
(from :file:`semi/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/semi/README.rst 


:ref:`You should see something like this <FigModelsemi>` and
:ref:`something like this <FigModelfssemi>`. Compare this to :ref:`the
bulk projected bands <FigModelbpb>`.
                      
.. _FigModelsemi:
.. figure:: pics/model/semi/edc.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Energy distribution curves for the semi-infinite slab.

.. _FigModelfssemi:
.. figure:: pics/model/semi/fssemi.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Surface Fermi surface spectral function.

Let's explain the script :file:`semi/slabify.py` now.

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/semi/slabify.py
   :linenos:

In line 32 the structure type is set. We u se ``numberoflayers=4`` in
this case, although it is not really needed. See documentation of
`numberoflayers <pyfplo.slabify.Slabify.numberoflayers>`. In lines
39-47 a band structure path is setup for the energy distribution curve
(EDC). Line 49 defines an energy contour (see `EnergyContour
<pyfplo.slabify.EnergyContour>`) with an automatic imaginary
part. Line 55 and 58 actually execute the EDC calculation
(`Slabify.calculateEDC <pyfplo.slabify.Slabify.calculateEDC>`) with
two different ``penetrationdepth``\ s.  The resulting files are called
:file:`+akbl_sf.spin1` (or `spin2`), which we modified via the
*suffix* argument.  The name means: ``akbl``\ =\
:math:`A_\mathrm{Bl}(\boldsymbol{k})` = Bloch-spectral-function and
``sf`` = slabify.

``penetrationdepth`` indicates to which depth the spectral
density is collected.  The larger the ``penetrationdepth`` the more
bulk signal will be sampled.


Lines 60-65 setup and calculate the surface Fermi surface, which is
basically the k,k-resolved spectral density for the 2d surface BZ
(`Slabify.calculateFermiSurfaceSpectralDensity
<pyfplo.slabify.Slabify.calculateFermiSurfaceSpectralDensity>`).  The
resulting files are called :file:`+fs_sf.spin1` (or `spin2`), which we
modified via the *suffix* argument. The name means ``fs`` =
Fermi-Surface-Spectral-Function and ``sf`` = slabify.

Semi infinite slab, doubled planar cell
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

At very last, we double the planar unit cell for illustrative purpose.

Please change into :file:`semix2/` and run the script
(from :file:`semix2/README.rst`):

.. literalinclude::   ../../DOC/pyfplo/Examples/slabify/model/semix2/README.rst 


:ref:`You should see something like this <FigModelsemix2>` and
:ref:`somehting like this <FigModelfssemix2>`. Compare this to the
left panel of :ref:`the finite slab result <FigModelslab10x2mod2cuts>`
with removed atoms. It demonstrates the backfolding in the
bulk projected bands region.
                      
.. _FigModelsemix2:
.. figure:: pics/model/semix2/edc.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   The energy distribution curves.

.. _FigModelfssemix2:
.. figure:: pics/model/semix2/fssemi.png
   :figwidth: 10cm
   :width: 10cm
   :align: center

   Surface Fermi-surface spectral function.

Let's explain the script :file:`semix2/slabify.py` now.

.. literalinclude:: ../../DOC/pyfplo/Examples/slabify/model/semix2/slabify.py
   :linenos:

The only thing we changed was line 34.


With this the introductory tutorial shall end.
