.. _chapter_reactions:

********************************************************************************
Reactions
********************************************************************************

.. index :: OEUniMolecularRxn, OELibraryGen

Reaction processing in **OEChem TK** is divided into two categories: unimolecular
reactions and library generation.
Unimolecular reactions are useful for (although not limited to) normalization
reactions.
The :oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` class in **OEChem TK**
applies chemical transformations to individual molecules.
Reactions can also be used to generate combinatorial libraries using **OEChem TK**.
Both 'clipping' and reaction based enumeration can be achieved using the
:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` class.

:ref:`Figure: OEUniMolecularRxn<figure_oeuni_concept>`  and
:ref:`Figure: OELibraryGen <figure_oelibgen_concept_A>` demonstrate
the difference between the operation of
:oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` and the operation of
:oe:cls:`OELibraryGen<OEChem::OELibraryGen>`.

:oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` always takes one
starting compound (see :ref:`Figure: OEUniMolecularRxn<figure_oeuni_concept>`)
to which the specified transformation is applied recursively, until no further reactant
pattern are
matched, thereby generating one final product.
See more details about :oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` class
in section :ref:`section_reactions_normalization`.

.. _figure_oeuni_concept:

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

   **OEUniMolecularRxn**

   *Example of amine nitrogen protonation using 'OEUniMolecularRxn'. Transformations are applied to the starting material recursively*

:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` performs transformations independently to
each other, enumerating all possible combinations.
As a result, three different products are generated when the same protonation transformation
is applied to the starting material using :oe:cls:`OELibraryGen<OEChem::OELibraryGen>`
(see :ref:`Figure: OELibraryGen<figure_oelibgen_concept_A>`).

.. _figure_oelibgen_concept_A:

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

   **OELibraryGen**

   *Example of amine nitrogen protonation using 'OELibraryGen'. Transformations are applied to the starting material independently*


When :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` is used to generate combinatorial
libraries (see :ref:`Figure: Library generation<figure_oelibgen_concept_B>`),
all starting material combinations are enumerated to generate products by
considering that any reactant patterns can be mapped to any
starting materials multiple times.
See more details about :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` class in section
:ref:`section_reactions_libgen`.

.. _figure_oelibgen_concept_B:

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

   **Library generation**

   *Example of library generation. 'OELibraryGen' enumerates all possible reacting pattern combinations to generate products.*

Reactions are represented in **OEChem TK** as query molecules ( :oe:cls:`OEQMolBase<OEChem::OEQMolBase>` ).
Sets of chemical transform operations are derived from reaction molecules by
differences between the reactant and product patterns and in the reaction
molecule.
For example, atoms and bonds that appear in the reactant pattern, but are
absent in the product pattern are *destroyed*.
Atoms and bonds that appear in the product pattern but not in the reactant
pattern are *created*.
Atoms are tracked between reactants and products by atom maps.
Atom maps are stored and retrieved using
the :oe:meth:`SetMapIdx<OEChem::OEAtomBase::SetMapIdx>` and
the :oe:meth:`GetMapIdx<OEChem::OEAtomBase::GetMapIdx>` methods.
Product atoms that have the same map index as reactant atoms originate from
their reactant counterpart.
Reactions are completely defined by a fields in a query molecule.
Reaction molecules can be created from virtually any reaction file format
(:term:`SMIRKS`, MDL RXN, etc.), and can even be constructed programmatically.

.. _section_reactions_normalization:

Normalization Reactions
================================================================================
.. index :: OEUniMolecularRxn

The :oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` class is designed to
apply a set of transformations defined by a reaction to exactly one reactant
molecule.
All possible transformations are applied to the initial set of atoms and bonds of
an input molecule.
For example, a reaction that affects a particular type of functional group will
be automatically applied twice to a bi-functional molecule.
The number of transformations applied by the
:oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` class is limited in order
to prevent infinite loops.
Consider a hypothetical reaction that methylates a methyl group.
If a methyl group added in a reaction were allowed to react again, the methyl
groups of a molecule would be methylated *ad infinitum*.
The first protection against infinite loops provided by
:oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` is that only original
atoms and bonds of the input molecule are allowed to react.
Atoms and bonds created by a reaction are excluded from involvement in further
reactions.
A more subtle source of potential infinite loops are reactions where product
atoms still match the reactant pattern after they have been involved in a
chemical transformation.
The :oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` class allows a set of
atoms that match a reactant pattern to react only once.

