qimpy.algorithms.Minimize

class Minimize(*, checkpoint_in, comm, name, n_iterations, energy_threshold, extra_thresholds, n_consecutive, method, cg_type='polak-ribiere', line_minimize='auto', step_size=None, i_iter_start=0, n_history=15, wolfe=None, converge_on='any')

Bases: Generic[Vector], ABC, TreeNode

Abstract base class implementing large-scale minimization algorithms. The Vector that is minimized over must support vector-space operators as specified by the Optimizable abstract base class.

Parameters:

  • checkpoint_in (CheckpointPath) –

  • comm (MPI.Comm) –

  • name (str) –

  • n_iterations (int) –

  • energy_threshold (float) –

  • extra_thresholds (dict[str, float]) –

  • n_consecutive (int) –

  • method (str) –

  • cg_type (str) –

  • line_minimize (str) –

  • step_size (Optional[dict]) –

  • i_iter_start (int) –

  • n_history (int) –

  • wolfe (Optional[dict]) –

  • converge_on (Union[str, int]) –

__init__(*, checkpoint_in, comm, name, n_iterations, energy_threshold, extra_thresholds, n_consecutive, method, cg_type='polak-ribiere', line_minimize='auto', step_size=None, i_iter_start=0, n_history=15, wolfe=None, converge_on='any')

Initialize minimization algorithm parameters.

Parameters:

  • checkpoint_in (CheckpointPath) –

  • comm (Comm) –

  • name (str) –

  • n_iterations (int) –

  • energy_threshold (float) –

  • extra_thresholds (dict[str, float]) –

  • n_consecutive (int) –

  • method (str) –

  • cg_type (str) –

  • line_minimize (str) –

  • step_size (dict | None) –

  • i_iter_start (int) –

  • n_history (int) –

  • wolfe (dict | None) –

  • converge_on (str | int) –

Return type:

None

Methods

__init__

Initialize minimization algorithm 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.

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

Move the state along direction by amount step_size

Attributes

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.
class StepSize(initial=1.0, minimum=1e-10, should_update=True, reduce_factor=0.1, grow_factor=3.0, n_adjust=10)

Bases: NamedTuple

Parameters for controlling line-minimize step size.

Parameters:

  • initial (float) –

  • minimum (float) –

  • should_update (bool) –

  • reduce_factor (float) –

  • grow_factor (float) –

  • n_adjust (int) –

grow_factor: float

Maximum step size growth at one time

initial: float

Initial step size

minimum: float

Smallest step size at which to give up

n_adjust: int

Number of step changes in one line minimize

reduce_factor: float

Reduction factor when a step fails

should_update: bool

Whether to update test step size

class Wolfe(energy=0.0001, gradient=0.9)

Bases: NamedTuple

Wolfe line minimize stopping conditions.

Parameters:

  • energy (float) –

  • gradient (float) –

energy: float

Dimensionless minimum energy reduction in step

gradient: float

Required reduction of projected gradient

abstract compute(state, energy_only)

Update energy and/or gradients in state. If energy_only is True, only update the energy, else update all entries including extra convergence checks, gradients and preconditioned gradient.

Parameters:
Return type:

None

constrain(v)

Override to impose any constraints, restricting to allowed subspace. The input may be modified in-place and returned for efficiency.

Parameters:

v (Vector) –

Return type:

Vector

finite_difference_test(direction, step_sizes=None)

Check gradient implementation by taking steps along direction. This will print ratio of actual energy differences along steps of various sizes in step_sizes and the expected energy difference based on the gradient. A correct implementation should show a ratio approaching 1 for a range of step sizes, with deviations at lower step sizes due to round off error and at higher step sizes due to nonlinearity.

Parameters:

  • direction (Vector) –

  • step_sizes (Sequence[float] | None) –

Return type:

None

minimize()

Minimize, and return optimized energy of system

Return type:

Energy

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

safe_step_size(direction)

Override to return maximum safe step size along direction, if any. By default, there is no upper bound on step size.

Parameters:

direction (Vector) –

Return type:

float

abstract step(direction, step_size)

Move the state along direction by amount step_size

Parameters:

  • direction (Vector) –

  • step_size (float) –

Return type:

None

cg_type: str

Polak-Ribiere, Fletcher-Reeves or Hestenes-Stiefel

comm: MPI.Comm

Communicator over which algorithm operates in unison

converge_on: str | int

Converge on ‘any’, ‘all’ or a number of thresholds

energy_threshold: float

Convergence threshold on energy change

extra_thresholds: dict[str, float]

Names and thresholds for any additional convergence quantities. These are in addition to energy, included by default. Use a name bracketed by | | for always-positive norm-like quantities for clarity in output. These must correspond (in order) to the outputs of compute().

i_iter_start: int

Starting iteration number (eg. if continuing from checkpoint)

line_minimize: str

Auto, Constant, Quadratic, Wolfe

Type:

Line minimization

method: str

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

n_consecutive: int

Number of consecutive iterations threshold must be satisfied

n_converge: int

Number of thresholds that converge_on corresponds to

n_history: int

Maximum history size (only used for L-BFGS)

n_iterations: int

Maximum number of iterations

name: str

Name of algorithm instance used in reporting eg. ‘Ionic’

step_size: StepSize

Step size options

wolfe: Wolfe

Wolfe line minimize stopping conditions