IterationControlParameters — Class for representing the parameters relevant for SCF iteration control within self-consistent electronic structure models.
The accuracy which the SCF loop must reach before termination.
Type: float > 0.0
Default:
4.0e-5
The maximum number of iteration steps the SCF loop should execute.
Type: int >= 0
Default:
100
The mixing strategy employed on the mixing variable in the SCF loop.
Type: PulayMixer | ParallelPulayMixer
Default:
PulayMixer
The fraction of the output value of the mixing parameter which is mixed into the next step.
Type: float in (0,1]
Default:
0.1
The total number of history steps to take into account for the mixing algorithm.
Type: int > 0
Default:
min(20, max_steps)
The total number of steps to wait before the mixing algorithm is used.
Type: int >= 0
Default:
0
The mixing variable used in the SCF loop.
Type: HamiltonianVariable
Default:
HamiltonianVariable
The preconditioner used in the SCF loop.
Type: Preconditioner.Off | Kerker()
Default:
Preconditioner.Off
Pulay steps which have a linear dependence lower than the threshold are discarded.
Type: float >= 0.0
Default:
0.0
A IterationControlParameters object provides the following methods:
This object supports cloning. See the section called “Cloning of ATK Python objects”.
algorithm
()
: Return the mixing algorithm stored by the IterationControlParameters object.
dampingFactor
()
: Return the damping factory stored by the IterationControlParameters object.
linearDependenceThreshold
()
: Return the linear dependence threshold value stored by the IterationControlParameters object.
maxSteps
()
: Return the maximum steps value stored by the IterationControlParameters object.
mixingVariable
()
: Return the mixing variable stored by the IterationControlParameters object.
numberOfHistorySteps
()
: Return the number of history steps value stored by the IterationControlParameters object.
Note that the value returned is bounded by the maximum number of steps.
preconditioner
()
: Return the preconditioner stored by the IterationControlParameters object.
startMixingAfterStep
()
: Return the step to start mixing after value stored by the IterationControlParameters object.
tolerance
()
: Return the tolerance value stored by the IterationControlParameters object.
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 PulayMixer and ParallelPulayMixer.
The mixing algorithm can be set using the algorithm
argument to IterationControlParameters.
The Pulay mixers implement the Pulay-Kerker method[9]
where is the input value and is the output value of the mixing_variable
at iteration
. Currently there is support for using HamiltonianVariable
for mixing.
The parameter is the
damping_factor
and the
number_of_history_steps
used for finding the input value for the
next iteration. The variables are obtained by minimizing the
residual error of the mixing_variable
assuming a linear relation
between the residual errors of different iteration numbers.
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.
A few important notes on the keyword argument tolerance
.
The tolerance
in ATK 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.