*****
DFTB+
*****

.. py:class:: DFTBplus

This interface supports energy and gradient evaluations with the
`DFTB+ <https://dftbplus.org/>`_ semi-empirical electronic structure package
(v20 or later).

A DFTB+ :ref:`Theory <theories>` object can be specified as follows::

  my_frag = Fragment(...)

  my_theory = DFTBplus(frag=my_frag,
                       ...)

which would then be called as ``theory=my_theory`` in subsequent tasks (see :ref:`Tasks <tasks>`).

Note that as it is a semi-empirical code, the DFTB+ interface will ignore
some keyword options that are common to other QM interfaces, such as
``basis``, ``ecp``, ``functional``, etc.


General options
===============

.. py:attribute:: method

   High-level method flag that will be used to set default parameters for the calculation. The value of ``skf_path`` should be set consistently.

   Allowed values:

   * ``'mio'``: (default) Slater-Koster parameters for "bio or organic molecules". Older than the newer 3ob set. 
   * ``'3ob'``: Slater-Koster parameters for third-order "bio and organic molecules". Intended to replace mio.
   * ``'matsci'`` : Slater-Koster parameters for "various problems in materials science".
   * ``'ob2'`` : Slater-Koster parameters for a "Long range corrected parameterization for bio and organic molecules"
   * ``'pbc'`` : Slater-Koster parameters for "solids and surfaces".

   If it is unambiguous, the method option will be used to set default values for ``max_angular_momentum``, ``hubbard_derivs``, ``spin_constants``, ``third_order`` and ``dispersion_param`` (although a dispersion correction will not be applied unless requested).
   Additional parameters may also be set on a case by case basis if the Slater-Koster parameter set instructions require them.

   Any options that have been set explicitly will over-write these defaults if they conflict.

.. py:attribute:: scc

   (default: ``True``) Use the Self-Consistent-Charge (SCC-DFTB) method.

.. py:attribute:: skf_path

   (default: ``''``) Path to directory containing Slater-Koster files (``*.skf``). These files can be downloaded from `https://dftb.org/parameters/download/ <https://dftb.org/parameters/download/>`_.


SCF options
===========

.. py:attribute:: hubbard_derivs

   (default: ``{}``) Hubbard derivatives for calculation of the 3rd order correction (if requested). These should be given as a dictionary, where a number is given for each elemental symbol in the calculation. The appropriate values depend on the Slater-Koster files employed, and default values will be set by the ``method`` option. For example, {'C':-0.1492}.

.. py:attribute:: hydrogen_correction

   Hydrogen correction to apply (if any).

   Allowed values:

   * ``''``: (default) No Hydrogen correction.
   * ``'damping'``: Damping method is applied to short-range interactions between Hydrogen-like atoms and other atoms.

.. py:attribute:: hydrogen_damping

   (default: 0.0) Damping factor applied when a damping Hydrogen correction is employed.

.. py:attribute:: max_angular_momentum

   (default: ``{}``) Dictionary containing the maximum angular momentum for each element in the calculation. Default values will be set by the ``method`` option. For example, {'H':'s', 'C':'p'}.

.. py:attribute:: maxiter

   (default: ``100``) Maximum SCC iterations allowed if using SCC-DFTB.

.. py:attribute:: smear

   (default: ``True``) Whether to apply smearing to the SCC occupation. DFTB+ refers to smearing as 'filling'.

.. py:attribute:: smear_method

   Smearing method to be applied when smearing is used.

   Allowed values:

   * ``'Fermi'``: (default) Apply a Fermi-Dirac distribution to the single electron states. 

   * ``'MethfesselPaxton'``: Apply a Methfessel-Paxton distribution to the single electron states, which can be an improvement for systems that require a high electronic temperature.

.. py:attribute:: smear_mp_order

   (default: ``2``) Order of the Methessel-Paxton smearing, if it is being employed.

.. py:attribute:: smear_temperature

   (default: ``'0.0'``) Electronic temperature for smearing, given in Kelvin.

.. py:attribite:: spin_constants

   (default: ``{}``) Additional parameters required for spin-polarised calculations. These should be given as a dictionary, where a string of shell resolved numbers is given for each elemental symbol in the calculation. The appropriate values depend on the Slater-Koster files employed, and default values will be set by the ``method`` option. For example, {'C':'-0.028  -0.024  -0.024  -0.022'}.

.. py:attribute:: third_order

   (defualt: ``None``) Whether to perform 3rd order DFTB. Default value depends on the ``method`` option. Corresponds to the ThirdOrderFull option in DFTB+.

   
Dispersion options
==================

   .. py:attribute:: dispersion

   Dispersion correction to apply (if any).

   Allowed values:

   * ``''`` : (default) No dispersion correction applied.
   * ``'LennardJones'`` : Dispersion is included via a Lennard-Jones potential between each pair of atoms. Parmeters are automatically taken from the Universal Force Field (UFF).
   * ``'D3'`` : The Grimme D3 correction. Parameters are defaulted from the ``method`` keyword, and can be modified using ``dispersion_param``.
   * ``'MBD'`` : Applies the Tkatchenko many-body-dispersion model.

.. py:attribute:: dispersion_param

   (default: ``{}``) A dictonary used to set parameters for dispersion corrections.

   Allowed keys:

   * ``'a1'``, ``'a2'``, ``'s6'``, ``'s8'`` : Parameters for the D3 dispersion correction.