Fillings input documentation
============================

Initialize occupation factor (smearing) scheme.


Used to initialize class :class:`qimpy.dft.electrons.Fillings`.

YAML template:
--------------

.. parsed-literal::

   :yamlparam:`qimpy.dft.electrons.Fillings:charge`: 0.0          :yamlcomment:`# Net charge of electrons + ions in e units.`
   :yamlparam:`qimpy.dft.electrons.Fillings:smearing`: gauss      :yamlcomment:`# Smearing method for setting electron occupations.`
   :yamlparam:`qimpy.dft.electrons.Fillings:sigma`: 0.002         :yamlcomment:`# Width of the smearing function in Hartrees.`
   :yamlparam:`qimpy.dft.electrons.Fillings:kT`: :yamlkey:`null`             :yamlcomment:`# Specify temperature instead of sigma for Fermi smearing.`
   :yamlparam:`qimpy.dft.electrons.Fillings:mu`: nan              :yamlcomment:`# Electron chemical potential in Hartrees.`
   :yamlparam:`qimpy.dft.electrons.Fillings:mu-constrain`: :yamlkey:`no`     :yamlcomment:`# Whether to hold chemical potential fixed to mu.`
   :yamlparam:`qimpy.dft.electrons.Fillings:B`: 0.0               :yamlcomment:`# External magnetic field (only for spin-polarized modes).`
   :yamlparam:`qimpy.dft.electrons.Fillings:M`: 0.0               :yamlcomment:`# Total magnetization (only for spin-polarized modes).`
   :yamlparam:`qimpy.dft.electrons.Fillings:M-constrain`: :yamlkey:`no`      :yamlcomment:`# Whether to hold magnetization fixed to M.`
   :yamlparam:`qimpy.dft.electrons.Fillings:n-bands`: atomic      :yamlcomment:`# Specify number of bands or scheme to determine it.`
   :yamlparam:`qimpy.dft.electrons.Fillings:n-bands-extra`: x0.1  :yamlcomment:`# Number of extra bands retained by diagonalizers.`

Parameters:
-----------

charge
++++++

*Type:* :yamltype:`float`, *Default:*  0.0

Net charge of electrons + ions in e units.
This determines n_electrons = ions.Z_tot - charge.

smearing
++++++++

*Type:* :yamltype:`string`, *Default:*  gauss

Smearing method for setting electron occupations.
Here 'gauss', 'fermi', 'cold', 'mp1' select Gaussian, Fermi-Dirac,
Cold and first order Methfessel-Paxton (MP1) smearing respectively.
Use :yamlkey:`no` (or :yamlkey:`null`) to disable smearing and keep the electron
occupations fixed at their initial values.

sigma
+++++

*Type:* :yamltype:`float`, *Default:*  0.002

Width of the smearing function in Hartrees.
This sets Gaussian width :math:`\sigma` in the Gaussian, Cold
and M-P schemes, and :math:`2k_BT` in the Fermi-Dirac scheme.
Overridden if `kT` is specified.

kT
++

*Type:* :yamltype:`float` or :yamltype:`null`, *Default:*  :yamlkey:`null`

Specify temperature instead of sigma for Fermi smearing.
This directly sets :math:`k_BT` in Hartrees and corresponds to
:math:`\sigma/2` for the other Gaussian-based smearing schemes.
Overrides `sigma` if specified.

mu
++

*Type:* :yamltype:`float`, *Default:*  nan

Electron chemical potential in Hartrees.
This serves as an initial guess (rarely needed) if `mu_constrain`
is :yamlkey:`no`, and otherwise, it is the required value to hold
:math:`\mu` fixed at.

mu-constrain
++++++++++++

*Type:* :yamltype:`bool`, *Default:*  :yamlkey:`no`

Whether to hold chemical potential fixed to mu.
If :yamlkey:`yes`, perform grand-canonical electronic DFT.
Note that this only takes effect when `smearing` is not :yamlkey:`null`.

B
+

*Type:* :yamltype:`float` or :yamltype:`list` of :yamltype:`float`, *Default:*  0.0

External magnetic field (only for spin-polarized modes).
Must be scalar for non-spinorial and 3-vector for spinorial modes.
If `M_constrain` is :yamlkey:`yes`, then this is only an initial guess as the
magnetic field then becomes a Legendre multiplier to constrain `M`.

M
+

*Type:* :yamltype:`float` or :yamltype:`list` of :yamltype:`float`, *Default:*  0.0

Total magnetization (only for spin-polarized modes).
Must be scalar for non-spinorial and 3-vector for spinorial modes.
This magnetization is assigned to the initial occupations and it
may change when smearing is present depending on `M_constrain`.

M-constrain
+++++++++++

*Type:* :yamltype:`bool`, *Default:*  :yamlkey:`no`

Whether to hold magnetization fixed to M.
This only matters when `smearing` is not :yamlkey:`null`.

n-bands
+++++++

*Type:* :yamltype:`int` or :yamltype:`string` or qimpy.io._default.Default[str], *Default:*  atomic

Specify number of bands or scheme to determine it.

* atomic: set to the number of atomic orbitals.
* x<scale>: scale relative to the minimum number of bands
  to accommodate electrons ('x1.5' implies 1.5 x n_bands_min).
* An integer explicitly sets the number of bands.

n-bands-extra
+++++++++++++

*Type:* :yamltype:`int` or :yamltype:`string` or qimpy.io._default.Default[str], *Default:*  x0.1

Number of extra bands retained by diagonalizers.
This is necessary to converge any degenerate subspaces straddling
n_bands. May be specified as:

* x<scale>: scale relative to n_bands
* An integer explicitly sets the number of extra bands