The following code demonstrates the use of the
:oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` class.
:oe:cls:`OEUniMolecularRxn<OEChem::OEUniMolecularRxn>` in this case is initialized
using a :term:`SMIRKS` pattern.
The example reaction (see :ref:`Figure: Protonation<figure_oeuni_example>`) protonates and charges
an amine nitrogen.
The reaction demonstrates the protection mechanisms in place to prevent
under-specified reactions from causing infinite loops.
The product in :ref:`Figure: Protonation<figure_oeuni_example>` still matches the reactant pattern,
however, subsequent reactions terminate when no unreacted atoms are identified.


.. oe:source:: Normalization.cpp
   :language: c++
   :caption:  Normalization
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: Normalization.py
   :language: python
   :caption:  Normalization
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: Normalization.java
   :language: java
   :caption:  Normalization
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: Normalization.cs
   :language: csharp
   :caption:  Normalization
   :refnum:   1
   :frag:     SNIPPET

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

.. code-block:: bash

   smiles =  C(C[NH3+])[NH3+]

.. _figure_oeuni_example:

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

   **Protonation**

   *Example of amine nitrogen protonation.*


.. _section_reactions_libgen:

Library Generation
================================================================================

.. index :: OELibraryGen

The :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` was designed to give programmers a
high degree of control when applying chemical transformations.
It was also designed for efficiency. Potentially costly preprocessing is performed
once before transformations can be carried out.
The relative setup cost of a :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instance may
be high, and the memory use large as preprocessed reactants are stored in memory.
Subsequent generation of products, however, is very efficient because setup
costs are paid in advance.
The  :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` class serves a dual purpose of
managing sets of preprocessed starting materials, and storing a list of chemical
transform operations defined by a reaction molecule.

Chemical transform operations are carried out on starting materials.
Starting materials provide most of the virtual matter that goes into
making virtual product molecules.
The :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` class provides an interface to
associate starting materials with reactant patterns using the
:oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>`  and
:oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>`  methods.
These methods associate starting materials to reactant patterns using the index
(reactant number) of the pattern.
In a SMIRKS pattern the first reactant (reactant number zero) is the furthest
reactant on the left.
Disconnected reactant patterns may be grouped into a single component using
component level grouping in SMIRKS, denoted by parentheses.



.. _subsection_reactions_libgen_initsmirks:

Initialization with SMIRKS
--------------------------------------------------------------------------------

:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` objects can be directly initialized
with a SMIRKS pattern or an :oe:cls:`OEQMolBase<OEChem::OEQMolBase>` object.
See example codes in :oe:src:`Listing 2<SNIPPET-ReactionsNonUnique>` --
:oe:src:`Listing 5<SNIPPET-ReactionsUsingValenceCorr>`.

A boolean argument is used to specify whether the SMIRKS string should be
interpreted using strict SMIRKS semantics. See the :term:`SMIRKS` definition
describing the strict SMIRKS semantics.
Passing a boolean value of false to the second method argument will relax
the strict SMIRKS restrictions.
The :oe:meth:`Init<OEChem::OELibraryGen::Init>` function returns false,
if :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` can not be initialized.

:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` objects can also be initialized from
an MDL reaction query file, for more details and examples see section
:ref:`subsection_reactions_libgen_MDL`.

.. _subsection_reactions_libgen_sm:

Starting Materials
--------------------------------------------------------------------------------

The :oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>`  and
:oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>`  methods
are used to initialize the starting materials corresponding to a reaction component
(reactant).
The declaration of these functions are:

.. oe:language:: c++

   .. code-block:: c++

      unsigned int SetStartingMaterial(OEIter<OEMolBase>&,     unsigned int reacnum, bool umatch=true);
      unsigned int AddStartingMaterial(OEIter<OEMolBase>&,     unsigned int reacnum, bool umatch=true);

      unsigned int SetStartingMaterial(OEIterBase<OEMolBase>*, unsigned int reacnum, bool umatch=true);
      unsigned int AddStartingMaterial(OEIterBase<OEMolBase>*, unsigned int reacnum, bool umatch=true);

      unsigned int SetStartingMaterial(const OEMolBase&,       unsigned int reacnum, bool umatch=true);
      unsigned int AddStartingMaterial(const OEMolBase&,       unsigned int reacnum, bool umatch=true);

.. oe:language:: python

   .. code-block:: python

      SetStartingMaterial(miter,reacnum,umatch)
      AddStartingMaterial(miter,reacnum,umatch)
      # miter - OEMolBaseIter, reacnum - int, umatch - bool (default value = True)
      # returns int

      SetStartingMaterial(mol,reacnum,umatch)
      AddStartingMaterial(mol,reacnum,umatch)
      # mol - OEMolBase, reacnum - int, umatch - bool (default value = True)
      # returns int

.. oe:language:: java

   .. code-block:: java

      int SetStartingMaterial(OEMolBaseIterBase, int reacnum, boolean umatch);
      int AddStartingMaterial(OEMolBaseIterBase, int reacnum, boolean umatch);
      // umatch (default value = true)

      int SetStartingMaterial(OEMolBase, int reacnum, boolean umatch);
      int AddStartingMaterial(OEMolBase, int reacnum, boolean umatch);
      // umatch (default value = true)

.. oe:language:: csharp

   .. code-block:: csharp

      uint SetStartingMaterial(OEMolBaseIterBase, uint reacnum, bool umatch);
      uint AddStartingMaterial(OEMolBaseIterBase, uint reacnum, bool umatch);
      // umatch (default value = true)

      uint SetStartingMaterial(OEMolBase, uint reacnum, bool umatch);
      uint AddStartingMaterial(OEMolBase, uint reacnum, bool umatch);
      // umatch (default value = true)


An iterator over molecules or a single molecule may be passed as the first argument
to these methods.
A copy of each starting material is stored internally along with the atom maps
obtained by performing a substructure search with the corresponding reactant pattern.

The difference between using :oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>` and
:oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>`  methods is that
by calling  :oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>` the
starting materials set in prior calls are discarded, while the
:oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>` methods append
to the list of starting materials set in prior calls.

The second argument specifies the reactant by number, starting with
zero, to which the starting materials correspond.  These numbers
correspond with the left to right lexical ordering of reactants in the
SMIRKS.  In the :oe:src:`Listing 2<SNIPPET-ReactionsNonUnique>` example code,
there is only one reactant pattern specified in the SMIRKS string,
therefore 0 is used to add the corresponding starting materials.

The final argument is used to control the pattern matching of the
reactant pattern to the starting material.  If the default true value
is used, then only matches that contain a unique set of atoms relative
to previously identified matches are used.  If the value is false,
every possible match including those related by symmetry will be used.
:oe:src:`Listing 2<SNIPPET-ReactionsNonUnique>` and the corresponding
:ref:`Figure: Non-unique search<figure_oelibgen_nonunique>` shows an
example in which two unique products are generated because the
reactant pattern can be mapped twice when a non-unique substructure
search is performed.  For more information about substructure searches
see section :ref:`section_patternmatch_sss`.

Both the :oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>` and
the :oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>` methods
return the number of matches found in the starting materials.

.. oe:source:: ReactionsNonUnique.cpp
   :language: c++
   :caption:  Library generation with non-unique pattern matching
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: ReactionsNonUnique.py
   :language: python
   :caption:  Library generation with non-unique pattern matching
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: ReactionsNonUnique.java
   :language: java
   :caption:  Library generation with non-unique pattern matching
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: ReactionsNonUnique.cs
   :language: csharp
   :caption:  Library generation with non-unique pattern matching
   :refnum:   2
   :frag:     SNIPPET


.. _figure_oelibgen_nonunique:

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

   **Non-unique search**

   *Example of generating two unique products when performing non-unique pattern matching.*


The output of :oe:src:`Listing 2<SNIPPET-ReactionsNonUnique>` is shown below:

.. code-block:: bash

   number of matches = 2
   product smiles = c1cnc2nccn2c1O
   product smiles = c1cn2ccnc2nc1O


.. _subsection_reactions_libgen_modes:

Valence Correction Modes
--------------------------------------------------------------------------------

Once a reaction has been defined, and starting materials have been associated with
each of the reactant patterns, chemical transformations can be applied to
combinations of starting materials.
To achieve a chemically reasonable output attention should be given to the mode
of valence (or hydrogen count) correction that matches the reaction.

The :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` class has three possible modes of
valence correction:

