.. _chapter_atomproperties:

********************************************************************************
Atom Properties
********************************************************************************

.. index:: OEAtomBase, atom properties

The :oe:cls:`OEAtomBase<OEChem::OEAtomBase>` class is the workhorse of the
**OEChem TK** library, representing the atoms of a molecule.
This section details some of its important and often used properties and methods.

.. _section_atomproperties_readwrite:

Read/Write Atom Properties
================================================================================

.. index::
   single: atomic number
   single: formal charge
   single: implicit hydrogens
   single: isotopic mass
   single: partial charge
   single: atomic hybridization
   single: integer atom type
   single: atom name
   single: atom type name
   single: atom radius
   single: reaction role
   single: reaction map index
   single: atom ring membership
   single: atom aromaticity
   single: atom chirality
   single: atom stereo

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

   * - Property Name
     - Type
     - Get Method
     - Set Method
     - See Also
   * - Atomic Number
     - unsigned int
     - :oe:meth:`GetAtomicNum<OEChem::OEAtomBase::GetAtomicNum>`
     - :oe:meth:`SetAtomicNum<OEChem::OEAtomBase::SetAtomicNum>`
     -
   * - Formal Charge
     - int
     - :oe:meth:`GetFormalCharge<OEChem::OEAtomBase::GetFormalCharge>`
     - :oe:meth:`SetFormalCharge<OEChem::OEAtomBase::SetFormalCharge>`
     - :ref:`Formal Charges<chapter_charges>`
   * - Implicit Hyd. Count
     - unsigned int
     - :oe:meth:`GetImplicitHCount<OEChem::OEAtomBase::GetImplicitHCount>`
     - :oe:meth:`SetImplicitHCount<OEChem::OEAtomBase::SetImplicitHCount>`
     - .. :ref:`chapter_hydrogens` STILL EMPTY CHAPTER
   * - Isotopic Mass
     - unsigned int
     - :oe:meth:`GetIsotope<OEChem::OEAtomBase::GetIsotope>`
     - :oe:meth:`SetIsotope<OEChem::OEAtomBase::SetIsotope>`
     -
   * - Partial Charge
     - double
     - :oe:meth:`GetPartialCharge<OEChem::OEAtomBase::GetPartialCharge>`
     - :oe:meth:`SetPartialCharge<OEChem::OEAtomBase::SetPartialCharge>`
     - :ref:`Partial Charges<chapter_charges>`
   * - Atomic Hybridization
     - unsigned int
     - :oe:meth:`GetHyb<OEChem::OEAtomBase::GetHyb>`
     - :oe:meth:`SetHyb<OEChem::OEAtomBase::SetHyb>`
     -
   * - Integer Atom Type
     - int
     - :oe:meth:`GetIntType<OEChem::OEAtomBase::GetIntType>`
     - :oe:meth:`SetIntType<OEChem::OEAtomBase::SetIntType>`
     -
   * - Atom Name
     - string
     - :oe:meth:`GetName<OEChem::OEAtomBase::GetName>`
     - :oe:meth:`SetName<OEChem::OEAtomBase::SetName>`
     -
   * - Atom Type Name
     - string
     - :oe:meth:`GetType<OEChem::OEAtomBase::GetType>`
     - :oe:meth:`SetType<OEChem::OEAtomBase::SetType>`
     -
   * - Atom Radius
     - double
     - :oe:meth:`GetRadius<OEChem::OEAtomBase::GetRadius>`
     - :oe:meth:`SetRadius<OEChem::OEAtomBase::SetRadius>`
     -
   * - Reaction Role
     - unsigned int
     - :oe:meth:`GetRxnRole<OEChem::OEAtomBase::GetRxnRole>`
     - :oe:meth:`SetRxnRole<OEChem::OEAtomBase::SetRxnRole>`
     - :ref:`chapter_reactions`
   * - Reaction Map Index
     - unsigned int
     - :oe:meth:`GetMapIdx<OEChem::OEAtomBase::GetMapIdx>`
     - :oe:meth:`SetMapIdx<OEChem::OEAtomBase::SetMapIdx>`
     - :ref:`chapter_reactions`
   * - Ring Membership
     - bool
     - :oe:meth:`IsInRing<OEChem::OEAtomBase::IsInRing>`
     - :oe:meth:`SetIsInRing<OEChem::OEAtomBase::SetInRing>`
     - :ref:`chapter_ring`
   * - Aromaticity
     - bool
     - :oe:meth:`IsAromatic<OEChem::OEAtomBase::IsAromatic>`
     - :oe:meth:`SetAromatic<OEChem::OEAtomBase::SetAromatic>`
     - :ref:`Aromaticity<chapter_aromaticity>`
   * -  Atom Chirality
     -  bool
     - :oe:meth:`IsChiral<OEChem::OEAtomBase::IsChiral>`
     - :oe:meth:`SetChiral<OEChem::OEAtomBase::SetChiral>`
     - :ref:`Stereochemistry<chapter_stereochemistry>`
   * -  Atom Stereo
     -  unsigned int
     - :oe:meth:`GetStereo<OEChem::OEAtomBase::GetStereo>`
     - :oe:meth:`SetStereo<OEChem::OEAtomBase::SetStereo>`
     - :ref:`Stereochemistry<chapter_stereochemistry>`


