.. include:: ../substitutions

..  _OECreateCanSmiString:

.. oe:namespace:: OEChem

.. meta::
   :keywords: OECreateCanSmiString

.. oe:function:: OECreateCanSmiString

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

      .. oe:api::

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

   .. oe:language:: python

      .. oe:api:: python

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

   Creates a :term:`canonical SMILES` string representing a given molecule,
   but without isotopic labeling or stereochemistry.
   This function is just a special case of the :oe:func:`OEChem::OECreateSmiString`
   function, called with the flavor :oe:const:`OEChem::OESMILESFlag::DEFAULT`.

   .. note::

      This function produces what Daylight Chemical Information Systems
      term a *unique* 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`,
   when writing the canonical SMILES format (:oe:const:`OEChem::OEFormat::CAN`)
   does invoke :oe:func:`OEChem::OEFindRingAtomsAndBonds` and
   :oe:func:`OEChem::OEAssignAromaticFlags`.

   .. seealso::

      * :oe:func:`OEChem::OEMolToSmiles` for a high-level and **preferred** 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::OECreateIsoSmiString` to create an :term:`canonical isomeric SMILES`

   **Validation:**

   The :oe:func:`OEChem::OECreateCanSmiString` 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::OECreateCanSmiString` function.

   .. table:: Performance of **OECreateCanSmiString** to generate :term:`canonical 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 19M unique molecules produces only
   in 57 failures.

