## Documentation for module fermi_utils

deal with the Fermi distribution, compute it, fix mu, get derivs

source: fermi_utils.F

#### public Subroutines/Functions:

SUBROUTINE
fermi (f, n, kts, e, mu, t, maxocc, estate, festate)
returns occupations according to Fermi-Dirac statistics for a given set of energies and fermi level. Note that singly occupied orbitals are assumed
SUBROUTINE
fermifixed (f, mu, kts, e, n, t, maxocc, estate, festate)
returns occupations according to Fermi-Dirac statistics for a given set of energies and number of electrons. Note that singly occupied orbitals are assumed. could fail if the fermi level lies out of the range of eigenvalues (to be fixed)
SUBROUTINE
fermifixedderiv (dfde, f, mu, kts, e, n, t, maxocc, l, estate, festate)
returns f and dfde for a given set of energies and number of electrons it is a numerical derivative, trying to use a reasonable step length it ought to yield an accuracy of approximately EPSILON()^(2/3) (~10^-11) l ~ 10*T yields best accuracy Note that singly occupied orbitals are assumed. To be fixed: this could be parallellized for better efficiency
SUBROUTINE
fermikp (f, mu, kts, e, nel, wk, t, maxocc)
Bisection search to find mu for a given nel (kpoint case)
SUBROUTINE
fermikp2 (f, mu, kts, e, nel, wk, t)
Bisection search to find mu for a given nel (kpoint case)

#### SUBROUTINEfermi(f, n, kts, e, mu, t, maxocc, estate, festate)^

returns occupations according to Fermi-Dirac statistics for a given set of energies and fermi level. Note that singly occupied orbitals are assumed

##### Arguments:
 REAL(dp), INTENT(out) :: f(:) occupations REAL(dp), INTENT(out) :: n total number of electrons (output) REAL(dp), INTENT(out) :: kts ... REAL(dp), INTENT(in) :: e(:) eigenvalues REAL(dp), INTENT(in) :: mu Fermi level (input) REAL(dp), INTENT(in) :: t electronic temperature REAL(dp), INTENT(in) :: maxocc maximum occupation of an orbital INTEGER, INTENT(in), OPTIONAL :: estate excited state in core level spectroscopy REAL(dp), INTENT(in), OPTIONAL :: festate occupation of the excited state in core level spectroscopy

#### SUBROUTINEfermifixed(f, mu, kts, e, n, t, maxocc, estate, festate)^

returns occupations according to Fermi-Dirac statistics for a given set of energies and number of electrons. Note that singly occupied orbitals are assumed. could fail if the fermi level lies out of the range of eigenvalues (to be fixed)

##### Arguments:
 REAL(dp), INTENT(out) :: f(:) occupations REAL(dp), INTENT(out) :: mu Fermi level (output) REAL(dp), INTENT(out) :: kts ... REAL(dp), INTENT(in) :: e(:) eigenvalues REAL(dp), INTENT(in) :: n total number of electrons (input) REAL(dp), INTENT(in) :: t electronic temperature REAL(dp), INTENT(in) :: maxocc maximum occupation of an orbital INTEGER, INTENT(in), OPTIONAL :: estate excited state in core level spectroscopy REAL(dp), INTENT(in), OPTIONAL :: festate occupation of the excited state in core level spectroscopy

#### SUBROUTINEfermifixedderiv(dfde, f, mu, kts, e, n, t, maxocc, l, estate, festate)^

returns f and dfde for a given set of energies and number of electrons it is a numerical derivative, trying to use a reasonable step length it ought to yield an accuracy of approximately EPSILON()^(2/3) (~10^-11) l ~ 10*T yields best accuracy Note that singly occupied orbitals are assumed. To be fixed: this could be parallellized for better efficiency

##### Arguments:
 REAL(dp), INTENT(out) :: dfde(:,:) derivatives of the occupation numbers with respect to the eigenvalues the ith column is the derivative of f wrt to e_i REAL(dp), INTENT(out) :: f(:) occupations REAL(dp), INTENT(out) :: mu Fermi level (input) REAL(dp), INTENT(out) :: kts ... REAL(dp), INTENT(in) :: e(:) eigenvalues REAL(dp), INTENT(in) :: n total number of electrons (output) REAL(dp), INTENT(in) :: t electronic temperature REAL(dp), INTENT(in) :: maxocc ... REAL(dp), INTENT(in) :: l typical lenght scale (~ 10 * T) INTEGER, INTENT(in), OPTIONAL :: estate ... REAL(dp), INTENT(in), OPTIONAL :: festate ...

#### SUBROUTINEfermikp(f, mu, kts, e, nel, wk, t, maxocc)^

Bisection search to find mu for a given nel (kpoint case)

##### Arguments:
 REAL(dp), INTENT(out) :: f(:,:) Occupation numbers REAL(dp), INTENT(out) :: mu chemical potential REAL(dp), INTENT(out) :: kts Entropic energy contribution REAL(dp), INTENT(in) :: e(:,:) orbital (band) energies REAL(dp), INTENT(in) :: nel Number of electrons (total) REAL(dp), INTENT(in) :: wk(:) kpoint weights REAL(dp), INTENT(in) :: t Temperature REAL(dp), INTENT(in) :: maxocc Maximum occupation

#### SUBROUTINEfermikp2(f, mu, kts, e, nel, wk, t)^

Bisection search to find mu for a given nel (kpoint case)

##### Arguments:
 REAL(dp), INTENT(out) :: f(:,:,:) Occupation numbers REAL(dp), INTENT(out) :: mu chemical potential REAL(dp), INTENT(out) :: kts Entropic energy contribution REAL(dp), INTENT(in) :: e(:,:,:) orbital (band) energies REAL(dp), INTENT(in) :: nel Number of electrons (total) REAL(dp), INTENT(in) :: wk(:) kpoint weights REAL(dp), INTENT(in) :: t Temperature