.. _chapter_molproperties:

********************************************************************************
Molecule Properties
********************************************************************************

.. index:: OEMolBase

Molecules in **OEChem TK** are represented by
:oe:cls:`OEMolBases<OEChem::OEMolBase>`. In addition to keeping track
of the atoms and bonds that constitute a molecule, the
:ref:`OEMolBase <OEChem_OEMolBase>` is also used to store global information
and :ref:`chapter_genericdata` about the molecule.

.. _section_molproperties_readwrite:

Read/Write Molecule Properties
================================================================================

The :ref:`OEMolBase <OEChem_OEMolBase>` API provides the following methods for
storing common global information about the molecule.

.. index:: molecule dimension, molecule energy, reaction molecule, molecule title

.. list-table::
   :widths: 30 15 20 20 30
   :header-rows: 1

   * - Property Name
     - Type
     - Get Method
     - Set Method
     - See Also
   * - Coordinates
     - ``float`` array
     - :oe:meth:`GetCoords<OEChem::OEMolBase::GetCoords>`
     - :oe:meth:`SetCoords<OEChem::OEMolBase::SetCoords>`
     - :oe:meth:`ClearCoords<OEChem::OEMolBase::ClearCoords>`
   * - Dimension
     - ``unsigned int``
     - :oe:meth:`GetDimension<OEChem::OEMolBase::GetDimension>`
     - :oe:meth:`SetDimension<OEChem::OEMolBase::SetDimension>`
     -
   * - Energy
     - ``float``
     - :oe:meth:`GetEnergy<OEChem::OEMolBase::GetEnergy>`
     - :oe:meth:`SetEnergy<OEChem::OEMolBase::SetEnergy>`
     -
   * - Perception
     - ``bool``
     - :oe:meth:`HasPerceived<OEChem::OEMolBase::HasPerceived>`
     - :oe:meth:`SetPerceived<OEChem::OEMolBase::SetPerceived>`
     -
   * - Rxn
     - ``bool``
     - :oe:meth:`IsRxn<OEChem::OEMolBase::IsRxn>`
     - :oe:meth:`SetRxn<OEChem::OEMolBase::SetRxn>`
     - :ref:`chapter_reactions`
   * - Title
     - ``string``
     - :oe:meth:`GetTitle<OEChem::OEMolBase::GetTitle>`
     - :oe:meth:`SetTitle<OEChem::OEMolBase::SetTitle>`
     - :ref:`section_mprop_title`


.. _section_mprop_title:

Title
================================================================================

.. index:: molecule title

The **Title** property is a string used to represent the name of the
molecule.  The default value is an empty string.  This field may be used
to store a registry number or other identifier, instead of a common name.
The string is typically trimmed of white space by most file format
readers.

The following code uses the :oe:meth:`GetTitle<OEChem::OEMolBase::GetTitle>`
method to list the names of the molecules in a file.
The input file is read and the list of identifiers
(molecule names) are written to standard-out.

.. oe:source:: GetTitle.cpp
   :language: c++
   :caption:  Printing molecule titles
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: GetTitle.py
   :language: python
   :caption:  Printing molecule titles
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: GetTitle.java
   :language: java
   :caption:  Printing molecule titles
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: GetTitle.cs
   :language: csharp
   :caption:  Printing molecule titles
   :refnum:   1
   :frag:     SNIPPET

.. _section_molproperties_atomsandbonds:

Atoms and Bonds
================================================================================

The :ref:`OEMolBase <OEChem_OEMolBase>` API provides the following methods for
accessing and altering the connection table of the molecule.

.. index:: number of atoms, number of bonds, maximum atom index, maximum bond index

.. list-table::
   :widths: 30 15 20 30
   :header-rows: 1

   * - Description
     - Return Type
     - Method
     - See Also
   * - Number of Atoms
     - ``unsigned int``
     - :oe:meth:`NumAtoms<OEChem::OEMolBase::NumAtoms>`
     -
   * - Number of Bonds
     - ``unsigned int``
     - :oe:meth:`NumBonds<OEChem::OEMolBase::NumBonds>`
     -
   * - Maximum Atom Index
     - ``unsigned int``
     - :oe:meth:`GetMaxAtomIdx<OEChem::OEMolBase::GetMaxAtomIdx>`
     - :ref:`chapter_atombondindices`
   * - Maximum Bond Index
     - ``unsigned int``
     - :oe:meth:`GetMaxBondIdx<OEChem::OEMolBase::GetMaxBondIdx>`
     - :ref:`chapter_atombondindices`
   * - Access to an Atom
     - :oe:cls:`OEAtomBase<OEChem::OEAtomBase>`
     - :oe:meth:`GetAtom<OEChem::OEMolBase::GetAtom>`
     - :ref:`chapter_predicates`
   * - Access to a Bond
     - :oe:cls:`OEBondBase<OEChem::OEBondBase>`
     - :oe:meth:`GetBond<OEChem::OEMolBase::GetBond>`
     - :ref:`chapter_predicates`
   * - Access to all Atoms
     - :oe:cls:`OEIterBase\<OEAtomBase><OESystem::OEIterBase>`
     - :oe:meth:`GetAtoms<OEChem::OEMolBase::GetAtoms>`
     - :ref:`chapter_atombondtraversal`
   * - Access to all Bonds
     - :oe:cls:`OEIterBase\<OEBondBase><OESystem::OEIterBase>`
     - :oe:meth:`GetBonds<OEChem::OEMolBase::GetBonds>`
     - :ref:`chapter_atombondtraversal`
   * - Create a new Atom
     - :ref:`OEAtomBase <OEChem_OEAtomBase>`
     - :oe:meth:`NewAtom<OEChem::OEMolBase::NewAtom>`
     - :ref:`section_molproperties_atomandbondcreation`
   * - Create a new Bond
     - :ref:`OEBondBase <OEChem_OEBondBase>`
     - :oe:meth:`NewBond<OEChem::OEMolBase::NewBond>`
     - :ref:`section_molproperties_atomandbondcreation`
   * - Remove an Atom
     - ``bool``
     - :oe:meth:`DeleteAtom<OEChem::OEMolBase::DeleteAtom>`
     -
   * - Remove a Bond
     - ``bool``
     - :oe:meth:`DeleteBond<OEChem::OEMolBase::DeleteBond>`
     -
   * - Rearrange Atoms
     - ``bool``
     - :oe:meth:`OrderAtoms<OEChem::OEMolBase::OrderAtoms>`
     -
   * - Rearrange Bonds
     - ``bool``
     - :oe:meth:`OrderBonds<OEChem::OEMolBase::OrderBonds>`
     -

