# Self Consistent Field (SCF)¶

The SCF procedure searches for a self-consistent density. The self-consistent error is the square root of the integral of the squared difference between the input and output density of the cycle operator.

\(\text{err}=\sqrt{\int dx \; (\rho_\text{out}(x)-\rho_\text{in}(x))^2 }\)

When the SCF error is below a certain criterion, controlled by subkey `Criterion`

of block key `Convergence`

, convergence is reached. The default criterion depends on the `NumericalQuality`

key.

NumericalQuality |
Convergence%Criterion |
---|---|

Basic |
1e-5 \(\sqrt{N_\text{atoms}}\) |

Normal |
1e-6 \(\sqrt{N_\text{atoms}}\) |

Good |
1e-7 \(\sqrt{N_\text{atoms}}\) |

VeryGood |
1e-8 \(\sqrt{N_\text{atoms}}\) |

The default method is the so-called MultiStepper. The MultiStepper is flexible, but somewhat harder to control by the user.

See also

Troubleshooting: SCF does not converge

## SCF block¶

```
SCF
Eigenstates Yes/No
Iterations integer
Method [DIIS | MultiSecant | MultiStepper]
Mixing float
MultiStepperPresetPath string
PMatrix Yes/No
PrintAllOccupiedBands Yes/No
PrintAllVirtualBands Yes/No
PrintAlwaysBandRanges Yes/No
Rate float
VSplit float
End
```

`SCF`

- Type
Block

- Description
Controls technical SCF parameters.

`Eigenstates`

- Type
Bool

- Description
The program knows two alternative ways to evaluate the charge density iteratively in the SCF procedure: from the P-matrix, and directly from the squared occupied eigenstates. By default the program actually uses both at least one time and tries to take the most efficient. If present, Eigenstates turns off this comparison and lets the program stick to one method (from the eigenstates).

`Iterations`

- Type
Integer

- Default value
300

- GUI name
Maximum number of cycles

- Description
The maximum number of SCF iterations to be performed.

`Method`

- Type
Multiple Choice

- Default value
MultiStepper

- Options
[DIIS, MultiSecant, MultiStepper]

- Description
Choose the general scheme used to converge the density in the SCF. In case of scf problems one can try the MultiSecant alternative at no extra cost per SCF cycle. For more details see the DIIS and MultiSecantConfig block.

`Mixing`

- Type
Float

- Default value
0.075

- Description
Initial ‘damping’ parameter in the SCF procedure, for the iterative update of the potential: new potential = old potential + mix (computed potential-old potential). Note: the program automatically adapts Mixing during the SCF iterations, in an attempt to find the optimal mixing value.

`MultiStepperPresetPath`

- Type
String

- Default value
DFTB/default2023.inc

- Description
Name of file containing a SCFMultiStepper key block. This will be used if no Explicit SCFMultiStepper block is in the input, and Method=MultiStepper. If the path is not absolute, it is relative to $AMSHOME/data/presets/multi_stepper’

`PMatrix`

- Type
Bool

- Description
If present, evaluate the charge density from the P-matrix. See also the key Eigenstates.

`PrintAllOccupiedBands`

- Type
Bool

- Default value
Yes

- Description
When printing the ranges of the bands, include all occupied ones.

`PrintAllVirtualBands`

- Type
Bool

- Default value
No

- Description
When printing the ranges of the bands, include all virtual ones.

`PrintAlwaysBandRanges`

- Type
Bool

- Default value
No

- Description
Normally the ranges of the bands are only printed at the last SCF cycle

`Rate`

- Type
Float

- Default value
0.99

- Description
Minimum rate of convergence for the SCF procedure. If progress is too slow the program will take measures (such as smearing out occupations around the Fermi level, see key Degenerate of block Convergence) or, if everything seems to fail, it will stop

`VSplit`

- Type
Float

- Default value
0.05

- Description
To disturb degeneracy of alpha and beta spin MOs the value of this key is added to the beta spin potential at the startup.

## Convergence¶

All options and parameters related to the convergence behavior of the SCF procedure are defined in the `Convergence`

block key. Also the finite temperature distribution is part of this

```
Convergence
Criterion float
CriterionFactor float
Degenerate string
ElectronicTemperature float
InitialDensity [rho | psi | frompot]
LessDegenerate Yes/No
ModestCriterion float
NoDegenerate Yes/No
NumBoltz integer
SpinFlip integer_list
SpinFlipEnabled Yes/No
SpinFlipRegion string
StartWithMaxSpin Yes/No
StartWithMaxSpinForSO Yes/No
End
```

