.. include:: ../common/cookbook/cookbook-hyperlinks

.. _chapter_ring:

********************************************************************************
Ring Perception
********************************************************************************

.. index:: ring processing, ring membership, cyclic membership

.. _section_ring_cyclic_membership:

Cycle Membership
================================================================================

The simplest form of ring processing in **OEChem TK** is testing
whether an atom or bond is in a ring or not.
The **OEChem TK** function
:oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>` is
used to determine which atoms and bonds are members of one or more
rings and which are acyclic.  This function uses an efficient
:math:`O(n)` algorithm.  Once
:oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>` has
been called, an atom or bond can be tested for being in a ring by
calling the :oe:meth:`OEChem::OEAtomBase::IsInRing` or the
:oe:meth:`OEChem::OEBondBase::IsInRing` methods respectively.

The function
:oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>` is
called automatically by the high-level file read function
:oe:func:`OEReadMolecule<OEChem::OEReadMolecule>` and 
:oe:func:`OESmilesToMol<OEChem::OESmilesToMol>`.  
However, whenever you modify a molecule by adding or deleting bonds, you'll need to
explicitly call :oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>`.

The following two 'equivalent' code snippets demonstrate
how to loop over chain
atoms using the :oe:cls:`OEAtomIsInRing<OEChem::OEAtomIsInRing>`
functor and the :oe:meth:`IsInRing<OEChem::OEAtomBase::IsInRing>`
method of the :oe:cls:`OEAtomBase<OEChem::OEAtomBase>` class.

.. oe:source:: PerceiveRing.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RING-LOOP1

.. oe:source:: PerceiveRing.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RING-LOOP2

.. oe:source:: PerceiveRing.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RING-LOOP1

.. oe:source:: PerceiveRing.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RING-LOOP2

.. oe:source:: PerceiveRing.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RING-LOOP1

.. oe:source:: PerceiveRing.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RING-LOOP2

.. oe:source:: PerceiveRing.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RING-LOOP1

.. oe:source:: PerceiveRing.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RING-LOOP2

The chain/ring bonds of a molecule can similarly be accessed using the
:oe:cls:`OEBondIsInRing<OEChem::OEBondIsInRing>` functor and the
:oe:meth:`IsInRing<OEChem::OEBondBase::IsInRing>` method of the
:oe:cls:`OEBondBase<OEChem::OEBondBase>` class.
For more information about functors see chapter :ref:`chapter_predicates`.

The user can also set the atom and bond ring flags manually using the
:oe:meth:`OEChem::OEAtomBase::SetInRing` and
:oe:meth:`OEChem::OEBondBase::SetInRing` methods.

.. admonition:: Code Example

   * `Ring Perception`_ **OpenEye Python Cookbook** recipe

.. _section_ring_ringsize_membership:

Membership in a Given Ring Size
================================================================================

.. index:: SSSR, smallest set of smallest rings

It is also possible to use **OEChem TK** to determine whether an atom or a bond is in a ring
of a given size, using the :oe:func:`OEAtomIsInRingSize<OEChem::OEAtomIsInRingSize>`
and :oe:func:`OEBondIsInRingSize<OEChem::OEBondIsInRingSize>` functions.

Both of these functions require that
:oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>` has previously been
called on the molecule.
Both of these functions take the query ring size as an argument, which should
be greater than or equal to three.
The definition of ring or cycle is not based upon the  ''smallest set of smallest rings''
(SSSR), and the functions return true if there is a bonded path of *size* unique atoms
where each atom is bonded to the next and the last is bonded to the first.

It is often the case that atoms may be in different sized cycles at
the same time.  For example, one way to identify the ring fusion atoms
in indole (the fusion of a five-membered pyrrole ring and a six-membered
benzene ring) is the following:

.. oe:source:: PerceiveRing.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RING-SIZE

.. oe:source:: PerceiveRing.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RING-SIZE

.. oe:source:: PerceiveRing.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RING-SIZE

.. oe:source:: PerceiveRing.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RING-SIZE


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

   **The fused atoms in indole belong to both a five- and a six-membered rings**

**OEChem TK** also provides an additional pair of functions,
:oe:func:`OEAtomIsInAromaticRingSize<OEChem::OEAtomIsInAromaticRingSize>` and
:oe:func:`OEBondIsInAromaticRingSize<OEChem::OEBondIsInAromaticRingSize>`, to
determine whether an atom or bond is in an aromatic ring or cycle of a given size.
These behave identically to :oe:func:`OEAtomIsInRingSize<OEChem::OEAtomIsInRingSize>`
and :oe:func:`OEBondIsInRingSize<OEChem::OEBondIsInRingSize>` except that each ring bond
in the path/cycle must be aromatic.
In addition to :oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>`,
these functions also require the user to have called
:oe:func:`OEAssignAromaticFlags<OEChem::OEAssignAromaticFlags>`.

