.. _chapter_designdecisions:

********************************************************************************
Design Decisions
********************************************************************************

This chapter seeks to give a general overview of the major design
decisions behind **OEChem TK**. The reader should have an understanding of
the basic **OEChem TK** objects and functions. The reader should also be
familiar with the basics of object oriented programming.

Throughout this manual, the :ref:`OEMol <OEChem_OEMol>`,
:ref:`OEGraphMol <OEChem_OEGraphMol>`, and :ref:`OEQMol <OEChem_OEQMol>` are the
concrete classes which handle most molecular representation in
**OEChem TK**. The :ref:`OEGraphMol <OEChem_OEGraphMol>` API is defined in the
:ref:`OEMolBase <OEChem_OEMolBase>` abstract base-class, the
:ref:`OEMol <OEChem_OEMol>` API is defined by the
:ref:`OEMolBase <OEChem_OEMolBase>` and
:oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>` abstract base-classes, and
the :ref:`OEQMol <OEChem_OEQMol>` API is defined by the
:ref:`OEMolBase <OEChem_OEMolBase>` and :ref:`OEQMolBase <OEChem_OEQMolBase>` abstract
base-classes. The :oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>` class
publicly inherits from the :ref:`OEMolBase <OEChem_OEMolBase>` class, which in
turn inherits from the :ref:`OEBase <OESystem_OEBase>` class. Similarly, the
:ref:`OEQMolBase <OEChem_OEQMolBase>` class publicly inherits from the
:ref:`OEMolBase <OEChem_OEMolBase>` class, which again inherits from the
:ref:`OEBase <OESystem_OEBase>` class. An :ref:`OEGraphMol <OEChem_OEGraphMol>`, can
be passed to any function which takes an :ref:`OEMolBase <OEChem_OEMolBase>`
argument. An :ref:`OEMol <OEChem_OEMol>` can be passed to any function
which takes an :oe:cls:`OEMCMolBase<OEChem::OEMCMolBase>` or
:ref:`OEMolBase <OEChem_OEMolBase>` argument, and an :ref:`OEQMol <OEChem_OEQMol>`
can be passed to any function which takes an
:ref:`OEQMolBase <OEChem_OEQMolBase>` or :ref:`OEMolBase <OEChem_OEMolBase>`
argument. :ref:`Figure: Hierarchy A<figure_molhierarchy>` represents the **OEChem TK**
molecule hierarchy described in this paragraph.

.. _figure_molhierarchy:

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

   **Hierarchy A**

   **OEChem TK** Molecule Hierarchy


.. seealso: STILL EMPTY CHAPTER

   The :ref:`chapter_genericdata` chapter discusses why everything
   derives from :ref:`OEBase <OESystem_OEBase>`.

.. _section_designdecisions_abstract_baseclasses:

Abstract Base-Classes
================================================================================

The most important data types in the **OEChem TK** library are
:ref:`OEMolBase <OEChem_OEMolBase>`, :ref:`OEAtomBase <OEChem_OEAtomBase>`, and
:ref:`OEBondBase <OEChem_OEBondBase>`. These three classes describe the
behaviors of molecules, atoms, and bonds respectively. However, these
types are `abstract classes
<http://en.wikipedia.org/wiki/Abstract_type>`_, describing the methods
and semantics of molecules, atoms and bonds, but without defining an
actual implementation.
(See :ref:`Figure: Hierarchy B<figure_baseclass_hierarchy>`)

.. _figure_baseclass_hierarchy:

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

   **Hierarchy B**

   **OEChem TK** Abstract Base-Classes


Hiding the implementation of these types is very important to the
longevity of **OEChem TK**. It avoids the problem of the `leaky abstraction
<http://en.wikipedia.org/wiki/Leaky_abstraction>`_. If code was
written that was expecting a certain behavior from the implementation
it would be fragile to arbitrary changes in implementation.
Therefore, these abstract base-classes are considered
stable, with a guarantee that they will not change from version to
version.

.. *OpenEye* spends quite a bit of resources in tuning implementations, doing so
   should not break downstream code from one version to the
   next.

.. note::

   Since :ref:`OEAtomBase <OEChem_OEAtomBase>`, :ref:`OEBondBase <OEChem_OEBondBase>`, and
   :oe:cls:`OEConfBase<OEChem::OEConfBase>` can only be accessed
   through their parent molecules, there is no need for concrete
   instances of these classes. In **OEChem TK**, these three classes are
   accessed via references to their respective base-classes, or
   through the iterator interface discussed in the
   :ref:`chapter_atombondtraversal` chapter.

.. _section_designdecisions_factoryfunctions:

Factory Functions
================================================================================

It is standard practice when working with abstract base-classes, such
as the :ref:`OEMolBase <OEChem_OEMolBase>`, to define a function which returns
a pointer to one of these objects. These functions, called `factories
<http://en.wikipedia.org/wiki/Factory_method_pattern>`_, give library
users access to concrete objects even when only the abstract
base-class is exposed in the public API. The following factory
functions are provided to create molecule objects in **OEChem TK**. The
associated symbolic namespace is used to control what type of molecule
implementation is returned.

