# Relax input documentation

Specify geometry relaxation algorithm and convergence parameters.

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

## YAML template:

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

## Parameters:

### n-iterations

Type: int, Default: 20

Maximum number of iterations.

### energy-threshold

Type: float, Default: 5e-05

Convergence threshold on energy change in Eh.

### fmax-threshold

Type: float, Default: 0.0005

Convergence threshold on maximum force in Eh/a0.

### stress-threshold

Type: float, Default: 1e-05

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

### n-consecutive

Type: int, Default: 1

Number of consecutive iterations each threshold must be satisfied.

### method

Type: 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: 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: 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: int, Default: 15

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

### converge-on

Type: string or 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: bool, Default: yes

Whether to drag atomic components of wavefunctions.

### save-history

Type: bool, Default: yes

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