Model Hamiltonians
******************

As of the 2020 release, the DFTB engine supports two different classes
of model Hamiltonians, Grimme's extended tight-binding, and the
classic Slater-Koster based DFTB. All of these model Hamiltonians are
obtained by applying tight-binding approximations to the DFT total
energy expression.


Slater-Koster based DFTB
========================

The efficiency of Slater-Koster based DFTB stems from its use of an
optimized minimum valence orbital basis that reduces the linear
algebra operations, and a two-center approximation for the Kohn-Sham
potential that allows pre-calculation and storage of integrals using
the Slater-Koster technique. This makes DFTB orders of magnitude
faster than DFT, but requires parameter files (containing the
integrals) for all pair-wise combinations of atoms in a molecule. Many
elements can be handled with the parameter sets included in the
distribution. Alternatively, sets of parameters in the SKF format can
be downloaded and used from third-party sources.

There are three flavors of Slater-Koster based DFTB available in our
implementation:

* The "plain" DFTB Hamiltonian as introduced by Porezag and Seifert
  without a self-consistency cycle.

* The second order self-consistent charge extension SCC-DFTB (also
  called DFTB2), which accounts for density fluctuations and improves
  results on polar bonds. Note that the self-consistent calculations
  are about an order of magnitude slower than calculations with the
  "plain" DFTB Hamiltonian.

* The third order extension known as DFTB3, which improves the
  description of hydrogen-bonded complexes and proton affinities. Note
  that DFTB3 calculations are only marginally slower than SCC-DFTB
  based calculations.

Note that since these methods have been respectively parametrized, it
is important to specify a matching parameter set when applying one of
these models.


Extended tight-binding (xTB)
============================

The extended tight-binding (xTB) model Hamiltonian was introduced by
Grimme and coworkers. It makes similar approximations as Slater-Koster
based DFTB, but instead of using precalculated integrals, xTB employs
a (small) basis of Slater-type orbitals and uses an extended Hückel-
like approximation for the Hamiltonian.

The DFTB engine supports the GFN1-xTB parameterization of xTB, which
is optimized for geometries, frequencies, and non-covalent
interactions and covers all elements of the periodic table up to
radon.


Model Hamiltonian
=================

The following keys allow you to select a model Hamiltonian and control
different aspects of how the stationary Schrodinger equation is
solved.

   Model [DFTB | SCC-DFTB | DFTB3 | GFN1-xTB | NonSCC-GFN1-xTB]

"Model"
   Type:
      Multiple Choice

   Default value:
      GFN1-xTB

   Options:
      [DFTB, SCC-DFTB, DFTB3, GFN1-xTB, NonSCC-GFN1-xTB]

   Description:
      Selects the Hamiltonian used in the DFTB calculation:
      - DFTB/DFTB0/DFTB1 for classic DFTB without a self-consistent
      charge cycle                   - SCC-DFTB/DFTB2 with a self-
      consistency loop for the Mulliken charges                   -
      DFTB3 for additional third-order contributions.
      - GFN1-xTB for Grimme's extended tight-binding model in the GFN1
      version.                   - NonSCC-GFN1-xTB for a less accurate
      but faster version of GFN1-xTB without a self-consistency cycle
      The choice has to be supported by the selected parameter set.

Different parameters may be suitable for different model Hamiltonians.
It is important to choose the appropriate parameter set for the type
of calculation and molecular system under study, see parameter sets.

   ResourcesDir string

"ResourcesDir"
   Type:
      String

   Description:
      The directory containing the parameter files. The path can be
      absolute or relative. Relative paths starting with ./ are
      considered relative to the directory in which the calculation is
      started, otherwise they are considered relative to
      $AMSRESOURCES/DFTB. This key is required for the Slater-Koster
      based DFTB models, but optional for xTB.

**Examples:**

"ResourcesDir Dresden"
   Uses the resource directory $AMSRESOURCES/DFTB/Dresden.

"ResourcesDir /home/myusername/myparamsdir"
   Uses the specified path /home/myusername/myparamsdir as the
   resource directory.

**NOTE:** Each resource directory must contain a file called
*metainfo.yaml*, which specifies the capabilities of the parameter
set. For details see metainfo.yaml.


Dispersion correction
=====================

The selected model Hamiltonian can be extended with dispersion
correction:

   DispersionCorrection [None | Auto | UFF | ULG | D2 | D3-BJ | D4]

