.. oe:namespace:: OEConfGen

.. meta::
   :keywords: OETorLib, TorLib


.. _OEConfGen_OETorLib:

.. oe:class:: OETorLib

   .. oe:api::

      class OETorLib

   Stores and manages torsion libraries used during conformer generation.
   Torsion rules can be loaded from files or added as SMARTS-based rule strings,
   and are consulted by :ref:`OETorDriver <OEConfGen_OETorDriver>` when sampling
   rotatable-bond dihedral angles.

   .. seealso::

      * :ref:`OETorDriveOptions <OEConfGen_OETorDriveOptions>` class

   .. oe:method:: Constructors

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

         .. oe:api::

            OETorLib(const unsigned type = OETorLibType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OETorLib(type: int) -> OETorLib
            OETorLib(arg2: OETorLib) -> OETorLib

      Default and copy constructors.  The constructor with the type
      parameter allows the user to set the torsion library type from values
      in the :oe:constns:`OEConfGen::OETorLibType` namespace.

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

      .. oe:api::

         OETorLib & operator=(const OETorLib &)

      Assignment operator.


   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns *false* if the :ref:`OETorLib <OEConfGen_OETorLib>` object is empty,
      otherwise returns *true*.

   .. _OEConfGen_OETorLib_AddTorsionLibrary:

   .. oe:method:: AddTorsionLibrary

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

         .. oe:api::

            bool AddTorsionLibrary(const std::string &)
            bool AddTorsionLibrary(OEPlatform::oeistream &)

      .. oe:language:: python

         .. oe:api:: python

            AddTorsionLibrary(arg2: str) -> bool
            AddTorsionLibrary(arg2: oeistream) -> bool

      Takes a ``string`` or an :ref:`oeistream <OEPlatform_oeistream>` object to add a torsion
      library.  This will put the new torsion library above the
      current torsion library, which means that they will be checked
      first for a match.  To replace the torsion library, call
      :oe:meth:`OEConfGen::OETorLib::SetTorsionLibrary`. The method returns
      *true* if the library is added successfully.

   .. _OEConfGen_AddTorsionRule:


   .. oe:method:: AddTorsionRule


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

         .. oe:api::

            bool AddTorsionRule(const std::string &)

      .. oe:language:: python

         .. oe:api:: python

            AddTorsionRule(arg2: str) -> bool

      Adds a single torsion rule as a string. The format for
      rules is a SMARTS pattern followed by the torsion angles. The method returns
      *true* if the rule is added successfully. The
      following is an example of a general rule::

         [*:1][CH2:2][a:3][a:4] 0 180 90 -90 45 -45 135 -135

      The following code demonstrates how to add a new torsion
      rule to an existing :ref:`OEOmega <OEConfGen_OEOmega>` object named ``omega``.

      .. oe:source:: AddTorsionRule.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-string
         :caption:  Example of adding a new torsion rule

      .. oe:source:: AddTorsionRule.py
         :language: python
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-string
         :caption:  Example of adding a new torsion rule.

      .. oe:language:: python

      :ref:`See the appendix for a full listing. <listing-AddTorsionRule.py>`

      .. oe:source:: AddTorsionRule.java
         :language: java
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-string
         :caption:  Example of adding a new torsion rule

      .. oe:source:: AddTorsionRule.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-string
         :caption:  Example of adding a new torsion rule

      The new rule will take precedence over all rules previously
      added to this object either from a file or from calling this method.

         .. oe:api::

            bool AddTorsionRule(OEChem::OEQMolBase &qmol,
                                std::vector<int> &degrees)

      The next signature of ``AddTorsionRule`` takes a generic
      :ref:`OEQMolBase <OEChem_OEQMolBase>` with a corresponding
      ``std::vector<int>`` containing the angles. The pattern
      represented by :ref:`OEQMolBase <OEChem_OEQMolBase>` should have map
      indices set on the atoms considered in the torsion. In
      :term:`SMARTS`, this means the atoms should have map indices
      numbered from 1 to 4. This can theoretically allow torsion rules to
      be written in other query file formats provided there is a
      method for setting the appropriate map indices. The following
      code demonstrates how to initialize an
      :ref:`OEQMolBase <OEChem_OEQMolBase>` and use it to define a new torsion rule.

      .. oe:source:: AddTorsionRule.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-OEQMol
         :caption:  Example of adding a new torsion rule from a query molecule

      .. oe:source:: AddTorsionRule.py
         :language: python
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-OEQMol
         :caption:  Example of adding a new torsion rule from a query molecule

      .. oe:language:: python

      :ref:`See the appendix for a full listing. <listing-AddTorsionRule.py>`

      .. oe:source:: AddTorsionRule.java
         :language: java
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-OEQMol
         :caption:  Example of adding a new torsion rule from a query molecule

      .. oe:source:: AddTorsionRule.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-AddTorsionRule-OEQMol
         :caption:  Example of adding a new torsion rule from a query molecule


   .. _OEConfGen_OETorLib_ClearTorsionLibrary:

   .. oe:method:: ClearTorsionLibrary

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

         .. oe:api::

            void ClearTorsionLibrary()

      .. oe:language:: python

         .. oe:api:: python

            ClearTorsionLibrary() -> None

      Clears the current torsion library.  **Omega** cannot operate with
      an empty torsion library, so a new torsion library must be set
      before running **Omega**.


   .. _OEConfGen_OETorLib_GetTorRule:

   .. oe:method:: GetTorRule

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

         .. oe:api::

            const OEChem::OESubSearch* GetTorRule(const OEChem::OEMolBase&,
                                                  const OEChem::OEBondBase&) const

      .. oe:language:: python

         .. oe:api:: python

            GetTorRule(mol: Union[OEGraphMol,OEMol,OEQMol], bond: OEBondBase) -> OESubSearch

      Returns the torsion rule associated with the specified bond of
      the specified molecule. The method returns a null pointer if a
      torsion rule is not found.
      The rules are stored as :ref:`OESubSearch <OEChem_OESubSearch>` objects.

   .. seealso::

         * :oe:func:`OEConfGen::OEGetTorValues` function.


   .. _OEConfGen_OETorLib_GetTorRules:

   .. oe:method:: GetTorRules

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

         .. oe:api::

            OESystem::OEIterBase<OEChem::OESubSearch>* GetTorRules()

      .. oe:language:: python

         .. oe:api:: python

            GetTorRules() -> Iterable[OESubSearch]

      Returns an iterator over the torsion rules.
      The rules are stored as :ref:`OESubSearch <OEChem_OESubSearch>` objects.


   .. _OEConfGen_OETorLib_HasTorRule:

   .. oe:method:: HasTorRule

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

         .. oe:api::

            bool HasTorRule(const OEChem::OEMolBase&, const OEChem::OEBondBase&) const

      .. oe:language:: python

         .. oe:api:: python

            HasTorRule(mol: Union[OEGraphMol,OEMol,OEQMol], bond: OEBondBase) -> bool

      Checks if a torsion rule exists with the specified bond of
      the specified molecule. Returns *true* if a rule exists.


   .. _OEConfGen_OETorLib_ResetTorsionLibrary:

   .. oe:method:: ResetTorsionLibrary

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

         .. oe:api::

            bool ResetTorsionLibrary()

      .. oe:language:: python

         .. oe:api:: python

            ResetTorsionLibrary() -> bool

      Resets the torsion library stored internally by **Omega**. The method returns
      *true* if the library is reset successfully.


   .. _OEConfGen_OETorLib_SetTorsionLibrary:

   .. oe:method:: SetTorsionLibrary


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

         .. oe:api::

            bool SetTorsionLibrary(const std::string &)
            bool SetTorsionLibrary(OEPlatform::oeistream &)
            bool SetTorsionLibrary(unsigned int type)

      .. oe:language:: python

         .. oe:api:: python

            SetTorsionLibrary(type: int) -> bool
            SetTorsionLibrary(arg2: str) -> bool
            SetTorsionLibrary(arg2: oeistream) -> bool

      Replaces the current torsion library with the one passed in as an
      argument.  If the argument is a type, it is expected to be a value
      in the :oe:constns:`OEConfGen::OETorLibType` namespace. The method returns
      *true* if the library is set successfully.
