Spectroscopy and properties
***************************


Electronic structure of periodic systems
========================================

   Periodic
      EffectiveMass
         Enabled Yes/No
         KPointCoord float_list
         NumAbove integer
         NumBelow integer
         StepSize float
         UseBandStructureInfoFromPath Yes/No
      End
      BandStructure
         Automatic Yes/No
         DeltaK float
         Enabled Yes/No
         FatBands Yes/No
         KPathFinderConvention [Setyawan-Curtarolo | Hinuma]
         UseSymmetry Yes/No
      End
      BZPath
         Path # Non-standard block. See details.
            ...
         End
      End
      DOS
         EMax float
         EMin float
         Enabled Yes/No
         NSteps integer
      End
   End

"Periodic"
   Type:
      Block

   Description:
      Block that sets various details of the calculation only relevant
      for periodic systems.

   "EffectiveMass"
      Type:
         Block

      Description:
         In a semi-conductor, the mobility of electrons and holes is
         related to the curvature of the bands at the top of the
         valence band and the bottom of the conduction band.
         With the effective mass option, this curvature is obtained by
         numerical differentiation.                      The
         estimation is done with the specified step size, and twice
         the specified step size, and both results are printed to give
         a hint on the accuracy. By far the most convenient way to use
         this key is without specifying any options.

      "Enabled"
         Type:
            Bool

         Default value:
            No

         GUI name:
            Effective mass

         Description:
            In a semi-conductor, the mobility of electrons and holes
            is related to the curvature of the bands at the top of the
            valence band and the bottom of the conduction band.
            With the effective mass option, this curvature is obtained
            by numerical differentiation.                         The
            estimation is done with the specified step size, and twice
            the specified step size, and both results are printed to
            give a hint on the accuracy. By far the most convenient
            way to use this key is without specifying any options.

      "KPointCoord"
         Type:
            Float List

         Unit:
            1/Bohr

         Recurring:
            True

         GUI name:
            At K-point

         Description:
            Coordinate of the k-points for which you would like to
            compute the effective mass.

      "NumAbove"
         Type:
            Integer

         Default value:
            1

         GUI name:
            Include N bands above

         Description:
            Number of bands to take into account above the Fermi
            level.

      "NumBelow"
         Type:
            Integer

         Default value:
            1

         GUI name:
            Include N bands below

         Description:
            Number of bands to take into account below the Fermi
            level.

      "StepSize"
         Type:
            Float

         Default value:
            0.001

         Description:
            Size of the step taken in reciprocal space to perform the
            numerical differentiation

      "UseBandStructureInfoFromPath"
         Type:
            Bool

         Default value:
            Yes

         Description:
            The (automatic) location of the HOMO and LUMO can be
            determined via band interpolation, or from the path as
            used by the BandStructure feature. The latter works better
            when they are located on the path. See also comments in
            the BandStructure block. To reproduce results from before
            ams2025 set to no.

   "BandStructure"
      Type:
         Block

      Description:
         Options for band structure plotting. This has no effect on
         the calculated energy. [Warning: The band structure is only
         computed in case of k-space sampling, i.e. it is not computed
         for Gamma-only calculations (see: Periodic%KSpace).]

      "Automatic"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Automatic generate path

         Description:
            Generate and use the standard path through the Brillouin
            zone.                         If not, use the user defined
            path (set via Custom path in the GUI, or with the
            Periodic%BZPath keyword in the run script).

      "DeltaK"
         Type:
            Float

         Default value:
            0.1

         Unit:
            1/Bohr

         GUI name:
            Interpolation delta-K

         Description:
            Step size in reciprocal space for band structure
            interpolation. Using a smaller number will produce
            smoother band curves at an increased computational time.

      "Enabled"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Calculate band structure

         Description:
            Whether or not to calculate the band structure.

      "FatBands"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Calculate fatbands

         Description:
            Control the computation of the fat bands (only when the
            bandstructure is calculated).                         The
            fat bands are the periodic equivalent of the Mulliken
            population analysis. The definition of the fat bands can
            be found in the Band Documentation.

      "KPathFinderConvention"
         Type:
            Multiple Choice

         Default value:
            Setyawan-Curtarolo

         Options:
            [Setyawan-Curtarolo, Hinuma]

         Description:
            This option determines how the path through the Brillouin
            zone is generated when using the automatic k-point mode.
            Available options:                         • "Setyawan-
            Curtarolo" (default for 1D and 2D lattices): Uses our
            built-in KPath program to find a path through high-
            symmetry points based on the method by Setyawan and
            Curtarolo
            (https://doi.org/10.1016/j.commatsci.2010.05.010). For 2D
            lattices, the path is derived from the intersection of the
            3D Brillouin zone with a plane. For 1D lattices, the path
            is simply Gamma-Z.                         • "Hinuma":
            Uses the external SeeKPath utility to generate the k-path
            (https://github.com/giovannipizzi/seekpath and
            https://doi.org/10.1016/j.commatsci.2016.10.015).

      "UseSymmetry"
         Type:
            Bool

         Default value:
            Yes

         Description:
            If set, only the irreducible wedge of the Wigner-Seitz
            cell is sampled. If not, the whole (inversion-unique)
            Wigner-Seitz cell is sampled. Only available for Setyawan
            and Curtarolo convention (see "KPathFinderConvention").

   "BZPath"
      Type:
         Block

      Description:
         If [BandStructure%Automatic] is disabled, DFTB will compute
         the band structure for the user-defined path in the [BZPath]
         block. You should define the vertices of your path in
         fractional coordinates (with respect to the reciprocal
         lattice vectors) in the [Path] sub-block. If you want to make
         a jump in your path, you need to specify a new [Path] sub-
         block.

      "Path"
         Type:
            Non-standard block

         Recurring:
            True

         Description:
            A section of a k space path.

   "DOS"
      Type:
         Block

      Description:
         The subkeys of [DOS] allow to customize the calculation of
         the density of states.

      "EMax"
         Type:
            Float

         Default value:
            0.75

         Unit:
            Hartree

         Description:
            Upper end of the energy interval in which the density of
            states is calculated.

      "EMin"
         Type:
            Float

         Default value:
            -0.75

         Unit:
            Hartree

         Description:
            Lower end of the energy interval in which the density of
            states is calculated.

      "Enabled"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Calculate DOS

         Description:
            Whether or not to calculate the DOS. Note that the DOS
            will always be calculated when also the band structure is
            calculated.

      "NSteps"
         Type:
            Integer

         Default value:
            300

         Description:
            The number of energy intervals between [EMin] and [EMax]
            for which the density of states is calculated.


Excited states with time-dependent DFTB
=======================================

DFTB allows for excited state calculations on molecular systems by
means of single orbital transitions as well as time-dependent DFTB as
published by Niehaus et al. in *Phys. Rev. B* **63**, 085108 (2001).
Singlet-singlet as well as singlet-triplet excitations can be
calculated. DFTB also supports the calculation of excited state
gradients, which allows geometry optimizations and vibrational
frequency calculations for excited states.

The TD-DFTB implementation uses the PRIMME library (PReconditioned
Iterative MultiMethod Eigensolver) by Andreas Stathopoulos and James
R. McCombs,  PRIMME: PReconditioned Iterative MultiMethod Eigensolver:
Methods and software description ACM Transaction on Mathematical
Software Vol. 37, No. 2, (2010), 21:1--21:30.

DFTB excited state calculations are controlled by the following
keywords:

   Properties
      Excitations
         SingleOrbTrans
            Enabled Yes/No
            Filter
               OSMin float
               dEMax float
               dEMin float
            End
            PrintLowest integer
         End
         TDDFTB
            Calc [None | Singlet | Triplet]
            DavidsonConfig
               ATCharges [Precalc | OnTheFly]
               SafetyMargin integer
               Tolerance float
            End
            Diagonalization [Auto | Davidson | Exact]
            Lowest integer
            Print string
            ScaleKernel float
            UpTo float
         End
         TDDFTBGradients
            Eigenfollow Yes/No
            Excitation integer_list
         End
      End
   End

"Properties"
   Type:
      Block

   Description:
      DFTB can calculate various properties of the simulated system.
      This block configures which properties will be calculated.

   "Excitations"
      Type:
         Block

      Description:
         Contains all options related to the calculation of excited
         states, either as simple single orbitals transitions or from
         a TD-DFTB calculation.

      "SingleOrbTrans"
         Type:
            Block

         Description:
            The simplest approximation to the true excitations are the
            single orbital transitions (sometimes called Kohn-Sham
            transitions), that is transitions where a single electron
            is excited from an occupied Kohn-Sham orbital into a
            virtual orbital. The calculation of these transitions is
            configured in this section. Note that the SingleOrbTrans
            section is optional even though the single orbital
            transitions are also needed for TD-DFTB calculations. If
            the section is not present all single orbital transitions
            will still be calculated and used in a subsequent TD-DFTB
            calculation, but no output will be produced.

         "Enabled"
            Type:
               Bool

            Default value:
               No

            GUI name:
               Single orbital transisitions: Calculate

            Description:
               Calculate the single orbital transitions.

         "Filter"
            Type:
               Block

            Description:
               This section allows to remove single orbital
               transitions based on certain criteria. All filters are
               disabled by default.

            "OSMin"
               Type:
                  Float

               GUI name:
                  Minimum oscillator strength

               Description:
                  Removes single orbital transitions with an
                  oscillator strength smaller than this threshold.
                  A typical value to start (if used at all) would be
                  1.0e-3.

            "dEMax"
               Type:
                  Float

               Unit:
                  Hartree

               Description:
                  Removes single orbital transitions with an orbital
                  energy difference larger than this threshold.

            "dEMin"
               Type:
                  Float

               Unit:
                  Hartree

               Description:
                  Removes single orbital transitions with an orbital
                  energy difference smaller than this threshold.

         "PrintLowest"
            Type:
               Integer

            Default value:
               10

            Description:
               The number of single orbital transitions that are
               printed to the screen and written to disk.
               If not a TD-DFTB calculation, the default is to print
               the 10 lowest single orbital transitions.
               In case of a TD-DFTB calculation it is assumed that the
               single orbital transitions are only used as an input
               for TD-DFTB and nothing will be printed unless
               PrintLowest is specified explicitly.

      "TDDFTB"
         Type:
            Block

         Description:
            Calculations with time-dependent DFTB can be configured in
            the TDDFTB section and should in general give better
            results than the raw single orbital transitions. TD-DFTB
            calculates the excitations in the basis of the single
            orbital transitions, whose calculation is configured in
            the SingleOrbTrans section. Using a filter in
            SingleOrbTrans can therefore be used to reduce the size of
            the basis for TD-DFTB. One possible application of this is
            to accelerate the calculation of electronic absorption
            spectra by removing single orbital transitions with small
            oscillator strengths from the basis. Note that the entire
            TDDFTB section is optional. If no TDDFTB section is found,
            the behavior depends on the existence of the
            SingleOrbTrans section: If no SingleOrbTrans section is
            found (the Excitations section is completely empty then) a
            TD-DFTB calculation with default parameters will be
            performed. If only the SingleOrbTrans section is present
            no TD-DFTB calculation will be done.

         "Calc"
            Type:
               Multiple Choice

            Default value:
               None

            Options:
               [None, Singlet, Triplet]

            GUI name:
               Type of excitations

            Description:
               Specifies the multiplicity of the excitations to be
               calculated.

         "DavidsonConfig"
            Type:
               Block

            Description:
               This section contains a number of keywords that can be
               used to override various internals of the Davidson
               eigensolver. The default values should generally be
               fine.

            "ATCharges"
               Type:
                  Multiple Choice

               Default value:
                  Precalc

               Options:
                  [Precalc, OnTheFly]

               GUI name:
                  Transition charges

               Description:
                  Select whether the atomic transition charges are
                  precalculated in advance or reevaluated during the
                  iterations of the Davidson solver.
                  Precalculating the charges will improve the
                  performance, but requires additional storage.
                  The default is to precalculate the atomic transition
                  charges, but the precalculation may be disabled if
                  not not enough memory is available.

            "SafetyMargin"
               Type:
                  Integer

               Default value:
                  4

               Description:
                  The number of eigenvectors the Davidson method will
                  calculate in addition to the ones requested by the
                  user. With the Davidson eigensolver it is generally
                  a good idea to calculate a few more eigenvectors
                  than needed, as depending on the initial guess for
                  the eigenvectors it can happen that the found ones
                  are not exactly the lowest ones. This problem is
                  especially prominent if one wants to calculate only
                  a small number of excitations for a symmetric
                  molecule, where the initial guesses for the
                  eigenvectors might have the wrong symmetry. Note
                  that the additionally calculated excitations will
                  neither be written to the result file nor be visible
                  in the output.

            "Tolerance"
               Type:
                  Float

               Default value:
                  1e-09

               Description:
                  Convergence criterion for the norm of the residual.

         "Diagonalization"
            Type:
               Multiple Choice

            Default value:
               Auto

            Options:
               [Auto, Davidson, Exact]

            GUI name:
               Method

            Description:
               Select the method used to solve the TD-DFTB eigenvalue
               equation.                            The most
               straightforward procedure is a direct diagonalization
               of the matrix from which the excitation energies and
               oscillator strengths are obtained. Since the matrix
               grows quickly with system size (number of used single
               orbital transitions squared), this option is possible
               only for small molecules.
               The alternative is the iterative Davidson method, which
               finds a few of the lowest excitations within an error
               tolerance without ever storing the full matrix.
               The default is to make this decision automatically
               based on the system size and the requested number of
               excitations.

         "Lowest"
            Type:
               Integer

            Default value:
               10

            GUI name:
               Number of excitations

            Description:
               Specifies the number of excitations that are
               calculated.                            Note that in
               case of the exact diagonalization all excitations are
               calculated, but only the lowest ones are printed to
               screen and written to the output file.
               Also note that if limited both by number and by energy,
               (lowest and upto), DFTB will always use whatever
               results in the smaller number of calculated
               excitations.

         "Print"
            Type:
               String

            Description:
               Specifies whether to print details on the contribution
               of the individual single orbital transitions to the
               calculated excitations.

         "ScaleKernel"
            Type:
               Float

            Default value:
               1.0

            Unit:
               None

            Description:
               Set the scaling parameter of the response kernel.
               A scaling approach can be used to identify plasmons in
               molecules. While single-particle excitations are only
               slightly affected by scaling of the response kernel,
               plasmonic excitations are sensitive to variations in
               the scaling parameter. Default no scaling is used
               (scaling parameter = 1.0)

         "UpTo"
            Type:
               Float

            Unit:
               Hartree

            GUI name:
               Excitations up to

            Description:
               Set the maximum excitation energy.
               Attempts to calculate all excitations up to a given
               energy by calculating a number of excitations equal to
               the number of single orbital transitions in this
               window. This is only approximately correct, so one
               should always add some safety margin.
               Note that if limited both by number and by energy,
               (lowest and upto), DFTB will always use whatever
               results in the smaller number of calculated
               excitations.

      "TDDFTBGradients"
         Type:
            Block

         Description:
            This block configures the calculation of analytical
            gradients for the TD-DFTB excitation energies, which
            allows the optimization of excited state geometries and
            the calculation of vibrational frequencies in excited
            states (see J. Comput. Chem., 28: 2589-2601). If the
            gradients are calculated, they will automatically be used
            for geometry optimizations or vibrational frequency
            calculations, if the corresponding Task is selected and
            only 1 excitation is selected. Vibrationally resolved
            UV/Vis spectroscopy (Franck-Condon Factors) can be
            calculated in combination with the FCF program or using
            the Vibrational Analysis Tools in AMS. See the ADF
            documentation on Vibrationally resolved electronic spectra
            or the AMS documentation for the Vibrational Analysis
            Tools.

         "Eigenfollow"
            Type:
               Bool

            Default value:
               No

            GUI name:
               Follow initial excitation

            Description:
               If this option is set, DFTB uses the transition density
               in atomic orbital basis to follow the initially
               selected excited state during a geometry optimization.
               This is useful if excited state potential energy
               surfaces cross each other and you want to follow the
               surface you started on.

         "Excitation"
            Type:
               Integer List

            GUI name:
               Excitation number

            Description:
               Select which excited states to calculate the gradients
               for.                            Gradients can only be
               calculated for an excited states that has been
               calculated using TD-DFTB. Make sure that enough
               excitations are calculated.


Excited state gradients
=======================

Excited state gradients can be calculated with TD-DFTB, see the
section Excited states with time-dependent DFTB.


Frequencies, phonons, VCD
=========================

Frequencies, phonons, and VCD can be computed via numerical
differentiation by the AMS driver. Several thermodynamic properties,
such as zero-point energy, internal energy, entropy, free energy, and
specific heat, are computed by default when calculating phonons.

* AMS manual: Vibrational Analysis

  * AMS manual: Infrared (IR) spectra / Normal Modes

  * AMS manual: Phonons

  * AMS manual: Thermodynamic properties

  * AMS manual: VCD (Vibrational Circular Dichroism)


Vibrationally resolved electronic spectra
=========================================

* AMS manual: Vibrationally resolved electronic spectra.

  * AMS manual: AH-FC Adiabatic Hessian Franck-Condon.

  * AMS manual: VG-FC Vertical Gradient Franck-Condon.


Stress tensor, Elasticity
=========================

The stress tensor and elastic tensor (and related elastic properties
such as bulk modulus, shear modulus, and Young modulus) can be
computed via numerical differentiation by AMS.

* AMS manual: Stress tensor

* AMS manual: Elastic tensor


Charges, Bond Orders, Dipole Moment, Polarizability
===================================================

Charges, Mayer bond orders, Dipole Moment, and Polarizability can be
requested to the DFTB engine in the AMS driver's input:

* AMS manual: Atomic charges

* AMS manual: Bond orders

* AMS manual: Dipole Moment

* AMS manual: Dipole Gradients


Fragment orbital analysis
=========================

The fragment orbital analysis is not available for periodic systems
calculated with multiple K-points.

A Mulliken population analysis based on the elementary atomic basis
functions can be calculated using

   Properties
      Fragments
      End
   End

For an atomic Mulliken population one should not specify any subkey
"File" in Properties%Fragments.

A Mulliken population analysis based on orbitals coming from larger
fragments, that may consist of more than 1 atom, can be calculated if
one includes the binary dftb.rkf result files of the calculated
fragments in the input, for example, like:

   Properties
      Fragments
         File frag1.results/dftb.rkf
         File frag2.results/dftb.rkf
      End
   End

Note that the nuclear coordinates of the atoms in the fragments should
be at exactly the same position as in the whole system. In addition,
each atom of the whole system should be present exactly once in one of
the fragment dftb.rkf files.

   Properties
      Fragments
         Analysis Yes/No
         EMax float
         Emin float
         File string
         TIDegeneracyThreshold float
         TransferIntegrals Yes/No
      End
   End

"Properties"
   "Fragments"
      Type:
         Block

      Description:
         Fragment files

      "Analysis"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Fragment analysis

         Description:
            Mulliken population analysis in terms of fragment
            orbitals.

      "EMax"
         Type:
            Float

         Default value:
            0.25

         Unit:
            Hartree

         Description:
            Upper end of the energy interval for which the orbitals
            are analyzed.

      "Emin"
         Type:
            Float

         Default value:
            -0.75

         Unit:
            Hartree

         Description:
            Lower end of the energy interval for which the orbitals
            are analyzed.

      "File"
         Type:
            String

         Recurring:
            True

         Description:
            Path (either absolute or relative) of fragment file

      "TIDegeneracyThreshold"
         Type:
            Float

         Default value:
            0.1

         Unit:
            eV

         Description:
            If the orbital energy of the fragment MO is within this
            threshold with fragment HOMO or LUMO energy, then this
            fragment MO is included in the calculation of the transfer
            integrals. Relevant in case there is (near) degeneracy.

      "TransferIntegrals"
         Type:
            Bool

         Default value:
            No

         GUI name:
            Charge transfer integrals

         Description:
            Calculate the charge transfer integrals, spatial overlap
            integrals and site energies.
            Charge transfer integrals can be used in models that
            calculate transport properties.


NBO analysis
============

An input for the GENNBO program of Prof. Weinhold's Natural Bond
Orbital (NBO) package, by E. Glendening et al., can be generated using
the key Properties%NBOInput. Not available for periodic systems.

   Properties
      NBOInput Yes/No
   End

"Properties"
   "NBOInput"
      Type:
         Bool

      Default value:
         No

      Description:
         Whether or not an input file for the NBO program is written
         to disk as nboInput.FILE47. The input file follows the FILE47
         format as described in the NBO6 manual available on
         nbo6.chem.wisc.edu. By default, only the calculation of the
         natural bond orbitals and the natural localized molecular
         orbitals is enabled, but the nboInput.FILE47 file can be
         edited by hand to enable other analysis models. Please refer
         to the NBO6 manual for details.

The GENNBO executable is included in the AMS distribution. The GENNBO
program can be called with:

   #!/bin/sh
   $AMSBIN/gennbo6 ams.results/dftb-nboInput.FILE47
