.. include:: ../toolkit-substitutions

.. _chapter_molctordtor:

********************************************************************************
Molecules
********************************************************************************

The :ref:`OEGraphMol <OEChem_OEGraphMol>` is the object
representing a molecule used in most example programs you will find in
**OEChem TK**'s example directories, or in the code examples of this
manual.  An :ref:`OEGraphMol <OEChem_OEGraphMol>` is a concrete class which can
be declared and used for most molecular functions in **OEChem TK**.  Much
of an :ref:`OEGraphMol <OEChem_OEGraphMol>`'s API is defined by the
:ref:`OEMolBase <OEChem_OEMolBase>` abstract base-class.  An
:ref:`OEGraphMol <OEChem_OEGraphMol>` can be passed to any function which takes
an :ref:`OEMolBase <OEChem_OEMolBase>` argument.

.. seealso::

   An :oe:cls:`OEGraphMol<OEChem::OEGraphMol>` contains atoms and
   bonds. Their access is discussed in chapter :ref:`chapter_atombondtraversal`.

.. _section_molctordtor_molcreatedestroy:

Construction and Destruction
================================================================================

.. oe:language:: c++

   **OEChem TK** molecules use C++ constructors and destructors, allowing
   them to be defined and used much like normal variables.  The
   following example represents the smallest possible **OEChem TK**
   program.  This creates a molecule called
   :oe:cls:`OEGraphMol<OEChem::OEGraphMol>` when the program is run,
   and destroys it automatically when the program finishes.

   .. oe:source:: CreateOEGraphMol.cpp
      :language: c++
      :caption:  Create a molecule
      :frag:     SNIPPET

   By using C++ constructors and destructors there is no need to
   explicitly call a function to allocate and initialize the molecule.
   There is also no need to explicitly de-initialize and destroy it
   when we're done.

   Of course, there may be times when it is necessary to create and
   destroy molecules dynamically.  This is possible using C++'s
   ``new`` and ``delete`` operators to allocate a molecule.

   .. oe:source:: CreateOEGraphMolPointer.cpp
      :language: c++
      :caption:  Allocate memory for a molecule
      :frag:     SNIPPET

   .. note::

      An :ref:`OEGraphMol <OEChem_OEGraphMol>` is essentially a smart pointer
      around any arbitrary :ref:`OEMolBase <OEChem_OEMolBase>`
      implementation. If dynamic allocation is truly needed it is
      often more beneficial to use the factory function
      :oe:func:`OEChem::OENewMolBase`.

.. oe:language:: python

   The example below represents the smallest possible Python **OEChem TK**
   program.  This program creates an :ref:`OEGraphMol <OEChem_OEGraphMol>` called
   ``mol`` when run.  When the program ends, Python automatically
   cleans up the molecule when there are no more references to it.

   .. oe:source:: CreateOEGraphMol.py
      :language: python
      :caption:  Create a molecule
      :frag:     SNIPPET

   There may be times when you want to delete (destroy) a molecule
   before the end of the script. This can be done by using the
   built-in command, ``del``.

   .. oe:source:: DestroyOEGraphMol.py
      :language: python
      :caption:  Destroy a molecule
      :frag:     SNIPPET

.. oe:language:: java

   The example below represents the smallest possible Java **OEChem TK**
   program.  This program creates an :ref:`OEGraphMol <OEChem_OEGraphMol>` called
   ``mol`` when run.  When the program ends, Java automatically
   cleans up the molecule when there are no more references to it.

   .. oe:source:: CreateOEGraphMol.java
      :language: java
      :caption:  Create a molecule
      :frag:     SNIPPET

.. oe:language:: csharp

   The example below represents the smallest possible C\# **OEChem TK**
   program.  This program creates an :ref:`OEGraphMol <OEChem_OEGraphMol>` called
   ``mol`` when run.  When the program ends, C# automatically
   cleans up the molecule when there are no more references to it.

   .. oe:source:: CreateOEGraphMol.cs
      :language: csharp
      :caption:  Create a molecule
      :frag:     SNIPPET

.. _section_molctordtor_molfromsmiles:

Construction from SMILES
================================================================================

.. index :: SMILES

A common method of creating a molecule in **OEChem TK** is via the SMILES
representation. SMILES notation is commonly used in chemical
information systems, as it provides a convenient string representation
of a molecule. An introduction to SMILES syntax is provided in chapter
:ref:`chapter_SMILES`. The following examples will use the SMILES
``c1ccccc1`` which describes the molecule benzene. A molecule can be
created from a SMILES string using the :oe:func:`OEChem::OESmilesToMol`
function. Similarly, a molecule can be created from a CXSMILES string
using the :oe:func:`OEChem::OECXSMILESToMol`