#.  the default explicit hydrogen mode (see example in section :ref:`subsection_reactions_libgen_explicitH`)

#.  the implicit hydrogen mode (see example in section :ref:`subsection_reactions_libgen_implicitH`)

#.  the automatic valence correction mode (see example in section :ref:`subsection_reactions_libgen_vcorrect`)

The valence correction mode must be assigned prior to adding starting materials
to an :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instance by calling the
:oe:meth:`SetExplicitHydrogens<OEChem::OELibraryGen::SetExplicitHydrogens>` and the
:oe:meth:`SetValenceCorrection<OEChem::OELibraryGen::SetValenceCorrection>` methods.

Note that the explicit hydrogen setting in effect modifies the semantics of SMIRKS.
If the programmer wishes to implement strict SMIRKS according to the Daylight
standard, in full, explicit hydrogens should be set on.



.. _subsection_reactions_libgen_explicitH:

Explicit Hydrogen Handling
--------------------------------------------------------------------------------
The default mode for valence correction and SMIRKS interpretation is to emulate
the Daylight Reaction Toolkit.
Hydrogen counts are adjusted using explicit hydrogens in SMIRKS patterns.
Reactions are carried out using explicit hydrogens, and valence
correction occurs when explicit hydrogens are added or deleted as
defined by a reaction.
The following example demonstrates strict SMIRKS and explicit hydrogen handling.


.. oe:source:: ReactionsUsingExplH.cpp
   :language: c++
   :caption:  Library generation using explicit hydrogens
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingExplH.py
   :language: python
   :caption:  Library generation using explicit hydrogens
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingExplH.java
   :language: java
   :caption:  Library generation using explicit hydrogens
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingExplH.cs
   :language: csharp
   :caption:  Library generation using explicit hydrogens
   :refnum:   3
   :frag:     SNIPPET

The output of :oe:src:`Listing 3<SNIPPET-ReactionsUsingExplH>` is shown below:

.. code-block:: bash

   product smiles = CCNC(=O)C
   product smiles = CCNC(=O)C

The program generates two products, each of them corresponds to the equivalent
protons attached to the amine (see example in :ref:`Figure: Hydrogen handling<figure_oelibgen_strict>`).
If a unique set of products is desired, canonical smiles strings may be stored
for verification that products generated are indeed unique.

.. _figure_oelibgen_strict:

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

   **Hydrogen handling**

   *Example of strict SMIRKS reaction handling with explicit hydrogen*


.. _subsection_reactions_libgen_implicitH:

Implicit Hydrogen Handling
--------------------------------------------------------------------------------

The following code demonstrates how the same basic reaction given in the previous
example can be carried out using the implicit hydrogen correction mode.
Notice that no explicit hydrogens appear in the reaction.
Instead, the SMARTS implicit hydrogen count operator appears on the right hand
side of the reaction and is used to assign the implicit hydrogen count of the
product nitrogen.