.. _section_atomproperties_readonly:

Read Only  Atom Properties
================================================================================

.. index::
   single: atom degree
   single: explicit atom degree
   single: explicit hydrogen count
   single: explicit valence
   single: atom heavy degree
   single: atom heavy valence
   single: atom parent
   single: total hydrogen count
   single: atom valence
   single  atom index
   single: atom connection

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

   * - Property Name
     - Type
     - Get Method
     - See Also
   * - Atom Degree
     - unsigned int
     - :oe:meth:`GetDegree<OEChem::OEAtomBase::GetDegree>`
     -
   * - Explicit Atom Degree
     - unsigned int
     - :oe:meth:`GetExplicitDegree<OEChem::OEAtomBase::GetExplicitDegree>`
     -
   * - Explicit Hydrogen Count
     - unsigned int
     - :oe:meth:`GetExplicitHCount<OEChem::OEAtomBase::GetExplicitHCount>`
     - .. :ref:`chapter_hydrogens` STILL EMPTY CHAPTER
   * - Explicit Valence
     - unsigned int
     - :oe:meth:`GetExplicitValence<OEChem::OEAtomBase::GetExplicitValence>`
     - :ref:`chapter_valence`
   * - Atom Heavy Degree
     - unsigned int
     - :oe:meth:`GetHvyDegree<OEChem::OEAtomBase::GetHvyDegree>`
     -
   * - Atom Heavy Valence
     - unsigned int
     - :oe:meth:`GetHvyValence<OEChem::OEAtomBase::GetHvyValence>`
     - :ref:`chapter_valence`
   * - Atom Parent
     - :oe:cls:`OEMolBase<OEChem::OEMolBase>`
     - :oe:meth:`GetParent<OEChem::OEAtomBase::GetParent>`
     -
   * - Total Hydrogen Count
     - unsigned int
     - :oe:meth:`GetTotalHCount<OEChem::OEAtomBase::GetTotalHCount>`
     - .. :ref:`chapter_hydrogens` STILL EMPTY CHAPTER
   * - Atom Valence
     - unsigned int
     - :oe:meth:`GetValence<OEChem::OEAtomBase::GetValence>`
     - :ref:`chapter_valence`
   * - Atom Index
     - unsigned int
     - :oe:meth:`GetIdx<OEChem::OEAtomBase::GetIdx>`
     - :ref:`chapter_atombondindices`
   * - Atom Has Stereo
     - bool
     - :oe:meth:`HasStereoSpecified<OEChem::OEAtomBase::HasStereoSpecified>`
     - :ref:`chapter_stereochemistry`
   * - Atom Connection
     - bool
     - :oe:meth:`IsConnected<OEChem::OEAtomBase::IsConnected>`
     -

.. _section_atomproperties_genericdata:

Attach Generic Data to Atoms
================================================================================

Generic data (see :ref:`chapter_genericdata`) can be attached to any object that
derives from the :ref:`OEBase <OESystem_OEBase>` class. The following program shows
an example where hydrogen bonding donor property is attached as a ``bool`` value
to the corresponding :ref:`OEAtomBase <OEChem_OEAtomBase>` object.

.. oe:source:: GenericDataToAtom.py
   :language: python
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. oe:language:: python

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



.. oe:source:: GenericDataToAtom.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. oe:source:: GenericDataToAtom.java
   :language: java
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. oe:source:: GenericDataToAtom.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

The :ref:`OEAtomBase <OEChem_OEAtomBase>` 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