"DispersionCorrection"
   Type:
      Multiple Choice

   Default value:
      None

   Options:
      [None, Auto, UFF, ULG, D2, D3-BJ, D4]

   GUI name:
      Dispersion

   Description:
      This key is used to specify an empirical dispersion model.
      Please refer to the DFTB documentation for details on the
      different methods.                   By default no dispersion
      correction will be applied. Setting this to auto applies the
      dispersion correction recommended in the DFTB parameter set's
      metainfo file. Note that the D3-BJ dispersion correction is
      enabled by default when using the GFN1-xTB model Hamiltonian,
      but can be disabled manually by setting this keyword to None.

The newest and most accurate dispersion correction is D4. We recommend
both the D3-BJ and D4 dispersion corrections as good defaults,
depending on their availability for the specific combination of the
model Hamiltonian and parameterization. Note that the D4 dispersion
correction is computationally more expensive than D3-BJ for bulk
periodic systems (it scales as O(N^3) with the number of atoms and is
not parallelized), so you may first want to evaluate whether the
increased accuracy justifies the increased computational cost.


Solvation (GBSA)
================

Solvation effects can be included via the implicit GBSA solvation
model. We gratefully acknowledge Grimme's group in Bonn for their
contribution of the GBSA solvation method code.

To enable the GBSA method, specify the desired solvent:

   Solvation
      Solvent [None | Acetone | Acetonitrile | CHCl3 | CS2 | DMSO | Ether | H2O | Methanol | 
               THF | Toluene]
   End

"Solvation"
   Type:
      Block

   Description:
      Generalized Born solvation model with Solvent Accessible Surface
      Area (GBSA).

   "Solvent"
      Type:
         Multiple Choice

      Default value:
         None

      Options:
         [None, Acetone, Acetonitrile, CHCl3, CS2, DMSO, Ether, H2O,
         Methanol, THF, Toluene]

      Description:
         Solvent used in the GBSA implicit solvation model.

More options can be specified in the "Solvation" block:

   Solvation
      UseGSASA Yes/No
      GSolvState [Gas1BarSolvent | Gas1MSolvent1M | Gas1BarSolvent1M]
      Temperature float
      SurfaceGrid [230 | 974 | 2030 | 5810]
   End

"Solvation"
   "UseGSASA"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Solvation Free Energy

      Description:
         Include shift term and G(SASA) terms in the energy and
         gradient.

   "GSolvState"
      Type:
         Multiple Choice

      Default value:
         Gas1MSolvent1M

      Options:
         [Gas1BarSolvent, Gas1MSolvent1M, Gas1BarSolvent1M]

      Description:
         Reference state for solvation free energy shift.

   "Temperature"
      Type:
         Float

      Default value:
         298.15

      Unit:
         Kelvin

      Description:
         The temperature used when calculating the solvation free
         energy shift. Only used for 'Gas1BarSolvent' and
         'Gas1BarSolvent1M' GSolvState options.

   "SurfaceGrid"
      Type:
         Multiple Choice

      Default value:
         230

      Options:
         [230, 974, 2030, 5810]

      Description:
         Number of angular grid points for the construction of the
         solvent accessible surface area. Usually the default number
         of grid point suffices, but in case of suspicious behaviors
         you can increase the number of points.


QM/FQ Embedding
===============

Environmental effects can be included in the calculation by means of
the Fluctuating Charge (FQ) model. The theory behind the model is
presented in the corresponding ADF manual page . The method can be
used for both ground-state and TD-DFTB calculations, as well as in
ground-state geometry optimizations.

To enable the FQ model one must include the QMFQ block keyword
containing the method options, parameters, and coordinates of the
environment atoms. More details on the input structure can also be
found in the ADF manual page .

   QMFQ
      AtomType
         Alpha float
         Area float
         Charge float
         Chi float
         Dfermi float
         Efermi float
         Eta float
         R0 float
         Sfermi float
         Sigma0 float
         Symbol string
         Tau float
         wFQFMuFile string
      End
      Coords # Non-standard block. See details.
         ...
      End
      FDERESP Yes/No
      Forcefield [FQ | FQFMU | wFQ | wFQ_RQ | wFQFmu | wFQFmu_RQRMU]
      Frozen Yes/No
      Kernel [OHNO | COUL | GAUS]
      LifeFrequency float
      LifeState integer
      MolCharge float
      NonEle [LJ | None]
      QMSCREEN [ERF | EXP | GAUS | NONE]
      QMSCREENFACTOR float
      ReadDynamicMatrix string
   End