.. oe:source:: ReactionsUsingImplH.cpp
   :language: c++
   :caption:  Library generation using implicit hydrogens
   :refnum:   4
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingImplH.py
   :language: python
   :caption:  Library generation using implicit hydrogens
   :refnum:   4
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingImplH.java
   :language: java
   :caption:  Library generation using implicit hydrogens
   :refnum:   4
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingImplH.cs
   :language: csharp
   :caption:  Library generation using implicit hydrogens
   :refnum:   4
   :frag:     SNIPPET

The output of :oe:src:`Listing 4<SNIPPET-ReactionsUsingImplH>` is the following:

.. code-block:: bash

   product smiles = CCNC(=O)C

The reaction is written to work with implicit hydrogens (using the lowercase
'h' primitive), and the :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instance
is set to work in implicit hydrogen mode using the
:oe:meth:`SetExplicitHydrogens<OEChem::OELibraryGen::SetExplicitHydrogens>`
method.


The :oe:meth:`SetExplicitHydrogens<OEChem::OELibraryGen::SetExplicitHydrogens>`
method sets the hydrogen handling mode for the :oe:cls:`OELibraryGen<OEChem::OELibraryGen>`
instance.
:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instances are constructed by default
with the explicit hydrogen mode set to true.
If the value is true, the  :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instance will add
explicit hydrogens to reactant molecules when they are initialized using either the
:oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>` or the
:oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>` methods.

If the value is false, then the :oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>`
and  the :oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>`
methods will suppress any explicit hydrogens in the reactant molecules, and simply
retain the implicit hydrogen counts for remaining non-hydrogen atoms.

Note that the explicit hydrogen setting in effect modifies the semantics of SMIRKS.
If the programmer wishes to implement strict SMIRKS according to the Daylight
standard, in full, explicit hydrogens should be set on.


.. _subsection_reactions_libgen_vcorrect:

Automatic Valence Correction
--------------------------------------------------------------------------------

The final example demonstrates automatic valence correction with implicit hydrogen mode.
The automatic valence correction attempts to add or subtract implicit
hydrogens in order to retain the valence state observed in the starting materials.

:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instances are constructed by default
with the valence correction mode being turned off.
It can be turned on by passing a boolean true value to
:oe:meth:`SetValenceCorrection<OEChem::OELibraryGen::SetValenceCorrection>`
method of :oe:cls:`OELibraryGen<OEChem::OELibraryGen>`
(see example in :oe:src:`Listing 5<SNIPPET-ReactionsUsingValenceCorr>`).

When valence correction mode is enabled, the valence state for each mapped reacting
atom is recorded before any chemical transformations commence.
After the transform operations are complete, :oe:cls:`OELibraryGen<OEChem::OELibraryGen>`
will attempt to adjust (either increase or decrease) the implicit hydrogen
count on atoms in the product molecule that are involved in the reaction
to match the original valence state of the corresponding reactant atom.
Formal charge is taken into account during the hydrogen count adjustment.

.. oe:source:: ReactionsUsingValenceCorr.cpp
   :language: c++
   :caption:  Library generation with automatic valence correction
   :refnum:   5
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingValenceCorr.py
   :language: python
   :caption:  Library generation with automatic valence correction
   :refnum:   5
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingValenceCorr.java
   :language: java
   :caption:  Library generation with automatic valence correction
   :refnum:   5
   :frag:     SNIPPET

.. oe:source:: ReactionsUsingValenceCorr.cs
   :language: csharp
   :caption:  Library generation with automatic valence correction
   :refnum:   5
   :frag:     SNIPPET

The output of :oe:src:`Listing 5<SNIPPET-ReactionsUsingValenceCorr>` is shown
below:

.. code-block:: bash

   product smiles = CCNC(=O)C

Note that valence correction in effect modifies the semantics of SMIRKS.
Thus, if the programmer wishes to implement strict SMIRKS according to the
Daylight standard, in full, valence correction should be turned off.

In general, automatic valence correction is a convenience that allows
straightforward reactions to be written in a simplified manner and
reduces the burden of valence state bookkeeping.  However, reactions that alter
the preferred valence state of an atom, oxidation for example, **may not
be automatically correctable**.

.. _subsection_reactions_libgen_tracking:

Reactant Tracking
--------------------------------------------------------------------------------

The title of a product molecule is generated by concatenating reactant molecule
titles with a delimiter or separator inserted between them.
The default separator is the underscore character '_'.
The title separator string may be changed by calling the
:oe:meth:`SetTitleSeparator<OEChem::OELibraryGen::SetTitleSeparator>` method
(see example in :oe:src:`Listing 6<SNIPPET-ReactionsReactantTrace>`).

.. oe:source:: ReactionsReactantTrace.cpp
   :language: c++
   :caption:  Tracing reactants
   :refnum:   6
   :frag:     SNIPPET

.. oe:source:: ReactionsReactantTrace.py
   :language: python
   :caption:  Tracing reactants
   :refnum:   6
   :frag:     SNIPPET

.. oe:source:: ReactionsReactantTrace.java
   :language: java
   :caption:  Tracing reactants
   :refnum:   6
   :frag:     SNIPPET

.. oe:source:: ReactionsReactantTrace.cs
   :language: csharp
   :caption:  Tracing reactants
   :refnum:   6
   :frag:     SNIPPET

