SCF input documentation
=======================

Initialize parameters of self-consistent field iteration (SCF).


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

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

.. parsed-literal::

   :yamlparam:`qimpy.dft.electrons.SCF:n-iterations`: 50           :yamlcomment:`# Number of self-consistent field iterations / cycles.`
   :yamlparam:`qimpy.dft.electrons.SCF:energy-threshold`: 1e-08    :yamlcomment:`# Energy convergence threshold in Hartrees.`
   :yamlparam:`qimpy.dft.electrons.SCF:residual-threshold`: 1e-07  :yamlcomment:`# Residual-norm convergence threshold.`
   :yamlparam:`qimpy.dft.electrons.SCF:n-consecutive`: 2           :yamlcomment:`# Number of consecutive iterations each threshold must be satisfied.`
   :yamlparam:`qimpy.dft.electrons.SCF:n-history`: 10              :yamlcomment:`# History size for Pulay mixing.`
   :yamlparam:`qimpy.dft.electrons.SCF:mix-fraction`: 0.5          :yamlcomment:`# Fraction of new variable mixed into current variable.`
   :yamlparam:`qimpy.dft.electrons.SCF:mix-fraction-mag`: 1.5      :yamlcomment:`# Different mix_fraction for magnetization components.`
   :yamlparam:`qimpy.dft.electrons.SCF:q-kerker`: 0.8              :yamlcomment:`# Characteristic wavevector for Kerker mixing.`
   :yamlparam:`qimpy.dft.electrons.SCF:q-metric`: 0.8              :yamlcomment:`# Characteristic wavevector controlling Pulay metric.`
   :yamlparam:`qimpy.dft.electrons.SCF:q-kappa`: :yamlkey:`null`              :yamlcomment:`# Long-range cutoff wavevector for grand-canonical SCF.`
   :yamlparam:`qimpy.dft.electrons.SCF:n-eig-steps`: 2             :yamlcomment:`# Number of inner eigenvalue iterations for each SCF cycle.`
   :yamlparam:`qimpy.dft.electrons.SCF:eig-threshold`: 1e-08       :yamlcomment:`# Convergence threshold on eigenvalues in Hartrees.`
   :yamlparam:`qimpy.dft.electrons.SCF:mix-density`: :yamlkey:`yes`           :yamlcomment:`# Whether to mix density or potential.`

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

n-iterations
++++++++++++

*Type:* :yamltype:`int`, *Default:*  50

Number of self-consistent field iterations / cycles.

energy-threshold
++++++++++++++++

*Type:* :yamltype:`float`, *Default:*  1e-08

Energy convergence threshold in Hartrees.
Stop when energy difference between consecutive iterations falls
below this threshold.

residual-threshold
++++++++++++++++++

*Type:* :yamltype:`float`, *Default:*  1e-07

Residual-norm convergence threshold.
Stop when the norm of the residual i.e. difference in mixed
variable (density / potential) between consecutive iterations
falls below this threshold.

n-consecutive
+++++++++++++

*Type:* :yamltype:`int`, *Default:*  2

Number of consecutive iterations each threshold must be satisfied.

n-history
+++++++++

*Type:* :yamltype:`int`, *Default:*  10

History size for Pulay mixing.
This sets the number of previous residuals and variables to use
in the Pulay mixing algorithm. Larger history could improve
convergence, while requiring more memory.

mix-fraction
++++++++++++

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

Fraction of new variable mixed into current variable.
Lower values (< 0.5) can improve stability, while higher values
(0.5 - 1) attempt more aggressive convergence.

mix-fraction-mag
++++++++++++++++

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

Different mix_fraction for magnetization components.
More aggressive fractions (> 1) are typically required to
converge the magnetization degrees of freedom, because they
tend to contribute less to the overall energy of the system
(compared to the overall electron density / potential).

q-kerker
++++++++

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

Characteristic wavevector for Kerker mixing.

q-metric
++++++++

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

Characteristic wavevector controlling Pulay metric.

q-kappa
+++++++

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

Long-range cutoff wavevector for grand-canonical SCF.
If unspecified, set based on Debye screening length.

n-eig-steps
+++++++++++

*Type:* :yamltype:`int`, *Default:*  2

Number of inner eigenvalue iterations for each SCF cycle.

eig-threshold
+++++++++++++

*Type:* :yamltype:`float`, *Default:*  1e-08

Convergence threshold on eigenvalues in Hartrees.
Stop when the maximum change in any eigenvalue between SCF cycles
falls below this threshold.

mix-density
+++++++++++

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

Whether to mix density or potential.
Mix density if :yamlkey:`yes`, and potential if :yamlkey:`no`.