"QMFQ"
   Type:
      Block

   Description:
      Block input key for QM/(w)FQ(FMu).

   "AtomType"
      Type:
         Block

      Recurring:
         True

      Description:
         Definition of atomic types in MM environment

      "Alpha"
         Type:
            Float

         Description:
            Polarizability of FQFMU atom

      "Area"
         Type:
            Float

         Description:
            Effective charge-transfer area time between same-type wFQ
            atoms

      "Charge"
         Type:
            Float

         Description:
            MM fixed charge (non-polarizable only)

      "Chi"
         Type:
            Float

         Description:
            Electronegativity of FQ atom

      "Dfermi"
         Type:
            Float

         Description:
            wFQ d parameter for Fermi damping

      "Efermi"
         Type:
            Float

         Description:
            Fermi Energy of wFQ carbon-based structure

      "Eta"
         Type:
            Float

         Description:
            Chemical Hardness of FQ atom

      "R0"
         Type:
            Float

         Description:
            wFQ R0 parameter for Fermi damping

      "Sfermi"
         Type:
            Float

         Description:
            wFQ s parameter for Fermi damping

      "Sigma0"
         Type:
            Float

         Description:
            Static conductivity time of wFQ atom

      "Symbol"
         Type:
            String

         Description:
            Symbol associated with atom type

      "Tau"
         Type:
            Float

         Description:
            Scattering time of wFQ atom

      "wFQFMuFile"
         Type:
            String

         Description:
            The absolute path to the wFQFMu interband polarizability
            file

   "Coords"
      Type:
         Non-standard block

      Description:
         Coordinates and fragment information (FQ only)

   "FDERESP"
      Type:
         Bool

      Default value:
         No

      Description:
         In response calculations (TD), the polarization contribution
         of the FDE part is introduced at the FQ level [See F. Egidi
         et al. J. Chem. Phys. 2021, 154, 164107].

   "Forcefield"
      Type:
         Multiple Choice

      Default value:
         FQ

      Options:
         [FQ, FQFMU, wFQ, wFQ_RQ, wFQFmu, wFQFmu_RQRMU]

      Description:
         Version of the FQ family of polarizable forcefields

   "Frozen"
      Type:
         Bool

      Default value:
         No

      Description:
         Expert option. Do not introduce polarization effect in
         response calculations.

   "Kernel"
      Type:
         Multiple Choice

      Default value:
         OHNO

      Options:
         [OHNO, COUL, GAUS]

      Description:
         Expert option. KERNEL can be used to choose the functional
         form of the charge-charge interaction kernel between MM
         atoms. Recommended is to use the default OHNO. The COUL
         screening is the standard Coulomb interaction 1/r. The OHNO
         choice introduce the Ohno functional (see [K. Ohno, Theoret.
         Chim. Acta 2, 219 (1964)]), which depends on a parameter n
         that is set equal to 2. Finally, the GAUS screening models
         each FQ charge by means of a spherical Gaussian-type
         distribution, and the interaction kernel is obtained
         accordingly. For QM/FQFMU only GAUS SCREEN is implemented.

   "LifeFrequency"
      Type:
         Float

      Default value:
         0.0

      Description:
         Input frequency for calculating TDDFT/wFQ(Fmu) lifetimes

   "LifeState"
      Type:
         Integer

      Default value:
         0

      Description:
         Target excited state for state-specific TDDFT/wFQ(Fmu)
         lifetimes

   "MolCharge"
      Type:
         Float

      Default value:
         0.0

      Description:
         Total charge of each fragment (FQ only)

   "NonEle"
      Type:
         Multiple Choice

      Default value:
         LJ

      Options:
         [LJ, None]

      Description:
         Whether to include non-electrostatic contributions to the
         energy. Default is the Lennard-Jones (LJ) model.

   "QMSCREEN"
      Type:
         Multiple Choice

      Default value:
         GAUS

      Options:
         [ERF, EXP, GAUS, NONE]

      Description:
         Expert option. QMSCREEN can be used to choose the functional
         form of the charge-charge interaction kernel between MM atoms
         and the QM density. The screening types available are ERF
         (error function), EXP (exponential), GAUS (Gaussian), or
         NONE. The default is GAUS.

   "QMSCREENFACTOR"
      Type:
         Float

      Default value:
         0.2

      Description:
         Expert option. Sets the QM/MM interaction kernel screening
         length. Recommended is to use the default value 0.2 with the
         GAUS QM/MM screening function.

   "ReadDynamicMatrix"
      Type:
         String

      Description:
         The absolute path to the decomposed wFQ(FMu) matrix file