If every reactant added to an :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` instance
has a unique identifier or name, then the title of a generated product unambiguous
determines from which reactants the product was constructed.
The output of :oe:src:`Listing 6<SNIPPET-ReactionsReactantTrace>` is shown below:

.. code-block:: bash

   Number of products=4
   product smiles = CCNC(=O)C acetyl chloride#ethanamine
   product smiles = CC(=O)NCCO acetyl chloride#2-aminoethanol
   product smiles = CCNC(=O)c1ccccc1 benzoyl chloride#ethanamine
   product smiles = c1ccc(cc1)C(=O)NCCO benzoyl chloride#2-aminoethanol


Both :oe:meth:`SetStartingMaterial<OEChem::OELibraryGen::SetStartingMaterial>` and
:oe:meth:`AddStartingMaterial<OEChem::OELibraryGen::AddStartingMaterial>` methods
return the number of substructure matches detected in the compounds(s) added to
:oe:cls:`OELibraryGen<OEChem::OELibraryGen>`.
Because :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` enumerates all possible reactant
combinations to generate products, the number of products that will be generated
can be calculated by multiplying the number of reactant matches.
In the example in :oe:src:`Listing 6<SNIPPET-ReactionsReactantTrace>`, there are four
expected products, because only one substructure match is detected for each reactant.

.. _subsection_reactions_libgen_atommapping:

Atom Mapping
--------------------------------------------------------------------------------

The atom mapping defines which atoms and bonds remain the same and which are altered
on the reactant and products sides of the reaction.


#.  Atoms that appear in both sides of the reaction are left intact.

#.  Atoms and bonds that appear in the product pattern(s) but not in the reactant
    pattern(s) are created.

#.  Atoms and bonds that disappear in the reactant pattern(s) but not in the product
    pattern(s) are deleted.
    When an atom is deleted all of its unmapped explicit hydrogens are automatically
    removed.

#.  Unmapped reactant atoms are deleted only in strict semantics.

The user should carefully consider whether to add a mapping or to leave unmapped an atom
in the reaction.
Consider, for example, the first reactant pattern in
:ref:`Figure: Incorrect reaction mapping (top)<figure_oelibgen_mapping_01_A>`
that can be mapped both to aldehydes or ketones.
Because the carbon atom of the carbonyl (mapping index 2) appears in both side of the
reaction, it remains intact during the reaction with all of its neighbor atoms that
are not described in the reactant pattern.
As a result, when the reactant pattern is mapped to an acyl chloride (see
:ref:`Figure: Incorrect reaction mapping (bottom)<figure_oelibgen_mapping_01_A>`) the chlorine atom is still bonded to
the carbon in the generated product.


.. _figure_oelibgen_mapping_01_A:

.. figure:: images/OELibGen-mapping-reaction-01-A.png
   :scale:  100
   :align:  center

   **Incorrect reaction mapping**

   *Example of incorrect reaction mapping; (top) reaction definition, (bottom) product generation.*

By removing the atom mapping from the carbon atom of the carbonyl
(:ref:`Figure: Correct reaction mapping (top)<figure_oelibgen_mapping_01_B>`), the carbon atom will be created on the
product side during the product generation.
As a result, when the reactant pattern is mapped to an acyl chloride
(see :ref:`Figure: Correct reaction mapping (bottom)<figure_oelibgen_mapping_01_B>`), the bond between the carbon
and the chlorine atom is broken.

.. _figure_oelibgen_mapping_01_B:

.. figure:: images/OELibGen-mapping-reaction-01-B.png
   :scale:  100
   :align:  center

   **Correct reaction mapping**

   *Example of correct reaction mapping; (top) reaction definition, (bottom) product generation.*


The :oe:meth:`SetRemoveUnmappedFragments<OEChem::OELibraryGen::SetRemoveUnmappedFragments>`
method  of :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` controls whether to keep
or remove the unmapped components on the product side after the reaction is
executed.
When it is enabled, by calling
:oe:meth:`SetRemoveUnmappedFragments<OEChem::OELibraryGen::SetRemoveUnmappedFragments>`
with the boolean value of 'true', any component on the product side that has no
mapped atom is automatically removed.
In case of the example in :ref:`Figure: Correct reaction mapping (bottom)<figure_oelibgen_mapping_01_B>`, this means
deleting the isolated chlorine atom.
The default behavior is to keep all components.

:ref:`Figure: Incomplete reaction (top)<figure_oelibgen_mapping_02_A>` shows an example, where not all ring
atoms in the reactants are mapped.
During the product generation, the unmapped atoms on the reactant side are deleted,
while the unmapped atoms on the products side are created.
As a result, ring substitutions are removed from the generated product in all
positions where atom mapping is missing (see generated product and the removed
ring substitution in :ref:`Figure: Incomplete reaction (bottom)<figure_oelibgen_mapping_02_A>`).
The unmapped fragment (CCN) can be automatically removed from the final product
by calling
:oe:meth:`SetRemoveUnmappedFragments<OEChem::OELibraryGen::SetRemoveUnmappedFragments>`
with the boolean value of 'true'.

.. _figure_oelibgen_mapping_02_A:

.. figure:: images/OELibGen-mapping-reaction-02-A.png
   :scale:  100
   :align:  center

   **Incomplete reaction**

   *Example of incomplete reaction ring mapping; (top) reaction definition, (bottom) product generation.*


By mapping all ring atoms in the reactants (see :ref:`Figure: Complete reaction (top)<figure_oelibgen_mapping_02_B>`),
all ring substitutions are left intact in the generated product
(see :ref:`Figure: Complete reaction (bottom)<figure_oelibgen_mapping_02_B>`).

.. _figure_oelibgen_mapping_02_B:

.. figure:: images/OELibGen-mapping-reaction-02-B.png
   :scale:  100
   :align:  center

   **Complete reaction**

   *Example of complete reaction ring mapping; (top) reaction definition, (bottom) product generation.*

.. _subsection_reactions_libgen_MDL:

MDL Reaction Query File
--------------------------------------------------------------------------------

An MDL reaction query file is comprised of a series of structural data
with various atom and bond query features to define each reactant and
product of a reaction.  Mapping indices on the atom blocks define
which reactant atom becomes which product atom through the reaction.

See section :ref:`section_mdlqueries_features` for the supported MDL query features
in **OEChem TK** and https://discover.3ds.com/ctfile-documentation-request-form
for the MDL reaction file format.

:oe:src:`Listing 7<SNIPPET-ReactionsRXN>` shows an example how to initialize an
:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` object from MDL reaction query.
The reaction defined in the 'amide.rxn' file is shown
:ref:`Figure: MDL query<figure_oelibgen_rxn_reaction>`.