.. list-table::
   :header-rows: 1

   * - Factory Function
     - Symbolic Namespace
   * - :oe:func:`OEChem::OENewMolBase`
     - :oe:constns:`OEChem::OEMolBaseType`
   * - :oe:func:`OEChem::OENewMCMolBase`
     - :oe:constns:`OEChem::OEMCMolType`
   * - :oe:func:`OEChem::OENewQMolBase`
     - :oe:constns:`OEChem::OEQMolType`

.. _section_designdecisions_smartpointers:

Smart Pointers
================================================================================

The problem with factory functions is that they require the user to
manage the object's memory. When the factory function returns a
pointer to an abstract base-class, it also passes ownership of the
memory to the programmer. To alleviate the problems associated with
memory management introduced by factories, the `smart-pointer
<http://en.wikipedia.org/wiki/Smart_pointer>`_ idiom is often
used. Simply put, a smart-pointer holds a real pointer to an object,
and deallocates the pointer's memory when the smart-pointer goes out
of scope (*e.g.* in its destructor). In **OEChem TK**,
:oe:cls:`OEGraphMols<OEChem::OEGraphMol>`,
:oe:cls:`OEMols<OEChem::OEMol>`, and :oe:cls:`OEQMols<OEChem::OEQMol>`
fulfill the function of both factories and smart-pointers. This gives
the user access to multiple implementations without the need of
worrying about memory management. The constructors allow the user to
specify which implementation they would like using the associated
symbolic namespace described in the previous table. Then the objects
themselves act as smart-pointers, cleaning up the implementation
pointers when the molecules go out of scope.

:oe:src:`Listing 1<SNIPPET-MolBaseType>` demonstrates how to specify an
alternative molecule implementation. A :ref:`SMILES <chapter_SMILES>`
string is then read into different implementation. This
demonstrates how implementations that adhere to the
:ref:`OEMolBase <OEChem_OEMolBase>` interface can reuse existing algorithms
written towards it.

.. oe:source:: MolBaseType.cpp
   :language: c++
   :caption:  Using an alternative molecule implementation
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: MolBaseType.py
   :language: python
   :caption:  Using an alternative molecule implementation
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: MolBaseType.java
   :language: java
   :caption:  Using an alternative molecule implementation
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: MolBaseType.cs
   :language: csharp
   :caption:  Using an alternative molecule implementation
   :refnum:   1
   :frag:     SNIPPET

.. _section_molimplementations_inmemorymolecules:

.. In Memory Molecules
.. ============================================================================


.. _section_molimplementations_querymolecules:

Query Molecules
============================================================================

It is not uncommon in chemical informatics to consider the equivalence
of the graph which represents a molecule and the graph which
represents a substructure query.  Indeed the simplest of queries are
molecules themselves.  If one considers each node (or atom) as a
potentially complex atom query, even highly complex queries can be
represented as molecules.

In **OEChem TK**, this concept of a query as a molecule is represented by
the :ref:`OEQMolBase <OEChem_OEQMolBase>` abstract base-class.  An
:ref:`OEQMolBase <OEChem_OEQMolBase>` contains :ref:`OEQAtomBase <OEChem_OEQAtomBase>` and
:ref:`OEQBondBase <OEChem_OEQBondBase>` atom and bond representations.  These
versions of **OEChem TK** atoms and bonds manage the atom and bond
expressions which comprise the query.

**OEChem TK** defines the concrete :ref:`OEQMol <OEChem_OEQMol>` class which
provides a programmer access to the API defined by the
:ref:`OEQMolBase <OEChem_OEQMolBase>` class.  This is analogous to the way an
:ref:`OEGraphMol <OEChem_OEGraphMol>` provides concrete access to
:ref:`OEMolBase <OEChem_OEMolBase>` API. :ref:`Figure: Hierarchy C<figure_qmolhierarchy>`
represents the **OEChem TK** query molecule hierarchy.

.. _figure_qmolhierarchy:

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

   **Hierarchy C**

   **OEChem TK** Query Molecule Hierarchy

This abstraction allows **OEChem TK** to treat separate query mechanisms to
work similarly. This is similar to how **OEChem TK** can represent any
molecular file format through a single :ref:`OEMolBase <OEChem_OEMolBase>`
interface. For example, :ref:`SMARTS <chapter_SMARTS>` can be parsed
into an :ref:`OEQMolBase <OEChem_OEQMolBase>` using the
:oe:func:`OEChem::OEParseSmarts` function. Also, :ref:`MDL Queries
<chapter_mdlqueries>` can be parsed into an
:ref:`OEQMolBase <OEChem_OEQMolBase>` using the
:oe:func:`OEChem::OEReadMDLQueryFile` file.

.. seealso::

   :ref:`chapter_patternmatch` for a general discussion of **OEChem TK**
   pattern matching facilities.

