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.

Table 7 The default `Convergence%Criterion` depends on the `NumericalQuality` and on the number of atoms in the unit cell.¶
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.

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: No
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 coefficents.

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. Overides 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. Overides 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) denstity.

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)

Electronic Structure

ADF

Periodic DFT

DFTB & MOPAC

Interatomic Potentials

ReaxFF

Machine Learning Potentials

Force Fields

kMC and Microkinetics

Bumblebee: OLED stacks

Fluid Thermodynamics

COSMO-RS

Workflows and Utilities

OLED workflows

ChemTraYzer2

Conformers

Reactions Discovery

AMS Driver

Properties

PES Exploration

Molecular Dynamics

Monte Carlo

Interfaces

ParAMS

PLAMS

GUI

VASP

Downloads

Windows

Mac

Linux

Documentation

Overview

Tutorials

Installation Manual

Brochures

Other Resources

Changelog

Workshops

Knowledgebank

FAQ

Pricing and licensing

Self Consistent Field (SCF)¶

SCF block¶

Convergence¶

DIIS¶

Multisecant¶

MultiStepper¶

DIRIS¶