.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :caption:  Library generation using a MDL reaction query
   :refnum:   7
   :frag:     SNIPPET

.. oe:source:: ReactionsRXN.py
   :language: python
   :caption:  Library generation using a MDL reaction query
   :refnum:   7
   :frag:     SNIPPET

.. oe:source:: ReactionsRXN.java
   :language: java
   :caption:  Library generation using a MDL reaction query
   :refnum:   7
   :frag:     SNIPPET

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :caption:  Library generation using a MDL reaction query
   :refnum:   7
   :frag:     SNIPPET


The output of :oe:src:`Listing 7<SNIPPET-ReactionsRXN>` is the following:

.. code-block:: bash

   Reactant atoms:
    atom: 0 C in component 1 with map index 1
    atom: 1 O in component 1 with map index 0
    atom: 2 O in component 1 with map index 2
    atom: 3 C in component 2 with map index 4
    atom: 4 N in component 2 with map index 3
   Product atoms :
    atom: 5 C in component 3 with map index 1
    atom: 6 N in component 3 with map index 3
    atom: 7 C in component 3 with map index 4
    atom: 8 O in component 3 with map index 2
   product smiles = CC(C)CNC(=O)c1ccccc1


.. index:: OEReadMDLReactionQueryFile

:oe:func:`OEReadMDLReactionQueryFile<OEChem::OEReadMDLReactionQueryFile>` function
reads the MDL reaction query directly into a :oe:cls:`OEQMolBase<OEChem::OEQMolBase>`
object, which then can be used to initialize an
:oe:cls:`OELibraryGen<OEChem::OELibraryGen>` object.


.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-READREACTION

.. oe:source:: ReactionsRXN.py
   :language: python
   :noindent:
   :frag:     SNIPPET-READREACTION

.. oe:source:: ReactionsRXN.java
   :language: java
   :noindent:
   :frag:     SNIPPET-READREACTION

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-READREACTION

The user can iterate over the reactant and product atoms of a reaction using
the :oe:cls:`OEAtomIsInReactant<OEChem::OEAtomIsInReactant>` and the
:oe:cls:`OEAtomIsInProduct<OEChem::OEAtomIsInProduct>` functors, respectively.

.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RXN-ATOMS

.. oe:source:: ReactionsRXN.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RXN-ATOMS

.. oe:source:: ReactionsRXN.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RXN-ATOMS

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RXN-ATOMS


.. _figure_oelibgen_rxn_reaction:

.. figure:: images/OELibGen-rxn-reaction.png
   :scale:  100
   :align:  center

   **MDL Query**

   *Example of MDL query reaction*

The reaction 'role' property of an atom can also be accessed with the
:oe:meth:`GetRxnRole<OEChem::OEAtomBase::GetRxnRole>` method
of the :oe:cls:`OEAtomBase<OEChem::OEAtomBase>` class.

The :oe:meth:`GetMapIdx<OEChem::OEAtomBase::GetMapIdx>`  method returns the
atom map index read from the reaction file.

.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RXN-MAPIDX

.. oe:source:: ReactionsRXN.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RXN-MAPIDX

.. oe:source:: ReactionsRXN.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RXN-MAPIDX

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RXN-MAPIDX

An unmapped atom has a map index zero.
For more information about these functions and the :oe:constns:`OEChem::OERxnRole`
namespace, please refer to the :ref:`oechem_part_api` manual.

Since the explicit hydrogens are suppressed when the reaction is converted
into a query molecule,

.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RXN-OPT

.. oe:source:: ReactionsRXN.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RXN-OPT

.. oe:source:: ReactionsRXN.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RXN-OPT

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RXN-OPT

the explicit hydrogens in the starting materials
can also be suppressed, yielding faster performance while still generating the same products.

.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RXN-EXPH

.. oe:source:: ReactionsRXN.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RXN-EXPH

.. oe:source:: ReactionsRXN.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RXN-EXPH

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RXN-EXPH

More details on suppressing hydrogens in a query can be found in section
:ref:`section_mdlqueries_hydrogens`.
It is also recommended to set the valence correction mode on.

.. oe:source:: ReactionsRXN.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-RXN-VCORRECT

