.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEAddExplicitHydrogens

.. oe:function:: OEAddExplicitHydrogens

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

      .. oe:api::

         bool OEAddExplicitHydrogens(OEMolBase& mol, bool polarOnly = false,
                                     bool set3D = true)
         bool OEAddExplicitHydrogens(OEMCMolBase& mol, bool polarOnly = false,
                                     bool set3D = true)

   .. oe:language:: python

      .. oe:api:: python

         OEAddExplicitHydrogens(mol: OEMol, polarOnly: bool = False,
                                set3D: bool = True) -> bool
         OEAddExplicitHydrogens(mol: Union[OEGraphMol,OEQMol],
                                polarOnly: bool = False, set3D: bool = True) -> bool

   Converts the implicit hydrogens on the atoms of a molecule to
   explicit hydrogen atoms.  Zero or more new atoms are created with
   atomic number :oe:const:`OEChem::OEElemNo::H`, and new bonds are
   created to connect these to the parent atom with a single bond.
   This function also resets the implicit hydrogen count to zero.  

   polarOnly
     If ``true``, this function only add explicit hydrogens to polar atoms,
     *i.e.* when :oe:meth:`OEChem::OEAtomBase::IsPolar` returns
     ``true``.

   set3D
     If ``true``, the default, and the molecule
     is 3D, then the :oe:func:`OEChem::OESet3DHydrogenGeom` function is 
     automatically called on any hydrogen atom in the molecule that has the
     same coordinates as its parent heavy atom.

     If ``false``, then the sprouted hydrogens are initially given the same
     coordinates as their parent heavy atom.

   .. hint::

      In case of a 2D molecule, the coordinates of the explicit hydrogens
      can be assigned by calling the
      :oe:func:`OEChem::OESet2DHydrogenGeom` function.

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

      .. oe:api::

         bool OEAddExplicitHydrogens(OEMolBase& mol, OEAtomBase* hvyatom)

   .. oe:language:: python

      .. oe:api:: python

         OEAddExplicitHydrogens(mol: Union[OEGraphMol,OEMol,OEQMol],
                                atm: OEAtomBase) -> bool

   This function creates a new :ref:`OEAtomBase <OEChem_OEAtomBase>` for every
   implicit hydrogen on 'hvyatom', as given by
   :oe:meth:`OEChem::OEAtomBase::GetImplicitHCount`.  The new hydrogen
   atoms are given the same coordinates as their parent, 'hvyatom'.
   This function currently always returns ``true``.  To set the 2D or 3D
   geometry of these atoms, call the :oe:func:`OEChem::OESet2DHydrogenGeom`
   or :oe:func:`OEChem::OESet3DHydrogenGeom` functions, respectively.

   .. seealso::

      * :oe:func:`OEChem::OESuppressHydrogens` function
      * :oe:func:`OEChem::OESet2DHydrogenGeom` function
      * :oe:func:`OEChem::OESet3DHydrogenGeom` function
