.. oe:namespace:: OESz

.. meta::
   :keywords: OETorsionScan

..  _OESz_OETorsionScan:

.. oe:function:: OETorsionScan

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

      .. oe:api::

         OESystem::OEIterBase<OETorsionScanResult>* OETorsionScan(OEChem::OEMCMolBase& dst,
                                                                  const OEChem::OEMCMolBase& src,
                                                                  const OEChem::OETorsion& torsion,
                                                                  const OETorsionScanOptions& opts)

   .. oe:language:: python

      .. oe:api:: python

         OETorsionScan(dst: OEMol, src: OEMol, torsion: OETorsion,
                       opts: OETorsionScanOptions) -> Iterable[OETorsionScanResult]


   Performs potential energy scan for a selected torsion in the input molecule.
   Torsion scan is preformed by a series of constrained Newton optimizations in which
   all internal degrees of freedom but selected torsion, are optimized.
   Returns an iterator to the :ref:`OETorsionScanResult <OESz_OETorsionScanResult>` objects from which the
   user can obtain actual values of the torsion angle within :math:`[0.0^{\circ}, 360.0^{\circ}]` 
   range and the corresponding relative energies.

   *dst*
     The output multi-conformation molecule that stores conformations corresponding to the
     points on the scan.

   *src*
     The input molecule of which torsion is scanned.

   *torsion*
     The torsion of the input molecule that is being scanned.

   *opts*
     The option that stores parameters for the scan such as force field, environment (vacuum or solution),
     and resolution (:ref:`OETorsionScanOptions <OESz_OETorsionScanOptions>`).
  
   .. note::

      Using multiple conformations for the input molecule (`src`)
      is not a requirement as the function will work for a single conformation.
      However using as many as possible conformations is recommended because it increases
      the probability of finding the minimum energy path for a given torsion.
      The indication that the torsion profile is not the minimum energy path is
      the occurrence of sharp drop(s) of potential energy, or/and different energy values
      obtained for 0.0 and 360.0 degrees. Increasing the number of the input geometries in such a
      situation might remove those symptoms.   

   .. note::

      As the function is identifying the minimum energy path the output conformations can come
      from different input conformations this means the SD data from the input conformations
      is not passed through to the output molecule.


   .. seealso::

      * :ref:`OETorsionScanOptions <OESz_OETorsionScanOptions>` class
      * :ref:`OETorsionScanResult <OESz_OETorsionScanResult>` class


   **Example to scan all torsions of a molecule:**

   .. oe:source:: TorsionScan.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OETORSIONSCAN

   .. oe:source:: TorsionScan.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OETORSIONSCAN

   .. oe:source:: TorsionScan.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OETORSIONSCAN

   .. oe:source:: TorsionScan.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OETORSIONSCAN