.. oe:source:: CreateOEGraphMolFromSMILES.cpp
   :language: c++
   :caption:  Creating a molecule from a SMILES string (version 1)
   :frag:     SNIPPET

.. oe:source:: CreateOEGraphMolFromSMILES.py
   :language: python
   :caption:  Creating a molecule from a SMILES string (version 1)
   :frag:     SNIPPET

.. oe:source:: CreateOEGraphMolFromSMILES.java
   :language: java
   :caption:  Creating a molecule from a SMILES string (version 1)
   :frag:     SNIPPET

.. oe:source:: CreateOEGraphMolFromSMILES.cs
   :language: csharp
   :caption:  Creating a molecule from a SMILES string (version 1)
   :frag:     SNIPPET

The :oe:func:`OEChem::OESmilesToMol` function returns a boolean value
indicating whether the input string was a valid SMILES representation
of a molecule. It is good programming practice to check the return
value and report an error message if anything went wrong.
The following example shows adding a check on the return status of
:oe:func:`OEChem::OESmilesToMol` and printing an error message if the
string was not a valid SMILES representation of a molecule.

.. oe:source:: OEGraphMolFromSMILESCheck.cpp
   :language: c++
   :caption:  Creating a molecule from a SMILES string (version 2)
   :frag:     SNIPPET

.. oe:source:: OEGraphMolFromSMILESCheck.py
   :language: python
   :caption:  Creating a molecule from a SMILES string (version 2)
   :frag:     SNIPPET

.. oe:source:: OEGraphMolFromSMILESCheck.java
   :language: java
   :caption:  Creating a molecule from a SMILES string (version 2)
   :frag:     SNIPPET

.. oe:source:: OEGraphMolFromSMILESCheck.cs
   :language: csharp
   :caption:  Creating a molecule from a SMILES string (version 2)
   :frag:     SNIPPET

The :oe:func:`OEChem::OESmilesToMol` is considered a **high-level** function.
In addition, to parsing the given SMILES string, the
:oe:func:`OEChem::OESmilesToMol` function also perceives:

* the rings of the molecule, by invoking the  :oe:func:`OEChem::OEFindRingAtomsAndBonds` function
* the aromaticity of the molecule, by calling the :oe:func:`OEChem::OEAssignAromaticFlags`
  function using the :oe:const:`OEChem::OEAroModel::OpenEye` aromaticity model
* the chirality of the molecule, by calling the :oe:func:`OEChem::OEPerceiveChiral`
  function

In cases where you want to preserve the aromaticity of the SMILES string (or the lack of it),
a **low-level** :oe:func:`OEChem::OEParseSmiles`
function can be used.
For example, if benzene is expressed as ``c1ccccc1``, all atoms and bonds
are marked as aromatic. But if it is expressed as a |Kekule| form,
``C1=CC=CC=C1``, all atoms and bonds are kept aliphatic.
The aromaticity of the molecule can be perceived by calling the
:oe:func:`OEChem::OEAssignAromaticFlags` function.

.. oe:source:: OEGraphMolFromSMILESAromatic.cpp
   :language: c++
   :caption:  Creating molecules from a SMILES string (version 3)
   :frag:     SNIPPET

.. oe:source:: OEGraphMolFromSMILESAromatic.py
   :language: python
   :caption:  Creating molecules from a SMILES string (version 3)
   :frag:     SNIPPET

.. oe:source:: OEGraphMolFromSMILESAromatic.java
   :language: java
   :caption:  Creating molecules from a SMILES string (version 3)
   :frag:     SNIPPET

.. oe:source:: OEGraphMolFromSMILESAromatic.cs
   :language: csharp
   :caption:  Creating molecules from a SMILES string (version 3)
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: console

   Number of aromatic atoms = 0
   Number of aromatic atoms = 6

.. hint::

   We highly recommend the use of the :oe:func:`OEChem::OESmilesToMol`
   function when creating a molecule from a SMILES string.

   We highly recommend the use of the :oe:func:`OEChem::OECXSMILESToMol`
   function when creating a molecule from either a SMILES or CXSMILES string
   and the specific format is not known.

.. seealso::

   * :ref:`chapter_aromaticity` chapter for further information about aromaticity models.
   * :oe:func:`OEChem::OESmilesToMol`
   * :oe:func:`OEChem::OECXSMILESToMol`


.. _section_molctordtor_molreuse:

Reuse
================================================================================

Consider the following code examples to parse two separate SMILES strings,
benzene and phenol, and print the number of heavy atoms in each.

.. oe:source:: ReuseMoleculeOESmilesToMol.cpp
   :language: c++
   :caption:  Reusing a molecule (OESmilesToMol)
   :frag:     SNIPPET

.. oe:source:: ReuseMoleculeOESmilesToMol.py
   :language: python
   :caption:  Reusing a molecule (OESmilesToMol)
   :frag:     SNIPPET

.. oe:source:: ReuseMoleculeOESmilesToMol.java
   :language: java
   :caption:  Reusing a molecule (OESmilesToMol)
   :frag:     SNIPPET

.. oe:source:: ReuseMoleculeOESmilesToMol.cs
   :language: csharp
   :caption:  Reusing a molecule (OESmilesToMol)
   :frag:     SNIPPET

The **high-level** :oe:func:`OEChem::OESmilesToMol` function automatically
clears the molecule before parsing the SMILES string.
The output of the preceding program is the following:

.. code-block:: console

   Number of benzene atoms: 6
   Number of phenol atoms: 7


.. oe:source:: ReuseMolecule.cpp
   :language: c++
   :caption:  Reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

.. oe:source:: ReuseMolecule.py
   :language: python
   :caption:  Reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

.. oe:source:: ReuseMolecule.java
   :language: java
   :caption:  Reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

.. oe:source:: ReuseMolecule.cs
   :language: csharp
   :caption:  Reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

In the second example the **low-level** :oe:func:`OEChem::OEParseSmiles`
function is called.
The output of the preceding program is the following:

.. code-block:: console

   Number of benzene atoms: 6
   Number of phenol atoms: 13

The second line, ``Number of phenol atoms: 13``, will be surprising to
some. The behavior of the :oe:func:`OEChem::OEParseSmiles` function is to
**add** the given SMILES to the current molecule. **OEChem TK** provides a
mechanism for reusing a molecule by calling the
:oe:meth:`Clear<OEChem::OEMolBase::Clear>` method.
:oe:meth:`Clear<OEChem::OEMolBase::Clear>` deletes all atoms and bonds
of a molecule, thereby resetting a molecule into its original "empty"
state.

.. oe:source:: ReuseMoleculeClear.cpp
   :language: c++
   :caption:  Clearing and reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

.. oe:source:: ReuseMoleculeClear.py
   :language: python
   :caption:  Clearing and reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

.. oe:source:: ReuseMoleculeClear.java
   :language: java
   :caption:  Clearing and reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

.. oe:source:: ReuseMoleculeClear.cs
   :language: csharp
   :caption:  Clearing and reusing a molecule (OEParseSmiles)
   :frag:     SNIPPET

The output of the preceding program is the following

.. code-block:: console

   Number of benzene atoms: 6
   Number of phenol atoms: 7

Using the :oe:meth:`Clear<OEChem::OEMolBase::Clear>` method is
recommended, for example, when processing multiple molecules
sequentially in a database. Instead of requiring a new molecule to be
allocated and destroyed for each entry, the
:oe:meth:`Clear<OEChem::OEMolBase::Clear>` method can be used to reset
a molecule to its initial "empty" state.

.. _section_molctordtor_smilesfrommol:

Unique Representation
================================================================================

It is sometimes useful to generate a unique representation of a
molecule for use as an identifier for a database key. The compact
nature of SMILES strings makes them ideal candidates for the
task. However, the same molecule can be represented by many different
SMILES strings. **OEChem TK** features an advanced algorithm for
generating a (unique) :term:`canonical isomeric SMILES` string.
A canonical isomeric SMILES string can be generated from a molecule
by calling the :oe:func:`OEChem::OEMolToSmiles` or :oe:func:`OEChem::OEMolToCXSMILES` functions.

.. oe:source:: OEMolToSmiles.cpp
   :language: c++
   :caption:  Creating a canonical isomeric SMILES string from a molecule
   :frag:     SNIPPET

.. oe:source:: OEMolToSmiles.py
   :language: python
   :caption:  Creating a canonical isomeric SMILES string from a molecule
   :frag:     SNIPPET

.. oe:source:: OEMolToSmiles.java
   :language: java
   :caption:  Creating a canonical isomeric SMILES string from a molecule
   :frag:     SNIPPET

.. oe:source:: OEMolToSmiles.cs
   :language: csharp
   :caption:  Creating a canonical isomeric SMILES string from a molecule
   :frag:     SNIPPET


The output of the preceding program is the following:

.. code-block:: console

   Canonical isomeric SMILES is c1ccccc1

The following slightly more complicated example reads SMILES from
standard input and writes the corresponding :term:`canonical isomeric SMILES` to
standard output.

.. oe:source:: OEMolToSmilesRW.cpp
   :language: c++
   :caption:  Creating canonical isomeric SMILES strings
   :frag:     SNIPPET

.. oe:source:: OEMolToSmilesRW.py
   :language: python
   :caption:  Creating canonical isomeric SMILES strings
   :frag:     SNIPPET

.. oe:source:: OEMolToSmilesRW.java
   :language: java
   :caption:  Creating canonical isomeric SMILES strings
   :frag:     SNIPPET

.. oe:source:: OEMolToSmilesRW.cs
   :language: csharp
   :caption:  Creating canonical isomeric SMILES strings
   :frag:     SNIPPET

.. table::

   ========================= ===========================================
   input                     output (:term:`canonical isomeric SMILES`)
   ========================= ===========================================
   C1CCCN[C@@H]1(O)          C1CCN[C@@H](C1)O
   C1CN[C@H](O)CC1           C1CCN[C@@H](C1)O
   C1CC[C@H](O)CC1           C1CC[C@@H](CC1)O
   C1CCC(O)CC1               C1CCC(CC1)O
   C1=NC=CN1C[C@H](N)C(=O)O  c1cn(cn1)C[C@@H](C(=O)O)N
   ========================= ===========================================

The :oe:func:`OEChem::OEMolToSmiles` and :oe:func:`OEChem::OEMolToCXSMILES` functions
are considered a **high-level** functions.
Prior to creating the :term:`canonical isomeric SMILES`, the
:oe:func:`OEChem::OEMolToSmiles` function perceives the following properties
*if necessary*:

* the rings of the molecule, by using :oe:func:`OEChem::OEFindRingAtomsAndBonds`.
* the aromaticity of the molecule, by calling the :oe:func:`OEChem::OEAssignAromaticFlags`.
  function using the :oe:const:`OEChem::OEAroModel::OpenEye` aromaticity model
* the atom and bond stereochemistry.

It is also possible to generate :term:`canonical SMILES` without
isomeric information by using the :oe:func:`OEChem::OECreateCanSmiString`
**low-level** function.
As was shown in the :ref:`section_molctordtor_molfromsmiles` section,
:oe:func:`OEChem::OEParseSmiles` preserves the aromaticity present in
the input SMILES string.  The function
:oe:func:`OEChem::OEAssignAromaticFlags` has to be used to perceive
aromaticity in a molecule.

.. oe:source:: CreateSMILESFromOEGraphMolRW.cpp
   :language: c++
   :caption:  Creating canonical SMILES strings
   :frag:     SNIPPET

.. oe:source:: CreateSMILESFromOEGraphMolRW.py
   :language: python
   :caption:  Creating canonical SMILES strings
   :frag:     SNIPPET

.. oe:source:: CreateSMILESFromOEGraphMolRW.java
   :language: java
   :caption:  Creating canonical SMILES strings
   :frag:     SNIPPET

.. oe:source:: CreateSMILESFromOEGraphMolRW.cs
   :language: csharp
   :caption:  Creating canonical SMILES strings
   :frag:     SNIPPET

Notice that the preceding program does not construct and destruct
molecules each time through the loop, but rather uses the
:oe:meth:`Clear<OEChem::OEMolBase::Clear>` function to reuse the
molecule.  If the line ``mol.Clear()`` were removed from the program,
the output would contain longer and longer SMILES containing
disconnected fragments. See section
:ref:`section_molctordtor_molreuse` for more details.

.. table::

   ====================== ===================================
   input                  output (:term:`canonical SMILES`)
   ====================== ===================================
   c1cccnc1(O)            c1ccnc(c1)O
   C1=CC=CC=C1            c1ccccc1
   C1=CN=CC=C1            c1ccncc1
   C1=CC=CC=N1            c1ccncc1
   C1=NC=CN1CCC(=O)O      c1cn(cn1)CCC(=O)O
   ====================== ===================================

.. hint::

   We highly recommend the usage of the :oe:func:`OEChem::OEMolToSmiles`
   function when creating a SMILES string.

   We highly recommend the usage of the :oe:func:`OEChem::OEMolToCXSMILES`
   function when structures may contain enhanced stereogroup information.

.. seealso::

   * :oe:func:`OEChem::OEMolToSmiles`
   * :oe:func:`OEChem::OEMolToCXSMILES`