SCC details and spin-polarization
=================================

With SCC DFTB the parametrized Hamiltonian depends on partial atomic
charges that need to be determined self-consistently. These charges
are usually atomic charges, but they may be shell and/or spin
resolved. The self-consistency requirement

\vec{q}^\text{in}=\vec{q}^\text{in}

is numerically expressed as

\frac{1}{\sqrt{N_\text{atoms}}}  | \vec{q}^\text{in}-\vec{q}^\text{in}
| < \epsilon

The vector norm is by default the so-called L-infinity norm, being the
maximum absolute value of the vector elements. The underlying
algorithm, however, will minimize the L-2 norm. Based on the history
of past input and output charge vectors, a next one is guessed

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

How many past vectors (N) are used and the value of the coefficients
depends on the algorithm, as does the mix factor \sigma. The default
method is the MultiStepper, which is explained separately. The older
DIIS method is simpler to tweak in case the SCC does not converge.

   SCC
      AlwaysClaimConvergence Yes/No
      Converge
         Charge float
         Norm [L2 | L-Infinity]
      End
      HXDamping Yes/No
      InheritMixFromPreviousResult Yes/No
      Iterations integer
      Method [DIIS | MultiStepper]
      MinimumAdaptiveMixingFactor float
      OrbitalDependent Yes/No
      SpinOrbit Yes/No
      Unrestricted Yes/No
   End

"SCC"
   Type:
      Block

   Description:
      This optional section configures various details of the self-
      consistent charge cycle. If the model Hamiltonian does not need
      a self-consistent solution (e.g. plain DFTB0), none of this
      information is used and the entire section will be ignored.

   "AlwaysClaimConvergence"
      Type:
         Bool

      Default value:
         No

      Description:
         Even if the SCC does not converge, claim convergence.

   "Converge"
      Type:
         Block

      Description:
         Controls the convergence criteria of the SCC cycle.

      "Charge"
         Type:
            Float

         Default value:
            1e-08

         GUI name:
            Charge convergence

         Description:
            The maximum change in atomic charges between subsequent
            SCC iterations. If the charges change less, the SCC cycle
            is considered converged.

      "Norm"
         Type:
            Multiple Choice

         Default value:
            L-Infinity

         Options:
            [L2, L-Infinity]

         Description:
            The LInfinity norm is the more stringent choice. The L2
            norm is directly what is optimized by the DIIS procedure,
            it is scaled by the extra constant factor 2/sqrt(nAtoms).

   "HXDamping"
      Type:
         Bool

      Description:
         This option activates the DFTB3 style damping for H-X bonds.
         Note that this is always enabled if the DFTB%Model key is set
         to DFTB3. Not used with xTB.

   "InheritMixFromPreviousResult"
      Type:
         Bool

      Default value:
         No

      Description:
         For some run types, such as GeometryOptimization, a previous
         result is available. By using the charges from the previous
         geometry a better initial guess for the SCC procedure may be
         obtained.                      Also the last mix factor from
         the previous result can be loaded, possibly speeding up the
         SCC.

   "Iterations"
      Type:
         Integer

      Default value:
         500

      Description:
         Allows to specify the maximum number of SCC iterations. The
         default should suffice for most standard calculations.
         Convergence issues may arise due to the use of the Aufbau
         occupations for systems with small HOMO-LUMO gaps. In this
         case the use of a Fermi broadening strategy may improve
         convergence.                      Choosing a smaller mixing
         parameter (see DFTB%SCC%Mixing) may also help with
         convergence issues: it often provides a more stable but
         slower way to converge the SCC cycle.

   "Method"
      Type:
         Multiple Choice

      Default value:
         MultiStepper

      Options:
         [DIIS, MultiStepper]

      Description:
         The DIIS option is the old method. The MultiStepper is much
         more flexible and is controlled by the SCFMultiSolver block

   "MinimumAdaptiveMixingFactor"
      Type:
         Float

      Default value:
         0.003

      Description:
         In case of AdaptiveMixing the lower bound for the
         MixingFactor.

   "OrbitalDependent"
      Type:
         Bool

      Description:
         Activates or disables orbital resolved calculations. If this
         key is absent the recommended settings from the parameter
         file's metainfo.

   "SpinOrbit"
      Type:
         Bool

      Default value:
         No

      Description:
         test

   "Unrestricted"
      Type:
         Bool

      Default value:
         No

      Description:
         Enables spin unrestricted calculations.
         Only collinear spin polarization is supported, see Theor Chem
         Acc (2016) 135: 232, for details.                      Must
         be supported by the chosen parameter set. Not yet compatible
         with DFTB3, k-space sampling periodic calculations or the xTB
         models.

   Occupation
      KT float
      NumBoltz integer
      Strategy [Auto | Aufbau | Fermi]
      Temperature float
   End