.. admonition:: Code Example

   * `Ring Perception`_ **OpenEye Python Cookbook** recipe

.. _section_ring_smallestring_membership:

Smallest Ring Membership
================================================================================

.. index:: smallest ring membership

In addition to determining whether an atom or a bond is in a ring or cycle of
a given size, it's often useful to know the size of the smallest ring or cycle
that an atom or bond is in.
To do this **OEChem TK** provides the functions
:oe:func:`OEAtomGetSmallestRingSize<OEChem::OEAtomGetSmallestRingSize>` and
:oe:func:`OEBondGetSmallestRingSize<OEChem::OEBondGetSmallestRingSize>`.
For acyclic atoms and bonds, these functions return the value zero.
For cyclic atoms and bonds, they return a value greater than or equal to
three.

.. oe:source:: PerceiveRing.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RING-SMALLEST-SIZE

.. oe:source:: PerceiveRing.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RING-SMALLEST-SIZE

.. oe:source:: PerceiveRing.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RING-SMALLEST-SIZE

.. oe:source:: PerceiveRing.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RING-SMALLEST-SIZE


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

   **OEAtomGetSmallestRingSize returns five for each heavy atom of norbornane**

.. admonition:: Code Example

   * `Ring Perception`_ **OpenEye Python Cookbook** recipe

.. _section_ring_system_components:

Connected Components Identification
================================================================================

.. index:: connected components identification

To aid in splitting molecules into discrete connected components, for
example to separate a parent compound from its salt, or a ligand from
a protein, **OEChem TK** provides the function
:oe:func:`OEDetermineComponents<OEChem::OEDetermineComponents>`.
This function arbitrarily assigns an integer index, starting from one, to
each disconnected part in the :oe:cls:`OEMolBase<OEChem::OEMolBase>`.

.. oe:language:: c++

   The user provides a pointer to an array of at least
   :oe:meth:`GetMaxAtomIdx<OEChem::OEMolBase::GetMaxAtomIdx>` unsigned ints,
   which is populated by the function.

On return this provides a mapping from each atom's index, obtained by
:oe:meth:`OEChem::OEAtomBase::GetIdx`, to its component index.
Unused atom indices are mapped to zero.
The function itself also returns the total number of components found, *i.e.*
the maximum part index stored in the array.
The following snippet provides a short example of how to use this function.


.. oe:source:: DetermineComponents.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-COMPONENTS

.. oe:source:: DetermineComponents.py
   :language: python
   :noindent:
   :frag:     SNIPPET-COMPONENTS

.. oe:source:: DetermineComponents.java
   :language: java
   :noindent:
   :frag:     SNIPPET-COMPONENTS

.. oe:source:: DetermineComponents.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-COMPONENTS


.. admonition:: Code Example

   * :ref:`section_example_oechem_parts2mols` **OEChem TK** example
   * `Ring Perception`_ **OpenEye Python Cookbook** recipe

.. _section_ring_system_identification:

Ring Systems Identification
================================================================================

.. index:: ring system identification, aromatic ring system identification

The **OEChem TK** function :oe:func:`OEChem::OEDetermineRingSystems`
and :oe:func:`OEChem::OEDetermineAromaticRingSystems`
behave very similarly to the :oe:func:`OEDetermineComponents<OEChem::OEDetermineComponents>`.
However, these functions return a mapping from atom indices to a ring or aromatic ring
system index, respectively (see example in :oe:src:`Listing 1<SNIPPET-PerceiveAromRingSystems>`).
These functions require that :oe:func:`OEFindRingAtomsAndBonds<OEChem::OEFindRingAtomsAndBonds>`
has been called previously. 
The function :oe:func:`OEChem::OEDetermineAromaticRingSystems` also requires
the aromaticity perception  by calling the :oe:func:`OEChem::OEAssignAromaticFlags` function.
The :oe:func:`OEChem::OESmilesToMol` used in the above example automatically calls 
both the :oe:func:`OEChem::OEFindRingAtomsAndBonds` and :oe:func:`OEChem::OEAssignAromaticFlags` 
functions.

When using the :oe:func:`OEDetermineRingSystems<OEChem::OEDetermineRingSystems>` function,
all acyclic atoms are mapped to the value zero.
When using the :oe:func:`OEDetermineAromaticRingSystems<OEChem::OEDetermineAromaticRingSystems>`
function, all aliphatic atoms are mapped to the value zero.


.. oe:source:: PerceiveAromRingSystems.cpp
   :language: c++
   :refnum:   1
   :caption:  Aromatic ring system identification
   :frag:     SNIPPET

