.. _FermiSurfer: http://fermisurfer.osdn.jp/
.. _pw.x: file:///C:/Users/kawamuura/program/qe/qe-dev/PW/Doc/INPUT_PW.html
.. _ph.x: file:///C:/Users/kawamuura/program/qe/qe-dev/PW/Doc/INPUT_PH.html

.. _sctk:

Reference manual
================

Features of the main program of Superconducting-Toolkit, sctk.x,
is as follows:

-  Compute the Coulomb interaction matrix
   :math:`K^{el}_{n {\bf k} n' {\bf k}'}` as a preprocess.
   This program uses Kohn-Sham orbitals generated by QE.
-  Solve the gap equation and obtain the superconducting
   gap function :math:`\Delta_{n {\bf k}}`.
-  Solve the gap equation and obtain the superconducting
   transition temperature with the bisection method.
-  Perform non-SCF calculation for generating files readable by FermiSurfer_.
-  Perform non-SCF calculation for obtaining quasi particle density of states.
-  Perform non-SCF calculation for obtaining ultrasonic attenuation
   coefficient(experimental).

Also, there is a script :ref:`twingrid` to generate the :math:`{\bf k}`-point grid
where Kohn-Sham orbitals
for :ref:`the calculation of the Coulomb interaction <kel>` are computed.

Usage
-----

.. code-block:: bash

    mpiexec options PATH/sctk.x -in input_file
        
Input-file format
-----------------

The format of the input file is as follows:

::

    &CONTROL
      prefix = 
      outdir = 
      calculation = 
    /
    &KEL
      start_q =
      last_q =
      nci =
      laddxc =
      ecutfock =
      nq1 =
      nq2 =
      nq3 =
      lsf
    /
    &SCDFT
      temp =
      fbee =
      lbee =
      xic =
      nmf =
      nx =
      ne =
      emin =
      emax =
      electron_maxstep =
      conv_thr =
      fildyn =
      spin_fluc =
    /
        
These parameter can be written in random order.
If a parameter is omitted, the default value is used.

Namelist CONTROL
~~~~~~~~~~~~~~~~

=========== ========= ============ ===================================================================
Parameter   Type      Default      Description
                      value
=========== ========= ============ ===================================================================
prefix      String    "pwscf"      It must be the same as ``prefix`` in the input of pw.x_.
outdir      String    "./"         It must be the same as ``outdir`` in the input of pw.x_.
calculation String    "kel"        Type of calculation
=========== ========= ============ ===================================================================

Namelist KEL
~~~~~~~~~~~~

Parameters used for ``calculation = "kel"``.

============= ========= =============== ===================================================================
Parameter     Type      Default         Description
                        value
============= ========= =============== ===================================================================
start_q       Positive  1               First :math:`{\bf q}` for computing screened Coulomb interaction
              integer                   and spin fluctuation
last_q        Positive  Number of       Last :math:`{\bf q}` for computing screened Coulomb interaction
              integer   :math:`{\bf q}`
                        in Irreducible
                        BZ
laddxc        0 or 1    0               Specify the approximation used in the calculation of 
                                        screened Coulomb interaction. 0 : RPA, 1: Adiabatic LDA.
lsf           0 or 1    0               Whether the spin-fluctuation is computed (1) or not (0)
ecutfock      Real      Same as pw.x_   Cutoff of plane waves for the polarization function. [Ry].
nq1, nq2, nq3 Positive  Same as         The :math:`{\bf k}` mesh of the Kohn-Sham orbitals.
              integer   :math:`{\bf k}` It must be the same as the :ref:`twingrid` input.
                        mesh of a2Fsave
nci           Positive  5               The number of Matsubara
              integer                   frequencies of screened Coulomb interactions.
============= ========= =============== ===================================================================

Namelist SCDFT
~~~~~~~~~~~~~~

Parameters used when ``calculation = "scdft"``.

================ ========= ============ ===================================================================
Parameter        Type      Default      Description
                           value
