.. include:: ../../toolkit-substitutions
.. include:: ../../common/cookbook/cookbook-hyperlinks

.. oe:namespace:: OEChem

.. oe:function:: OEHelmToMol

   .. attention::

      |PRELIMINARY-API|

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

      .. oe:api::

         bool OEHelmToMol(OEMolBase& mol, const std::string& helm,
                          const OEMonomerSet& monomers)
         bool OEHelmToMol(OEMolBase& mol, const std::string& helm,
                          const OEMonomerSet& monomers,
                          OEHelmParsingResult& result)

   .. oe:language:: python

      .. oe:api:: python

         OEHelmToMol(mol: Union[OEGraphMol,OEMol,OEQMol], helm: str,
                     monomers: OEMonomerSet) -> bool
         OEHelmToMol(mol: Union[OEGraphMol,OEMol,OEQMol], helm: str,
                     monomers: OEMonomerSet, result: OEHelmParsingResult) -> bool


   Converts a :term:`HELM` string into a molecule. The function will return true
   if the :term:`HELM` string can be parsed and interpreted successfully, otherwise
   the function will return false and a given molecule will be cleared.

   mol
    The constructed molecule (:oe:cls:`OEChem::OEMolBase`).

   helm
    The :term:`HELM` string that is parsed into the molecule. 

   monomers
    The monomer set (:oe:cls:`OEChem::OEMonomerSet`) that stores the monomers that
    are used to interpret the :term:`HELM` string.

    If the given monomer set supports multiple code sets, :oe:func:`OEChem::OEHelmToMol` automatically
    selects the code set that contains all monomer codes needed to parse the :term:`HELM` string.

   result
    Is specified, the :oe:cls:`OEChem::OEHelmParsingResult` object will store additional
    parsing information.

   After constructing the molecule the following properties are perceived:

   * Rings are perceived by calling the
     :oe:func:`OEChem::OEFindRingAtomsAndBonds` function.

   * The aromaticity is assigned by calling the
     :oe:func:`OEChem::OEAssignAromaticFlags` function using the
     :oe:const:`OEChem::OEAroModel::OpenEye` aromaticity model.

   * The chirality is perceived by calling the
     :oe:func:`OEChem::OEPerceiveChiral` function.

   .. warning::

      The current implementation of HELM parsing algorithm does not support ``RNA`` polymers.

   **Example**

   .. oe:source:: HelmToMol.py
      :language: python
      :noindent:
      :frag:     SNIPPET

   .. oe:source:: HelmToMol.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET


   :oe:func:`OEChem::OEHelmToMol` can parse :term:`HELM` strings with embedded SMILES in various styles.
   The examples below illustrate valid representations of eledoisin:

   .. code-block:: text
      :linenos:

      PEPTIDE1{[N1[C@@H](CCC1=O)C([R2])=O].P.S.K.D.A.F.I.G.L.M.[am]}$$$$
      PEPTIDE1{[N1[C@@H](CCC1=O)C([*:2])=O].P.S.K.D.A.F.I.G.L.M.[am]}$$$$
      PEPTIDE1{[N1[C@@H](CCC1=O)C(*)=O |$;;;;;;;_R2;$|].P.S.K.D.A.F.I.G.L.M.[am]}$$$$

   In case when the :oe:func:`OEChem::OEHelmToMol` function successfully parses a :term:`HELM` string
   the atoms that are generated for a specific monomer are added to a molecule
   as a group (:oe:cls:`OEChem::OEGroupBase`)

   .. seealso::

      * [Zhang-2012]_ publications
      * :oe:func:`OEChem::OEGetHelmMonomerCodes` function
      * :oe:func:`OEChem::OEGetHelmChainNames` function
      * :oe:func:`OEChem::OEMolToHelm` function

   .. admonition:: OpenEye Python Cookbook Code Example

      * `Convert HELM to SMILES`_
      * `Convert HELM File to Molecule File`_

