*************
QM interfaces
*************

This section describes the options in common to most QM interfaces.

In addition to these options, each QM interface may contain
options specific to that code. For details please see the individual
interface manual pages:

.. toctree::
   :titlesonly:

   castep
   cp2k
   dftbplus
   fhi-aims
   gamess-uk
   gaussian
   lsdalton
   mndo
   molpro
   nwchem
   orca
   pyscf
   turbomole

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

.. py:attribute:: basis

   (default: ``'3-21g'``) Basis set name or a filename (e.g., ``'my_basis.txt'``) of plain text containing basis set parameters. In the latter case, a basis set file can be generated from the 
   `Basis Set Exchange <https://www.basissetexchange.org/>`_.

   Py-ChemShell also supports the BSE (Basis Set Exchange) plugin. For installation please see :ref:`Installing ChemShell <install>`. In this case, the :py:attr:`basis` keyword argument can take a ChemShell :py:class:`BSE` instance as the value. For example, to simply specify a basis set name for all atoms::

    my_basis = addons.BSE('3-21g')
    my_qm = NWChem(frag=my_frag, method='dft', basis=my_basis)

   Or to use a hybrid basis set for various elements by a :py:class:`dict` (both element symbol and atomic number are accepted)::

    my_basis = addons.BSE({1:'3-21g', 'O':'6-31g*'})

   Or a hybrid basis set for various atom names (especially useful for calculating the :ref:`finite cluster model <cutting_clusters>`)::

    my_basis = addons.BSE({'Mg1':'cc-pvdz','O1':'aug-cc-pVDZ'})

   with a :py:class:`dict` specifying hybrid basis sets for various atom names. Or::

.. py:attribute:: charge

   (default: ``0``) Charge to be used in the QM calculation

   Allowed types of value:

   * A Python `int <https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex>`_ for an integer charge

   * A Python `float <https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex>`_ what will be rounded to the nearest integer charge

   * A Python `str <https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str>`_ being ``'automatic'`` or ``'dl_field'`` makes ChemShell determine the charge by summing up the formal charges (typically useful when charges are not initially available but assigned later by DL_FIELD in a QM/MM calculation)

.. py:attribute:: ecp
   :noindex:

   (default: ``''``) A filename (e.g., ``'my_ecp.txt'``) of plain text containing effective core potential (ECP) parameters.

.. py:attribute:: functional

   (default: ``'blyp'``) Choice of exchange-correlation functional in DFT calculations

.. py:attribute:: method

   Allowed values:

   * ``'dft'``: (default) Density functional theory (DFT) for quantum chemical method

   * ``'hf'``: Hartree-Fock method

.. py:attribute:: mult

   (default: ``1``) Spin multiplicity to be used in the QM calculation

.. py:attribute:: scftype

   Allowed values:

   * ``'rhf'``: (default) restricted HF (or DFT) for singlet systems of molecular orbital calculation

   * ``'uhf'``: unrestricted HF for higher spins

   * ``'rohf'``: restricted open-shell 

   * ``'rks'``, ``'uks'``, or ``'roks'``: may also be specified, with identical behaviour

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

.. py:attribute:: damping

   Allowed values:

   * ``True``: (default) Use damping during SCF iterations

   * ``False``: Do not use damping

.. py:attribute:: diis

   Allowed values:

   * ``True``: (default) Use DIIS during SCF iterations

   * ``False``: Do not use DIIS

.. py:attribute:: direct
   :noindex:

   Allowed values:

   * ``False``: (default) Switch off :py:attr:`direct`

   * ``True``: Request direct evaluation for a given wavefunction.

.. py:attribute:: guess
   :noindex:

   (default: ``''``) Free text input for initial guess: can be either Python multi-line string (such as ``'''...'''``) or a filename (e.g., ``'my_guess.txt'``) of plain text containing multi-line string.

.. py:attribute:: maxiter

   (default: ``100``) Maximum number of SCF cycles allowed

.. py:attribute:: path

   (default: ``''``) Path to the executable file for a system call

.. py:attribute:: pseudopotential

   (default: ``''``) Pseudopotential

   Allowed types of value:

   * A Python `str <https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str>`_ for pseudopotential name

   * A Python `dict <https://docs.python.org/3/library/stdtypes.html#mapping-types-dict>`_ of element---to---pseudopotential mapping

.. py:attribute:: restart

   Allowed values:

   * ``False``: (default) Not to restart from a saved wavefunction guess

   * ``True``: Restart from a saved wavefunction guess

.. py:attribute:: scf

   (default: ``1.0E-5``) Threshold for SCF convergence