qimpy.algorithms.Pulay

class Pulay(*, checkpoint_in, comm, name, n_iterations, energy_threshold, residual_threshold, extra_thresholds, n_consecutive, n_history, mix_fraction)

Bases: Generic[Variable], ABC, TreeNode

Abstract base class implementing the Pulay mixing algorithm. The mixed Variable must support vector-space operators as specified by the Optimizable abstract base class.

Parameters:

  • checkpoint_in (CheckpointPath) –

  • comm (Comm) –

  • name (str) –

  • n_iterations (int) –

  • energy_threshold (float) –

  • residual_threshold (float) –

  • extra_thresholds (dict[str, float]) –

  • n_consecutive (int) –

  • n_history (int) –

  • mix_fraction (float) –

__init__(*, checkpoint_in, comm, name, n_iterations, energy_threshold, residual_threshold, extra_thresholds, n_consecutive, n_history, mix_fraction)

Initialize Pulay algorithm parameters.

Parameters:

  • checkpoint_in (CheckpointPath) –

  • comm (Comm) –

  • name (str) –

  • n_iterations (int) –

  • energy_threshold (float) –

  • residual_threshold (float) –

  • extra_thresholds (dict[str, float]) –

  • n_consecutive (int) –

  • n_history (int) –

  • mix_fraction (float) –

Return type:

None

Methods

__init__

Initialize Pulay 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.

cycle

Single cycle of the Pulay-mixed self-consistent iteration.

metric

Apply metric to variable/residual.

optimize

Minimize residual using a Pulay-mixing / DIIS algorithm.

precondition

Apply preconditioner to variable/residual.

report

Override to perform optional reporting.

save_checkpoint

Save self and all children in hierarchy to cp_path.

Attributes

energy

Current energy components of the system (read-only).

residual

Get the current residual from state of system (read-only).

variable

Current variable in the state of the system.

comm

Communicator over which algorithm operates in unison

name

Name of algorithm instance used in reporting eg.

n_iterations

Maximum number of iterations

energy_threshold

Convergence threshold on energy change

residual_threshold

Covergence threshold on residual

n_consecutive

Number of consecutive iterations threshold must be satisfied

n_history

Number of past variables / residuals to retain

mix_fraction

Variable mixing fraction between cycles

extra_thresholds

Names and thresholds for any additional convergence quantities.

child_names

Names of attributes with child objects.
abstract cycle(dEprev)

Single cycle of the Pulay-mixed self-consistent iteration. In each subsequent cycle, Pulay will try to zero the difference between get_variable() before and after the cycle. The implementation should only do the work of computing the updated variable; debug printing and I/O, if any, should occur in report() instead.

Parameters:

dEprev (float) – Energy change at previous cycle, which may be used to adjust accuracy of any inner optimizations

Returns:

Any quantities beyond energy and residual that require convergence checking, corresponding to extra_thresholds.

Return type:

Sequence[float]

abstract metric(v)

Apply metric to variable/residual.

Parameters:

v (Variable) –

Return type:

Variable

optimize()

Minimize residual using a Pulay-mixing / DIIS algorithm.

Return type:

None

abstract precondition(v)

Apply preconditioner to variable/residual.

Parameters:

v (Variable) –

Return type:

Variable

report(i_iter)

Override to perform optional reporting.

Parameters:

i_iter (int) –

Return type:

None

comm: Comm

Communicator over which algorithm operates in unison

abstract property energy: Energy

Current energy components of the system (read-only).

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 and residual, 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 extra values output by cycle().

mix_fraction: float

Variable mixing fraction between cycles

n_consecutive: int

Number of consecutive iterations threshold must be satisfied

n_history: int

Number of past variables / residuals to retain

n_iterations: int

Maximum number of iterations

name: str

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

property residual: Variable

Get the current residual from state of system (read-only). Override this only if this Pulay mixing is not for a self-consistent iteration i.e. the residual is not the change of variable.

residual_threshold: float

Covergence threshold on residual

abstract property variable: Variable

Current variable in the state of the system.