================ ========= ============ ===================================================================
temp             Positive  0.1          Temperature(Kelvin).
                 real
                 number 
fbee             Positive  1            The first band in the gap equation.
                 integer 
lbee             Positive  nbnd in      The last band in the gap equation.
                 integer   pw.x_
xic              Real      -1.0         Parameter for gap-function extrapolation method.
                 number                 Ry unit. When this is lower than
                                        ``0.0``, gap function extrapolation is not used
                                        (in default this extrapolation is not used.)
nmf              Real      10           The number of Matsubara frequencies
                 number                 in the calculation of the Coulomb kernel.
                                        When it is ``0`` static Coulomb kernel is used.
                                        When negative value is specified,
                                        Coulomb kernel becomes 0.
                                        (Only the phononic kernel is used).
nx               Positive  100          The number of auxiliary energy grid
                 integer                in the vicinity of the Fermi level.
ne               Positive  50           Used only in the :ref:`calculation of quasi-particle DOS <qpdos>`.
                 integer                The number of energy grid for quasi particle density of states.
emin             Positive  1.0e-7       Minimum energy scale parameter for auxiliary energy grid. Ry unit.
                 real
                 number
emax             Positive  5.0          Used only in the :ref:`calculation of quasi-particle DOS <qpdos>`.
                 real                   The maximum energy where QPDOS is computed. meV unit.
                 number
electron_maxstep Positive  100          The maximum iteration number for solving gap equation.
                 integer                
conv_thr         Positive  1.0e-15      The convergence threshold for the gap equation.
                 real                   When the norm of the difference between the new- and the old-
                 number                 gap function becomes lower than it,
                                        the system is thought to be converged. Ry unit.
filedyn          String    "matdyn"     It must be the same as filedyn in ph.x_.
spin_fluc        Logical   .False.      If .True., the spin-fluctuation :ref:`[3] <ref>` is included.
scdft_kernel     Positive  1            1: Lüders2005 :ref:`[4] <ref>`, 2: Sanna2020 :ref:`[5] <ref>`
                 integer
lz_coulomb       Logical   .False.      Coulomb renormalization :ref:`[6] <ref>`
================ ========= ============ ===================================================================

Data files
----------

The following files are read/written by sctk.x:

.. _xml:

{prefix}.xml
~~~~~~~~~~~~

It contains informations about lattice constant, etc.
It is generated by pw.x_.

.. _a2fsave:

{prefix}.a2Fsave
~~~~~~~~~~~~~~~~

It contains the Kohn-Sham
energy,information of :math:`{\bf k}` mesh, and symmetrical operations.
It is generated by pw.x_ with la2f=.true.

.. _wfc:

{prefix}.save/wfc\*.dat
~~~~~~~~~~~~~~~~~~~~~~~

It contains Kohn-Sham orbitals at each :math:`{\bf k}` point.
\* should be the index of :math:`{\bf k}` point.
It is generated by pw.x_.

.. _veldat:

vel\*.dat
~~~~~~~~~

It contains coefficients of
the Chebyshev interpolation of the screened Coulomb interaction at
each :math:`{\bf q}` point.
\* should be the index of :math:`{\bf q}` point.
It is generated by sctk.x with :ref:`calculation="kel" <kel>`.

.. _elphdat:

elph\*.dat
~~~~~~~~~~

It contains electron-phonon
interactions and phonon frequencies at each :math:`{\bf q}` point.
\* should be the index of :math:`{\bf q}` point.
It is generated by modified ph.x_.

.. _lambdafrmsf:

lambda.frmsf, mu.frmsf
~~~~~~~~~~~~~~~~~~~~~~

Data files for FermiSurfer_ for displaying the mass-renormalization factor
:math:`\lambda_{n {\bf k}}` on the Fermi surface.
It is generated by sctk.x with  :ref:`calculation="lambda_mu_k" <lambdamuk>`.

.. _deltadat:

delta.dat
~~~~~~~~~

