# 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)

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, see also the exx_energy_tolerance parameter. 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) – 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. 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. 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 (PhysicalQuantity of type energy.) – The accuracy of the exact exchange (EXX) energy, which the outer SCF loop must reach before termination. This parameter is only used in hybrid DFT calculations. For best convergence, the tolerance on the DFT SCF loop should be smaller than this tolerance. If there is trouble converging the exact exchange energy, try reducing the tolerance parameter. Default: A value 10 times larger than the energy tolerance of the inner SCF loop. If this parameter is set but tolerance is left s default, the value of tolerance will be set to be 0.1 times the value of this parameter, thus it is often enough to only set the exx_energy_tolerance for hybrid calculations. 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. non_convergence_behavior (StopCalculation | ContinueCalculation) – Determines the behavior when the SCF loop does not reach the desired tolerance. Default: ContinueCalculation()
algorithm()
Returns: The mixing algorithm stored by the IterationControlParameters object. PulayMixer | AndersonMixer
dampingFactor()
Returns: The damping factory stored by the IterationControlParameters object. float
exxEnergyTolerance()
Returns: The SCF tolerance on the exact exchange energy. PhysicalQuantity of type energy
linearDependenceThreshold()
Returns: The linear dependence threshold value stored by the IterationControlParameters object. float
maxExxUpdates()
Returns: The maximum number of exact exchange operator updates. int
maxSteps()
Returns: The maximum steps value stored by the IterationControlParameters object. int
mixingVariable()
Returns: The mixing variable stored by the IterationControlParameters object. HamiltonianVariable
nonConvergenceBehavior()
Returns: Determines the behavior when the SCF loop does not reach the desired tolerance. StopCalculation | ContinueCalculation
numberOfHistorySteps()
Returns: The number of history steps value stored by the IterationControlParameters object. 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. Preconditioner.Off | Kerker
startMixingAfterStep()
Returns: The step to start mixing after value stored by the IterationControlParameters object. int
tolerance()
Returns: The tolerance value stored by the IterationControlParameters object. float

## 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.