`Convergence`

- Type
Block

- Description
Options and parameters related to the convergence behavior of the SCF procedure.

`Criterion`

- Type
Float

- Description
Criterion for termination of the SCF procedure. The default depends on the NumericalQuality and on the number of atoms in the system. Can be used for EngineAutomations

`CriterionFactor`

- Type
Float

- Default value
1.0

- Description
Multiply Criterion (which depends on system and quality) with this factor. Can be used for EngineAutomations

`Degenerate`

- Type
String

- Default value
default

- Description
Smooths (slightly) occupation numbers around the Fermi level, so as to insure that nearly-degenerate states get (nearly-) identical occupations. Be aware: In case of problematic SCF convergence the program will turn this key on automatically, unless the key ‘Nodegenerate’ is set in input. The smoothing depends on the argument to this key, which can be considered a ‘degeneration width’. When the argument reads default, the program will use the value 1e-4 a.u. for the energy width.

`ElectronicTemperature`

- Type
Float

- Default value
0.0

- Unit
Hartree

- Description
(KT) Specify this key for a gradient independent electronic temperature

`InitialDensity`

- Type
Multiple Choice

- Default value
rho

- Options
[rho, psi, frompot]

- Description
The SCF is started with a guess of the density. There are the following choices RHO: the sum of atomic density. PSI: construct an initial eigensystem by occupying the atomic orbitals. The guessed eigensystem is orthonormalized, and from this the density is calculated/

`LessDegenerate`

- Type
Bool

- Default value
No

- Description
If smoothing of occupations over nearly degenerate orbitals is applied (see Degenerate key), then, if this key is set in the input file, the program will limit the smoothing energy range to 1e-4 a.u. as soon as the SCF has converged ‘halfway’, i.e. when the SCF error has decreased to the square root of its convergence criterion.

`ModestCriterion`

- Type
Float

- Default value
-1.0

- Description
If this is specified band will consider the SCF converged if the error is below this criterion (after using the maximum number of iterations).

`NoDegenerate`

- Type
Bool

- Default value
No

- Description
This key prevents any internal automatic setting of the key DEGENERATE.

`NumBoltz`

- Type
Integer

- Default value
10

- Description
The electronic temperature is done with a Riemann Stieltjes numerical integration, between zero and one occupation. This defines the number of points to be used.

`SpinFlip`

- Type
Integer List

- GUI name
Flip spin for atoms

- Description
List here the atoms for which you want the initial spin polarization to be flipped. This way you can distinguish between ferromagnetic and anti ferromagnetic states. Currently, it is not allowed to give symmetry equivalent atoms a different spin orientation. To achieve that you have to break the symmetry.

`SpinFlipEnabled`

- Type
Bool

- Default value
Yes

- Description
If set to False, the keys SpinFlip and SpinFlipRegion are ignored. Only useful/convenient when trying to compare in a script the effect of spin flip.

`SpinFlipRegion`

- Type
String

- Recurring
True

- GUI name
Flip spin for region

- Description
Specify here the region for which you want the initial spin polarization to be flipped. This way you can distinguish between ferromagnetic and anti ferromagnetic states. Currently, it is not allowed to give symmetry equivalent atoms a different spin orientation. To achieve that you have to break the symmetry.

`StartWithMaxSpin`

- Type
Bool

- Default value
Yes

- Description
To break the initial perfect symmetry of up and down densities there are two strategies. One is to occupy the numerical orbitals in a maximum spin configuration. The alternative is to add a constant to the potential. See also Vsplit key.

`StartWithMaxSpinForSO`

- Type
Bool

- Default value
No

- Description
Same as the StartWithMaxSpin option. In case of spin-orbit band always used to split the potential. Now will use maxspin in case of SpinFlip. With this option it will always do that.

## DIIS¶

The DIIS procedure to obtain the SCF solution depends on several parameters. Default values can be overruled with this block.

```
DIIS
Adaptable Yes/No
CHuge float
CLarge float
Condition float
DiMix float
DiMixMax float
DiMixMin float
NCycleDamp integer
NVctrx integer
Variant [DIIS | LISTi | LISTb | LISTd]
End
```

`DIIS`

- Type
Block

- Description
Parameters for the DIIS procedure to obtain the SCF solution

`Adaptable`

- Type
Bool

- Default value
Yes