.. oe:source:: ReactionsRXN.py
   :language: python
   :noindent:
   :frag:     SNIPPET-RXN-VCORRECT

.. oe:source:: ReactionsRXN.java
   :language: java
   :noindent:
   :frag:     SNIPPET-RXN-VCORRECT

.. oe:source:: ReactionsRXN.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-RXN-VCORRECT


.. index:: OEBuildMDLQueryExpressions

The MDL reaction query can also be read into a :oe:cls:`OEMolBase<OEChem::OEMolBase>`
object (see code snippet below).
In this case, the :oe:func:`OEReadMDLReactionQueryFile<OEChem::OEReadMDLReactionQueryFile>`
function attaches the query features present in the input MDL file to the related
atoms and bonds of the :oe:cls:`OEMolBase<OEChem::OEMolBase>` object.
The :oe:cls:`OEQMolBase<OEChem::OEQMolBase>` object can be subsequently created by
calling the :oe:func:`OEBuildMDLQueryExpressions<OEChem::OEBuildMDLQueryExpressions>`
function with :oe:const:`OEChem::OEMDLQueryOpts::ReactionQuery` option.


.. oe:language:: c++

   .. code-block:: c++

      OEGraphMol reaction;
      OEReadMDLReactionQueryFile(rfile,reaction);
      // reaction can be manipulated here
      OEQMol qreaction;
      // build OEQMol with OEMDLQueryOpts::ReactionQuery option
      OEBuildMDLQueryExpressions(qreaction,reaction,OEMDLQueryOpts::ReactionQuery);
      OELibraryGen libgen;
      libgen.Init(qreaction);


.. oe:language:: python

   .. code-block:: python

      reaction = OEGraphMol()
      OEReadMDLReactionQueryFile(rfile,reaction)
      # reaction can be manipulated here
      qreaction = OEQMol()
      # build OEQMol with OEMDLQueryOpts_ReactionQuery option
      OEBuildMDLQueryExpressions(qreaction,reaction,OEMDLQueryOpts_ReactionQuery)
      libgen OELibraryGen()
      libgen.Init(qreaction)


.. oe:language:: java

   .. code-block:: java

      OEGraphMol reaction = new OEGraphMol();
      oechem.OEReadMDLReactionQueryFile(rfile,reaction);
      // reaction can be manipulated here
      OEQMol qreaction = new OEQMol();
      // build OEQMol with OEMDLQueryOpts.ReactionQuery option
      oechem.OEBuildMDLQueryExpressions(qreaction,reaction,OEMDLQueryOpts.ReactionQuery);
      OELibraryGen libgen = new OELibraryGen();
      libgen.Init(qreaction);

.. oe:language:: csharp

   .. code-block:: csharp

      OEGraphMol reaction = new OEGraphMol();
      OEChem.OEReadMDLReactionQueryFile(rfile,reaction);
      // reaction can be manipulated here
      OEQMol qreaction = new OEQMol();
      // build OEQMol with OEMDLQueryOpts.ReactionQuery option
      OEChem.OEBuildMDLQueryExpressions(qreaction,reaction,OEMDLQueryOpts.ReactionQuery);
      OELibraryGen libgen = new OELibraryGen();
      libgen.Init(qreaction);

The declarations of these functions are:

.. oe:language:: c++

   .. code-block:: c++

      bool OEReadMDLReactionQueryFile(oemolistream &ifs, OEMolBase& mol);
      bool OEReadMDLReactionQueryFile(oemolistream &ifs, OEQMolBase& qmol,
                                      unsigned int opts = OEMDLQueryOpts::ReactionQuery);

      bool OEBuildMDLQueryExpressions(OEQMolBase &qmol, const OEMolBase &mol,
                                      unsigned int opts = OEMDLQueryOpts::Default);

.. oe:language:: python

   .. code-block:: python


      OEReadMDLReactionQueryFile(ifs,mol)
      # ifs - oemolistream, mol - OEMolBase
      # returns True or False
      OEReadMDLReactionQueryFile(ifs,qmol,opts)
      # ifs - oemolistream, mol - OEQMolBase,
      # opts - integer ( default value = OEMDLQueryOpts_ReactionQuery )
      # returns True or False
      OEBuildMDLQueryExpressions(qmol,mol,opts)
      # ifs - oemolistream, mol - OEQMolBase,
      # opts - integer ( default value = OEMDLQueryOpts_Default )
      # returns True or False

.. oe:language:: java

   .. code-block:: java

      boolean OEReadMDLReactionQueryFile(oemolistream ifs, OEMolBase mol);
      boolean OEReadMDLQueryFile(oemolistream ifs, OEQMolBase qmol, int opts);
      // opts (default value = OEMDLQueryOpts.ReactionQuery)
      boolean OEBuildMDLQueryExpressions(OEQMolBase qmol, OEMolBase mol, int opts);
      // opts (default value = OEMDLQueryOpts.Default)

.. oe:language:: csharp

   .. code-block:: csharp

      bool OEReadMDLReactionQueryFile(oemolistream ifs, OEMolBase mol);
      bool OEReadMDLQueryFile(oemolistream ifs, OEQMolBase qmol, uint opts);
      // opts (default value = OEMDLQueryOpts.ReactionQuery)
      bool OEBuildMDLQueryExpressions(OEQMolBase qmol, OEMolBase mol, uint opts);
      // opts (default value = OEMDLQueryOpts.Default)