.. _section_molctordtor_inchifrommol:

InChI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Canonical SMILES is not the only unique representation available.
The IUPAC International Chemical Identifier (InChI), and its corresponding
hashkey representation (InChIKey) are also unique to the compound
they describe [InChI-2013]_.
InChIs can be created from molecules using the :oe:func:`OEChem::OECreateInChI`,
:oe:func:`OEChem::OEMolToInChI`, or :oe:func:`OEChem::OEMolToSTDInChI` functions.

.. oe:source:: CreateStandardInChI.cpp
   :language: c++
   :caption:  Creating standard InChI
   :frag:     SNIPPET

.. oe:source:: CreateStandardInChI.py
   :language: python
   :caption:  Creating standard InChI
   :frag:     SNIPPET

.. oe:source:: CreateStandardInChI.java
   :language: java
   :caption:  Creating standard InChI
   :frag:     SNIPPET

.. oe:source:: CreateStandardInChI.cs
   :language: csharp
   :caption:  Creating standard InChI
   :frag:     SNIPPET

.. table::

   =============================================== ===============================================
   input (SMILES)                                  output (Standard InChI)
   =============================================== ===============================================
   c1ccnc(c1)O                                     InChI=1S/C5H5NO/c7-5-3-1-2-4-6-5/h1-4H,(H,6,7)
   =============================================== ===============================================

.. note::

   The 'S' in 'InChI=1S' denotes standard InChI.

The following slightly more complicated example reads InChI strings from
standard input and writes InChI strings to standard output.

.. oe:source:: OEMolToInChIRW.cpp
   :language: c++
   :caption:  Reading and writing InChI strings
   :frag:     SNIPPET

.. oe:source:: OEMolToInChIRW.py
   :language: python
   :caption:  Reading and writing InChI strings
   :frag:     SNIPPET

.. oe:source:: OEMolToInChIRW.java
   :language: java
   :caption:  Reading and writing InChI strings
   :frag:     SNIPPET

.. oe:source:: OEMolToInChIRW.cs
   :language: csharp
   :caption:  Reading and writing InChI strings
   :frag:     SNIPPET

A nonstandard InChI can be generated by passing in an :ref:`OEInChIOptions <OEChem_OEInChIOptions>`
object to the :oe:func:`OEChem::OECreateInChI` function.
The options available are documented in the :ref:`OEInChIOptions <OEChem_OEInChIOptions>` class.

.. oe:source:: CreateNonStandardInChI.cpp
   :language: c++
   :caption:  Creating nonstandard InChI strings
   :frag:     SNIPPET

.. oe:source:: CreateNonStandardInChI.py
   :language: python
   :caption:  Creating nonstandard InChI strings
   :frag:     SNIPPET

.. oe:source:: CreateNonStandardInChI.java
   :language: java
   :caption:  Creating nonstandard InChI strings
   :frag:     SNIPPET

.. oe:source:: CreateNonStandardInChI.cs
   :language: csharp
   :caption:  Creating nonstandard InChI strings
   :frag:     SNIPPET

.. table::

   ===================================================== =====================================================
   input (SMILES)                                        output (nonstandard InChI)
   ===================================================== =====================================================
   c1ccnc(c1)O                                           InChI=1/C5H5NO/c7-5-3-1-2-4-6-5/h1-4H,(H,6,7)/f/h7H
   ===================================================== =====================================================


The 27-character-long InChIKey is made of three parts connected by hyphens.
The first part is 14 characters long and is based on the connectivity and 
proton layers of an InChI string. The second part, contains 9 characters 
that are related to all other InChI layers (isotopes, stereochemistry, etc.) 
and also contains the version of InChI and its standard/nonstandard property
in the last two characters. The third part is one letter, describing the 
(de)protonation layer of the original InChI.

.. oe:source:: CreateInChIKey.cpp
   :language: c++
   :caption:  CreateInChIKey
   :frag:     SNIPPET

.. oe:source:: CreateInChIKey.py
   :language: python
   :caption:  CreateInChIKey
   :frag:     SNIPPET

.. oe:source:: CreateInChIKey.java
   :language: java
   :caption:  CreateInChIKey
   :frag:     SNIPPET

.. oe:source:: CreateInChIKey.cs
   :language: csharp
   :caption:  CreateInChIKey
   :frag:     SNIPPET

.. table::

   ================================= =================================
   input (**SMILES**)                output (InChI Key)
   ================================= =================================
   c1ccnc(c1)O                       UBQKCCHYAOITMY-UHFFFAOYSA-N
   ================================= =================================
