.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OELibraryGen, LibraryGen


.. _OEChem_OELibraryGen:

.. oe:class:: OELibraryGen

   .. oe:api::

      class OELibraryGen

   This class represents :ref:`OELibraryGen <OEChem_OELibraryGen>` that is designed to perform
   library generation.

   .. seealso::

      * :ref:`chapter_reactions` chapter
      * :term:`SMIRKS`
      * :ref:`section_example_oechem_libgen` example
      * :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` class

   .. oe:method:: Constructors

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

         .. oe:api::

            OELibraryGen()

      .. oe:language:: python

         .. oe:api:: python

            OELibraryGen() -> OELibraryGen

      Default constructor.

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

         .. oe:api::

            OELibraryGen(const OELibraryGen& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OELibraryGen(rhs: OELibraryGen) -> OELibraryGen

      Copy constructor.

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

         .. oe:api::

            OELibraryGen(const char * smirks, bool strictSmirks = true)

      .. oe:language:: python

         .. oe:api:: python

            OELibraryGen(arg2: str, strictSmirks: bool = True) -> OELibraryGen

      Creates a :ref:`OELibraryGen <OEChem_OELibraryGen>` object with the given :term:`SMIRKS`
      reaction.
      Success of initialization can be tested using the operator
      :oe:meth:`OEChem::OELibraryGen::operator bool` method.

      Passing a value of ``false`` to the second method argument will relax
      the strict SMIRKS restrictions.
      A mapped reactant atom that does not have a corresponding mapped
      product atom is valid, and will be destroyed as part of the
      reaction.
      Unmapped reactant atoms will be used to match the reactant
      pattern, but are not destroyed when the reaction is applied.
      The resulting SMIRKS like reactions may therefore be more easily
      readable by humans as fewer atoms may be required to be mapped.

      Atoms in the provided reaction must have unique mapping numbers, otherwise
      there is ambiguity as to the correspondence of reactant to product atoms.
      A duplicate mapping number warning message indicates that the SMIRKS must be
      corrected prior to use.

      *smirks*
         The string representing the reaction for library generation.

      *strictSmirks*
         The parameter that specifies the interpretation of the :term:`SMIRKS`
         semantics.

      .. seealso::

         * :oe:meth:`OEChem::OELibraryGen::Init` method
         * :term:`SMIRKS`


   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OELibraryGen &operator=(const OELibraryGen &rhs)

      Assignment operator.


   .. oe:method:: operator()

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

         .. oe:api::

            bool operator()(OEMolBase &) const

      .. oe:language:: python

         .. oe:api:: python

            __call__(arg2: Union[OEGraphMol,OEMol,OEQMol]) -> bool

   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns ``true``, if the :ref:`OELibraryGen <OEChem_OELibraryGen>`
      object was initialized with no failures using either the
      constructors or one of the
      :oe:meth:`OEChem::OELibraryGen::Init` methods.

      The method will return ``false`` when the
      :ref:`OELibraryGen <OEChem_OELibraryGen>` object has not been properly
      initialized as it will be unable to apply transform operations
      to molecules.

   .. oe:method:: AddStartingMaterial

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

         .. oe:api::

            unsigned int AddStartingMaterial(const OEMolBase& mol,
                                             unsigned int reacnum,
                                             bool umatch = true)
            unsigned int AddStartingMaterial(OESystem::OEIter<OEMolBase> &,
                                             unsigned int reacnum,
                                             bool umatch = true)
            unsigned int AddStartingMaterial(OESystem::OEIterBase<OEMolBase> *,
                                             unsigned int reacnum,
                                             bool umatch = true)

      .. oe:language:: python

         .. oe:api:: python

            AddStartingMaterial(mol: Union[OEGraphMol,OEMol,OEQMol],
                                reacnum: int, umatch: bool = True) -> int

      Initializes the starting materials corresponding to a reaction
      component.
      An iterator over molecules or a single molecule may be passed as
      the first argument to the overloaded methods.
      Subsequent calls to the
      :oe:meth:`OEChem::OELibraryGen::AddStartingMaterial` methods
      append to the list of starting materials set in prior calls.
      The second argument (``reacnum``) specifies the reactant to which
      the starting materials correspond.  The return value is the number of
      starting materials that were successfully added for the specified reaction component.

      A copy of the starting material molecules are stored internally
      with the atom maps from the reactant pattern.
      This is done for efficiency, as each product molecule requires
      very little computational work to be done because of the
      starting material preprocessing.

      The final argument (``umatch``) is used to control the pattern
      matching of the reactant pattern to the starting material.
      If the value passed is ``true``, only matches that contain a
      unique set of atoms relative to previously identified matches
      are used.
      If the value is ``false``, every possible match including those
      related by symmetry will be used. Reactant patterns are unique
      matched by default.

      .. seealso::

         * :oe:meth:`OEChem::OELibraryGen::ClearStartingMaterial` method
         * :oe:meth:`OEChem::OELibraryGen::SetStartingMaterial` method
         * :ref:`subsection_reactions_libgen_sm` section of the
           :ref:


   .. oe:method:: ClearStartingMaterial

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

         .. oe:api::

            void ClearStartingMaterial(unsigned reacnum)

      .. oe:language:: python

         .. oe:api:: python

            ClearStartingMaterial(reacnum: int) -> None

      Removes any starting materials previously set by either the
      :oe:meth:`OEChem::OELibraryGen::AddStartingMaterial` or the
      :oe:meth:`OEChem::OELibraryGen::SetStartingMaterial` methods
      corresponding to the reactant pattern number ('reacnum' ) passed
      as the argument to the method.


   .. oe:method:: GetAssignMapIdx

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

         .. oe:api::

            bool GetAssignMapIdx() const

      .. oe:language:: python

         .. oe:api:: python

            GetAssignMapIdx() -> bool

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetAssignMapIdx` setter method


   .. oe:method:: GetClearCoordinates

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

         .. oe:api::

            bool GetClearCoordinates() const

      .. oe:language:: python

         .. oe:api:: python

            GetClearCoordinates() -> bool

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetClearCoordinates` setter method


   .. oe:method:: GetExplicitHydrogens

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

         .. oe:api::

            bool GetExplicitHydrogens() const

      .. oe:language:: python

         .. oe:api:: python

            GetExplicitHydrogens() -> bool

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetExplicitHydrogens` setter method


   .. oe:method:: GetProducts

      .. oe:api::

         OESystem::OEIterBase<OEMolBase> *GetProducts() const

      Returns an iterator over all the products generated by the library
      generation.


   .. oe:method:: GetRemoveUnmappedFragments

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

         .. oe:api::

            bool GetRemoveUnmappedFragments() const

      .. oe:language:: python

         .. oe:api:: python

            GetRemoveUnmappedFragments() -> bool

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetRemoveUnmappedFragments` setter method


   .. oe:method:: GetStartingMaterial

      .. oe:api::

         OESystem::OEIterBase<OEMolBase> *GetStartingMaterial(unsigned int rnum) const

      Returns an iterator over all the starting materials that have been successfully added to
      the :ref:`OELibraryGen <OEChem_OELibraryGen>` object.

      .. seealso::

         * :oe:meth:`OEChem::OELibraryGen::AddStartingMaterial` method
         * :oe:meth:`OEChem::OELibraryGen::SetStartingMaterial` method


   .. oe:method:: GetTitleSeparator

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

         .. oe:api::

            const std::string& GetTitleSeparator() const

      .. oe:language:: python

         .. oe:api:: python

            GetTitleSeparator() -> str

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetTitleSeparator` setter method


   .. oe:method:: GetValenceCorrection

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

         .. oe:api::

            bool GetValenceCorrection() const

      .. oe:language:: python

         .. oe:api:: python

            GetValenceCorrection() -> bool

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetValenceCorrection` setter method


   .. oe:method:: GetValidateKekule

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

         .. oe:api::

            bool GetValidateKekule() const

      .. oe:language:: python

         .. oe:api:: python

            GetValidateKekule() -> bool

      .. seealso::

         * Corresponding :oe:meth:`OEChem::OELibraryGen::SetValidateKekule` setter method


   .. oe:method:: Init

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

         .. oe:api::

            bool Init(const OEQMolBase& mol, bool strictSmirks = true)
            bool Init(const char* smirks, bool strictSmirks = true)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: OEQMol, strictSmirks: bool = True) -> bool
            Init(c: str, strictSmirks: bool = True) -> bool

      The first method initializes an :ref:`OELibraryGen <OEChem_OELibraryGen>`
      object with the :oe:cls:`OEQMolBase<OEChem::OEQMolBase>` object.
      The second method initializes an :ref:`OELibraryGen <OEChem_OELibraryGen>`
      object with the 'smirks' pattern.
      By default, the SMIRKS string is interpreted using strict semantics.

      Passing a value of ``false`` to the second method argument will relax
      the strict SMIRKS restrictions.
      A mapped reactant atom that does not have a corresponding mapped
      product atom is valid, and will be destroyed as part of the
      reaction.
      Unmapped reactant atoms will be used to match the reactant
      pattern, but are not destroyed when the reaction is applied.
      The resulting SMIRKS like reactions may therefore be more easily
      readable by humans as fewer atoms may be required to be mapped.


   .. oe:method:: NumReactants

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

         .. oe:api::

            unsigned int NumReactants() const

      .. oe:language:: python

         .. oe:api:: python

            NumReactants() -> int

      Returns the number of separate reactants that the
      :ref:`OELibraryGen <OEChem_OELibraryGen>` object perceived during
      initialization.
      The value returned will be equal to the number of graphically
      disconnected reactants that are not grouped together using the
      :term:`SMIRKS` parts primitive.


   .. oe:method:: NumPossibleProducts

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

         .. oe:api::

            unsigned int NumPossibleProducts() const

      .. oe:language:: python

         .. oe:api:: python

            NumPossibleProducts() -> int

      Returns the number of all possible products generated by the
      library generation. A warning message will be thrown if the
      number possible combinations exceeds the :math:`2^{32}` limit.

   .. oe:method:: SetAssignMapIdx

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

         .. oe:api::

            bool SetAssignMapIdx(bool)

      .. oe:language:: python

         .. oe:api:: python

            SetAssignMapIdx(arg2: bool) -> bool

      Sets whether the atom mapping of the reaction is transferred to the
      product.
      The default setting is ``false`` i.e. no mapping will be transferred to
      the product.

      .. list-table:: **Example of assigning map indices**
         :header-rows: 1

         * - reaction
           - product

         * - .. image:: ../images/amide-map.*
                :width:  500pt
           - .. image:: ../images/amide-product-map.*
                :width:  230pt

   .. oe:method:: SetClearCoordinates

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

         .. oe:api::

            bool SetClearCoordinates(bool clearcoords)

      .. oe:language:: python

         .. oe:api:: python

            SetClearCoordinates(arg2: bool) -> bool

      Sets whether the coordinates of a molecule are cleared when the
      molecule is added to the library generation by calling the
      :oe:meth:`OEChem::OELibraryGen::AddStartingMaterial` or
      :oe:meth:`OEChem::OELibraryGen::SetStartingMaterial` methods.
      The default setting is ``false`` i.e. the coordinates will be kept.

      .. note::

         The :ref:`OELibraryGen <OEChem_OELibraryGen>` modifies the molecular
         graph of the reactant(s) to generate products.
         Generating valid 2D or 3D coordinates for the products is
         beyond the scope of the :ref:`OELibraryGen <OEChem_OELibraryGen>`
         class.

         It is recommended to either clear the coordinates by
         invoking the :oe:meth:`OEChem::OELibraryGen::SetClearCoordinates`
         method or regenerate the coordinates of the products afterwards.


   .. oe:method:: SetExplicitHydrogens

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

         .. oe:api::

            bool SetExplicitHydrogens(bool explcitH)

      .. oe:language:: python

         .. oe:api:: python

            SetExplicitHydrogens(arg2: bool) -> bool

      Sets whether to add explicit hydrogens or suppress them when a
      starting material is added to the library.
      The default setting is ``true`` i.e. explicit hydrogens will be added.

      .. seealso::

         * :ref:`subsection_reactions_libgen_sm` section of the
           :ref:`chapter_reactions` chapter


   .. oe:method:: SetRemoveUnmappedFragments

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

         .. oe:api::

            bool SetRemoveUnmappedFragments(bool remove)

      .. oe:language:: python

         .. oe:api:: python

            SetRemoveUnmappedFragments(arg2: bool) -> bool

      Sets whether unmapped components of the products are removed or kept
      prior to returning them by the :oe:meth:`OEChem::OELibraryGen::GetProducts`
      method.
      The default setting is ``false`` i.e. unmapped components will be kept.

      .. seealso::

         * :ref:`subsection_reactions_libgen_atommapping` section of the
           :ref:`chapter_reactions` chapter


   .. oe:method:: SetStartingMaterial

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

         .. oe:api::

            unsigned int SetStartingMaterial(const OEMolBase& mol,
                                             unsigned int reacnum,
                                             bool umatch = true)
            unsigned int SetStartingMaterial(OESystem::OEIter<OEMolBase> &,
                                             unsigned int reacnum,
                                             bool umatch = true)
            unsigned int SetStartingMaterial(OESystem::OEIterBase<OEMolBase> *,
                                             unsigned int reacnum,
                                             bool umatch = true)

      .. oe:language:: python

         .. oe:api:: python

            SetStartingMaterial(mol: Union[OEGraphMol,OEMol,OEQMol],
                                reacnum: int, umatch: bool = True) -> int

      Initializes the starting materials corresponding to a reaction
      component.
      An iterator over molecules or a single molecule may be passed as
      the first argument to the overloaded methods.
      Subsequent calls to the
      :oe:meth:`OEChem::OELibraryGen::SetStartingMaterial` methods
      discard the list of starting materials set in prior calls.
      The second argument ('reacnum') specifies the reactant to which
      the starting materials correspond.

      A copy of the starting material molecules are stored internally
      with the atom maps from the reactant pattern.
      This is done for efficiency, as each product molecule requires
      very little computational work to be done because of the
      starting material preprocessing.

      The final argument ('umatch') is used to control the pattern
      matching of the reactant pattern to the starting material.
      If the value passed is ``true``, only matches that contain a
      unique set of atoms relative to previously identified matches
      are used.
      If the value is ``false``, every possible match including those
      related by symmetry will be used. Reactant patterns are unique
      matched by default.

      .. seealso::

         * :oe:meth:`OEChem::OELibraryGen::ClearStartingMaterial`
         * :oe:meth:`OEChem::OELibraryGen::AddStartingMaterial`
         * :ref:`subsection_reactions_libgen_sm` section of the
           :ref:`chapter_reactions` chapter


   .. oe:method:: SetTitleSeparator

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

         .. oe:api::

            bool SetTitleSeparator(const char* c)

      .. oe:language:: python

         .. oe:api:: python

            SetTitleSeparator(c: str) -> bool

      Sets the separator or delimiter used by the
      :ref:`OELibraryGen <OEChem_OELibraryGen>` object to compose product molecule
      titles.
      Product molecule titles are created by concatenating reactant
      molecule titles separated by a title separator or delimiter.
      The default separator is the underscore character ``_``.

      .. note::

         The title separator must be set prior to calling
         :oe:meth:`OEChem::OELibraryGen::GetProducts`.
         Calling :oe:meth:`OEChem::OELibraryGen::SetTitleSeparator`
         after calling :oe:meth:`OEChem::OELibraryGen::GetProducts`
         will have no affect on the resultant product molecule titles.

      .. seealso::

         * :ref:`subsection_reactions_libgen_tracking` section of the
           :ref:`chapter_reactions` chapter


   .. oe:method:: SetValenceCorrection

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

         .. oe:api::

            bool SetValenceCorrection(bool)

      .. oe:language:: python

         .. oe:api:: python

            SetValenceCorrection(arg2: bool) -> bool

      Sets whether valence correction is applied to the products prior to
      returning them by the :oe:meth:`OEChem::OELibraryGen::GetProducts`
      method.
      The default setting is ``false`` i.e. no valence correction will be performed.

      .. seealso::

         * :ref:`subsection_reactions_libgen_modes` section of the
           :ref:`chapter_reactions` chapter


   .. oe:method:: SetValidateKekule

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

         .. oe:api::

            bool SetValidateKekule(bool validate)

      .. oe:language:: python

         .. oe:api:: python

            SetValidateKekule(arg2: bool) -> bool

      Sets whether the generated products are simply returned after a
      Kekulization attempt, or if the |Kekule| form is validated more
      rigorously. If the extra validation is enabled and an invalid
      |Kekule| form is identified, alternatives are tried by adding
      and removing implicit hydrogens from aromatic nitrogens to
      produce a valid |Kekule| form.  No further attempt is made to
      return the most reasonable or chemically sensible result.  By
      default, the extra |Kekule| validation is enabled.
      The default setting is ``true`` i.e.  |Kekule| form
      validation will be performed.

      .. seealso::

         * :ref:`subsection_reactions_libgen_kekule` section of the
           :ref:`chapter_reactions` chapter