- Description
Change automatically the value of dimix during the SCF.

`CHuge`

- Type
Float

- Default value
20.0

- GUI name
No DIIS (but damping) when coefs >

- Description
When the largest coefficient in the DIIS expansion exceeds this value, damping is applied

`CLarge`

- Type
Float

- Default value
20.0

- GUI name
Reduce DIIS space when coefs >

- Description
When the largest DIIS coefficient exceeds this value, the oldest DIIS vector is removed and the procedure re-applied

`Condition`

- Type
Float

- Default value
1000000.0

- Description
The condition number of the DIIS matrix, the largest eigenvalue divided by the smallest, must not exceed this value. If this value is exceeded, this vector will be removed.

`DiMix`

- Type
Float

- Default value
0.2

- GUI name
Bias DIIS towards latest vector with

- Description
Mixing parameter for the DIIS procedure

`DiMixMax`

- Type
Float

- Default value
-1.0

- Description
For adaptive diis: A negative value means automatic, see DiMixatnvctrx. If positive it is an absolute upper bound for (adaptive) dimix

`DiMixMin`

- Type
Float

- Default value
0.01

- Description
An absolute lower bound for adaptive dimix.

`NCycleDamp`

- Type
Integer

- Default value
1

- GUI name
Do not start DIIS before cycle

- Description
Number of initial iterations where damping is applied, before any DIIS is considered

`NVctrx`

- Type
Integer

- Default value
20

- GUI name
Size of DIIS space

- Description
Maximum number of DIIS expansion vectors

`Variant`

- Type
Multiple Choice

- Default value
DIIS

- Options
[DIIS, LISTi, LISTb, LISTd]

- Description
Which variant to use. In case of problematic SCF convergence, first try MultiSecant, and if that does not work the LISTi is the advised method. Note: LIST is computationally more expensive per SCF iteration than DIIS.

## Multisecant¶

For more detais on the multisecant method see ref 1.

```
MultiSecantConfig
CMax float
InitialSigmaN float
MaxSigmaN float
MaxVectors integer
MinSigmaN float
End
```

`MultiSecantConfig`

- Type
Block

- Description
Parameters for the Multi-secant SCF convergence method.

`CMax`

- Type
Float

- Default value
20.0

- GUI name
Max coeff

- Description
Maximum coefficient allowed in expansion

`InitialSigmaN`

- Type
Float

- Default value
0.1

- GUI name
Initial

- Description
This is a lot like a mix factor: bigger means bolder

`MaxSigmaN`

- Type
Float

- Default value
0.3

- GUI name
Max

- Description
Upper bound for the SigmaN parameter

`MaxVectors`

- Type
Integer

- Default value
20

- GUI name
Number of cycles to use

- Description
Maximum number of previous cycles to be used

`MinSigmaN`

- Type
Float

- Default value
0.01

- GUI name
Min

- Description
Lower bound for the SigmaN parameter

## MultiStepper¶

The MultiStepper introduces the concept of alternating between different steppers (methods). Methods are not switched at every SCF cycle, but rather after a sequence of them, called a stint. At the end of a stint it is considered whether it makes sense to try another stepper.

The key component is the Stepper. This wraps the type of the Stepper, say DIIS or SimpleMixing. Another important component is the MixAdapter. A step is controlled by a mix factor \(\sigma\), also often called greed. The next guess density is a linear combination of previous input and output densities

\(\rho^\text{guess}=\sum_i c_{i-1}^N (\rho^\text{in}_i + \sigma(\rho^\text{out}_i-\rho^\text{in}_i))\)

The larger the mix factor the more aggressive the algorithm. Choosing it too small may simply stall the progress and choosing it too large can cause the error to grow. That is why using a MixAdapter is useful. It tries to predict a reasonable mix value, based on the progress of the error and also based on the number of previous iterations \(N\) that can be used without running into numerical problems.

A whole SCFMultiStepper block can be loaded from a file as a preset, and many reside in `$AMSHOME/data/presets/multi_stepper`

. Normal users are not recommended to try to improve the standard preset. Which preset to loaded is controlled by the `SCF%MultiStepperPresetPath`

key, and this may be an absolute path to your own preset.

The the log file (ams.log) shows the active stepper and mix factor.

