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
- 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
- algorithm (
AndersonMixer) – The mixing strategy employed on the mixing variable in the SCF loop. Default: A default
- 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.
- number_of_history_steps (int) – The total number of history steps to take into account for the mixing algorithm. Should
- start_mixing_after_step (int) – The total number of steps to wait before the mixing algorithm is used. Should be
- mixing_variable (
HamiltonianVariable) – The mixing variable used in the SCF loop. Default: A default
- preconditioner (
Kerker) – The preconditioner used in the SCF loop. Default:
- linear_dependence_threshold (float) – Pulay steps which have a linear dependence lower than the threshold are discarded.
Should be non-negative.
- 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 (
ContinueCalculation) – Determines the behavior when the SCF loop does not reach the desired tolerance. Default:
Returns: The mixing algorithm stored by the
Returns: The damping factory stored by the
Return type: float
Returns: The SCF tolerance on the exact exchange energy. Return type: PhysicalQuantity of type energy
Returns: The linear dependence threshold value stored by the
Return type: float
Returns: The maximum number of exact exchange operator updates. Return type: int
Returns: The maximum steps value stored by the
Return type: int
Returns: The mixing variable stored by the
Returns: Determines the behavior when the SCF loop does not reach the desired tolerance. Return type:
Returns: The number of history steps value stored by the
Return type: int
The value returned is bounded above by the maximum number of steps, and below by 1.
Returns: The preconditioner stored by the
Returns: The step to start mixing after value stored by the
Return type: int
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, )
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
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
tolerancein 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
toleranceparameter itself should, however, be given without any unit. The
toleranceparameter is the maximally tolerated difference between an element of the Hamiltonian in two successive self-consistent iterations.
- In order to achieve a better
accuracythan 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.