It contains the superconducting gap functions
:math:`\Delta_{n {\bf k}}`, associated Kohn-Sham energy :math:`\xi_{n {\bf k}}`,
integration weights, band indices, :math:`{\bf k}`-indices, and the
renormalization :math:`Z_{n {\bf k}}`.
It is generated by sctk.x with :ref:`calculation="scdft" <scdft>`.

.. _qpdosdat:

qpdos.dat
~~~~~~~~~

First column:
quasiparticle energy (meV unit), Second column: quasiparticle density
of states (Ry\ :math:`^{-1}` unit).
It is generated by sctk.x with :ref:`calculation="qpdos" <qpdos>`.

.. _deltafrmsf:

delta.frmsf, Z.frmsf
~~~~~~~~~~~~~~~~~~~~

Data files for FermiSurfer_ for displaying the superconducting gaps
:math:`\Delta_{n {\bf k}}` and the renormalization :math:`Z_{n {\bf k}}` on the Fermi
surface.
It is generated by sctk.x with :ref:`calculation="deltaf" <deltaf>`.

Type of calculation
-------------------

We can specify the type of calculation by inputting the following string into
the parameter ``calculation``.

.. _kel:

kel : Screened Coulomb interaction / spin-fluctuation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following files must be put on the directory where the program runs.

-  :ref:`xml`
-  :ref:`a2fsave`
-  :ref:`wfc`

The following files are generated in the directory where program runs.

-  :ref:`veldat`

.. _lambdamuk:

lambda_mu_k : Electron-phonon parameter at each orbital
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following files must be put on the directory where the program runs.

-  :ref:`xml`
-  :ref:`a2fsave`
-  :ref:`elphdat`   
-  :ref:`veldat`

The following files are generated in the directory where program runs.

-  :ref:`lambdafrmsf`

.. _scdft:

scdft : SCDFT calculation at specific temperature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following files must be put on the directory where the program runs.

-  :ref:`xml`
-  :ref:`a2fsave`
-  :ref:`elphdat`   
-  :ref:`veldat`

The following files are generated in the directory where program runs.

-  :ref:`deltadat`

.. _scdfttc:

scdft_tc : Calculation of transition temperature with bisection method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following files must be put on the directory where the program runs.

-  :ref:`xml`
-  :ref:`a2fsave`
-  :ref:`elphdat`   
-  :ref:`veldat`

The following files are generated in the directory where program runs.

-  :ref:`deltadat`

.. _qpdos:

qpdos : Quasi-particle density of states
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following files must be put on the directory where the program runs.

-  :ref:`xml`
-  :ref:`a2fsave`
-  :ref:`elphdat`   
-  :ref:`veldat`
-  :ref:`deltadat`

The following files are generated in the directory where program runs.

-  :ref:`qpdosdat`

.. _deltaf:

deltaf : Output FermiSurfer file of gap function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following files must be put on the directory where the program runs.

-  :ref:`xml`
-  :ref:`a2fsave`
-  :ref:`elphdat`   
-  :ref:`veldat`
-  :ref:`deltadat`

The following files are generated in the directory where program runs.

-  :ref:`deltafrmsf`

ultrasonic : Ultrasonic attenuation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _twingrid:
   
twingrid.x
----------

This script  generates the double :math:`{\bf k}`-point grid for pw.x_.
The output orbitals of this pw.x_-run is used by sctk.x with
:ref:`calculation = "kel" <kel>`.

Usage
~~~~~

.. code-block:: bash

    $ bash PATH/twingrid.x nk1 nk2 nk3 >> input_file_for_pw
        

*nk1*, *nk2*, *nk3* indicate the number of :math:`{\bf k}` points along each
reciprocal lattice vectors.

Standard output
~~~~~~~~~~~~~~~

::

    K_POINTS crystal
    Total_number_of_k
    k_vector1 1.0
    k_vector2 1.0
    k_vector3 1.0
     :
        
It generates two :math:`{\bf k}` grids; the first one contains :math:`\Gamma` point, and
the other is translated with a half grid. In the above usage, the
standard output of this utility is redirected to the end of the input
file of pw.x_.