```
<Nov22-2022> <15:24:28> cyc= 0 err=0.00E+00 cpu= 75s ela= 76s
<Nov22-2022> <15:25:26> cyc= 1 err=4.26E+00 meth=1 nvec= 1 mix=0.0750 cpu= 57s ela= 58s fit=7.06E-02
<Nov22-2022> <15:26:26> cyc= 2 err=8.33E+00 meth=1 nvec= 2 mix=0.1455 cpu= 59s ela= 60s fit=6.49E-02
<Nov22-2022> <15:27:23> cyc= 3 err=7.85E+00 meth=1 nvec= 3 mix=0.1499 cpu= 56s ela= 57s fit=6.42E-02
<Nov22-2022> <15:28:24> cyc= 4 err=7.09E+00 meth=1 nvec= 4 mix=0.1544 cpu= 60s ela= 61s fit=6.37E-02
<Nov22-2022> <15:29:21> cyc= 5 err=9.49E+00 meth=2 nvec= 1 mix=0.0060 cpu= 57s ela= 57s fit=7.91E-02
<Nov22-2022> <15:30:20> cyc= 6 err=2.63E+00 meth=2 nvec= 2 mix=0.0062 cpu= 59s ela= 59s fit=7.88E-02
<Nov22-2022> <15:31:18> cyc= 7 err=3.82E+00 meth=2 nvec= 3 mix=0.0060 cpu= 57s ela= 58s fit=7.84E-02
<Nov22-2022> <15:32:16> cyc= 8 err=3.53E+00 meth=2 nvec= 4 mix=0.0062 cpu= 58s ela= 58s fit=7.81E-02
```

From cycle 5 (cyc=5) on the second stepper is tried (meth=2), in this case because the error has grown too much since the start. Furthermore it restarts from the first density, not shown in the log file, using only one older density (nvec=1). Note that the second stepper starts with using a much more conservative mix factor (mix=0.006).

```
SCF
SCFMultiStepper
AlwaysChangeStepper Yes/No
ErrorGrowthAbortFactor float
FractionalStepFactor float
MinStintCyclesForAbort integer
Stepper header
AbortSlope float
DIISStepper
EDIISAlpha float
MaxCoefficient float
MaxVectors integer
MinVectors integer
Mix float
End
ErrorGrowthAbortFactor float
ExpectedSlope float
FractionalStepFactor float
MaxInitialError float
MaxIterationNumber integer
MaxStintNumber integer
MinInitialError float
MinIterationNumber integer
MinStintCyclesForAbort integer
MinStintNumber integer
MixAdapter
ErrorGrowthPanicFactor float
GrowthFactor float
MaxMix float
MinMix float
NTrialMixFactors integer
TrialMode [CurrentMixCentered | FullRange]
Type [Error | Energy | UnpredictedStep | Trial]
End
MixStepper
Mix float
End
MultiSecantStepper
MaxCoefficient float
MaxVectors integer
Mix float
Variant [MSB1 | MSB2 | MSR1 | MSR1s]
End
StintLength integer
End
StintLength integer
UsePreviousStintForErrorGrowthAbort Yes/No
End
End
```

`SCF`

`SCFMultiStepper`

- Type
Block

- Description
To solve the self-consistent problem multiple steppers can be tried during stints using the ones that give the best progress.

`AlwaysChangeStepper`

- Type
Bool

- Default value
No

- Description
When the progress is fine there is no reason to change the stepper. In practice this is always set to true, because also the Stepper%ExpectedSlope can be used to achieve similar behavior.

`ErrorGrowthAbortFactor`

- Type
Float

- Default value
1000.0

- Description
Abort stint when the error grows too much, compared to the error at the start of the stint.

`FractionalStepFactor`

- Type
Float

- Default value
-1.0

- Description
Multiply the step by this factor. If smaller than zero this is not used.

`MinStintCyclesForAbort`

- Type
Integer

- Default value
0

- Description
Look at ErrorGrowthAbortFactor only when a number of steps has been completed since the start of the stint. A value of 0 means always.

`Stepper`

- Type
Block

- Recurring
True

- Description
??

`AbortSlope`

- Type
Float

- Default value
100.0

- Description
If the slope (at the end of a stint) is larger than this: abort the stepper

`DIISStepper`

- Type
Block

- Description
DIIS stepper

`EDIISAlpha`

- Type
Float

- Default value
0.01

- Description
The extra energy vector is weighed by this factor. .

`MaxCoefficient`

- Type
Float

- Default value
20.0

- Description
The largest allowed value of the expansion coefficients. If exceed the number of vectors is reduces until the criterion is met.

`MaxVectors`

- Type
Integer

