qimpy.dft.geometry.Relax

class Relax(*, comm, lattice, n_iterations=20, energy_threshold=5e-05, fmax_threshold=0.0005, stress_threshold=1e-05, n_consecutive=1, method='l-bfgs', cg_type='polak-ribiere', line_minimize='auto', n_history=15, converge_on='all', drag_wavefunctions=True, save_history=True, checkpoint_in=(None, ''))

Bases: Minimize[Gradient]

Relax geometry of ions and/or lattice. Whether lattice changes is controlled by lattice.movable.

Parameters:

  • comm (MPI.Comm) –

  • lattice (Lattice) –

  • n_iterations (int) –

  • energy_threshold (float) –

  • fmax_threshold (float) –

  • stress_threshold (float) –

  • n_consecutive (int) –

  • method (str) –

  • cg_type (str) –

  • line_minimize (str) –

  • n_history (int) –

  • converge_on (Union[str, int]) –

  • drag_wavefunctions (bool) –

  • save_history (bool) –

  • checkpoint_in (CheckpointPath) –

__init__(*, comm, lattice, n_iterations=20, energy_threshold=5e-05, fmax_threshold=0.0005, stress_threshold=1e-05, n_consecutive=1, method='l-bfgs', cg_type='polak-ribiere', line_minimize='auto', n_history=15, converge_on='all', drag_wavefunctions=True, save_history=True, checkpoint_in=(None, ''))

Specify geometry relaxation algorithm and convergence parameters.

Parameters:

  • n_iterations (int) – [Input file] Maximum number of iterations.

  • energy_threshold (float) – [Input file] Convergence threshold on energy change in Eh.

  • fmax_threshold (float) – [Input file] Convergence threshold on maximum force in Eh/a0.

  • stress_threshold (float) – [Input file] Convergence threshold on |stress| (stress tensor norm) in Eh/a0^3.

  • n_consecutive (int) – [Input file] Number of consecutive iterations each threshold must be satisfied.

  • method (str) – [Input file] 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 (str) – [Input file] CG variant: Polak-Ribiere, Fletcher-Reeves or Hestenes-Stiefel. Variant of conjugate gradients method (only matters if method is CG).

  • line_minimize (str) – [Input file] 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 (int) – [Input file] Maximum history size (only used for L-BFGS).

  • converge_on (str | int) – [Input file] 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 (bool) – [Input file] Whether to drag atomic components of wavefunctions.

  • save_history (bool) – [Input file] Whether to save history along the trajectory. Saved quantities include positions, forces, energies, stress (if available) and lattice (if movable).

  • comm (Comm) –

  • lattice (Lattice) –

  • checkpoint_in (CheckpointPath) –

Return type:

None

Methods

__init__

Specify geometry relaxation algorithm and convergence parameters.

add_child

Construct child object self.`attr_name` of type cls.

add_child_one_of

Invoke add_child on one of several child options in args.

compute

Update energy and/or gradients in state.

constrain

Override to impose any constraints, restricting to allowed subspace.

finite_difference_test

Check gradient implementation by taking steps along direction.

minimize

Minimize, and return optimized energy of system

report

Override to perform optional reporting / processing every few steps.

run

safe_step_size

Override to return maximum safe step size along direction, if any.

save_checkpoint

Save self and all children in hierarchy to cp_path.

step

Update the geometry along direction by amount step_size

Attributes

latticeK

Preconditioning factor of lattice relative to ions

drag_wavefunctions

Whether to drag atomic components of wavefunctions

history

Utility to save trajectory data

stepper

Interface to move ions/lattice and compute forces/stress

comm

Communicator over which algorithm operates in unison

name

Name of algorithm instance used in reporting eg.

i_iter_start

Starting iteration number (eg.

n_iterations

Maximum number of iterations

energy_threshold

Convergence threshold on energy change

n_consecutive

Number of consecutive iterations threshold must be satisfied

method

CG, L-BFGS or Gradient (i.e steepest descent)

cg_type

Polak-Ribiere, Fletcher-Reeves or Hestenes-Stiefel

line_minimize

Auto, Constant, Quadratic, Wolfe

step_size

Step size options

n_history

Maximum history size (only used for L-BFGS)

wolfe

Wolfe line minimize stopping conditions

converge_on

Converge on 'any', 'all' or a number of thresholds

n_converge

Number of thresholds that converge_on corresponds to

extra_thresholds

Names and thresholds for any additional convergence quantities.

child_names

Names of attributes with child objects.
compute(state, energy_only)

Update energy and/or gradients in state.

Parameters:
Return type:

None

report(i_iter)

Override to perform optional reporting / processing every few steps. Return True if the state was modified in the process eg. to perform some kind of reset to stabilize the system. (This will be used to correspondingly reset search directions.)

Parameters:

i_iter (int) –

Return type:

bool

step(direction, step_size)

Update the geometry along direction by amount step_size

Parameters:

  • direction (Gradient) –

  • step_size (float) –

Return type:

None

drag_wavefunctions: bool

Whether to drag atomic components of wavefunctions

history: History | None

Utility to save trajectory data

latticeK: float

Preconditioning factor of lattice relative to ions

stepper: Stepper

Interface to move ions/lattice and compute forces/stress