.. include:: ../substitutions

.. oe:namespace:: OEChem

..  _OECreateIsoSmiString:

.. meta::
   :keywords: OECreateIsoSmiString

.. oe:function:: OECreateIsoSmiString

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

      .. oe:api::

         void OECreateIsoSmiString(std::string& str, const OEMolBase& mol)

   .. oe:language:: python

      .. oe:api:: python

         OECreateIsoSmiString(str: str, mol: Union[OEGraphMol,OEMol,OEQMol]) -> None

   Creates an :term:`canonical isomeric SMILES` string representing a given molecule.

   This function is just a special case of the :oe:func:`OEChem::OECreateSmiString`
   function, called with the flavor :oe:const:`OEChem::OESMILESFlag::ISOMERIC`.

   .. note::

      This function produces SMILES that correspond  what *Daylight*  Chemical Information
      Systems term an '*absolute*' SMILES

   Note that the canonical SMILES generated by this function remains
   dependent on the state of the molecule, especially its aromaticity
   state (see examples in :ref:`section_aromaticity_models` section).
   Thus, to generate a canonical smiles suitable for purposes
   such as a database key, the user must assure that the state of
   the molecule has been standardized.
   In particular, aromaticity should be perceived according to the preferred model.

   In contrast, the high-level output function :oe:func:`OEChem::OEWriteMolecule`
   (and :oe:func:`OEChem::OEMolToSmiles`) , when
   writing the canonical SMILES format (:oe:const:`OEChem::OEFormat::ISM`) does invoke
   :oe:func:`OEChem::OEFindRingAtomsAndBonds` and :oe:func:`OEChem::OEAssignAromaticFlags`.

   Furthermore, whether :oe:func:`OEChem::OEWriteMolecule` or
   :oe:func:`OEChem::OECreateIsoSmiString` is used, the canonical SMILES generated depends on
   the current stereo specifications for the molecule.
   If the goal is a :term:`canonical isomeric SMILES` which is unique for all representations
   of an equivalent stereoisomer, *i.e.*, for use as a database key, it is the user's
   responsibility to assure that the stereochemical state of the molecule has been
   rationalized and standardized, using methods such as:

   * :oe:func:`OEChem::OEPerceiveChiral`, :oe:func:`OEChem::OE3DToAtomStereo`, :oe:func:`OEChem::OE3DToBondStereo`
   * :oe:meth:`OEChem::OEAtomBase::IsChiral`, :oe:meth:`OEChem::OEAtomBase::SetStereo`
   * :oe:meth:`OEChem::OEBondBase::IsChiral`, :oe:meth:`OEChem::OEBondBase::SetStereo`

   .. seealso::

      .. oe:language:: c++

         * :oe:func:`OEChem::OEMolToSmiles` for a high-level way to create
           :term:`SMILES` equivalent to what is written by
           :oe:func:`OEChem::OEWriteMolecule`.
         * :oe:func:`OEChem::OECreateAbsSmiString` to create an arbitrary :term:`SMILES`
         * :oe:func:`OEChem::OECreateCanSmiString` to create a :term:`canonical SMILES`
         * Example program :ref:`uniqmol.cpp<section_example_oechem_uniqmol>`

      .. oe:language:: python

         * :oe:func:`OEChem::OEMolToSmiles` for a high-level way to create
           :term:`SMILES` equivalent to what is written by
           :oe:func:`OEChem::OEWriteMolecule`.
         * :oe:func:`OEChem::OECreateAbsSmiString` to create an arbitrary :term:`SMILES`
         * :oe:func:`OEChem::OECreateCanSmiString` to create a :term:`canonical SMILES`
         * Example program :ref:`uniqmol.py<section_example_oechem_uniqmol>`

      .. oe:language:: java

         * :oe:func:`OEChem::OEMolToSmiles` for a high-level way to create
           :term:`SMILES` equivalent to what is written by
           :oe:func:`OEChem::OEWriteMolecule`.
         * :oe:func:`OEChem::OECreateAbsSmiString` to create an arbitrary :term:`SMILES`
         * :oe:func:`OEChem::OECreateCanSmiString` to create a :term:`canonical SMILES`
         * Example program :ref:`UniqMol.java<section_example_oechem_uniqmol>`

      .. oe:language:: csharp

         * :oe:func:`OEChem::OEMolToSmiles` for a high-level way to create
           :term:`SMILES` equivalent to what is written by
           :oe:func:`OEChem::OEWriteMolecule`.
         * :oe:func:`OEChem::OECreateAbsSmiString` to create an arbitrary :term:`SMILES`
         * :oe:func:`OEChem::OECreateCanSmiString` to create a :term:`canonical SMILES`
         * Example program :ref:`UniqMol.cs<section_example_oechem_uniqmol>`


   **Validation:**

   The :oe:func:`OEChem::OECreateIsoSmiString` is rigorously tested to ensure
   that it generates unique string representations of molecules.
   This test involves randomly reordering the atoms and bonds of molecules
   and confirming that this has no effect on the SMILES generated by the
   :oe:func:`OEChem::OECreateIsoSmiString` function.

   .. table:: Performance of **OECreateIsoSmiString** to generate :term:`canonical isomeric SMILES`

      =================== ========= ============
      Database            Size      Success Rate
      =================== ========= ============
      Wombat              53K       100.0 %
      Maybridge           64K       100.0 %
      MDDR                111K      100.0 %
      NCI                 250K      100.0 %
      =================== ========= ============

   Running the validation test on 24M unique molecules produces only
   129 failure cases.