- Default value
10

- Description
Maximum number of previous densities to be used (size of the history).

`MinVectors`

- Type
Integer

- Default value
-1

- Description
Try to prevent to make nVectors shrink below this value, by allowing for significantly larger coefficients.

`Mix`

- Type
Float

- Default value
0.2

- Description
Also known as greed. It determines the amount of output density to be used. May be changed by the MixAdapter.

`ErrorGrowthAbortFactor`

- Type
Float

- Default value
-1.0

- Description
Abort stint when the error grows too much, compared to the error at the start of the stint. Overrides global ErrorGrowthAbortFactor when set to a value > 0

`ExpectedSlope`

- Type
Float

- Default value
-100.0

- Description
If the slope of the total SCF is better than this keep on going.

`FractionalStepFactor`

- Type
Float

- Default value
-1.0

- Description
Multiply the step by this factor. If smaller than zero this is not used.

`MaxInitialError`

- Type
Float

- Description
Only use the stepper when error is smaller than this.

`MaxIterationNumber`

- Type
Integer

- Default value
-1

- Description
Stepper will only be active for iterations smaller than this number. (Negative value means: Ignore this option)

`MaxStintNumber`

- Type
Integer

- Default value
-1

- Description
Stepper will only be active for stints smaller than this number. (Negative value means: Ignore this option)

`MinInitialError`

- Type
Float

- Description
Only use the stepper when error is larger than this.

`MinIterationNumber`

- Type
Integer

- Default value
-1

- Description
Stepper will only be active for iterations larger than this number.

`MinStintCyclesForAbort`

- Type
Integer

- Default value
0

- Description
Look at ErrorGrowthAbortFactor only when a number of steps has been completed since the start of the stint. A value of 0 means always. Overrides global value.

`MinStintNumber`

- Type
Integer

- Default value
-1

- Description
Stepper will only be active for stints larger than this number.

`MixAdapter`

- Type
Block

- Description
Generic mix adapter

`ErrorGrowthPanicFactor`

- Type
Float

- Default value
10.0

- Description
When the error increases more than this factor, this mix is reduced a lot.

`GrowthFactor`

- Type
Float

- Default value
1.1

- Description
When the mix is considered too low it is multiplied by this factor. Otherwise it is divided by it.

`MaxMix`

- Type
Float

- Default value
0.3

- Description
Do not grow the mix above this value.

`MinMix`

- Type
Float

- Default value
0.1

- Description
Do not shrink the mix below this value.

`NTrialMixFactors`

- Type
Integer

- Default value
3

- Description
Only used with Type=Trial. Must be an odd number.

`TrialMode`

- Type
Multiple Choice

- Default value
CurrentMixCentered

- Options
[CurrentMixCentered, FullRange]

- Description
How are the NTrialMixFactors chosen?

`Type`

- Type
Multiple Choice

- Default value
Error

- Options
[Error, Energy, UnpredictedStep, Trial]

- Description
Adapt the mix factor based on the observed progress (slope).

`MixStepper`

- Type
Block

- Description
Simple mixing stepper, only using the previous (in/out) density.

`Mix`

- Type
Float

- Default value
0.1

- Description
???.

`MultiSecantStepper`

- Type
Block

- Description
Multi secant stepper.

`MaxCoefficient`

- Type
Float

- Default value
20.0

- Description
???.

`MaxVectors`

- Type
Integer

- Default value
10

- Description
???.

`Mix`

- Type
Float

- Default value
0.2

- Description
???.

`Variant`

- Type
Multiple Choice

- Default value
MSB2

- Options
[MSB1, MSB2, MSR1, MSR1s]

- Description
There are several version of the Multi secant method.

`StintLength`

- Type
Integer

- Description
Override global StintLength.

`StintLength`

- Type
Integer

- Default value
10

- Description
A stepper is active during a number of SCF cycles, called a stint.

`UsePreviousStintForErrorGrowthAbort`

- Type
Bool

- Default value
No

- Description
The error is normally checked against the first error of the stint. With this option that will be the one from the previous stint, if performed with the same stepper.

## DIRIS¶

In the DIRIS block, which has the same options as the `DIIS`

block, you can specify the DIIS options to be used in the Dirac subprogram, for numerical single atom calculations, which constructs the radial tables for the NAOs.

- 1
L. D. Marks and D. R. Luke,

*Robust mixing for ab initio quantum mechanical calculations*, Phys. Rev. B 78, 075114 (2008)