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.


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.

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)