.. oe:source:: PerceiveAromRingSystems.py
   :language: python
   :refnum:   1
   :caption:  Aromatic ring system identification
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-PerceiveAromRingSystems.py>`



.. oe:source:: PerceiveAromRingSystems.java
   :language: java
   :refnum:   1
   :caption:  Aromatic ring system identification
   :frag:     SNIPPET

.. oe:source:: PerceiveAromRingSystems.cs
   :language: csharp
   :refnum:   1
   :caption:  Aromatic ring system identification
   :frag:     SNIPPET

.. _figure_ring_aromsystems:

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

   **Example structure of aromatic ring system identification**


The output of :oe:src:`Listing 1<SNIPPET-PerceiveAromRingSystems>` is the following:

.. code-block:: bash

   Aliphatic atoms: 0 1 2 11 12 13 14
   Number of aromatic ring systems = 2
   1 . aromatic ring system: 3 4 5 6 7 8 9 10 21
   2 . aromatic ring system: 15 16 17 18 19 20

.. admonition:: Code Example

   * `Ring Perception`_ **OpenEye Python Cookbook** recipe

.. _section_sssr:

Smallest Set of Smallest Rings (SSSR) Considered Harmful
================================================================================

.. index:: SSSR

In graph-theoretical terms, a bond is considered cyclic if its removal from the
structure  would not lead to the structure being broken into separate components.
Despite this simple definition, a large number of algorithms for ring detection
exist.
(See article [Downs-1989]_ for an extensive and comparative review.)
The diversity and multitude of the ring perception methods derives from the
fact that, while determining whether an atom is part of a ring is a very simple
problem,  the identification of "chemically meaningful" rings among the potentially
large number of cyclic subgraphs of a molecular structure can be a surprisingly
complex task.

The *Smallest set of smallest rings* (SSSR) [Plotkin-1971]_  is the most broadly used
type of ring set in computational chemistry. However SSSR is not a unique subset
of all possible cycles of a molecule (see :ref:`Figure: Example of SSSR<figure_ring_sssr>`).
Obviously SSSR membership can not be used as a graph theoretical invariant in symmetry
perception.  Indeed the choice of which rings are part of the SSSR and which are not
is arbitrary, and often dependent upon the input order of the molecule.
Because of the potential ambiguity of SSSR, many alternative ring set definitions to SSSR
have been proposed over the years, including extended SSSR,
the set of "synthetically important" rings, the set of elementary rings (SER),
the essential set of essential rings (ESER), :math:`\kappa`-rings, etc...

.. _figure_ring_sssr:

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

   **Example of SSSR**
   *SSSR is not an invariant subset of all possible rings; (a), (b) and (c) depict the three equally valid SSSR of the bridged structure (on the left)*

We believe that it is a great service to our customers that we do not
include any SSSR functionality in **OEChem TK**.  This is a conscious (and
consensus) decision.  The forerunners of **OEChem TK**, Babel and OELib,
both contained efficient algorithms for determining SSSR, and these
remain freely available on the Internet today.  Furthermore, many
useful ring perception routines are available in **OEChem TK**, including:

* the ability to detect whether an atom or bond is acyclic or part of a ring
  (For more details on  :oe:meth:`OEChem::OEAtomBase::IsInRing` and
  :oe:meth:`OEChem::OEBondBase::IsInRing`, see section :ref:`section_ring_cyclic_membership`)

* the ability to detect whether an atom or a bond is in a ring of a particular size
  (For more details on :oe:func:`OEAtomIsInRingSize<OEChem::OEAtomIsInRingSize>` and
  :oe:func:`OEBondIsInRingSize<OEChem::OEBondIsInRingSize>`,
  see section :ref:`section_ring_ringsize_membership`)

* the ability to detect whether an atom or a bond is in an aromatic ring of a particular size
  (For more details on :oe:func:`OEAtomIsInAromaticRingSize<OEChem::OEAtomIsInAromaticRingSize>` and
  :oe:func:`OEBondIsInAromaticRingSize<OEChem::OEBondIsInAromaticRingSize>`,
  see section :ref:`section_ring_ringsize_membership`)

* the size of the smallest ring an atom or bond belongs to
  (For more details on :oe:func:`OEAtomGetSmallestRingSize<OEChem::OEAtomGetSmallestRingSize>`
  and :oe:func:`OEBondGetSmallestRingSize<OEChem::OEBondGetSmallestRingSize>`,
  see section :ref:`section_ring_smallestring_membership`)

* the ability to determine whether atoms belong to the same ring system
  (:oe:func:`OEDetermineRingSystems<OEChem::OEDetermineRingSystems>`)
  or the same aromatic ring system
  (:oe:func:`OEDetermineAromaticRingSystems<OEChem::OEDetermineAromaticRingSystems>`).
  See section :ref:`section_ring_system_identification` for more details.

.. seealso::

   * [Balducci-1994]_
   * [Baumer-1991]_
   * [Downs-1989]_
   * [Figueras-1996]_
   * [Fujita-1988]_
   * [Gasteiger-1979]_
   * [Hanser-1996]_
   * [Plotkin-1971]_
   * [Qian-1990]_
   * [Roos-Kozel-1981]_
   * [Takahashi-1994]_
   * [Zamora-1976]_


