Relax input documentation
=========================


Specify geometry relaxation algorithm and convergence parameters.


Used to initialize class :class:`qimpy.dft.geometry.Relax`.

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

.. parsed-literal::

   :yamlparam:`qimpy.dft.geometry.Relax:n-iterations`: 20         :yamlcomment:`# Maximum number of iterations.`
   :yamlparam:`qimpy.dft.geometry.Relax:energy-threshold`: 5e-05  :yamlcomment:`# Convergence threshold on energy change in Eh.`
   :yamlparam:`qimpy.dft.geometry.Relax:fmax-threshold`: 0.0005   :yamlcomment:`# Convergence threshold on maximum force in Eh/a0.`
   :yamlparam:`qimpy.dft.geometry.Relax:stress-threshold`: 1e-05  :yamlcomment:`# Convergence threshold on |stress| (stress tensor norm) in Eh/a0^3.`
   :yamlparam:`qimpy.dft.geometry.Relax:n-consecutive`: 1         :yamlcomment:`# Number of consecutive iterations each threshold must be satisfied.`
   :yamlparam:`qimpy.dft.geometry.Relax:method`: l-bfgs           :yamlcomment:`# Relaxation algorithm: L-BFGS, CG or Gradient.`
   :yamlparam:`qimpy.dft.geometry.Relax:cg-type`: polak-ribiere   :yamlcomment:`# CG variant: Polak-Ribiere, Fletcher-Reeves or Hestenes-Stiefel.`
   :yamlparam:`qimpy.dft.geometry.Relax:line-minimize`: auto      :yamlcomment:`# Line minimization scheme: Auto, Constant, Quadratic, Wolfe.`
   :yamlparam:`qimpy.dft.geometry.Relax:n-history`: 15            :yamlcomment:`# Maximum history size (only used for L-BFGS).`
   :yamlparam:`qimpy.dft.geometry.Relax:converge-on`: all         :yamlcomment:`# Converge on 'any', 'all' or a specific number of thresholds.`
   :yamlparam:`qimpy.dft.geometry.Relax:drag-wavefunctions`: :yamlkey:`yes`  :yamlcomment:`# Whether to drag atomic components of wavefunctions.`
   :yamlparam:`qimpy.dft.geometry.Relax:save-history`: :yamlkey:`yes`        :yamlcomment:`# Whether to save history along the trajectory.`

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

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

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

Maximum number of iterations.

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

*Type:* :yamltype:`float`, *Default:*  5e-05

Convergence threshold on energy change in Eh.

fmax-threshold
++++++++++++++

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

Convergence threshold on maximum force in Eh/a0.

stress-threshold
++++++++++++++++

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

Convergence threshold on |stress| (stress tensor norm) in Eh/a0^3.

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

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

Number of consecutive iterations each threshold must be satisfied.

method
++++++

*Type:* :yamltype:`string`, *Default:*  l-bfgs

Relaxation algorithm: L-BFGS, CG or Gradient.
The default L-BFGS (limited-memory Broyden–Fletcher–Goldfarb–Shanno)
method is strongly recommended as it requires the least number of force
evaluations per line minimize step (with the `Wolfe` line minimize).
Only use CG (conjugate gradients) if L-BFGS fails for some system.
The steepest-descent `Gradient` method is only for special test cases.

cg-type
+++++++

*Type:* :yamltype:`string`, *Default:*  polak-ribiere

CG variant: Polak-Ribiere, Fletcher-Reeves or Hestenes-Stiefel.
Variant of conjugate gradients method (only matters if `method` is CG).

line-minimize
+++++++++++++

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

Line minimization scheme: Auto, Constant, Quadratic, Wolfe.
Auto matches the line minimization scheme to `method` (recommended).
Constant is a constant step-size usable with the Gradient-descent method.
Quadratic is best-suited for conjugate-gradients methods.
Wolfe is a cubic line step best suited for L-BFGS.

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

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

Maximum history size (only used for L-BFGS).

converge-on
+++++++++++

*Type:* :yamltype:`string` or :yamltype:`int`, *Default:*  all

Converge on 'any', 'all' or a specific number of thresholds.
If set to `any`, reaching threshold on any one of energy, force and stress
(wherever applicable) will lead to convergence. When set to `all`, all
applicable thresholds must be satisfied. If set to an integer between 1
and the number of applicable thresholds, require that many thresholds to
be satisfied simultaneously to achieve convergence.

drag-wavefunctions
++++++++++++++++++

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

Whether to drag atomic components of wavefunctions.

save-history
++++++++++++

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

Whether to save history along the trajectory.
Saved quantities include positions, forces, energies,
stress (if available) and lattice (if movable).