"Occupation"
   Type:
      Block

   Description:
      Configures the details of how the molecular orbitals are
      occupied with electrons.

   "KT"
      Type:
         Float

      Unit:
         Hartree

      Description:
         (KT) Boltzmann constant times temperature, used for
         electronic temperature with strategy is auto.
         The default value is the default value for
         Temperature*3.166815423e-6.                      This key and
         Temperature are mutually exclusive.

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

   "Strategy"
      Type:
         Multiple Choice

      Default value:
         Auto

      Options:
         [Auto, Aufbau, Fermi]

      GUI name:
         Occupation

      Description:
         This optional key allows to specify the fill strategy to use
         for the molecular orbitals.                      Can either
         be 'Aufbau' for simply filling the energetically lowest
         orbitals, or 'Fermi' for a smeared out Fermi-Dirac
         occupation. By default the occupation strategy is determined
         automatically, based on the other settings (such as the
         number of unpaired electrons).

   "Temperature"
      Type:
         Float

      Default value:
         300.0

      Unit:
         Kelvin

      GUI name:
         Fermi temperature

      Description:
         The Fermi temperature used for the Fermi-Dirac distribution.
         Ignored in case of aufbau occupations.

   UnpairedElectrons integer

"UnpairedElectrons"
   Type:
      Integer

   Default value:
      0

   GUI name:
      Spin polarization

   Description:
      This specifies the number of unpaired electrons (not the
      multiplicity!).                   This number will then be used
      in the orbital-filling strategy. Has to be compatible with the
      total number of electrons, meaning it must be an even number if
      the total number of electrons is even and odd if the total
      number is odd. Must be an integer value.                   Note
      that this does not activate spin polarization, it only affects
      the filling of the orbitals.


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 charge vector is a linear combination of
previous input and output charges

