from __future__ import annotations
from pathlib import Path
from typing import Iterable, Literal, Sequence
from scm.pisa.block import DriverBlock,EngineBlock,FixedBlock,FreeBlock,InputBlock
from scm.pisa.key import BoolKey,FloatKey,FloatListKey,IntKey,IntListKey,MultipleChoiceKey,PathStringKey,StringKey,BoolType
[docs]class DFTB(EngineBlock):
r"""
:ivar DispersionCorrection: 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.
:vartype DispersionCorrection: Literal["None", "Auto", "UFF", "ULG", "D2", "D3-BJ", "D4"]
:ivar Model: 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.
:vartype Model: Literal["DFTB", "DFTB0", "DFTB1", "SCC-DFTB", "DFTB2", "DFTB3", "GFN1-xTB", "NonSCC-GFN1-xTB"]
:ivar NumericalQuality: Set the quality of some technical aspects of a DFTB calculation. It sets the quality of: KSpace (reciprocal space integration). Note: the quality defined in the block of a specific technical aspects supersedes the value defined in NumericalQuality (e.g. if I specify 'NumericalQuality Basic' and 'KSpace%Quality Good', the quality of the KSpace will be 'Good')
:vartype NumericalQuality: Literal["Basic", "Normal", "Good", "VeryGood", "Excellent"]
:ivar RadialExtrapolation: Advanced control option. Overrides the extrapolation method for Slater-Koster grid values between the end of the tabulated grid and the cutoff distance (value for which atoms are considered too far to interact). Depending on the structure of your Slater-Koster tables, a different radial extrapolation method may be needed in order to guarantee correct behavior, in particular for large and periodic systems. See the DFTB documentation for a description of the various available methods.
:vartype RadialExtrapolation: Literal["Auto", "ScreenTail", "None", "Linear", "Original", "Improved", "Bezier"]
:ivar ResourcesDir: 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.
:vartype ResourcesDir: str | Path | StringKey
:ivar StoreMatrices: Determines whether the Hamiltonian and overlap matrices are stored in the binary result file.
:vartype StoreMatrices: BoolType | BoolKey
:ivar StoreOrbitals: Determines whether the orbital coefficients are stored in the binary result file. They are needed for displaying orbitals and densities in amsview.
:vartype StoreOrbitals: BoolType | BoolKey
:ivar UnpairedElectrons: 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.
:vartype UnpairedElectrons: int | IntKey
:ivar UseSymmetry:
:vartype UseSymmetry: BoolType | BoolKey
:ivar KSpace: Options for the k-space integration (i.e. the grid used to sample the Brillouin zone)
:vartype KSpace: DFTB._KSpace
:ivar Occupation: Configures the details of how the molecular orbitals are occupied with electrons.
:vartype Occupation: DFTB._Occupation
:ivar Periodic: Block that sets various details of the calculation only relevant for periodic systems.
:vartype Periodic: DFTB._Periodic
:ivar Properties: DFTB can calculate various properties of the simulated system. This block configures which properties will be calculated.
:vartype Properties: DFTB._Properties
:ivar QMFQ: Block input key for QM/FQ(FMu).
:vartype QMFQ: DFTB._QMFQ
:ivar Repulsion: Configures various details of the repulsive potential.
:vartype Repulsion: DFTB._Repulsion
:ivar SCC: 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.
:vartype SCC: DFTB._SCC
:ivar Solvation: Generalized Born solvation model with Solvent Accessible Surface Area (GBSA).
:vartype Solvation: DFTB._Solvation
:ivar Technical: This optional section is about technical aspects of the program that should not concern the normal user.
:vartype Technical: DFTB._Technical
:ivar XTBConfig: This block allows for minor tweaking.
:vartype XTBConfig: DFTB._XTBConfig
"""
[docs] class _KSpace(FixedBlock):
r"""
Options for the k-space integration (i.e. the grid used to sample the Brillouin zone)
:ivar Analytical: 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.
:vartype Analytical: BoolType | BoolKey
:ivar Quality: 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.
:vartype Quality: Literal["Auto", "GammaOnly", "Basic", "Normal", "Good", "VeryGood", "Excellent"]
:ivar Type: 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).
:vartype Type: Literal["Regular", "Symmetric"]
:ivar Regular: Options for the regular k-space integration grid.
:vartype Regular: DFTB._KSpace._Regular
:ivar Symmetric: Options for the symmetric k-space integration grid.
:vartype Symmetric: DFTB._KSpace._Symmetric
"""
[docs] class _Regular(FixedBlock):
r"""
Options for the regular k-space integration grid.
:ivar DoubleCount: Increase for each dimension the grid. A sequence of doubling, with a special meaning for grid with odd numbers. Useful when checking k-space convergence.
:vartype DoubleCount: int | IntKey
:ivar KMesh: Undocumented.
:vartype KMesh: int | IntKey
:ivar NumberOfPoints: 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.
:vartype NumberOfPoints: Iterable[int] | IntListKey
:ivar PreferEvenNumberOfPoints: In case of an automatic grid normally odd numbers will be generated (1,3,5,9), suitable for a quadratic grid. With this option the suggested odd numbers will be increased by one, unless it is one.
:vartype PreferEvenNumberOfPoints: BoolType | BoolKey
:ivar SplitCubeInSix: Undocumented.
:vartype SplitCubeInSix: BoolType | BoolKey
:ivar SplitLongest: Undocumented.
:vartype SplitLongest: BoolType | BoolKey
:ivar SplitPermutation: Undocumented.
:vartype SplitPermutation: int | IntKey
"""
def __post_init__(self):
self.DoubleCount: int | IntKey = IntKey(name='DoubleCount', comment='Increase for each dimension the grid. A sequence of doubling, with a special meaning for grid with odd numbers. Useful when checking k-space convergence.', hidden=True, default=0)
self.KMesh: int | IntKey = IntKey(name='KMesh', comment='Undocumented.', hidden=True, default=4)
self.NumberOfPoints: Iterable[int] | IntListKey = IntListKey(name='NumberOfPoints', comment='Use a regular grid with the specified number of k-points along each reciprocal lattice vector.\n\nFor 1D periodic systems you should specify only one number, for 2D systems two numbers, and for 3D systems three numbers.')
self.PreferEvenNumberOfPoints: BoolType | BoolKey = BoolKey(name='PreferEvenNumberOfPoints', comment='In case of an automatic grid normally odd numbers will be generated (1,3,5,9), suitable for a quadratic grid. With this option the suggested odd numbers will be increased by one, unless it is one.', hidden=True, default=False)
self.SplitCubeInSix: BoolType | BoolKey = BoolKey(name='SplitCubeInSix', comment='Undocumented.', hidden=True, default=False)
self.SplitLongest: BoolType | BoolKey = BoolKey(name='SplitLongest', comment='Undocumented.', hidden=True, default=False)
self.SplitPermutation: int | IntKey = IntKey(name='SplitPermutation', comment='Undocumented.', hidden=True, default=-1)
[docs] class _Symmetric(FixedBlock):
r"""
Options for the symmetric k-space integration grid.
:ivar KInteg: 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.
:vartype KInteg: int | IntKey
:ivar KMesh: Undocumented.
:vartype KMesh: int | IntKey
"""
def __post_init__(self):
self.KInteg: int | IntKey = IntKey(name='KInteg', comment='Specify the accuracy for the Symmetric method.\n\n1: absolutely minimal (only the G-point is used)\n2: linear tetrahedron method, coarsest spacing\n3: quadratic tetrahedron method, coarsest spacing\n4,6,... (even): linear tetrahedron method\n5,7.... (odd): quadratic method\n\nThe tetrahedron method is usually by far inferior.', gui_name='Accuracy:')
self.KMesh: int | IntKey = IntKey(name='KMesh', comment='Undocumented.', hidden=True, default=2)
def __post_init__(self):
self.Analytical: BoolType | BoolKey = BoolKey(name='Analytical', comment='For analytical integration the BZ is split into simplices, whereover the bands are interpolated, ater which the integrals can be performed analytically.\n\nAlternatively, the set of eigenvalues in the discrete set of k-points are just handled as distinct molecular orbitals.\n\nUsing analytical=no can improve SCF convergence in combination with smearing/temperature.', default=True)
self.Quality: Literal["Auto", "GammaOnly", "Basic", "Normal", "Good", "VeryGood", "Excellent"] = MultipleChoiceKey(name='Quality', comment="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. \n\nThe 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.\n\nThe CPU-time and accuracy strongly depend on this option.", gui_name='K-space:', default='Auto', choices=['Auto', 'GammaOnly', 'Basic', 'Normal', 'Good', 'VeryGood', 'Excellent'])
self.Type: Literal["Regular", "Symmetric"] = MultipleChoiceKey(name='Type', comment="The type of k-space integration grid used to sample the Brillouin zone (BZ) used.\n\n'Regular': simple regular grid.\n\n'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).", gui_name='K-space grid type:', default='Regular', choices=['Regular', 'Symmetric'])
self.Regular: DFTB._KSpace._Regular = self._Regular(name='Regular', comment='Options for the regular k-space integration grid.')
self.Symmetric: DFTB._KSpace._Symmetric = self._Symmetric(name='Symmetric', comment='Options for the symmetric k-space integration grid.')
[docs] class _Occupation(FixedBlock):
r"""
Configures the details of how the molecular orbitals are occupied with electrons.
:ivar KT: (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.
:vartype KT: float | FloatKey
:ivar NumBoltz: 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.
:vartype NumBoltz: int | IntKey
:ivar Strategy: 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).
:vartype Strategy: Literal["Auto", "Aufbau", "Fermi"]
:ivar Temperature: The Fermi temperature used for the Fermi-Dirac distribution. Ignored in case of aufbau occupations.
:vartype Temperature: float | FloatKey
"""
def __post_init__(self):
self.KT: float | FloatKey = FloatKey(name='KT', comment='(KT) Boltzmann constant times temperature, used for electronic temperature with strategy is auto.\nThe default value is the default value for Temperature*3.166815423e-6.\nThis key and Temperature are mutually exclusive.', unit='Hartree')
self.NumBoltz: int | IntKey = IntKey(name='NumBoltz', comment='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.', default=10)
self.Strategy: Literal["Auto", "Aufbau", "Fermi"] = MultipleChoiceKey(name='Strategy', comment="This optional key allows to specify the fill strategy to use for the molecular orbitals.\n\nCan 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).", gui_name='Occupation:', default='Auto', choices=['Auto', 'Aufbau', 'Fermi'])
self.Temperature: float | FloatKey = FloatKey(name='Temperature', comment='The Fermi temperature used for the Fermi-Dirac distribution. Ignored in case of aufbau occupations.', gui_name='Fermi temperature:', default=300.0, unit='Kelvin')
[docs] class _Periodic(FixedBlock):
r"""
Block that sets various details of the calculation only relevant for periodic systems.
:ivar BZPath: 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.
:vartype BZPath: DFTB._Periodic._BZPath
:ivar BandStructure: 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).]
:vartype BandStructure: DFTB._Periodic._BandStructure
:ivar DOS: The subkeys of [DOS] allow to customize the calculation of the density of states.
:vartype DOS: DFTB._Periodic._DOS
:ivar EffectiveMass: 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.
:vartype EffectiveMass: DFTB._Periodic._EffectiveMass
"""
[docs] class _BZPath(FixedBlock):
r"""
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.
:ivar Path: A section of a k space path.
:vartype Path: str | Sequence[str] | FreeBlock
"""
[docs] class _Path(FreeBlock):
r"""
A section of a k space path.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.Path: str | Sequence[str] | FreeBlock = self._Path(name='Path', comment='A section of a k space path.', unique=False)
[docs] class _BandStructure(FixedBlock):
r"""
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).]
:ivar Automatic: 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).
:vartype Automatic: BoolType | BoolKey
:ivar DeltaK: Step size in reciprocal space for band structure interpolation. Using a smaller number will produce smoother band curves at an increased computational time.
:vartype DeltaK: float | FloatKey
:ivar Enabled: Whether or not to calculate the band structure.
:vartype Enabled: BoolType | BoolKey
:ivar FatBands: 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.
:vartype FatBands: BoolType | BoolKey
:ivar KPathFinderConvention: 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).
:vartype KPathFinderConvention: Literal["Setyawan-Curtarolo", "Hinuma"]
:ivar UseSymmetry: 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``).
:vartype UseSymmetry: BoolType | BoolKey
"""
def __post_init__(self):
self.Automatic: BoolType | BoolKey = BoolKey(name='Automatic', comment='Generate and use the standard path through the Brillouin zone.\n\nIf not, use the user defined path (set via Custom path in the GUI, or with the Periodic%BZPath keyword in the run script).', gui_name='Automatic generate path:', default=True)
self.DeltaK: float | FloatKey = FloatKey(name='DeltaK', comment='Step size in reciprocal space for band structure interpolation. Using a smaller number will produce smoother band curves at an increased computational time.', gui_name='Interpolation delta-K:', default=0.1, unit='1/Bohr')
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Whether or not to calculate the band structure.', gui_name='Calculate band structure:', default=True)
self.FatBands: BoolType | BoolKey = BoolKey(name='FatBands', comment='Control the computation of the fat bands (only when the bandstructure is calculated).\n\nThe fat bands are the periodic equivalent of the Mulliken population analysis. The definition of the fat bands can be found in the Band Documentation.', gui_name='Calculate fatbands:', default=True)
self.KPathFinderConvention: Literal["Setyawan-Curtarolo", "Hinuma"] = MultipleChoiceKey(name='KPathFinderConvention', comment='This option determines how the path through the Brillouin zone is generated when using the automatic k-point mode.\n\nAvailable options:\n\n• ``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.\n\n• ``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).', default='Setyawan-Curtarolo', choices=['Setyawan-Curtarolo', 'Hinuma'])
self.UseSymmetry: BoolType | BoolKey = BoolKey(name='UseSymmetry', comment='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``).', default=True)
[docs] class _DOS(FixedBlock):
r"""
The subkeys of [DOS] allow to customize the calculation of the density of states.
:ivar EMax: Upper end of the energy interval in which the density of states is calculated.
:vartype EMax: float | FloatKey
:ivar EMin: Lower end of the energy interval in which the density of states is calculated.
:vartype EMin: float | FloatKey
:ivar Enabled: Whether or not to calculate the DOS. Note that the DOS will always be calculated when also the band structure is calculated.
:vartype Enabled: BoolType | BoolKey
:ivar NSteps: The number of energy intervals between [EMin] and [EMax] for which the density of states is calculated.
:vartype NSteps: int | IntKey
"""
def __post_init__(self):
self.EMax: float | FloatKey = FloatKey(name='EMax', comment='Upper end of the energy interval in which the density of states is calculated.', default=0.75, unit='Hartree')
self.EMin: float | FloatKey = FloatKey(name='EMin', comment='Lower end of the energy interval in which the density of states is calculated.', default=-0.75, unit='Hartree')
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Whether or not to calculate the DOS. Note that the DOS will always be calculated when also the band structure is calculated.', gui_name='Calculate DOS:', default=True)
self.NSteps: int | IntKey = IntKey(name='NSteps', comment='The number of energy intervals between [EMin] and [EMax] for which the density of states is calculated.', default=300)
[docs] class _EffectiveMass(FixedBlock):
r"""
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.
:ivar Enabled: 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.
:vartype Enabled: BoolType | BoolKey
:ivar KPointCoord: Coordinate of the k-points for which you would like to compute the effective mass.
:vartype KPointCoord: Iterable[float] | FloatListKey
:ivar NumAbove: Number of bands to take into account above the Fermi level.
:vartype NumAbove: int | IntKey
:ivar NumBelow: Number of bands to take into account below the Fermi level.
:vartype NumBelow: int | IntKey
:ivar StepSize: Size of the step taken in reciprocal space to perform the numerical differentiation
:vartype StepSize: float | FloatKey
:ivar UseBandStructureInfoFromPath: 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.
:vartype UseBandStructureInfoFromPath: BoolType | BoolKey
"""
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='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.\n\nWith the effective mass option, this curvature is obtained by numerical differentiation.\n\nThe 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.', gui_name='Effective mass:', default=False)
self.KPointCoord: Iterable[float] | FloatListKey = FloatListKey(name='KPointCoord', comment='Coordinate of the k-points for which you would like to compute the effective mass.', unique=False, gui_name='At K-point:', unit='1/Bohr')
self.NumAbove: int | IntKey = IntKey(name='NumAbove', comment='Number of bands to take into account above the Fermi level.', gui_name='Include N bands above:', default=1)
self.NumBelow: int | IntKey = IntKey(name='NumBelow', comment='Number of bands to take into account below the Fermi level.', gui_name='Include N bands below:', default=1)
self.StepSize: float | FloatKey = FloatKey(name='StepSize', comment='Size of the step taken in reciprocal space to perform the numerical differentiation', default=0.001)
self.UseBandStructureInfoFromPath: BoolType | BoolKey = BoolKey(name='UseBandStructureInfoFromPath', comment='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.', default=True)
def __post_init__(self):
self.BZPath: DFTB._Periodic._BZPath = self._BZPath(name='BZPath', comment='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.')
self.BandStructure: DFTB._Periodic._BandStructure = self._BandStructure(name='BandStructure', comment='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).]')
self.DOS: DFTB._Periodic._DOS = self._DOS(name='DOS', comment='The subkeys of [DOS] allow to customize the calculation of the density of states.')
self.EffectiveMass: DFTB._Periodic._EffectiveMass = self._EffectiveMass(name='EffectiveMass', comment='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.\n\nWith the effective mass option, this curvature is obtained by numerical differentiation.\n\nThe 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.')
[docs] class _Properties(FixedBlock):
r"""
DFTB can calculate various properties of the simulated system. This block configures which properties will be calculated.
:ivar NBOInput: 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.
:vartype NBOInput: BoolType | BoolKey
:ivar Excitations: Contains all options related to the calculation of excited states, either as simple single orbitals transitions or from a TD-DFTB calculation.
:vartype Excitations: DFTB._Properties._Excitations
:ivar Fragments: Fragment files
:vartype Fragments: DFTB._Properties._Fragments
:ivar RESPONSE: Linear response module to compute electric (complex) polarizabilities
:vartype RESPONSE: DFTB._Properties._RESPONSE
"""
[docs] class _Excitations(FixedBlock):
r"""
Contains all options related to the calculation of excited states, either as simple single orbitals transitions or from a TD-DFTB calculation.
:ivar SingleOrbTrans: 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.
:vartype SingleOrbTrans: DFTB._Properties._Excitations._SingleOrbTrans
:ivar TDDFTB: 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.
:vartype TDDFTB: DFTB._Properties._Excitations._TDDFTB
:ivar TDDFTBGradients: 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.
:vartype TDDFTBGradients: DFTB._Properties._Excitations._TDDFTBGradients
"""
[docs] class _SingleOrbTrans(FixedBlock):
r"""
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.
:ivar Enabled: Calculate the single orbital transitions.
:vartype Enabled: BoolType | BoolKey
:ivar PrintLowest: 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.
:vartype PrintLowest: int | IntKey
:ivar Filter: This section allows to remove single orbital transitions based on certain criteria. All filters are disabled by default.
:vartype Filter: DFTB._Properties._Excitations._SingleOrbTrans._Filter
"""
[docs] class _Filter(FixedBlock):
r"""
This section allows to remove single orbital transitions based on certain criteria. All filters are disabled by default.
:ivar MinPertCont: The energy range up to which SOTs are considered primary in Grimme's sTDA based filter.
:vartype MinPertCont: float | FloatKey
:ivar OSMin: 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.
:vartype OSMin: float | FloatKey
:ivar PrimRange: The energy range up to which SOTs are considered primary in Grimme's sTDA based filter.
:vartype PrimRange: float | FloatKey
:ivar UsePertCorr: The energy range up to which SOTs are considered primary in Grimme's sTDA based filter.
:vartype UsePertCorr: BoolType | BoolKey
:ivar dEMax: Removes single orbital transitions with an orbital energy difference larger than this threshold.
:vartype dEMax: float | FloatKey
:ivar dEMin: Removes single orbital transitions with an orbital energy difference smaller than this threshold.
:vartype dEMin: float | FloatKey
"""
def __post_init__(self):
self.MinPertCont: float | FloatKey = FloatKey(name='MinPertCont', comment="The energy range up to which SOTs are considered primary in Grimme's sTDA based filter.", hidden=True)
self.OSMin: float | FloatKey = FloatKey(name='OSMin', comment='Removes single orbital transitions with an oscillator strength smaller than this threshold.\n\nA typical value to start (if used at all) would be 1.0e-3.', gui_name='Minimum oscillator strength:')
self.PrimRange: float | FloatKey = FloatKey(name='PrimRange', comment="The energy range up to which SOTs are considered primary in Grimme's sTDA based filter.", hidden=True)
self.UsePertCorr: BoolType | BoolKey = BoolKey(name='UsePertCorr', comment="The energy range up to which SOTs are considered primary in Grimme's sTDA based filter.", hidden=True)
self.dEMax: float | FloatKey = FloatKey(name='dEMax', comment='Removes single orbital transitions with an orbital energy difference larger than this threshold.', unit='Hartree')
self.dEMin: float | FloatKey = FloatKey(name='dEMin', comment='Removes single orbital transitions with an orbital energy difference smaller than this threshold.', unit='Hartree')
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Calculate the single orbital transitions.', gui_name='Single orbital transisitions: Calculate', default=False)
self.PrintLowest: int | IntKey = IntKey(name='PrintLowest', comment='The number of single orbital transitions that are printed to the screen and written to disk.\n\nIf not a TD-DFTB calculation, the default is to print the 10 lowest single orbital transitions.\n\nIn 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.', default=10)
self.Filter: DFTB._Properties._Excitations._SingleOrbTrans._Filter = self._Filter(name='Filter', comment='This section allows to remove single orbital transitions based on certain criteria. All filters are disabled by default.')
[docs] class _TDDFTB(FixedBlock):
r"""
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.
:ivar ATChargeAnalysis: Which analysis method to use for the calculation of the atomic transition charges.
:vartype ATChargeAnalysis: Literal["Mulliken", "Loewdin"]
:ivar Calc: Specifies the multiplicity of the excitations to be calculated.
:vartype Calc: Literal["None", "Singlet", "Triplet"]
:ivar Diagonalization: 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.
:vartype Diagonalization: Literal["Auto", "Davidson", "Exact"]
:ivar Lowest: 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.
:vartype Lowest: int | IntKey
:ivar Print: Specifies whether to print details on the contribution of the individual single orbital transitions to the calculated excitations.
:vartype Print: str | StringKey
:ivar ScaleKernel: 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)
:vartype ScaleKernel: float | FloatKey
:ivar UpTo: 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.
:vartype UpTo: float | FloatKey
:ivar DavidsonConfig: 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.
:vartype DavidsonConfig: DFTB._Properties._Excitations._TDDFTB._DavidsonConfig
"""
[docs] class _DavidsonConfig(FixedBlock):
r"""
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.
:ivar ATCharges: 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.
:vartype ATCharges: Literal["Precalc", "OnTheFly"]
:ivar SafetyMargin: 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.
:vartype SafetyMargin: int | IntKey
:ivar Tolerance: Convergence criterion for the norm of the residual.
:vartype Tolerance: float | FloatKey
"""
def __post_init__(self):
self.ATCharges: Literal["Precalc", "OnTheFly"] = MultipleChoiceKey(name='ATCharges', comment='Select whether the atomic transition charges are precalculated in advance or reevaluated during the iterations of the Davidson solver.\n\nPrecalculating the charges will improve the performance, but requires additional storage.\n\nThe default is to precalculate the atomic transition charges, but the precalculation may be disabled if not not enough memory is available.', gui_name='Transition charges:', default='Precalc', choices=['Precalc', 'OnTheFly'])
self.SafetyMargin: int | IntKey = IntKey(name='SafetyMargin', comment='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.', default=4)
self.Tolerance: float | FloatKey = FloatKey(name='Tolerance', comment='Convergence criterion for the norm of the residual.', default=1e-09)
def __post_init__(self):
self.ATChargeAnalysis: Literal["Mulliken", "Loewdin"] = MultipleChoiceKey(name='ATChargeAnalysis', comment='Which analysis method to use for the calculation of the atomic transition charges.', hidden=True, default='Mulliken', choices=['Mulliken', 'Loewdin'])
self.Calc: Literal["None", "Singlet", "Triplet"] = MultipleChoiceKey(name='Calc', comment='Specifies the multiplicity of the excitations to be calculated.', gui_name='Type of excitations:', default='None', choices=['None', 'Singlet', 'Triplet'])
self.Diagonalization: Literal["Auto", "Davidson", "Exact"] = MultipleChoiceKey(name='Diagonalization', comment='Select the method used to solve the TD-DFTB eigenvalue equation.\n\nThe 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.\n\nThe alternative is the iterative Davidson method, which finds a few of the lowest excitations within an error tolerance without ever storing the full matrix.\n\nThe default is to make this decision automatically based on the system size and the requested number of excitations.', gui_name='Method:', default='Auto', choices=['Auto', 'Davidson', 'Exact'])
self.Lowest: int | IntKey = IntKey(name='Lowest', comment='Specifies the number of excitations that are calculated.\n\nNote 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.\n\nAlso 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.', gui_name='Number of excitations:', default=10)
self.Print: str | StringKey = StringKey(name='Print', comment='Specifies whether to print details on the contribution of the individual single orbital transitions to the calculated excitations.')
self.ScaleKernel: float | FloatKey = FloatKey(name='ScaleKernel', comment='Set the scaling parameter of the response kernel.\n\nA 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)', default=1.0, unit='None')
self.UpTo: float | FloatKey = FloatKey(name='UpTo', comment='Set the maximum excitation energy.\n\nAttempts 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.\n\nNote 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.', gui_name='Excitations up to:', unit='Hartree')
self.DavidsonConfig: DFTB._Properties._Excitations._TDDFTB._DavidsonConfig = self._DavidsonConfig(name='DavidsonConfig', comment='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.')
[docs] class _TDDFTBGradients(FixedBlock):
r"""
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.
:ivar Eigenfollow: 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.
:vartype Eigenfollow: BoolType | BoolKey
:ivar Excitation: 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.
:vartype Excitation: Iterable[int] | IntListKey
"""
def __post_init__(self):
self.Eigenfollow: BoolType | BoolKey = BoolKey(name='Eigenfollow', comment='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.', gui_name='Follow initial excitation:', default=False)
self.Excitation: Iterable[int] | IntListKey = IntListKey(name='Excitation', comment='Select which excited states to calculate the gradients for.\n\nGradients can only be calculated for an excited states that has been calculated using TD-DFTB. Make sure that enough excitations are calculated.', gui_name=' Excitation number:')
def __post_init__(self):
self.SingleOrbTrans: DFTB._Properties._Excitations._SingleOrbTrans = self._SingleOrbTrans(name='SingleOrbTrans', comment='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.')
self.TDDFTB: DFTB._Properties._Excitations._TDDFTB = self._TDDFTB(name='TDDFTB', comment='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.')
self.TDDFTBGradients: DFTB._Properties._Excitations._TDDFTBGradients = self._TDDFTBGradients(name='TDDFTBGradients', comment='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.')
[docs] class _Fragments(FixedBlock):
r"""
Fragment files
:ivar Analysis: Mulliken population analysis in terms of fragment orbitals.
:vartype Analysis: BoolType | BoolKey
:ivar EMax: Upper end of the energy interval for which the orbitals are analyzed.
:vartype EMax: float | FloatKey
:ivar Emin: Lower end of the energy interval for which the orbitals are analyzed.
:vartype Emin: float | FloatKey
:ivar File: Path (either absolute or relative) of fragment file
:vartype File: str | StringKey
:ivar TIDegeneracyThreshold: 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.
:vartype TIDegeneracyThreshold: float | FloatKey
:ivar TransferIntegrals: Calculate the charge transfer integrals, spatial overlap integrals and site energies.
Charge transfer integrals can be used in models that calculate transport properties.
:vartype TransferIntegrals: BoolType | BoolKey
"""
def __post_init__(self):
self.Analysis: BoolType | BoolKey = BoolKey(name='Analysis', comment='Mulliken population analysis in terms of fragment orbitals.', gui_name='Fragment analysis:', default=True)
self.EMax: float | FloatKey = FloatKey(name='EMax', comment='Upper end of the energy interval for which the orbitals are analyzed.', default=0.25, unit='Hartree')
self.Emin: float | FloatKey = FloatKey(name='Emin', comment='Lower end of the energy interval for which the orbitals are analyzed.', default=-0.75, unit='Hartree')
self.File: str | StringKey = StringKey(name='File', comment='Path (either absolute or relative) of fragment file', unique=False)
self.TIDegeneracyThreshold: float | FloatKey = FloatKey(name='TIDegeneracyThreshold', comment='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.', default=0.1, unit='eV')
self.TransferIntegrals: BoolType | BoolKey = BoolKey(name='TransferIntegrals', comment='Calculate the charge transfer integrals, spatial overlap integrals and site energies.\n\nCharge transfer integrals can be used in models that calculate transport properties.', gui_name='Charge transfer integrals:', default=False)
[docs] class _RESPONSE(FixedBlock):
r"""
Linear response module to compute electric (complex) polarizabilities
:ivar ATChargeAnalysis: Which analysis method to use for the calculation of the atomic transition charges.
:vartype ATChargeAnalysis: Literal["Mulliken", "Loewdin"]
:ivar Frequencies: List of frequencies of incident light
:vartype Frequencies: Iterable[float] | FloatListKey
:ivar LifeTime: Phenomenological damping
:vartype LifeTime: float | FloatKey
:ivar Solver: Solver details for CPKS
:vartype Solver: DFTB._Properties._RESPONSE._Solver
"""
[docs] class _Solver(FixedBlock):
r"""
Solver details for CPKS
:ivar Algorithm: Choice of solver for CPKS
:vartype Algorithm: Literal["EXACT", "ITER"]
:ivar Debug: Print technical information from solver
:vartype Debug: BoolType | BoolKey
:ivar NumIt: Maximum number of iterations (ITER solver only)
:vartype NumIt: int | IntKey
:ivar RMSE: Threshold for convergence (ITER solver only)
:vartype RMSE: float | FloatKey
"""
def __post_init__(self):
self.Algorithm: Literal["EXACT", "ITER"] = MultipleChoiceKey(name='Algorithm', comment='Choice of solver for CPKS', default='EXACT', choices=['EXACT', 'ITER'])
self.Debug: BoolType | BoolKey = BoolKey(name='Debug', comment='Print technical information from solver', default=False)
self.NumIt: int | IntKey = IntKey(name='NumIt', comment='Maximum number of iterations (ITER solver only)', default=100)
self.RMSE: float | FloatKey = FloatKey(name='RMSE', comment='Threshold for convergence (ITER solver only)', default=1e-06)
def __post_init__(self):
self.ATChargeAnalysis: Literal["Mulliken", "Loewdin"] = MultipleChoiceKey(name='ATChargeAnalysis', comment='Which analysis method to use for the calculation of the atomic transition charges.', hidden=True, default='Mulliken', choices=['Mulliken', 'Loewdin'])
self.Frequencies: Iterable[float] | FloatListKey = FloatListKey(name='Frequencies', comment='List of frequencies of incident light', default=[0.0], unit='eV')
self.LifeTime: float | FloatKey = FloatKey(name='LifeTime', comment='Phenomenological damping', unit='Hartree')
self.Solver: DFTB._Properties._RESPONSE._Solver = self._Solver(name='Solver', comment='Solver details for CPKS')
def __post_init__(self):
self.NBOInput: BoolType | BoolKey = BoolKey(name='NBOInput', comment='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.', default=False)
self.Excitations: DFTB._Properties._Excitations = self._Excitations(name='Excitations', comment='Contains all options related to the calculation of excited states, either as simple single orbitals transitions or from a TD-DFTB calculation.', extra_info='not_in_fragment')
self.Fragments: DFTB._Properties._Fragments = self._Fragments(name='Fragments', comment='Fragment files')
self.RESPONSE: DFTB._Properties._RESPONSE = self._RESPONSE(name='RESPONSE', comment='Linear response module to compute electric (complex) polarizabilities')
[docs] class _QMFQ(FixedBlock):
r"""
Block input key for QM/FQ(FMu).
:ivar DEBUG: The DEBUG subkey will print additional information from the FQ subroutines.
:vartype DEBUG: BoolType | BoolKey
:ivar Forcefield: Version of the FQ family of polarizable forcefields
:vartype Forcefield: Literal["FQ", "FQ_RQ", "FQFMU", "FQFMU_RQRMU", "NOPOL"]
:ivar Frozen: Expert option. Do not introduce polarization effect in response calculations.
:vartype Frozen: BoolType | BoolKey
:ivar Kernel: 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.
:vartype Kernel: Literal["OHNO", "COUL", "GAUS"]
:ivar MolCharge: Total charge of each fragment (FQ only)
:vartype MolCharge: float | FloatKey
:ivar NOGROUNDSTATE: Avoid introducing FQ effects on ground state calculations
:vartype NOGROUNDSTATE: BoolType | BoolKey
:ivar NonEle: Whether to include non-electrostatic contributions to the energy. Default is the Lennard-Jones (LJ) model.
:vartype NonEle: Literal["LJ", "None"]
:ivar QMSCREEN: 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.
:vartype QMSCREEN: Literal["ERF", "EXP", "GAUS", "NONE"]
:ivar QMSCREENFACTOR: 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.
:vartype QMSCREENFACTOR: float | FloatKey
:ivar AtomType: Definition of atomic types in MM environment
:vartype AtomType: DFTB._QMFQ._AtomType
:ivar Coords: Coordinates and fragment information (FQ only)
:vartype Coords: str | Sequence[str] | FreeBlock
:ivar Solver:
:vartype Solver: DFTB._QMFQ._Solver
"""
[docs] class _AtomType(FixedBlock):
r"""
Definition of atomic types in MM environment
:ivar Alpha: Polarizability of FQFMU atom
:vartype Alpha: float | FloatKey
:ivar Charge: MM fixed charge (non-polarizable only)
:vartype Charge: float | FloatKey
:ivar Chi: Electronegativity of FQ atom
:vartype Chi: float | FloatKey
:ivar Eta: Chemical Hardness of FQ atom
:vartype Eta: float | FloatKey
:ivar RMU: Variance for FQFMU_RQRMU Gaussians
:vartype RMU: float | FloatKey
:ivar RQ: Variance for FQ_RQ Gaussians
:vartype RQ: float | FloatKey
:ivar Symbol: Symbol associated with atom type
:vartype Symbol: str | StringKey
"""
def __post_init__(self):
self.Alpha: float | FloatKey = FloatKey(name='Alpha', comment='Polarizability of FQFMU atom')
self.Charge: float | FloatKey = FloatKey(name='Charge', comment='MM fixed charge (non-polarizable only)')
self.Chi: float | FloatKey = FloatKey(name='Chi', comment='Electronegativity of FQ atom')
self.Eta: float | FloatKey = FloatKey(name='Eta', comment='Chemical Hardness of FQ atom')
self.RMU: float | FloatKey = FloatKey(name='RMU', comment='Variance for FQFMU_RQRMU Gaussians', hidden=True)
self.RQ: float | FloatKey = FloatKey(name='RQ', comment='Variance for FQ_RQ Gaussians', hidden=True)
self.Symbol: str | StringKey = StringKey(name='Symbol', comment='Symbol associated with atom type')
[docs] class _Coords(FreeBlock):
r"""
Coordinates and fragment information (FQ only)
"""
def __post_init__(self):
pass
[docs] class _Solver(FixedBlock):
r"""
:ivar Algorithm:
:vartype Algorithm: Literal["DIRECT", "ITER"]
:ivar Debug:
:vartype Debug: BoolType | BoolKey
:ivar NumIt:
:vartype NumIt: int | IntKey
:ivar THRESH:
:vartype THRESH: float | FloatKey
"""
def __post_init__(self):
self.Algorithm: Literal["DIRECT", "ITER"] = MultipleChoiceKey(name='Algorithm', default='DIRECT', choices=['DIRECT', 'ITER'])
self.Debug: BoolType | BoolKey = BoolKey(name='Debug', default=False)
self.NumIt: int | IntKey = IntKey(name='NumIt', default=100)
self.THRESH: float | FloatKey = FloatKey(name='THRESH', default=1e-06)
def __post_init__(self):
self.DEBUG: BoolType | BoolKey = BoolKey(name='DEBUG', comment='The DEBUG subkey will print additional information from the FQ subroutines.', hidden=True, default=False)
self.Forcefield: Literal["FQ", "FQ_RQ", "FQFMU", "FQFMU_RQRMU", "NOPOL"] = MultipleChoiceKey(name='Forcefield', comment='Version of the FQ family of polarizable forcefields', default='FQ', choices=['FQ', 'FQ_RQ', 'FQFMU', 'FQFMU_RQRMU', 'NOPOL'], hiddenchoices=['FQ_RQ', 'FQFMU_RQRMU', 'NOPOL'])
self.Frozen: BoolType | BoolKey = BoolKey(name='Frozen', comment='Expert option. Do not introduce polarization effect in response calculations.', default=False)
self.Kernel: Literal["OHNO", "COUL", "GAUS"] = MultipleChoiceKey(name='Kernel', comment='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. ', default='OHNO', choices=['OHNO', 'COUL', 'GAUS'])
self.MolCharge: float | FloatKey = FloatKey(name='MolCharge', comment='Total charge of each fragment (FQ only)', default=0.0)
self.NOGROUNDSTATE: BoolType | BoolKey = BoolKey(name='NOGROUNDSTATE', comment='Avoid introducing FQ effects on ground state calculations', hidden=True, default=False)
self.NonEle: Literal["LJ", "None"] = MultipleChoiceKey(name='NonEle', comment='Whether to include non-electrostatic contributions to the energy. Default is the Lennard-Jones (LJ) model.', default='LJ', choices=['LJ', 'None'])
self.QMSCREEN: Literal["ERF", "EXP", "GAUS", "NONE"] = MultipleChoiceKey(name='QMSCREEN', comment='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.', default='GAUS', choices=['ERF', 'EXP', 'GAUS', 'NONE'])
self.QMSCREENFACTOR: float | FloatKey = FloatKey(name='QMSCREENFACTOR', comment='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.', default=0.2)
self.AtomType: DFTB._QMFQ._AtomType = self._AtomType(name='AtomType', comment='Definition of atomic types in MM environment', unique=False)
self.Coords: str | Sequence[str] | FreeBlock = self._Coords(name='Coords', comment='Coordinates and fragment information (FQ only)')
self.Solver: DFTB._QMFQ._Solver = self._Solver(name='Solver', hidden=True)
[docs] class _Repulsion(FixedBlock):
r"""
Configures various details of the repulsive potential.
:ivar ForcePolynomial: Forces the use of the polynomial repulsion, even if a spline repulsion is present in the Slater-Koster files.
:vartype ForcePolynomial: BoolType | BoolKey
"""
def __post_init__(self):
self.ForcePolynomial: BoolType | BoolKey = BoolKey(name='ForcePolynomial', comment='Forces the use of the polynomial repulsion, even if a spline repulsion is present in the Slater-Koster files.', hidden=True, default=False)
[docs] class _SCC(FixedBlock):
r"""
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.
:ivar AdaptiveMixing: 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.
:vartype AdaptiveMixing: BoolType | BoolKey
:ivar AdaptiveMixingStrategy: Currently there are three flavors, 1, 2, and 3. The first is the most conservative. The difference between 2 and 3 is that number 3 decreases the mixing when the energy seems to go up.
:vartype AdaptiveMixingStrategy: int | IntKey
:ivar AlwaysClaimConvergence: Even if the SCC does not converge, claim convergence.
:vartype AlwaysClaimConvergence: BoolType | BoolKey
:ivar HXDamping: 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.
:vartype HXDamping: BoolType | BoolKey
:ivar InheritMixFromPreviousResult: 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.
:vartype InheritMixFromPreviousResult: BoolType | BoolKey
:ivar Iterations: 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.
:vartype Iterations: int | IntKey
:ivar Method: The DIIS option is the old method. The MultiStepper is much more flexible and is controlled by the SCFMultiSolver block
:vartype Method: Literal["DIIS", "MultiStepper"]
:ivar MinimumAdaptiveMixingFactor: In case of AdaptiveMixing the lower bound for the MixingFactor.
:vartype MinimumAdaptiveMixingFactor: float | FloatKey
:ivar MultiStepperPresetPath: 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'
:vartype MultiStepperPresetPath: str | Path | StringKey
:ivar OrbitalDependent: Activates or disables orbital resolved calculations. If this key is absent the recommended settings from the parameter file's metainfo.
:vartype OrbitalDependent: BoolType | BoolKey
:ivar PrintIterationDetails: Print nIterationsGlobal, etc. to standard output.
:vartype PrintIterationDetails: BoolType | BoolKey
:ivar SpinOrbit: test
:vartype SpinOrbit: BoolType | BoolKey
:ivar Unrestricted: 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.
:vartype Unrestricted: BoolType | BoolKey
:ivar Converge: Controls the convergence criteria of the SCC cycle.
:vartype Converge: DFTB._SCC._Converge
:ivar DIIS: Parameters influencing the DIIS self-consistency method
:vartype DIIS: DFTB._SCC._DIIS
:ivar SCFMultiStepper: To solve the self-consistent problem multiple steppers can be tried during stints using the ones that give the best progress.
:vartype SCFMultiStepper: DFTB._SCC._SCFMultiStepper
"""
[docs] class _Converge(FixedBlock):
r"""
Controls the convergence criteria of the SCC cycle.
:ivar Charge: The maximum change in atomic charges between subsequent SCC iterations. If the charges change less, the SCC cycle is considered converged.
:vartype Charge: float | FloatKey
:ivar Norm: 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).
:vartype Norm: Literal["L2", "L-Infinity"]
"""
def __post_init__(self):
self.Charge: float | FloatKey = FloatKey(name='Charge', comment='The maximum change in atomic charges between subsequent SCC iterations. If the charges change less, the SCC cycle is considered converged.', gui_name='Charge convergence:', default=1e-08)
self.Norm: Literal["L2", "L-Infinity"] = MultipleChoiceKey(name='Norm', comment='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). ', default='L-Infinity', choices=['L2', 'L-Infinity'])
[docs] class _DIIS(FixedBlock):
r"""
Parameters influencing the DIIS self-consistency method
:ivar Enabled: If not enabled simple mixing without DIIS acceleration will be used.
:vartype Enabled: BoolType | BoolKey
:ivar MaxSamples: 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.
:vartype MaxSamples: int | IntKey
:ivar MaximumCoefficient: 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.
:vartype MaximumCoefficient: float | FloatKey
:ivar MinSamples: 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.
:vartype MinSamples: int | IntKey
:ivar MixingFactor: 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.
:vartype MixingFactor: float | FloatKey
"""
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='If not enabled simple mixing without DIIS acceleration will be used.', default=True)
self.MaxSamples: int | IntKey = IntKey(name='MaxSamples', comment='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.', default=20)
self.MaximumCoefficient: float | FloatKey = FloatKey(name='MaximumCoefficient', comment='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.', default=10.0)
self.MinSamples: int | IntKey = IntKey(name='MinSamples', comment='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.', default=-1)
self.MixingFactor: float | FloatKey = FloatKey(name='MixingFactor', comment='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.', default=0.15)
[docs] class _SCFMultiStepper(FixedBlock):
r"""
To solve the self-consistent problem multiple steppers can be tried during stints using the ones that give the best progress.
:ivar AlwaysChangeStepper: 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.
:vartype AlwaysChangeStepper: BoolType | BoolKey
:ivar ErrorGrowthAbortFactor: Abort stint when the error grows too much, compared to the error at the start of the stint.
:vartype ErrorGrowthAbortFactor: float | FloatKey
:ivar FractionalStepFactor: Multiply the step by this factor. If smaller than zero this is not used.
:vartype FractionalStepFactor: float | FloatKey
:ivar MinStintCyclesForAbort: Look at ErrorGrowthAbortFactor only when a number of steps has been completed since the start of the stint. A value of 0 means always.
:vartype MinStintCyclesForAbort: int | IntKey
:ivar StintLength: A stepper is active during a number of SCF cycles, called a stint.
:vartype StintLength: int | IntKey
:ivar UsePreviousStintForErrorGrowthAbort: 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.
:vartype UsePreviousStintForErrorGrowthAbort: BoolType | BoolKey
:ivar Stepper: ??
:vartype Stepper: DFTB._SCC._SCFMultiStepper._Stepper
"""
[docs] class _Stepper(FixedBlock):
r"""
??
:ivar AbortSlope: If the slope (at the end of a stint) is larger than this: abort the stepper
:vartype AbortSlope: float | FloatKey
:ivar AlwaysAbortAtBeginOfStint: For debugging only: no matter what abort this stepper at the begin of the stint (doing only one step).
:vartype AlwaysAbortAtBeginOfStint: BoolType | BoolKey
:ivar AlwaysAbortAtEndOfStint: For debugging only: no matter what abort this stepper at the end of the stint.
:vartype AlwaysAbortAtEndOfStint: BoolType | BoolKey
:ivar ErrorGrowthAbortFactor: 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
:vartype ErrorGrowthAbortFactor: float | FloatKey
:ivar ExpectedSlope: If the slope of the total SCF is better than this keep on going.
:vartype ExpectedSlope: float | FloatKey
:ivar FractionalStepFactor: Multiply the step by this factor. If smaller than zero this is not used.
:vartype FractionalStepFactor: float | FloatKey
:ivar InitialMixFromPreviousStint: Similar to MixFromPreviousStint, but only done the first time that a stepper is used.
:vartype InitialMixFromPreviousStint: BoolType | BoolKey
:ivar MaxInitialError: Only use the stepper when error is smaller than this.
:vartype MaxInitialError: float | FloatKey
:ivar MaxIterationNumber: Stepper will only be active for iterations smaller than this number. (Negative value means: Ignore this option)
:vartype MaxIterationNumber: int | IntKey
:ivar MaxStintNumber: Stepper will only be active for stints smaller than this number. (Negative value means: Ignore this option)
:vartype MaxStintNumber: int | IntKey
:ivar MaxStints: Maximum number of stints that a stepper should be used.
:vartype MaxStints: int | IntKey
:ivar MinInitialError: Only use the stepper when error is larger than this.
:vartype MinInitialError: float | FloatKey
:ivar MinIterationNumber: Stepper will only be active for iterations larger than this number.
:vartype MinIterationNumber: int | IntKey
:ivar MinStintCyclesForAbort: 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.
:vartype MinStintCyclesForAbort: int | IntKey
:ivar MinStintNumber: Stepper will only be active for stints larger than this number.
:vartype MinStintNumber: int | IntKey
:ivar MixFromPreviousStint: When starting a new stint use the mix from the previous stepper, even if it is of another type.
:vartype MixFromPreviousStint: BoolType | BoolKey
:ivar StintLength: Override global StintLength.
:vartype StintLength: int | IntKey
:ivar DIISStepper: DIIS stepper
:vartype DIISStepper: DFTB._SCC._SCFMultiStepper._Stepper._DIISStepper
:ivar MixAdapter: Generic mix adapter
:vartype MixAdapter: DFTB._SCC._SCFMultiStepper._Stepper._MixAdapter
:ivar MixStepper: Simple mixing stepper, only using the previous (in/out) density.
:vartype MixStepper: DFTB._SCC._SCFMultiStepper._Stepper._MixStepper
:ivar MultiSecantStepper: Multi secant stepper.
:vartype MultiSecantStepper: DFTB._SCC._SCFMultiStepper._Stepper._MultiSecantStepper
"""
[docs] class _DIISStepper(FixedBlock):
r"""
DIIS stepper
:ivar EDIIS: Use energy DIIS. The energy is used as extra info and only interpolation is done (all coefficients in the interval [0,1]).
:vartype EDIIS: BoolType | BoolKey
:ivar EDIISAlpha: The extra energy vector is weighed by this factor. .
:vartype EDIISAlpha: float | FloatKey
:ivar MaxBMatrixRange: If larger than zero: limit the ratio between the oldest and last diagonal B matrix element.
:vartype MaxBMatrixRange: float | FloatKey
:ivar MaxCoefficient: The largest allowed value of the expansion coefficients. If exceed the number of vectors is reduces until the criterion is met.
:vartype MaxCoefficient: float | FloatKey
:ivar MaxConditionNumber: If larger than zero: check condition number of the B matrix. If too large reduce nVectors.
:vartype MaxConditionNumber: float | FloatKey
:ivar MaxVectors: Maximum number of previous densities to be used (size of the history).
:vartype MaxVectors: int | IntKey
:ivar MinLastCoefficient: If larger than zero: If the most recent vector gets a (abs) coefficient smaller than this the mix is boosted.
:vartype MinLastCoefficient: float | FloatKey
:ivar MinVectors: Try to prevent to make nVectors shrink below this value, by allowing for significantly larger coefficients.
:vartype MinVectors: int | IntKey
:ivar Mix: Also known as greed. It determines the amount of output density to be used. May be changed by the MixAdapter.
:vartype Mix: float | FloatKey
:ivar RescaleBMatrix: Rescale the B matrix so that is's values are of the same order as those of the constraints.
:vartype RescaleBMatrix: BoolType | BoolKey
:ivar UseHalfMixForFirstCycle: Use half the mix factor at iteration 1 (if applicable).
:vartype UseHalfMixForFirstCycle: BoolType | BoolKey
"""
def __post_init__(self):
self.EDIIS: BoolType | BoolKey = BoolKey(name='EDIIS', comment='Use energy DIIS. The energy is used as extra info and only interpolation is done (all coefficients in the interval [0,1]).', hidden=True, default=False)
self.EDIISAlpha: float | FloatKey = FloatKey(name='EDIISAlpha', comment='The extra energy vector is weighed by this factor. .', default=0.01)
self.MaxBMatrixRange: float | FloatKey = FloatKey(name='MaxBMatrixRange', comment='If larger than zero: limit the ratio between the oldest and last diagonal B matrix element.', hidden=True, default=-1.0)
self.MaxCoefficient: float | FloatKey = FloatKey(name='MaxCoefficient', comment='The largest allowed value of the expansion coefficients. If exceed the number of vectors is reduces until the criterion is met.', default=20.0)
self.MaxConditionNumber: float | FloatKey = FloatKey(name='MaxConditionNumber', comment='If larger than zero: check condition number of the B matrix. If too large reduce nVectors.', hidden=True, default=-1.0)
self.MaxVectors: int | IntKey = IntKey(name='MaxVectors', comment='Maximum number of previous densities to be used (size of the history).', default=10)
self.MinLastCoefficient: float | FloatKey = FloatKey(name='MinLastCoefficient', comment='If larger than zero: If the most recent vector gets a (abs) coefficient smaller than this the mix is boosted.', hidden=True, default=-1.0)
self.MinVectors: int | IntKey = IntKey(name='MinVectors', comment='Try to prevent to make nVectors shrink below this value, by allowing for significantly larger coefficients.', default=-1)
self.Mix: float | FloatKey = FloatKey(name='Mix', comment='Also known as greed. It determines the amount of output density to be used. May be changed by the MixAdapter.', default=0.2)
self.RescaleBMatrix: BoolType | BoolKey = BoolKey(name='RescaleBMatrix', comment="Rescale the B matrix so that is's values are of the same order as those of the constraints.", hidden=True, default=True)
self.UseHalfMixForFirstCycle: BoolType | BoolKey = BoolKey(name='UseHalfMixForFirstCycle', comment='Use half the mix factor at iteration 1 (if applicable).', hidden=True, default=True)
[docs] class _MixAdapter(FixedBlock):
r"""
Generic mix adapter
:ivar CorrelateMixWithSlope: For the last two mixing factors the one with the best slope is preferred.
:vartype CorrelateMixWithSlope: BoolType | BoolKey
:ivar ErrorGrowthPanicFactor: When the error increases more than this factor, this mix is reduced a lot.
:vartype ErrorGrowthPanicFactor: float | FloatKey
:ivar GrowWhenSpaceGrows: Has only effect when the error goes down. If nVectors increases grow the mix factor, otherwise do not change the mix
:vartype GrowWhenSpaceGrows: BoolType | BoolKey
:ivar GrowthFactor: When the mix is considered too low it is multiplied by this factor. Otherwise it is divided by it.
:vartype GrowthFactor: float | FloatKey
:ivar MaxMix: Do not grow the mix above this value.
:vartype MaxMix: float | FloatKey
:ivar MinMix: Do not shrink the mix below this value.
:vartype MinMix: float | FloatKey
:ivar NTrialMixFactors: Only used with Type=Trial. Must be an odd number.
:vartype NTrialMixFactors: int | IntKey
:ivar TrialMode: How are the NTrialMixFactors chosen?
:vartype TrialMode: Literal["CurrentMixCentered", "FullRange"]
:ivar Type: Adapt the mix factor based on the observed progress (slope).
:vartype Type: Literal["Error", "Energy", "UnpredictedStep", "Trial"]
"""
def __post_init__(self):
self.CorrelateMixWithSlope: BoolType | BoolKey = BoolKey(name='CorrelateMixWithSlope', comment='For the last two mixing factors the one with the best slope is preferred.', hidden=True, default=False)
self.ErrorGrowthPanicFactor: float | FloatKey = FloatKey(name='ErrorGrowthPanicFactor', comment='When the error increases more than this factor, this mix is reduced a lot.', default=10.0)
self.GrowWhenSpaceGrows: BoolType | BoolKey = BoolKey(name='GrowWhenSpaceGrows', comment='Has only effect when the error goes down. If nVectors increases grow the mix factor, otherwise do not change the mix', hidden=True, default=True)
self.GrowthFactor: float | FloatKey = FloatKey(name='GrowthFactor', comment='When the mix is considered too low it is multiplied by this factor. Otherwise it is divided by it.', default=1.1)
self.MaxMix: float | FloatKey = FloatKey(name='MaxMix', comment='Do not grow the mix above this value.', default=0.3)
self.MinMix: float | FloatKey = FloatKey(name='MinMix', comment='Do not shrink the mix below this value.', default=0.1)
self.NTrialMixFactors: int | IntKey = IntKey(name='NTrialMixFactors', comment='Only used with Type=Trial. Must be an odd number.', default=3)
self.TrialMode: Literal["CurrentMixCentered", "FullRange"] = MultipleChoiceKey(name='TrialMode', comment='How are the NTrialMixFactors chosen?', default='CurrentMixCentered', choices=['CurrentMixCentered', 'FullRange'])
self.Type: Literal["Error", "Energy", "UnpredictedStep", "Trial"] = MultipleChoiceKey(name='Type', comment='Adapt the mix factor based on the observed progress (slope).', default='Error', choices=['Error', 'Energy', 'UnpredictedStep', 'Trial'])
[docs] class _MixStepper(FixedBlock):
r"""
Simple mixing stepper, only using the previous (in/out) density.
:ivar Mix: ???.
:vartype Mix: float | FloatKey
"""
def __post_init__(self):
self.Mix: float | FloatKey = FloatKey(name='Mix', comment='???.', default=0.1)
[docs] class _MultiSecantStepper(FixedBlock):
r"""
Multi secant stepper.
:ivar AlphaMSR1: For the MSR1 variant: W = Y + alpha S.
:vartype AlphaMSR1: float | FloatKey
:ivar MaxCoefficient: ???.
:vartype MaxCoefficient: float | FloatKey
:ivar MaxConditionNumber: If set larger than zero this condition number of the matrix to be inverted will be checked. If exceeded the space is reduced.
:vartype MaxConditionNumber: float | FloatKey
:ivar MaxVectors: ???.
:vartype MaxVectors: int | IntKey
:ivar Mix: ???.
:vartype Mix: float | FloatKey
:ivar PredictGreed: Try to predict the optimal greed.
:vartype PredictGreed: BoolType | BoolKey
:ivar ScaleYTY: Scale matrix before inversion
:vartype ScaleYTY: BoolType | BoolKey
:ivar SigmaRegularize: Prevent division by zero by adding a small number. Makes most sense when using renormalization.
:vartype SigmaRegularize: float | FloatKey
:ivar Variant: There are several version of the Multi secant method.
:vartype Variant: Literal["MSB1", "MSB2", "MSR1", "MSR1s"]
"""
def __post_init__(self):
self.AlphaMSR1: float | FloatKey = FloatKey(name='AlphaMSR1', comment='For the MSR1 variant: W = Y + alpha S.', hidden=True, default=0.1)
self.MaxCoefficient: float | FloatKey = FloatKey(name='MaxCoefficient', comment='???.', default=20.0)
self.MaxConditionNumber: float | FloatKey = FloatKey(name='MaxConditionNumber', comment='If set larger than zero this condition number of the matrix to be inverted will be checked. If exceeded the space is reduced.', hidden=True, default=-1.0)
self.MaxVectors: int | IntKey = IntKey(name='MaxVectors', comment='???.', default=10)
self.Mix: float | FloatKey = FloatKey(name='Mix', comment='???.', default=0.2)
self.PredictGreed: BoolType | BoolKey = BoolKey(name='PredictGreed', comment='Try to predict the optimal greed.', hidden=True, default=False)
self.ScaleYTY: BoolType | BoolKey = BoolKey(name='ScaleYTY', comment='Scale matrix before inversion', hidden=True, default=True)
self.SigmaRegularize: float | FloatKey = FloatKey(name='SigmaRegularize', comment='Prevent division by zero by adding a small number. Makes most sense when using renormalization.', hidden=True, default=1e-12)
self.Variant: Literal["MSB1", "MSB2", "MSR1", "MSR1s"] = MultipleChoiceKey(name='Variant', comment='There are several version of the Multi secant method.', default='MSB2', choices=['MSB1', 'MSB2', 'MSR1', 'MSR1s'])
def __post_init__(self):
self.AbortSlope: float | FloatKey = FloatKey(name='AbortSlope', comment='If the slope (at the end of a stint) is larger than this: abort the stepper', default=100.0)
self.AlwaysAbortAtBeginOfStint: BoolType | BoolKey = BoolKey(name='AlwaysAbortAtBeginOfStint', comment='For debugging only: no matter what abort this stepper at the begin of the stint (doing only one step).', hidden=True, default=False)
self.AlwaysAbortAtEndOfStint: BoolType | BoolKey = BoolKey(name='AlwaysAbortAtEndOfStint', comment='For debugging only: no matter what abort this stepper at the end of the stint.', hidden=True, default=False)
self.ErrorGrowthAbortFactor: float | FloatKey = FloatKey(name='ErrorGrowthAbortFactor', comment='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', default=-1.0)
self.ExpectedSlope: float | FloatKey = FloatKey(name='ExpectedSlope', comment='If the slope of the total SCF is better than this keep on going.', default=-100.0)
self.FractionalStepFactor: float | FloatKey = FloatKey(name='FractionalStepFactor', comment='Multiply the step by this factor. If smaller than zero this is not used.', default=-1.0)
self.InitialMixFromPreviousStint: BoolType | BoolKey = BoolKey(name='InitialMixFromPreviousStint', comment='Similar to MixFromPreviousStint, but only done the first time that a stepper is used.', hidden=True, default=False)
self.MaxInitialError: float | FloatKey = FloatKey(name='MaxInitialError', comment='Only use the stepper when error is smaller than this.')
self.MaxIterationNumber: int | IntKey = IntKey(name='MaxIterationNumber', comment='Stepper will only be active for iterations smaller than this number. (Negative value means: Ignore this option)', default=-1)
self.MaxStintNumber: int | IntKey = IntKey(name='MaxStintNumber', comment='Stepper will only be active for stints smaller than this number. (Negative value means: Ignore this option)', default=-1)
self.MaxStints: int | IntKey = IntKey(name='MaxStints', comment='Maximum number of stints that a stepper should be used.', hidden=True, default=-1)
self.MinInitialError: float | FloatKey = FloatKey(name='MinInitialError', comment='Only use the stepper when error is larger than this.')
self.MinIterationNumber: int | IntKey = IntKey(name='MinIterationNumber', comment='Stepper will only be active for iterations larger than this number.', default=-1)
self.MinStintCyclesForAbort: int | IntKey = IntKey(name='MinStintCyclesForAbort', comment='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.', default=0)
self.MinStintNumber: int | IntKey = IntKey(name='MinStintNumber', comment='Stepper will only be active for stints larger than this number.', default=-1)
self.MixFromPreviousStint: BoolType | BoolKey = BoolKey(name='MixFromPreviousStint', comment='When starting a new stint use the mix from the previous stepper, even if it is of another type.', hidden=True, default=False)
self.StintLength: int | IntKey = IntKey(name='StintLength', comment='Override global StintLength.')
self.DIISStepper: DFTB._SCC._SCFMultiStepper._Stepper._DIISStepper = self._DIISStepper(name='DIISStepper', comment='DIIS stepper')
self.MixAdapter: DFTB._SCC._SCFMultiStepper._Stepper._MixAdapter = self._MixAdapter(name='MixAdapter', comment='Generic mix adapter')
self.MixStepper: DFTB._SCC._SCFMultiStepper._Stepper._MixStepper = self._MixStepper(name='MixStepper', comment='Simple mixing stepper, only using the previous (in/out) density.')
self.MultiSecantStepper: DFTB._SCC._SCFMultiStepper._Stepper._MultiSecantStepper = self._MultiSecantStepper(name='MultiSecantStepper', comment='Multi secant stepper.')
def __post_init__(self):
self.AlwaysChangeStepper: BoolType | BoolKey = BoolKey(name='AlwaysChangeStepper', comment='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.', default=False)
self.ErrorGrowthAbortFactor: float | FloatKey = FloatKey(name='ErrorGrowthAbortFactor', comment='Abort stint when the error grows too much, compared to the error at the start of the stint.', default=1000.0)
self.FractionalStepFactor: float | FloatKey = FloatKey(name='FractionalStepFactor', comment='Multiply the step by this factor. If smaller than zero this is not used.', default=-1.0)
self.MinStintCyclesForAbort: int | IntKey = IntKey(name='MinStintCyclesForAbort', comment='Look at ErrorGrowthAbortFactor only when a number of steps has been completed since the start of the stint. A value of 0 means always.', default=0)
self.StintLength: int | IntKey = IntKey(name='StintLength', comment='A stepper is active during a number of SCF cycles, called a stint.', default=10)
self.UsePreviousStintForErrorGrowthAbort: BoolType | BoolKey = BoolKey(name='UsePreviousStintForErrorGrowthAbort', comment='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.', default=False)
self.Stepper: DFTB._SCC._SCFMultiStepper._Stepper = self._Stepper(name='Stepper', comment='??', unique=False, header=True)
def __post_init__(self):
self.AdaptiveMixing: BoolType | BoolKey = BoolKey(name='AdaptiveMixing', comment='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.', default=True)
self.AdaptiveMixingStrategy: int | IntKey = IntKey(name='AdaptiveMixingStrategy', comment='Currently there are three flavors, 1, 2, and 3. The first is the most conservative. The difference between 2 and 3 is that number 3 decreases the mixing when the energy seems to go up.', hidden=True, default=3)
self.AlwaysClaimConvergence: BoolType | BoolKey = BoolKey(name='AlwaysClaimConvergence', comment='Even if the SCC does not converge, claim convergence.', default=False)
self.HXDamping: BoolType | BoolKey = BoolKey(name='HXDamping', comment='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.')
self.InheritMixFromPreviousResult: BoolType | BoolKey = BoolKey(name='InheritMixFromPreviousResult', comment='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.\nAlso the last mix factor from the previous result can be loaded, possibly speeding up the SCC.', default=False)
self.Iterations: int | IntKey = IntKey(name='Iterations', comment='Allows to specify the maximum number of SCC iterations. The default should suffice for most standard calculations.\n\nConvergence 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.\n\nChoosing 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.', default=500)
self.Method: Literal["DIIS", "MultiStepper"] = MultipleChoiceKey(name='Method', comment='The DIIS option is the old method. The MultiStepper is much more flexible and is controlled by the SCFMultiSolver block', default='MultiStepper', choices=['DIIS', 'MultiStepper'])
self.MinimumAdaptiveMixingFactor: float | FloatKey = FloatKey(name='MinimumAdaptiveMixingFactor', comment='In case of AdaptiveMixing the lower bound for the MixingFactor.', default=0.003)
self.MultiStepperPresetPath: str | Path | StringKey = PathStringKey(name='MultiStepperPresetPath', comment="Name of file containing a SCFMultiStepper key block. This will be used if no Explicit SCFMultiStepper block is in the input, and Method=MultiStepper.\nIf the path is not absolute, it is relative to $AMSHOME/data/presets/multi_stepper'", default='DFTB/default2023.inc', ispath=True, gui_type='{} {} data/presets/multi_stepper relative')
self.OrbitalDependent: BoolType | BoolKey = BoolKey(name='OrbitalDependent', comment="Activates or disables orbital resolved calculations. If this key is absent the recommended settings from the parameter file's metainfo.")
self.PrintIterationDetails: BoolType | BoolKey = BoolKey(name='PrintIterationDetails', comment='Print nIterationsGlobal, etc. to standard output.', hidden=True, default=False)
self.SpinOrbit: BoolType | BoolKey = BoolKey(name='SpinOrbit', comment='test', default=False)
self.Unrestricted: BoolType | BoolKey = BoolKey(name='Unrestricted', comment='Enables spin unrestricted calculations.\n\nOnly collinear spin polarization is supported, see Theor Chem Acc (2016) 135: 232, for details.\n\nMust be supported by the chosen parameter set. Not yet compatible with DFTB3, k-space sampling periodic calculations or the xTB models.', default=False)
self.Converge: DFTB._SCC._Converge = self._Converge(name='Converge', comment='Controls the convergence criteria of the SCC cycle.')
self.DIIS: DFTB._SCC._DIIS = self._DIIS(name='DIIS', comment='Parameters influencing the DIIS self-consistency method')
self.SCFMultiStepper: DFTB._SCC._SCFMultiStepper = self._SCFMultiStepper(name='SCFMultiStepper', comment='To solve the self-consistent problem multiple steppers can be tried during stints using the ones that give the best progress.', extra_info='not_in_fragment')
[docs] class _Solvation(FixedBlock):
r"""
Generalized Born solvation model with Solvent Accessible Surface Area (GBSA).
:ivar GSolvState: Reference state for solvation free energy shift.
:vartype GSolvState: Literal["Gas1BarSolvent", "Gas1MSolvent1M", "Gas1BarSolvent1M"]
:ivar Solvent: Solvent used in the GBSA implicit solvation model.
:vartype Solvent: Literal["None", "Acetone", "Acetonitrile", "Benzene", "CH2Cl2", "CHCl3", "CS2", "DMSO", "Ether", "H2O", "Methanol", "THF", "Toluene"]
:ivar SurfaceGrid: 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.
:vartype SurfaceGrid: Literal["230", "974", "2030", "5810"]
:ivar Temperature: The temperature used when calculating the solvation free energy shift. Only used for 'Gas1BarSolvent' and 'Gas1BarSolvent1M' GSolvState options.
:vartype Temperature: float | FloatKey
:ivar UseGSASA: Include shift term and G(SASA) terms in the energy and gradient.
:vartype UseGSASA: BoolType | BoolKey
"""
def __post_init__(self):
self.GSolvState: Literal["Gas1BarSolvent", "Gas1MSolvent1M", "Gas1BarSolvent1M"] = MultipleChoiceKey(name='GSolvState', comment='Reference state for solvation free energy shift.', default='Gas1MSolvent1M', choices=['Gas1BarSolvent', 'Gas1MSolvent1M', 'Gas1BarSolvent1M'])
self.Solvent: Literal["None", "Acetone", "Acetonitrile", "Benzene", "CH2Cl2", "CHCl3", "CS2", "DMSO", "Ether", "H2O", "Methanol", "THF", "Toluene"] = MultipleChoiceKey(name='Solvent', comment='Solvent used in the GBSA implicit solvation model.', default='None', choices=['None', 'Acetone', 'Acetonitrile', 'Benzene', 'CH2Cl2', 'CHCl3', 'CS2', 'DMSO', 'Ether', 'H2O', 'Methanol', 'THF', 'Toluene'], hiddenchoices=['Benzene', 'CH2Cl2'])
self.SurfaceGrid: Literal["230", "974", "2030", "5810"] = MultipleChoiceKey(name='SurfaceGrid', comment='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.', default='230', choices=['230', '974', '2030', '5810'])
self.Temperature: float | FloatKey = FloatKey(name='Temperature', comment="The temperature used when calculating the solvation free energy shift. Only used for 'Gas1BarSolvent' and 'Gas1BarSolvent1M' GSolvState options.", default=298.15, unit='Kelvin')
self.UseGSASA: BoolType | BoolKey = BoolKey(name='UseGSASA', comment='Include shift term and G(SASA) terms in the energy and gradient.', gui_name='Solvation Free Energy:', default=True)
[docs] class _Technical(FixedBlock):
r"""
This optional section is about technical aspects of the program that should not concern the normal user.
:ivar AnalyticalStressTensor: 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.
:vartype AnalyticalStressTensor: BoolType | BoolKey
:ivar AssumeInsulator: (Expert option) Assume that the material has only fully occupied bands. Only relevant for periodic structures. If you know the material is an insulator this can be a bit faster. Use with care.
:vartype AssumeInsulator: BoolType | BoolKey
:ivar MatricesViaFullMaxSize: Matrices smaller than this size are constructed via a full matrix. This is faster, but uses more memory in the construction.
:vartype MatricesViaFullMaxSize: int | IntKey
:ivar ReuseKSpaceConfig: 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.
:vartype ReuseKSpaceConfig: BoolType | BoolKey
:ivar UseGeneralizedDiagonalization: Whether or not to use generalized diagonalization. Does not affect the results, but might be faster or slower.
:vartype UseGeneralizedDiagonalization: BoolType | BoolKey
:ivar EwaldSummation: Configures the details of the Ewald summation of the Coulomb interaction.
:vartype EwaldSummation: DFTB._Technical._EwaldSummation
:ivar Parallel: Calculation of the orbitals in several k-points is trivially parallel.
:vartype Parallel: DFTB._Technical._Parallel
:ivar Screening: 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.
:vartype Screening: DFTB._Technical._Screening
"""
[docs] class _EwaldSummation(FixedBlock):
r"""
Configures the details of the Ewald summation of the Coulomb interaction.
:ivar CellRangeFactor: Smaller values will make the Ewald summation less accurate but faster.
:vartype CellRangeFactor: float | FloatKey
:ivar Enabled: Whether to use Ewald summation for the long-range part of the Coulomb interaction. Otherwise screening is used.
:vartype Enabled: BoolType | BoolKey
:ivar Tolerance: Larger values will make the Ewald summation less accurate but faster.
:vartype Tolerance: float | FloatKey
"""
def __post_init__(self):
self.CellRangeFactor: float | FloatKey = FloatKey(name='CellRangeFactor', comment='Smaller values will make the Ewald summation less accurate but faster.', default=2.0)
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Whether to use Ewald summation for the long-range part of the Coulomb interaction. Otherwise screening is used.', default=True)
self.Tolerance: float | FloatKey = FloatKey(name='Tolerance', comment='Larger values will make the Ewald summation less accurate but faster.', default=1e-10)
[docs] class _Parallel(FixedBlock):
r"""
Calculation of the orbitals in several k-points is trivially parallel.
:ivar nCoresPerGroup: Number of cores in each working group.
:vartype nCoresPerGroup: int | IntKey
:ivar nGroups: Total number of processor groups. This is the number of tasks that will be executed in parallel.
:vartype nGroups: int | IntKey
:ivar nNodesPerGroup: 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.
:vartype nNodesPerGroup: int | IntKey
"""
def __post_init__(self):
self.nCoresPerGroup: int | IntKey = IntKey(name='nCoresPerGroup', comment='Number of cores in each working group.')
self.nGroups: int | IntKey = IntKey(name='nGroups', comment='Total number of processor groups. This is the number of tasks that will be executed in parallel.')
self.nNodesPerGroup: int | IntKey = IntKey(name='nNodesPerGroup', comment='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.', gui_name='Cores per task:')
[docs] class _Screening(FixedBlock):
r"""
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.
:ivar DirectionalScreening:
:vartype DirectionalScreening: BoolType | BoolKey
:ivar dMadel: Sets the smoothness of the screening function. The default is 1/10 of [rMadel].
:vartype dMadel: float | FloatKey
:ivar rMadel: Sets the range of the screening function. The default is 2x the norm of the longest lattice vector.
:vartype rMadel: float | FloatKey
"""
def __post_init__(self):
self.DirectionalScreening: BoolType | BoolKey = BoolKey(name='DirectionalScreening', hidden=True, default=True)
self.dMadel: float | FloatKey = FloatKey(name='dMadel', comment='Sets the smoothness of the screening function. The default is 1/10 of [rMadel].', unit='Bohr')
self.rMadel: float | FloatKey = FloatKey(name='rMadel', comment='Sets the range of the screening function. The default is 2x the norm of the longest lattice vector.', unit='Bohr')
def __post_init__(self):
self.AnalyticalStressTensor: BoolType | BoolKey = BoolKey(name='AnalyticalStressTensor', comment='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.', default=True)
self.AssumeInsulator: BoolType | BoolKey = BoolKey(name='AssumeInsulator', comment='(Expert option) Assume that the material has only fully occupied bands. Only relevant for periodic structures. If you know the material is an insulator this can be a bit faster. Use with care.', hidden=True, default=False)
self.MatricesViaFullMaxSize: int | IntKey = IntKey(name='MatricesViaFullMaxSize', comment='Matrices smaller than this size are constructed via a full matrix. This is faster, but uses more memory in the construction.', default=2047)
self.ReuseKSpaceConfig: BoolType | BoolKey = BoolKey(name='ReuseKSpaceConfig', comment='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.', default=True)
self.UseGeneralizedDiagonalization: BoolType | BoolKey = BoolKey(name='UseGeneralizedDiagonalization', comment='Whether or not to use generalized diagonalization. Does not affect the results, but might be faster or slower.', default=True)
self.EwaldSummation: DFTB._Technical._EwaldSummation = self._EwaldSummation(name='EwaldSummation', comment='Configures the details of the Ewald summation of the Coulomb interaction.')
self.Parallel: DFTB._Technical._Parallel = self._Parallel(name='Parallel', comment='Calculation of the orbitals in several k-points is trivially parallel.')
self.Screening: DFTB._Technical._Screening = self._Screening(name='Screening', comment='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.')
[docs] class _XTBConfig(FixedBlock):
r"""
This block allows for minor tweaking.
:ivar SlaterRadialThreshold: 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.
:vartype SlaterRadialThreshold: float | FloatKey
:ivar useXBTerm: Whether to use the Halogen bonding (XB) term. This is not advised as it has a non-continuous PES.
:vartype useXBTerm: BoolType | BoolKey
"""
def __post_init__(self):
self.SlaterRadialThreshold: float | FloatKey = FloatKey(name='SlaterRadialThreshold', comment='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.', default=1e-05)
self.useXBTerm: BoolType | BoolKey = BoolKey(name='useXBTerm', comment='Whether to use the Halogen bonding (XB) term. This is not advised as it has a non-continuous PES.', default=False)
def __post_init__(self):
self.DispersionCorrection: Literal["None", "Auto", "UFF", "ULG", "D2", "D3-BJ", "D4"] = MultipleChoiceKey(name='DispersionCorrection', comment="This key is used to specify an empirical dispersion model. Please refer to the DFTB documentation for details on the different methods.\n\nBy 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.", gui_name='Dispersion:', default='None', choices=['None', 'Auto', 'UFF', 'ULG', 'D2', 'D3-BJ', 'D4'])
self.Model: Literal["DFTB", "DFTB0", "DFTB1", "SCC-DFTB", "DFTB2", "DFTB3", "GFN1-xTB", "NonSCC-GFN1-xTB"] = MultipleChoiceKey(name='Model', comment="Selects the Hamiltonian used in the DFTB calculation:\n- DFTB/DFTB0/DFTB1 for classic DFTB without a self-consistent charge cycle\n- SCC-DFTB/DFTB2 with a self-consistency loop for the Mulliken charges\n- DFTB3 for additional third-order contributions.\n- GFN1-xTB for Grimme's extended tight-binding model in the GFN1 version.\n- NonSCC-GFN1-xTB for a less accurate but faster version of GFN1-xTB without a self-consistency cycle\n\nThe choice has to be supported by the selected parameter set.", default='GFN1-xTB', choices=['DFTB', 'DFTB0', 'DFTB1', 'SCC-DFTB', 'DFTB2', 'DFTB3', 'GFN1-xTB', 'NonSCC-GFN1-xTB'], hiddenchoices=['DFTB0', 'DFTB1', 'DFTB2'], gui_type='literal choices')
self.NumericalQuality: Literal["Basic", "Normal", "Good", "VeryGood", "Excellent"] = MultipleChoiceKey(name='NumericalQuality', comment="Set the quality of some technical aspects of a DFTB calculation. It sets the quality of: KSpace (reciprocal space integration). Note: the quality defined in the block of a specific technical aspects supersedes the value defined in NumericalQuality (e.g. if I specify 'NumericalQuality Basic' and 'KSpace%Quality Good', the quality of the KSpace will be 'Good')", hidden=True, default='Normal', choices=['Basic', 'Normal', 'Good', 'VeryGood', 'Excellent'])
self.RadialExtrapolation: Literal["Auto", "ScreenTail", "None", "Linear", "Original", "Improved", "Bezier"] = MultipleChoiceKey(name='RadialExtrapolation', comment='Advanced control option. Overrides the extrapolation method for Slater-Koster grid values between the end of the tabulated grid and the cutoff distance (value for which atoms are considered too far to interact). Depending on the structure of your Slater-Koster tables, a different radial extrapolation method may be needed in order to guarantee correct behavior, in particular for large and periodic systems. See the DFTB documentation for a description of the various available methods.', hidden=True, default='Auto', choices=['Auto', 'ScreenTail', 'None', 'Linear', 'Original', 'Improved', 'Bezier'])
self.ResourcesDir: str | Path | StringKey = PathStringKey(name='ResourcesDir', comment='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.', ispath=True, rootdir='DFTB')
self.StoreMatrices: BoolType | BoolKey = BoolKey(name='StoreMatrices', comment='Determines whether the Hamiltonian and overlap matrices are stored in the binary result file.', default=False, extra_info='not_in_fragment')
self.StoreOrbitals: BoolType | BoolKey = BoolKey(name='StoreOrbitals', comment='Determines whether the orbital coefficients are stored in the binary result file. They are needed for displaying orbitals and densities in amsview.', default=True, extra_info='not_in_fragment')
self.UnpairedElectrons: int | IntKey = IntKey(name='UnpairedElectrons', comment='This specifies the number of unpaired electrons (not the multiplicity!).\n\nThis 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.\n\nNote that this does not activate spin polarization, it only affects the filling of the orbitals.', gui_name='Spin polarization:', default=0)
self.UseSymmetry: BoolType | BoolKey = BoolKey(name='UseSymmetry', hidden=True)
self.KSpace: DFTB._KSpace = self._KSpace(name='KSpace', comment='Options for the k-space integration (i.e. the grid used to sample the Brillouin zone)')
self.Occupation: DFTB._Occupation = self._Occupation(name='Occupation', comment='Configures the details of how the molecular orbitals are occupied with electrons.', extra_info='not_in_fragment')
self.Periodic: DFTB._Periodic = self._Periodic(name='Periodic', comment='Block that sets various details of the calculation only relevant for periodic systems.')
self.Properties: DFTB._Properties = self._Properties(name='Properties', comment='DFTB can calculate various properties of the simulated system. This block configures which properties will be calculated.', extra_info='not_in_fragment')
self.QMFQ: DFTB._QMFQ = self._QMFQ(name='QMFQ', comment='Block input key for QM/FQ(FMu).', extra_info='not_in_fragment')
self.Repulsion: DFTB._Repulsion = self._Repulsion(name='Repulsion', comment='Configures various details of the repulsive potential.')
self.SCC: DFTB._SCC = self._SCC(name='SCC', comment='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.', extra_info='not_in_fragment')
self.Solvation: DFTB._Solvation = self._Solvation(name='Solvation', comment='Generalized Born solvation model with Solvent Accessible Surface Area (GBSA).', extra_info='not_in_fragment')
self.Technical: DFTB._Technical = self._Technical(name='Technical', comment='This optional section is about technical aspects of the program that should not concern the normal user.')
self.XTBConfig: DFTB._XTBConfig = self._XTBConfig(name='XTBConfig', comment='This block allows for minor tweaking.')
