IterationControlParameters

class IterationControlParameters(tolerance=None, max_steps=None, algorithm=None, damping_factor=None, number_of_history_steps=None, start_mixing_after_step=None, mixing_variable=None, preconditioner=None, linear_dependence_threshold=None, exx_energy_tolerance=None, max_exx_updates=None, non_convergence_behavior=None, enable_scf_stop_file=None)

Class for representing the parameters relevant for SCF iteration control within self-consistent electronic structure models.

Some parameter defaults are specific for each calculator, see HuckelCalculator, SlaterKosterCalculator, SemiEmpiricalCalculator, LCAOCalculator, PlaneWaveCalculator, DeviceHuckelCalculator, DeviceSlaterKosterCalculator, DeviceSemiEmpiricalCalculator, or DeviceLCAOCalculator.

Parameters:
  • tolerance (float) – The accuracy which the SCF loop must reach before termination. Should be positive.
    Default: Specific for each calculator. When doing hybrid DFT calculations, this will also be the tolerance used for the outer SCF loop that updates the exact exchange operator.

  • max_steps (int) – The maximum number of iteration steps the SCF loop should execute. Should be non-negative.
    Default: 100

  • algorithm (PulayMixer | AndersonMixer) – The mixing strategy employed on the mixing variable in the SCF loop.
    Default: A default PulayMixer instance

  • damping_factor (float | AdaptiveDampingFactor) – The fraction of the output value of the mixing parameter which is mixed into the next step. Should be at least 0 and smaller than 1. For bulk LCAO calculations, it is also possible to provide an instance of AdaptiveDampingFactor. In this case, the damping factor will be changed to an optimal value for the system during the SCF loop. The optimal value is calculated from the system’s band gap. Using an adaptive damping factor can improve the SCF convergence especially for semi-conductor and insulator systems.
    Default: 0.1

  • number_of_history_steps (int) – The total number of history steps to take into account for the mixing algorithm. Should be positive.
    Default: min(20, max_steps)

  • start_mixing_after_step (int) – The total number of steps to wait before the mixing algorithm is used. Should be non-negative.
    Default: 0

  • mixing_variable (HamiltonianVariable) – The mixing variable used in the SCF loop.
    Default: A default HamiltonianVariable instance

  • preconditioner (Preconditioner.Off | Kerker) – The preconditioner used in the SCF loop. If damping_factor is an instance of AdaptiveDampingFactor, Kerker preconditioner is not supported.
    Default: Preconditioner.Off

  • linear_dependence_threshold (float) – Pulay steps which have a linear dependence lower than the threshold are discarded. Should be non-negative.
    Default: 0.0

  • exx_energy_tolerance (Not used.) –
    Deprecated: from v2019.12, see tolerance.

  • max_exx_updates (int) – The maximum number of updates of the exact exchange operator that will be performed. If this number is reached, the SCF loop will be terminated whether it is converged or not. Should be an integer larger than 0. This parameter is only used in hybrid DFT calculations.
    Default: 50

  • non_convergence_behavior (StopCalculation | ContinueCalculation) – Determines the behavior when the SCF loop does not reach the desired tolerance.
    Default: ContinueCalculation()

  • enable_scf_stop_file (bool) – Determines whether to enable a file for stopping the SCF loop. If True, creation of the stop file will stop the SCF at the next step. The name of the file for this SCF calculation will be shown in the log output. The file must be created in the current working directory.
    Default: True

algorithm()
Returns:

The mixing algorithm stored by the IterationControlParameters object.

Return type:

PulayMixer | AndersonMixer

dampingFactor()
Returns:

The damping factory stored by the IterationControlParameters object.

Return type:

float | AdaptiveDampingFactor

enableScfStopFile()
Returns:

Determines whether to enable a file for stopping the SCF loop.

Return type:

bool

exxEnergyTolerance()


Deprecated: from v2019.12

linearDependenceThreshold()
Returns:

The linear dependence threshold value stored by the IterationControlParameters object.

Return type:

float

maxExxUpdates()
Returns:

The maximum number of exact exchange operator updates.

Return type:

int

maxSteps()
Returns:

The maximum steps value stored by the IterationControlParameters object.

Return type:

int

mixingVariable()
Returns:

The mixing variable stored by the IterationControlParameters object.

Return type:

HamiltonianVariable

nonConvergenceBehavior()
Returns:

Determines the behavior when the SCF loop does not reach the desired tolerance.

Return type:

StopCalculation | ContinueCalculation

numberOfHistorySteps()
Returns:

The number of history steps value stored by the IterationControlParameters object.

Return type:

int

Note

The value returned is bounded above by the maximum number of steps, and below by 1.

preconditioner()
Returns:

The preconditioner stored by the IterationControlParameters object.

Return type:

Preconditioner.Off | Kerker

startMixingAfterStep()
Returns:

The step to start mixing after value stored by the IterationControlParameters object.

Return type:

int

tolerance()
Returns:

The tolerance value stored by the IterationControlParameters object.

Return type:

float

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Setup iteration control parameters for difficult convergence case

iteration_control_parameters = IterationControlParameters(
    damping_factor=0.05,
    number_of_history_steps=12,
    )

calculator = HuckelCalculator(
    iteration_control_parameters=iteration_control_parameters,
    )

Setup iteration control parameters with a preconditioner for a large system that is difficult to converge

iteration_control_parameters = IterationControlParameters(
    damping_factor=0.2,
    preconditioner=Kerker(0.02*Hartree, 0.5*Hartree, 0.01),
    mixing_variable=HamiltonianVariable,
    number_of_history_steps=12,
    )

calculator = LCAOCalculator(
    iteration_control_parameters=iteration_control_parameters,
    )

Notes

Mixing algorithm

The available SCF mixing algorithms are the distributed and non-distributed version of the PulayMixer, and the AndersonMixer. The mixing algorithm can be set using the algorithm argument to IterationControlParameters.

Preconditioner

It is possible to add a preconditioner within the SCF loop. For HamiltonianVariable mixing the preconditioner will damp the variations in the low Fourier components of the Hartree potential. Currently a Kerker style preconditioner is available when PulayMixer is selected as mixing algorithm.

Tolerance and accuracy

A few important notes on the keyword argument tolerance.

  • The tolerance in QuantumATK is not relative, but absolute. For the total energy and the band-structure energy the internal unit is Hartree, thus for these quantities the tolerance gives the accuracy as measured in Hartree. For iteration control of a matrix (e.g., the Hamiltonian or the density matrix) it is maximum value of the difference between the corresponding matrix elements of the old and new matrix. This means that the tolerance should be interpreted as given in Hartree. The tolerance parameter itself should, however, be given without any unit. The tolerance parameter is the maximally tolerated difference between an element of the Hamiltonian in two successive self-consistent iterations.

  • In order to achieve a better accuracy than the one corresponding to the choice of default values, it is often a good idea to decrease the tolerance by one or two orders of magnitude. Often, but not always, this will only add a few extra iterations to the calculation, since the Pulay mixing algorithm usually performs very well once it approaches equilibrium. If only a fast rough estimation of the results is needed the accuracy can be lowered by increasing the tolerance value.