\vec{q}^\text{guess}=\sum_i c_{i-1}^N (\vec{q}^\text{in}_i +
\sigma(\vec{q}^\text{out}_i-\vec{q}^\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 is loaded is controlled by the "SCF%MultiStepperPresetPath"
key, and this may be an absolute path to your own preset.

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

   SCC
      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
      MultiStepperPresetPath string
   End

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

   "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'


DIIS
----

When selecting the SCC method DIIS, these are the relevant options.
Compared to the MultiStepper it is more straightforward to tweak.

   SCC
      AdaptiveMixing Yes/No
      DIIS
         Enabled Yes/No
         MaxSamples integer
         MaximumCoefficient float
         MinSamples integer
         MixingFactor float
      End
   End

"SCC"
   "AdaptiveMixing"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Change the mixing parameter based on the monitored energy. A
         significant increase of energy will strongly reduce the
         mixing. Then it will slowly grow back to the SCC%Mixing
         value.

   "DIIS"
      Type:
         Block

      Description:
         Parameters influencing the DIIS self-consistency method

      "Enabled"
         Type:
            Bool

         Default value:
            Yes

         Description:
            If not enabled simple mixing without DIIS acceleration
            will be used.

      "MaxSamples"
         Type:
            Integer

         Default value:
            20

         Description:
            Specifies the maximum number of samples considered during
            the direct inversion of iteration of subspace (DIIS)
            extrapolation of the atomic charges during the SCC
            iterations. A smaller number of samples potentially leads
            to a more aggressive convergence acceleration, while a
            larger number often guarantees a more stable iteration.
            Due to often occurring linear dependencies within the set
            of sample vectors, the maximum number of samples is
            reached only in very rare cases.

      "MaximumCoefficient"
         Type:
            Float

         Default value:
            10.0

         Description:
            When the diis expansion coefficients exceed this
            threshold, the solution is rejected. The vector space is
            too crowded. The oldest vector is discarded, and the
            expansion is re-evaluated.

      "MinSamples"
         Type:
            Integer

         Default value:
            -1

         Description:
            When bigger than one, this affects the shrinking of the
            DIIS space on linear dependence. It will not reduce to a
            smaller space than MinSamples unless there is extreme
            dependency.

      "MixingFactor"
         Type:
            Float

         Default value:
            0.15

         Description:
            The parameter used to mix the DIIS linear combination of
            previously sampled atomic charge vectors with an analogous
            linear combination of charge vectors resulting from
            population analysis combination. It can assume real values
            between 0 and 1.


k-space integration
===================

As of the 2019 release, the k-space integration is unified between
BAND and DFTB and uses the same keys as input, and the same defaults.
See the page on k-space integration in the BAND manual for details and
recommendations.

   KSpace
      Analytical Yes/No
      Quality [Auto | GammaOnly | Basic | Normal | Good | VeryGood | Excellent]
      Regular
         NumberOfPoints integer_list
      End
      Symmetric
         KInteg integer
      End
      Type [Regular | Symmetric]
   End

"KSpace"
   Type:
      Block

   Description:
      Options for the k-space integration (i.e. the grid used to
      sample the Brillouin zone)

   "Analytical"
      Type:
         Bool

      Default value:
         Yes

      Description:
         For analytical integration the BZ is split into simplices,
         whereover the bands are interpolated, ater which the
         integrals can be performed analytically.
         Alternatively, the set of eigenvalues in the discrete set of
         k-points are just handled as distinct molecular orbitals.
         Using analytical=no can improve SCF convergence in
         combination with smearing/temperature.

   "Quality"
      Type:
         Multiple Choice

      Default value:
         Auto

      Options:
         [Auto, GammaOnly, Basic, Normal, Good, VeryGood, Excellent]

      GUI name:
         K-space

      Description:
         Select the quality of the K-space grid used to sample the
         Brillouin Zone. If 'Auto', the quality defined in the
         'NumericalQuality' will be used. If 'GammaOnly', only one
         point (the gamma point) will be used.
         The actual number of K points generated depends on this
         option and on the size of the unit cell. The larger the real
         space cell, the fewer K points will be generated.
         The CPU-time and accuracy strongly depend on this option.

   "Regular"
      Type:
         Block

      Description:
         Options for the regular k-space integration grid.

      "NumberOfPoints"
         Type:
            Integer List

         Description:
            Use a regular grid with the specified number of k-points
            along each reciprocal lattice vector.
            For 1D periodic systems you should specify only one
            number, for 2D systems two numbers, and for 3D systems
            three numbers.

   "Symmetric"
      Type:
         Block

      Description:
         Options for the symmetric k-space integration grid.

      "KInteg"
         Type:
            Integer

         GUI name:
            Accuracy

         Description:
            Specify the accuracy for the Symmetric method.
            1: absolutely minimal (only the G-point is used)
            2: linear tetrahedron method, coarsest spacing
            3: quadratic tetrahedron method, coarsest spacing
            4,6,... (even): linear tetrahedron method
            5,7.... (odd): quadratic method
            The tetrahedron method is usually by far inferior.

   "Type"
      Type:
         Multiple Choice

      Default value:
         Regular

      Options:
         [Regular, Symmetric]

      GUI name:
         K-space grid type

      Description:
         The type of k-space integration grid used to sample the
         Brillouin zone (BZ) used.                      'Regular':
         simple regular grid.                      'Symmetric':
         symmetric grid for the irreducible wedge of the first BZ
         (useful when high-symmetry points in the BZ are needed to
         capture the correct physics of the system, graphene being a
         notable example).


xTB specific keywords
=====================

A few keywords only apply to the xTB model Hamiltonian.

   XTBConfig
      SlaterRadialThreshold float
      useXBTerm Yes/No
   End

"XTBConfig"
   Type:
      Block

   Description:
      This block allows for minor tweaking.

   "SlaterRadialThreshold"
      Type:
         Float

      Default value:
         1e-05

      Description:
         Threshold determining the range of the basis functions. Using
         a larger threshold will speed up the calculation, but will
         also make the results less accurate.

   "useXBTerm"
      Type:
         Bool

      Default value:
         No

      Description:
         Whether to use the Halogen bonding (XB) term. This is not
         advised as it has a non-continuous PES.

Note:

  The GFN1-xTB implementation in AMS currently does not implement the
  electronic entropy term from the article by Grimme et al. It
  therefore gives slightly different energies (but not gradients!) for
  systems with partially occupied molecular orbitals.


Technical options
=================

   Technical
      AnalyticalStressTensor Yes/No
      EwaldSummation
         CellRangeFactor float
         Enabled Yes/No
         Tolerance float
      End
      MatricesViaFullMaxSize integer
      Parallel
         nCoresPerGroup integer
         nGroups integer
         nNodesPerGroup integer
      End
      ReuseKSpaceConfig Yes/No
      Screening
         dMadel float
         rMadel float
      End
      UseGeneralizedDiagonalization Yes/No
   End

"Technical"
   Type:
      Block

   Description:
      This optional section is about technical aspects of the program
      that should not concern the normal user.

   "AnalyticalStressTensor"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to compute the stress tensor analytically. Note: This
         can only be used together with Ewald summation as it will
         give (slightly) wrong results with Madelung screening.

   "EwaldSummation"
      Type:
         Block

      Description:
         Configures the details of the Ewald summation of the Coulomb
         interaction.

      "CellRangeFactor"
         Type:
            Float

         Default value:
            2.0

         Description:
            Smaller values will make the Ewald summation less accurate
            but faster.

      "Enabled"
         Type:
            Bool

         Default value:
            Yes

         Description:
            Whether to use Ewald summation for the long-range part of
            the Coulomb interaction. Otherwise screening is used.

      "Tolerance"
         Type:
            Float

         Default value:
            1e-10

         Description:
            Larger values will make the Ewald summation less accurate
            but faster.

   "MatricesViaFullMaxSize"
      Type:
         Integer

      Default value:
         2047

      Description:
         Matrices smaller than this size are constructed via a full
         matrix. This is faster, but uses more memory in the
         construction.

   "Parallel"
      Type:
         Block

      Description:
         Calculation of the orbitals in several k-points is trivially
         parallel.

      "nCoresPerGroup"
         Type:
            Integer

         Description:
            Number of cores in each working group.

      "nGroups"
         Type:
            Integer

         Description:
            Total number of processor groups. This is the number of
            tasks that will be executed in parallel.

      "nNodesPerGroup"
         Type:
            Integer

         GUI name:
            Cores per task

         Description:
            Number of nodes in each group. This option should only be
            used on homogeneous compute clusters, where all used
            compute nodes have the same number of processor cores.

   "ReuseKSpaceConfig"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Keep the number of k-points constant during a lattice
         optimization. Otherwise the PES might display jumps, because
         the number of points depends on the lattice vector sizes. If
         this option is on it will always use the number of k-points
         that was used from a previous result.

   "Screening"
      Type:
         Block

      Description:
         For SCC-DFTB in periodic systems the Coulomb interaction can
         (instead of using Ewald summation) be screened with a Fermi-
         Dirac like function defined as
         S(r)=1/(exp((r-r_madel)/d_madel)+1). This section allows to
         change some details of the screening procedure. Note that
         Coulomb screening is only used if the Ewald summation is
         disabled.

      "dMadel"
         Type:
            Float

         Unit:
            Bohr

         Description:
            Sets the smoothness of the screening function. The default
            is 1/10 of [rMadel].

      "rMadel"
         Type:
            Float

         Unit:
            Bohr

         Description:
            Sets the range of the screening function. The default is
            2x the norm of the longest lattice vector.

   "UseGeneralizedDiagonalization"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether or not to use generalized diagonalization. Does not
         affect the results, but might be faster or slower.

   StoreMatrices Yes/No

"StoreMatrices"
   Type:
      Bool

   Default value:
      No

   Description:
      Determines whether the Hamiltonian and overlap matrices are
      stored in the binary result file.
