IterationControlParameters

	IterationControlParameters
InitialSpin	NormConservingPseudoPotential

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:

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:

start_mixing_after_step

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

Type: int >= 0

Default:

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:

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

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.


InitialSpin		NormConservingPseudoPotential