
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples\00-band_structure\plot_ipr.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_00-band_structure_plot_ipr.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_00-band_structure_plot_ipr.py:


.. _ref_plot_ipr:

Plotting Inverse participation ratio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Often it is needed to search for **localized** modes within the band structure, typical examples are surface/interface states and defect levels. 
The usual procedure for detecting them is looking for bands with a large projection around the atoms at the surface or defect. 
This procedure is both cumbersome for the user and error-prone. For instance, the lowest unoccupied levels
of the neutral :math:`C_N` defect in h-BN has practically no projection on the defect atom and its nearest neighbors. 
This delayed its identification as a single-photon emitter.[jara2021,auburger2021] 
A much simpler way to detect these localized levels is by means of the **Inverse Participation Ratio**, defined as

.. math::
  IPR_{nk} = \frac{\sum_{a} |c_{nki}|^4}{\left(\sum_a c_{nka}\right)^2}

where the indexes :math:`n,k,a` are the band, k-point and atom, respectively. 
This function has been extensively applied in the context of Anderson localization.[Evers2000] 
However, can capture any kind of localization. A perfectly localized state -**i.e.** 
localized in a single atom- would have :math:`IPR=1`, but a fully extended state has :math:`IPR=\frac{1}{N}`, with :math:`N` the total number of atoms.

Preparation
-----------
Before diving into plotting, we need to download the example files. 
Use the following code to do this. Once downloaded, specify the `data_dir` to point to the location of the downloaded data.

.. code-block::
  :caption: Downloading example

  import pyprocar

  bi2se3_data_dir = pyprocar.download_example(
                              save_dir='', 
                              material='Bi2Se3-spinorbit-surface',
                              code='vasp', 
                              spin_calc_type='spin-polarized-colinear',
                              calc_type='bands'
                              )

  C_data_dir = pyprocar.download_example(
                              save_dir='', 
                              material='NV-center',
                              code='vasp', 
                              spin_calc_type='spin-polarized-colinear',
                              calc_type='bands'
                              )

.. GENERATED FROM PYTHON SOURCE LINES 50-53

Setting up the environment
--------------------------
First, we will import the necessary libraries and set up our data directory path.

.. GENERATED FROM PYTHON SOURCE LINES 53-66

.. code-block:: Python


    import os

    import pyprocar

    # Define the directory containing the example data
    bi2se3_data_dir = os.path.join(
        pyprocar.utils.DATA_DIR, "examples", "Bi2Se3-spinorbit-surface"
    )


    C_data_dir = os.path.join(pyprocar.utils.DATA_DIR, "examples", "NV-center")








.. GENERATED FROM PYTHON SOURCE LINES 67-75

Topologically-protected surface states in :math:`Bi_2Se_3`
-----------------------------------------------------------

The first example is the detection of topologically-protected surface states in :math:`Bi_2Se_3`, [zhang2009].
The whole slab has six van der Waals layers (quintuple layers), each is five atom thick. The surface states localize on the outer quintuple layers,
in contrast a extended state cover the six quintuple layers.
The ratio between the localization of both types of states is 1 to 3, and the $IPR$ has enough resolution to provide a clear visual identification.
The PyProcar code is:

.. GENERATED FROM PYTHON SOURCE LINES 75-87

.. code-block:: Python


    pyprocar.bandsplot(
        dirname=bi2se3_data_dir,
        elimit=[-1.0, 1.0],
        mode="ipr",
        code="vasp",
        spins=[0],
        fermi=2.0446,
        clim=[0, 0.2],
    )





.. image-sg:: /examples/00-band_structure/images/sphx_glr_plot_ipr_001.png
   :alt: plot ipr
   :srcset: /examples/00-band_structure/images/sphx_glr_plot_ipr_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


                ----------------------------------------------------------------------------------------------------------
                There are additional plot options that are defined in the configuration file. 
                You can change these configurations by passing the keyword argument to the function.
                To print a list of all plot options set `print_plot_opts=True`

                Here is a list modes : plain , parametric , scatter , atomic , overlay , overlay_species , overlay_orbitals
                ----------------------------------------------------------------------------------------------------------
            

    (<Figure size 900x600 with 2 Axes>, <Axes: xlabel='K vector', ylabel='E - E$_F$ (eV)'>)



.. GENERATED FROM PYTHON SOURCE LINES 88-99

:math:`NV^-` defect in diamond
---------------------------------

The second example is the :math:`NV^-` defect in diamond, it is a negatively charged N substitution plus an adjacent vacancy.
This defect if of interest as a source of single photons. Its ground state is a triplet, allowing the control of the spin by microwave radiation.[DOHERTY2013]
The supercell has 215 atoms, hence :math:`IPR\to0` for bulk states (blue lines).
Several defect levels lie within the fundamental band gap of diamond (dark red lines). The closest levels to the Fermi energy are double degenerate (**i.e.** triplet),
but only occupied for the spin majority. Hence, according to the optical transition takes place between the bands with index :math:`430\to431` or :math:`430\to432`
of the spin channel labelled `spin-1`. The calculation of the main emission line involves a calculation of the excited state,
which can be simulated by fixing the occupations of the mentioned levels, **i.e.** the :math:`\Delta` SCFmethod.[Jin2021]
The pyprocar code is:

.. GENERATED FROM PYTHON SOURCE LINES 99-109

.. code-block:: Python


    pyprocar.bandsplot(
        dirname=C_data_dir,
        elimit=[-3.0, 2.5],
        mode="ipr",
        code="vasp",
        fermi=12.4563,
        spins=[0, 1],
        clim=[0, 0.1],
    )



.. image-sg:: /examples/00-band_structure/images/sphx_glr_plot_ipr_002.png
   :alt: plot ipr
   :srcset: /examples/00-band_structure/images/sphx_glr_plot_ipr_002.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


                ----------------------------------------------------------------------------------------------------------
                There are additional plot options that are defined in the configuration file. 
                You can change these configurations by passing the keyword argument to the function.
                To print a list of all plot options set `print_plot_opts=True`

                Here is a list modes : plain , parametric , scatter , atomic , overlay , overlay_species , overlay_orbitals
                ----------------------------------------------------------------------------------------------------------
            
    C:\Users\lllang\Desktop\Current_Projects\pyprocar\pyprocar\plotter\ebs_plot.py:701: UserWarning: Attempting to set identical low and high xlims makes transformation singular; automatically expanding.
      self.ax.set_xlim(interval)
    Atomic plot: bands.shape  : (2, 540, 2)
    Atomic plot: spd.shape    : (2, 540, 215, 1, 9, 2)
    Atomic plot: kpoints.shape: (2, 3)

    (<Figure size 900x600 with 2 Axes>, <Axes: xlabel='K vector', ylabel='E - E$_F$ (eV)'>)




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 21.526 seconds)


.. _sphx_glr_download_examples_00-band_structure_plot_ipr.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_ipr.ipynb <plot_ipr.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_ipr.py <plot_ipr.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_ipr.zip <plot_ipr.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
