Name

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

Synopsis

Namespace: NanoLanguage
IterationControlParameters(
tolerance,
max_steps,
algorithm,
damping_factor,
number_of_history_steps,
start_mixing_after_step,
mixing_variable,
preconditioner,
linear_dependence_threshold
)

Description

IterationControlParameters Arguments

tolerance

The accuracy which the SCF loop must reach before termination.

Type: float > 0.0

Default: 4.0e-5
max_steps

The maximum number of iteration steps the SCF loop should execute.

Type: int >= 0

Default: 100
algorithm

The mixing strategy employed on the mixing variable in the SCF loop.

Type: PulayMixer

Default: PulayMixer
damping_factor

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
number_of_history_steps

The total number of history steps to take into account for the mixing algorithm.

Type: int > 0

Default: 20
start_mixing_after_step

The total number of steps to wait before the mixing algorithm is used.

Type: int >= 0

Default: 0
mixing_variable

The mixing variable used in the SCF loop.

Type: HamiltonianVariable

Default: HamiltonianVariable
preconditioner

The preconditioner used in the SCF loop

Type: Preconditioner.Off | Kerker()

Default: Preconditioner.Off
linear_dependence_threshold

Pulay steps which have a linear dependence lower than the threshold are discarded.

Type: float >= 0.0

Default: 0.0

IterationControlParameters Methods

A IterationControlParameters object provides the following methods:

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

Currently the only SCF mixing algorithm is a PulayMixer . The Pulay Mixer implements the Pulay-Kerker method

\displaystyle

    h_{n+1}^\mathrm{in} = \eta \sum_{i=n-n^\mathrm{hist}}^{n} \alpha_i h_i^\mathrm{out} + (1-\eta) \sum_{i=1}^{n-n^\mathrm{hist}} \alpha_i h_i^\mathrm{in}

where  h_i^\mathrm{in} is the input value and  h_i^\mathrm{out}
    is the output value of the mixing_variable at iteration i. Currently there is support for using HamiltonianVariable for mixing. The parameter \eta is the damping_factor and n^\mathrm{hist} the number_of_history_steps used for finding the input value for the next iteration. The variables  \alpha_i are obtained by minimizing the Residual error of the mixing_variable assuming a linear relation between the residual errors of different iteration numbers.

  • A few notes on the variable tolerance are listed in the following.

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

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.