**************
Charge Fitting
**************

.. py:class:: ChargeFitting

Charge fitting calculations can be carried out using the :py:obj:`ChargeFitting()` driver, which
expects a QM-level :ref:`Theory <theories>` object, e.g.::

  my_frag = Fragment(coords='my_frag.xyz')

  my_theory = GAMESS_UK(frag=my_frag,
                        method='dft',
                        functional='b3lyp',
                        basis='6-31g*')

  my_fit1 = ChargeFitting(theory=my_theory,
                          npoints=2400,
                          type='shell',
                          vdw_scale=1.5,
                          nlayers=2,
                          vdw_incr=0.2)

The charge fitting calculation is run with::

  my_job.run()

Then the resulting charges will be stored in :py:obj:`my_frag.charges` (see: `\<class Fragment\>`_).

.. _`\<class Fragment\>`: fragment.html

ChemShell implements the ESP and RESP charge fitting methods, which are based on fitting point charges
in the QM region such that the correct electrostatic potential is recovered far from the QM atoms.
ChemShell will construct a grid of points for evaluating the electrostatic potential automatically
based on the options supplied.

Methods
=======

.. py:method:: ChargeFitting.run()

   This will run the charge fitting optimisation, according to the supplied options.

Options
=======

The single-point driver takes the following arguments:

.. py:attribute:: theory

   Choose the QM theory by specifying a :ref:`Theory <theories>` instance.

.. py:attribute:: constraints
   :noindex:

   (default: ``[]``) Constraint definition.

.. py:attribute:: frozen

   (default: ``[]``) A list of indices of atoms to freeze.

.. py:attribute:: method
   :noindex:

   Allowed values:

   * ``'resp'``: (default) Kolllman's restrained electrostatic potential (RESP). See: C. I. Bayly, et al., J. Phys. Chem. 1993, 97, 10269

   * ``'esp'``: Earlier electrostatic potential (ESP) method. See: F. A. Momany, J. Phys. Chem. 1978, 82, 592

.. py:attribute:: tolerance
   :noindex:

   (default: ``1.0E-12``) Convergence tolerance for the charge fitting, applied to the norm of the gradient.

Electrostatic Grid
==================

These options control the generation of grid points for the sampling of the electrostatic potential. Appropriate values
will depend on the particular example being considered.

.. py:attribute:: type

  Allowed values:
  * ``'shell'``: (default) Uses shell-like grid points.

.. py:attribute:: nlayers

   (default: ``4``) Number of layers of grid points. Each layer is an individual shell of points.

.. py:attribute:: npoints

   (default: :py:attr:`200*theory.frag.natoms`) Number of grid points to generate.

.. py:attribute:: vdw_scale

   (default: ``1.2``) When determining the distance from electrostatic grid point to atoms, their van der Waals radius is multiplied by this number.

.. py:attribute:: vdw_incr

   (default: ``0.2``) Increment of van der Waals : :py:attr:`0.4/nlayers**0.5`

Optimisation
============

The following options enable greater control over the optimiser, if convergence is difficult to obtain.

.. py:attribute:: alpha

   (default: ``1.0``) Search direction for optimisation.

.. py:attribute:: conserve

   (default: ``10``) The charge conservation constraint is enforced every :py:attr:`conserve` cycles

.. py:attribute:: initial

   (default: ``[]``) Initial values for the charges being fitted. Can be given as a single value, or as a list for each atom individually.

.. py:attribute:: maxcycles
   :noindex:

   (default: ``10000``) Maximum number of iterations for the charge fitting algorithm.

.. py:attribute:: maxinners

   (default: ``10``)  Maximum number of inner iterations for the charge fitting algorithm.

.. py:attribute:: tol_inner

   (default: ``1.0E-5``) Convergence tolerance for inner iterations.

RESP
====

These options only apply to the RESP method.

.. py:attribute:: a

   (default: ``0.0005``) Constant :py:attr:`a` used in RESP method (in (Ha/*e*)**2).

.. py:attribute:: b

   (default: ``0.2``) Constant :py:attr:`b` used in RESP method (in elementary charge *e*).