.. _section_molproperties_atomandbondcreation:

Atom and Bond Creation
================================================================================

**OEChem TK** contains functions that allow molecules to be constructed
from atoms and bonds explicitly. :oe:src:`Listing 2<SNIPPET-CreatingAtoms>`
demonstrates how to create the water molecule.

Atoms are created by calling the :oe:meth:`OEChem::OEMolBase::NewAtom`
method, and bonds are created by calling the
:oe:meth:`OEChem::OEMolBase::NewBond`
method. :oe:meth:`NewAtom<OEChem::OEMolBase::NewAtom>` takes the atomic
number of the atom to create and returns the new
:ref:`OEAtomBase <OEChem_OEAtomBase>`.
:oe:meth:`NewBond<OEChem::OEMolBase::NewBond>` takes two
:oe:cls:`OEAtomBases<OEChem::OEAtomBase>` and an integer bond order as
arguments and returns the new :ref:`OEBondBase <OEChem_OEBondBase>`.

.. oe:source:: CreatingAtoms.cpp
   :language: c++
   :caption:  Creating new atoms and bonds
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: CreatingAtoms.py
   :language: python
   :caption:  Creating new atoms and bonds
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: CreatingAtoms.java
   :language: java
   :caption:  Creating new atoms and bonds
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: CreatingAtoms.cs
   :language: csharp
   :caption:  Creating new atoms and bonds
   :refnum:   2
   :frag:     SNIPPET

In :oe:src:`Listing 2<SNIPPET-CreatingAtoms>` the atomic numbers of oxygen, 8,
and hydrogen, 1, are explicitly encoded in the program. To make code
easier to read and less error prone, **OEChem TK** provides symbolic
constants for the first 109 elements in the
:oe:constns:`OEChem::OEElemNo` namespace. The
:oe:constns:`OEChem::OEElemNo` namespace defines the atomic symbols
with the appropriate atomic number.

.. oe:source:: CreatingAtoms2.cpp
   :language: c++
   :caption:  Using OEElemNo namespace
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: CreatingAtoms2.py
   :language: python
   :caption:  Using OEElemNo namespace
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: CreatingAtoms2.java
   :language: java
   :caption:  Using OEElemNo namespace
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: CreatingAtoms2.cs
   :language: csharp
   :caption:  Using OEElemNo namespace
   :refnum:   3
   :frag:     SNIPPET


.. note::

   The atoms and bonds of a molecule are automatically deleted when
   their parent molecule is destroyed.

.. _section_molproperties_genericdata:

Attach Generic Data to Molecules
================================================================================

Generic data can be attached to any object that derives from the
:ref:`OEBase <OESystem_OEBase>` class. The following two snippets demonstrate how
generic data (e.g. molecule weight) can be attached to a molecule:

.. oe:source:: GenericData.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING


After annotation, the data can be accessed with the same integer or character string
identifier:

.. oe:source:: GenericData.py
  :language: python
  :noindent:
  :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.py
  :language: python
  :noindent:
  :frag:     SNIPPET-GET-DATA-STRING

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-GET-DATA-STRING

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-GET-DATA-STRING

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-GET-DATA-STRING


The :ref:`OEMolBase <OEChem_OEMolBase>` API provides the following
methods, publicly inherited from :ref:`OEBase <OESystem_OEBase>`, that
allow the manipulation of generic data.

.. list-table:: **Methods to manipulate generic data**
   :widths: 15 40
   :header-rows: 1

   * - Method
     - Description

   * - :oe:meth:`SetData<OESystem::OEBase::SetData>`
     - sets a generic data associating it with the given tag

   * - :oe:meth:`AddData<OESystem::OEBase::AddData>`
     -  adds a generic data associating it with the given tag

   * - :oe:meth:`HasData<OESystem::OEBase::HasData>`
     - determines whether a molecule has any generic data with a given tag

   * - :oe:meth:`GetData<OESystem::OEBase::GetData>`
     - returns the generic data associated with the given tag

   * - :oe:meth:`DeleteData<OESystem::OEBase::DeleteData>`
     - deletes all generic data  with the given tag

   * - :oe:meth:`Clear<OESystem::OEBase::Clear>`
     - clears all stored generic data

.. note::

   Generic data attached to a molecule or any of its atoms or bonds is automatically
   saved when the molecule is written into an :file:`.oeb` file.

.. seealso::

   * :ref:`section_attaching_other_objects` section
   * :ref:`section_moltaggeddata_SD` section
   * :ref:`section_moltaggeddata_PDB` section
   * For using tag data with multi-conformer molecules, see :ref:`section_oemol_sddata`