.. _section_designdecisions_freefunctions:

Free-Functions
============================================================================

**OEChem TK** is an object-oriented library. However, the design philosophy
is that molecule objects are primarily data containers with data
access member functions. Most powerful data analysis and manipulation
routines in **OEChem TK** are implemented as free functions rather than
member functions. This decision is based on the realization that the
abstraction of a molecule can be neither stable nor consistent. To one
programmer, a molecule should describe and perceive the space group of
organometallic complexes, while to another a molecule should describe
the residues and secondary structure of a macromolecule. Both of these
perspectives are reasonable and should be supported. Further, a nearly
infinite additional list of molecule designs can be imagined and
should be supported. In order to do this, the **OEChem TK** molecule must be
extensible, light-weight, and easily re-implemented. Thus, major
changes to the **OEChem TK** molecules can be made, without need to
re-implement more than a handful of functions. Conversely, an entire
new area of chemistry can be added to the **OEChem TK** repertoire through
free-functions without needing to implement the function in multiple
molecules. We have used namespaces extensively to keep the
free-functions from cluttering the global namespace.

.. oe:language:: c++ java csharp

   The concrete classes are provided for the reasons described in the
   :ref:`section_designdecisions_smartpointers` section. Function
   parameters should never specify these concrete classes. Instead,
   they should always be declared using the corresponding abstract
   base-classes. For instance, rather than:

.. oe:language:: c++

   .. code-block:: c++

      void fcn(const OEGraphMol &mol)
      {
        ...
      }


.. oe:language:: java

   .. code-block:: java

      void fcn(OEGraphMol mol)
      {
        ...
      }

.. oe:language:: csharp

   .. code-block:: csharp

      void fcn(OEGraphMol mol)
      {
        ...
      }

.. oe:language:: c++ java csharp

   Functions parameters should use the appropriate abstract base-class
   like the following:

.. oe:language:: c++

   .. code-block:: c++

      void fcn(const OEMolBase &mol)
      {
        ...
      }


.. oe:language:: java

   .. code-block:: java

      void fcn(OEMolBase mol)
      {
        ...
      }

.. oe:language:: csharp

   .. code-block:: csharp

      void fcn(OEMolBase mol)
      {
        ...
      }

.. seealso::

   The :ref:`OEChem Functions<chapter_oechemfunctions>` API section for
   a complete listing of all of **OEChem TK**'s free-functions.


.. _section_designdecisions_programminglayers:

Programming Layers: The Deep and Twisted Path
================================================================================

**OEChem TK** was designed to provide a library which puts powerful
algorithms in the hands of novice users without hand-cuffing the
expert. For this reason, **OEChem TK** can at the same time seem trivial
and overwhelming. There are often several ways to carry out certain
tasks in **OEChem TK** each with its subtle advantages, which can benefit
an experienced user. There are very few algorithms we have shied away
from including in **OEChem TK**, and many of the methods are new, unique
and powerful. This gives **OEChem TK** a very rich interface, yet to gain
this efficiency and power **OEChem TK** may force the user to think about
problems in ways they are not accustomed to doing. The hope is that
the user can benefit from the experience.

.. If it appears difficult to
   carry out a task with **OEChem TK**, please do not hesitate to contact
   *OpenEye* support (support@eyesopen.com).

**OEChem TK** has several layers of interfaces to most of its
functionality. There are "high-level" interfaces, which provide the
user with an enormous amount of power with minimal code. This level is
exemplified by the :oe:func:`OEChem::OEReadMolecule` and
:oe:func:`OEChem::OEWriteMolecule` functions. With these functions the
functionality of the ``babel`` file-format conversion program is
trivial. While this is trivial to write and understand (maybe after
understanding this manual), it should not belie the fact that **OEChem TK**
is carrying out an enormous amount of work under the surface.

A perhaps "mid-level" interface in **OEChem TK** is the ability to fine
tune molecule file-formats using flavors described in
:ref:`section_molreadwrite_flavoredinputandoutput` section. Flavors
are most useful when file-formats are being used for more than they
were originally intended, for example, PDB files.  While this
functionality is perhaps not for the first-day user, it certainly
doesn't require a stout heart.

Finally, for advanced programmers, **OEChem TK** provides access to nearly
all of the details. **OEChem TK** molecules have a simple API which can be
used to derived custom molecule implementations. The free-function
heavy API lets the user apply **OEChem TK's** powerful algorithms on custom
data structures. Similarly, many of the functions that are wrapped in
high level functions (like the molecule readers and writers) are also
available directly to the user at the low level. For instance,
:oe:func:`OEChem::OEWritePDBFile` allows the user to write out a PDB
file with a very specific flavor without any normalization that
:oe:func:`OEChem::OEWriteMolecule` may perform.

**OEChem TK** is a still a live moving software project. If a roadblock is
found a particular level, dig deeper into the next level. Often, the
functionality is already present.
