.. _chapter_charges:

********************************************************************************
Formal and Partial Charges
********************************************************************************

.. index:: formal charge, partial charge

Each :oe:cls:`OEAtomBase<OEChem::OEAtomBase>` keeps track of two types of charges:  

* The first, **formal charge**, is an integer property that is essential for the correct 
  valence representation of a molecule.  
  Together with atomic valences, bond order and the connectivity, this field 
  defines the identity of a molecule.

* The second type of charge, **partial charge**, is a floating 
  point property used in computational chemistry and molecular modeling.  
  This value is used to represent the electronic distribution/wave-function of a 
  molecule by approximating the molecule's electrostatic field with a set of point
  charges located at each atom.

.. list-table::
   :widths: 30 15 20 20 
   :header-rows: 1

   * - Property Name
     - Type
     - Get Method
     - Set Method
   * - Formal Charge
     - integer
     - :oe:meth:`GetFormalCharge<OEChem::OEAtomBase::GetFormalCharge>`
     - :oe:meth:`SetFormalCharge<OEChem::OEAtomBase::SetFormalCharge>`
   * - Partial Charge
     - double
     - :oe:meth:`GetPartialCharge<OEChem::OEAtomBase::GetPartialCharge>`
     - :oe:meth:`SetPartialCharge<OEChem::OEAtomBase::SetPartialCharge>`

Neither the formal charge nor the partial charge is a directly observable property 
of an atom.  
Instead the same molecule may be represented by different valence representations, 
each placing the formal charges in different locations, *i.e.* different partial 
charging algorithms may assign significantly different partial charges to the same atom
(for example benzene can be represented as ``[cH+]1[cH-][cH+][cH-][cH+][cH-]1``)


Formal Charges Assignment
================================================================================

Normally, file formats such as SMILES, SLN or MDL's SDF format, specify the formal 
charges on each atom of a connection table.  
However, when reading from other file formats or when repairing 'broken' molecules, 
it may be convenient to assign formal charges to each atom such that the atomic
valence is consistent.  
**OEChem TK** provides this functionality via the 
:oe:func:`OEAssignFormalCharges<OEChem::OEAssignFormalCharges>` function.  
This function requires that bond orders and implicit hydrogen counts have been set 
on a molecule.  
It then adjusts the formal charge on each uncharged atom to correct common valence
model mismatches.  
For example, quaternary nitrogens are assigned a +1 formal charge, and terminal 
oxygen connected only by a single bond (with no implicit hydrogens) is assigned a 
-1 formal charge.

A more technical discussion of the formal charges that are assigned by
this function are described in the :ref:`subsection_valence_openeye_charge`
section.

.. _section_charges_Gasteiger:

Gasteiger Partial Charge Calculation
================================================================================

.. index:: Gasteiger charge

To assign Marsilli-Gasteiger partial charges to a molecule, **OEChem TK** provides the 
:oe:func:`OEGasteigerPartialCharges<OEChem::OEGasteigerPartialCharges>` function.  
This sets the partial charge property of each atom, using the 
:oe:meth:`SetPartialCharge<OEChem::OEAtomBase::SetPartialCharge>` method.  
The algorithm itself reproduces the partial charges as calculated by Tripos Inc's Sybyl
software, with default parameter settings, which is the *de facto*
reference implementation for Gasteiger charges.

The Gasteiger partial charge algorithm currently assumes that all hydrogen atoms are 
represented explicitly, for example by calling 
:oe:func:`OEAddExplicitHydrogens<OEChem::OEAddExplicitHydrogens>`.

The current version of :oe:func:`OEGasteigerPartialCharges<OEChem::OEGasteigerPartialCharges>`
should return the same results independent of the currently assigned aromaticity 
models and the values of each  atom's "integer atom type" property.
Early versions of **OEChem TK** allowed customization of the Gasteiger charge calculation 
by explicitly assigning the Tripos atoms types of each atom of the molecule.  
Unfortunately, this required assigning Tripos' aromaticity and assigning Tripos 
atom types before each call to 
:oe:func:`OEGasteigerPartialCharges<OEChem::OEGasteigerPartialCharges>`.  
The more recent behavior is less error-prone (as it's no longer possible to forget 
to prepare a molecule) and greatly simplifies common usage.

The first stage of the Marsilli-Gasteiger *"Partial Equalization of Orbital 
Electronegativities"* (PEOE)" calculation [Gasteiger-1980]_  is assignment of
seed charges to each atom.  
Typically for neutral atoms the partial charge seed is zero, but for example, 
each oxygen in a carboxylate is assigned -0.5, and the net formal charge on 
conjugated rings is shared equally amongst the atoms of the ring system.  
These seed charges may also be useful in some applications, and can be assigned
using the :oe:func:`OEGasteigerInitialCharges<OEChem::OEGasteigerInitialCharges>` 
method.

.. seealso::

   * [Gasteiger-1978]_  
   * [Gasteiger-1980]_
 
