.. include:: ../toolkit-substitutions

.. _chapter_connectivity:

********************************************************************************
Connectivity Perception
********************************************************************************

**OEChem TK** provides several functions for determining the connectivity and/or bond
orders from various input file formats.
For correct molecule processing, **OEChem TK** requires all the covalent bonds to be
represented in a molecule and each bond to have a defined bond order,
1 for single, 2 for double, 3 for triple and 4 for quadruple.
Given this explicit |Kekule| representation of a molecule, **OEChem TK** can perceive
and re-perceive high order attributes such as ring membership or aromaticity
as defined by different aromaticity models.

Alas, unlike MDL's SD file format, not all file formats explicitly specify a
|Kekule| form of a molecule with explicit bond orders.
The functions, described in this chapter, attempt to deduce such a representation
from the information that is available in such file formats.

.. _section_connectivity_from3d:

Connectivity From 3D Coordinates
================================================================================

For file formats that provide 3D coordinates, but not explicit bond information
(or only partial bond information), **OEChem TK** uses the
:oe:func:`OEDetermineConnectivity<OEChem::OEDetermineConnectivity>` function.
This function deduces the pattern of covalent bonding in a molecule from the
proximity of atoms.
Two atoms are considered bonded if they are located within the sum of their
covalent radii (:oe:func:`OEGetCovalentRadius<OEChem::OEGetCovalentRadius>`)
plus an additional "slop" factor of 0.45 Angstroms.


.. _figure_connectivity_nobond:

.. figure:: images/connectivity-01.png
   :scale:  100
   :align:  center

   *Example of 3D molecule with no explicit bond information*

:oe:func:`OEDetermineConnectivity<OEChem::OEDetermineConnectivity>` will not
create a bond between two atoms that are less than 0.4 Angstroms apart.
Such unreasonably short bond lengths indicate the structure is either severely
distorted, or doesn't have coordinate information at all.

All bonds created by :oe:func:`OEDetermineConnectivity<OEChem::OEDetermineConnectivity>`
have bond orders set to one.
To perceive bond order information, see **OEChem TK**'s
:oe:func:`OEPerceiveBondOrders<OEChem::OEPerceiveBondOrders>` function described
in the next section.

.. figure:: images/connectivity-02.png
   :scale:  100
   :align:  center

   *Example of 3D molecule with perceived bond connectivity*

The :oe:func:`OEDetermineConnectivity<OEChem::OEDetermineConnectivity>` function
checks whether a bond already exists between two atoms before creating a new
bond.
This allows this function to be used with file formats that may specify partial
connectivity, such as only multiple (double, triple or quadruple) bonds.

.. _section_connectivity_bond_order_perception:

Bond Order Perception
================================================================================

The :oe:func:`OEPerceiveBondOrders<OEChem::OEPerceiveBondOrders>` function is
used to deduce bond orders from the 3D coordinates and simple connectivity
of a molecule.
If the simple connectivity, *i.e.* bonds without bond orders isn't specified in
the input file, :oe:func:`OEDetermineConnectivity<OEChem::OEDetermineConnectivity>`
should be called first to deduce this information from the 3D coordinates.

.. figure:: images/connectivity-03.png
   :scale:  100
   :align:  center

   *Example of 3D molecule with perceived connectivity and bond order*

The following code snippet shows how to perceive connectivity and bond order if a
molecule has 3D information but no explicit bond information:

.. oe:source:: PerceiveConnectivity.cpp
   :language: c++
   :frag:     SNIPPET-CONNECT-PERCEIVE
   :noindent:

.. oe:source:: PerceiveConnectivity.py
   :language: python
   :frag:     SNIPPET-CONNECT-PERCEIVE
   :noindent:

.. oe:source:: PerceiveConnectivity.java
   :language: java
   :frag:     SNIPPET-CONNECT-PERCEIVE
   :noindent:

.. oe:source:: PerceiveConnectivity.cs
   :language: csharp
   :frag:     SNIPPET-CONNECT-PERCEIVE
   :noindent:

.. seealso::

   * :oe:func:`OEChem::OEDetermineConnectivity`
   * :oe:func:`OEChem::OEFindRingAtomsAndBonds`
   * :oe:func:`OEChem::OEPerceiveBondOrders`
   * :oe:func:`OEChem::OEAssignImplicitHydrogens`
   * :oe:func:`OEChem::OEAssignFormalCharges`


|Kekule| Form Assignment
================================================================================

.. index::  Kekule form, kekulization

A number of file formats don't represent a connection table as a
single representative |Kekule| form but instead denote some bonds,
such as those in benzene, as aromatic.  **OEChem TK** provides a method for
determining a valid, but arbitrary, |Kekule| form for such connection
tables using the :oe:func:`OEKekulize<OEChem::OEKekulize>` function
(see example in :ref:`Figure: Kekulization of
quinolin<figure_connectivity_kekule>`).  On input to
:oe:func:`OEKekulize<OEChem::OEKekulize>`, the integer bond type
property of each bond represents either the bond order (1 for single,
2 for double, 3 for triple or 4 for quadruple) or the value 5
indicating the bond is aromatic or resonant.  The algorithm sets the
bond order property from the bond type property, with the exception of
bond type 5, which is assigned a bond order of either 1 or 2
representing either a single or double bond.  The boolean return value
indicates whether a valid |Kekule| form could be assigned.

.. seealso::

   :oe:func:`OEKekulize<OEChem::OEKekulize>` function is normally only used by
   low-level file readers for interpreting input connection tables.
   To write out a |Kekule| SMILES string, the aromaticity atom and bond flags
   have to be cleared by the :oe:func:`OEClearAromaticFlags<OEChem::OEClearAromaticFlags>`
   function in order to consider a molecule as aliphatic with explicit bond order.
   See example code in :ref:`section_aromaticity_clearing`.

.. _figure_connectivity_kekule:

.. figure:: images/OEKekulize.*
   :scale:  100
   :align:  center

   **Kekulization of quinolin**

   *OEKekulize() function arbitrary generates one of the three valid Kekulé forms*

.. seealso::

   * [Baber-1992]_
   * [Hendlich-1997]_
   * [Kearsley-1993]_
   * [Labute-1996]_
   * [Meng-1991]_


.. _section_kekule_assignment_of_new_bonds:

|Kekule| Assignment of New Bonds
================================================================================

Molecules input to
:oe:func:`OEKekulize<OEChem::OEKekulize>` must have their integer bond type set.
The property of each bond represents either the bond order (1 for single,
2 for double, 3 for triple or 4 for quadruple) or the value 5 indicating
the bond is aromatic or resonant. When creating new atoms and bonds internally
the integer type is set to a default value of 0. The following code snippet
outlines how to prepare modified molecules by setting the bond int type so that
they can be passed to :oe:func:`OEKekulize<OEChem::OEKekulize>`:

.. oe:source:: PerceiveKekule.cpp
   :language: c++
   :frag:     SNIPPET-CORRECT-COMPLEX
   :noindent:

.. oe:source:: PerceiveKekule.py
   :language: python
   :frag:     SNIPPET-CORRECT-COMPLEX
   :noindent:

.. oe:source:: PerceiveKekule.java
   :language: java
   :frag:     SNIPPET-CORRECT-COMPLEX
   :noindent:

.. oe:source:: PerceiveKekule.cs
   :language: csharp
   :frag:     SNIPPET-CORRECT-COMPLEX
   :noindent:
