************
Hybrid QM/MM
************

.. py:class:: QMMM

QM/MM calculations can be specified with the ``QMMM()`` class as follows::

  my_frag = Fragment(coords=...)

  my_qm = ...

  my_mm = ...

  my_qmmm = QMMM(frag=...,
                 qm_region=...,
                 qm=my_qm,
                 mm=my_mm,
                 ...)

where ``frag`` is a :py:class:`<class Fragment`> object, ``qm_region`` is a list of QM atoms, and
``qm`` and ``mm`` are `QM`_ and `MM interfaces`_ objects.

.. _`QM`: qm.html

.. _`MM interfaces`: mm.html

Once the :py:class:`QMMM` driver theory has been set up, it can be used in tasks like
any other theory object, e.g. for a single-point calculation::

  sp = SP(theory=qmmm, gradients=True)

  sp.run()

The following options relate to the standard additive QM/MM scheme which is the
scheme that is appropriate for most use cases including the solid state 
embedded cluster model. For other schemes, see the subsections:

.. toctree::
   :titlesonly:

   subtractive
   qmme



Additive QM/MM options
======================

.. py:attribute:: coupling

   Allowed values:

   * ``'covalent'``: (default) Covalent type of QM/MM coupling for which link atoms are automatically generated

   * ``'ionic'``: Ionic type of QM/MM coupling for which boundary pseudopotentials are expected

.. py:attribute:: dipole_adjust

   (default: ``False``) Adjust the dipoles accross the QM/MM boundary. See 

.. py:attribute:: embedding

   Allowed values:

   * ``'electrostatic'``: (default) Electrostatic embedding

   * ``'mechanical'``: Mechanical embedding

.. py:attribute:: mm

   `MM interfaces`_ object containing the details of the MM calculation

.. _`MM interfaces`: mm.html

.. py:attribute:: qm

   `QM interfaces`_ object containing the details of the QM calculation

.. _`QM interfaces`: qm.html

.. py:attribute:: qm_region

   List of atom indices in the QM region: nested lists are accecpted, for example::

    QMMM(qm_region=[range(6),12,18,[25,27]])

   is equivalent to::

    QMMM(qm_region=[0,1,2,3,4,5,12,18,25,27])

.. note:: Python counts from 0!

.. py:attribute:: restart

   (default: ``False``) Restart from a previous calculation, for both QM and MM

.. py:attribute:: scheme

   We do not yet support the conventional subtractive QM/MM scheme, while we strongly
   recommend to use the additive one.

   Allowed values:

   * ``'additive'``: (default) The additive QM/MM scheme

   * ``'qm/me'``: The QM/Me scheme: see :ref:`QM/Me <qmme>`

.. py:attribute:: separate_ecps

   (default: ``False``) Use separate boundary ECPs in ionic embedded cluster calculations

.. py:attribute:: shl_maxcycles

   (default: ``5``) Maximum number of self-consistent shell relaxation cycles
   in shell model QM/MM.

.. py:attribute:: shl_tolerance

   (default: ``0.0001``) Threshold for convergence of shell relaxation cycles
   in shell model QM/MM.