The 'opts' parameter defines how the MDL query is interpreted when
:oe:cls:`OEQMolBase<OEChem::OEQMolBase>` object is constructed.

For more details on the various options in the :oe:constns:`OEChem::OEMDLQueryOpts`
namespace and the MDL query based substructure search, please see chapter
:ref:`chapter_mdlqueries`.


.. _subsection_reactions_libgen_reactH:

Hydrogens on the Reactant Side
--------------------------------------------------------------------------------

When defining a reaction it is very important to consider not only correct atom
mapping but also to anticipate the different kind of starting materials the reactant
pattern(s) will match.

At first glance, the reaction shown in :ref:`Figure: Missing hydrogen (reaction)<figure_oelibgen_missing_hydrogen_reaction>`
seems correct, however some of the generated products have carbon atom with incorrect 5 valences
see example 'A' in :ref:`Figure: Missing hydrogen (products)<figure_oelibgen_missing_hydrogen_example>`.

.. _figure_oelibgen_missing_hydrogen_reaction:

.. figure:: images/OELibGen-hydrogen-reaction.png
   :scale:  100
   :align:  center

   **Missing hydrogen (reaction)**

   *Example of missing explicit/implicit hydrogen in reactant (equivalent  SMIRKS: [c:2]1[c:3][c:4][c:5][c:6][c:1]1([C:7](=O)[C:8])>>[c:2]1[c:3][c:4][c:5][c:6][c:1]1([C:7]2[C:8]=CCC(=O)C2)*


.. _figure_oelibgen_missing_hydrogen_example:

.. figure:: images/OELibGen-hydrogen-example.png
   :scale:  100
   :align:  center

   **Missing hydrogen (products)**

   *Example of products generated with reaction defined in 'Missing hydrogen (reaction)'*


By adding two explicit (or implicit) hydrogens to the reactant atom with atom map ``8``
in :ref:`Figure: Missing hydrogen (reaction)<figure_oelibgen_missing_hydrogen_reaction>`,
ensures that only reaction 'B'
is executed, since the starting material of reaction 'A' no longer matches the
reaction pattern.

.. note::

   In order to generate products with correct valences, a mapped reactant atom should
   have as many as explicit or implicit hydrogens as many as new bonds the atom
   forms on the product side

.. _subsection_reactions_libgen_kekule:

Product Kekulization
--------------------------------------------------------------------------------

.. index:: OEKekulize, OEAssignAromaticFlags

Prior to returning a generated product, :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` calls
the :oe:func:`OEKekulize<OEChem::OEKekulize>` and
:oe:func:`OEAssignAromaticFlags<OEChem::OEAssignAromaticFlags>` functions to
determine the Kekulé form and aromaticity of the generated product.
Since :oe:func:`OEKekulize<OEChem::OEKekulize>` requires the correct specification
of the formal charges and implicit hydrogen counts of each atom, the Kekulé form of
a generated product depends on the reaction specification.

The three reactions shown in :ref:`figure_oelibgen_arom_reaction` describe the
same set of transformations, but they generate products with different but valid
Kekulé forms.
Reactions 'A' and 'B' in :ref:`figure_oelibgen_arom_reaction` will produce products
'A' and 'B' in  :ref:`figure_oelibgen_arom_example`, respectively.
However, reaction 'C' arbitrarily generates either product 'A' or its tautomer
product 'B', since this reaction describes ambiguous  Kekulé form for the 5-membered
ring in the product.

.. _figure_oelibgen_arom_reaction:

.. figure:: images/OELibGen-arom-reaction.png
   :scale:  100
   :align:  center

   **Identical transformations**

   *Three reactions describing the same transformation*

.. _figure_oelibgen_arom_example:

.. figure:: images/OELibGen-arom-example.png
   :scale:  100
   :align:  center

   **Products**

   *Example of products generated with reactions defined in 'Identical transformations'*


.. note::

   In order to generate products with the desired Kekulé form, either the product
   has to have only specific bonds or explicit/implicit hydrogens have to be
   specified to eliminate ambiguities.


Even though the reaction in :ref:`figure_oelibgen_arom_reaction_2` defines an
unambiguous Kekulé form, this form is not suited for every product generated by
the reaction (see examples in :ref:`figure_oelibgen_arom_example_2`).
In order to ensure that the :oe:cls:`OELibraryGen<OEChem::OELibraryGen>` generates
products with valid Kekulé form the following steps are performed.
First, Kekulization is performed based on the reaction specification.
If it is unsuccessful, *i.e.* :oe:func:`OEKekulize<OEChem::OEKekulize>` function
returns false, alternatives are tried by adding and removing implicit hydrogens
from aromatic nitrogens, until a valid Kekulé form is found.


.. _figure_oelibgen_arom_reaction_2:

.. figure:: images/OELibGen-arom-reaction-2.png
   :scale:  100
   :align:  center

   **Reaction**

   *Example of reaction with generic atoms in an aromatic ring system (``s*`` = number of non-hydrogen substituents as drawn).*

.. _figure_oelibgen_arom_example_2:

.. figure:: images/OELibGen-arom-example-2.png
   :scale:  100
   :align:  center

   **Products**

   *Example of products generated with the reaction shown in previous figure*

