.. oe:namespace:: OESz

.. meta::
   :keywords: OETorsionScanOptions, TorsionScanOptions


.. _OESz_OETorsionScanOptions:

.. oe:class:: OETorsionScanOptions

   .. oe:api::

      class OETorsionScanOptions : public OELigandChargeOptions

   Configuration options for :oe:func:`OESz::OETorsionScan` torsion-energy scans.

   .. seealso::

      * :ref:`OETorsionScanResult <OESz_OETorsionScanResult>` class
      * :oe:func:`OESz::OETorsionScan` function

   The following methods are publicly inherited from :ref:`OELigandChargeOptions <OESz_OELigandChargeOptions>`:
    * :oe:meth:`GetGenerateElfConfs<OESz::OELigandChargeOptions::GetGenerateElfConfs>` and
      :oe:meth:`SetGenerateElfConfs<OESz::OELigandChargeOptions::SetGenerateElfConfs>`
    * :oe:meth:`GetLigandCharge<OESz::OELigandChargeOptions::GetLigandCharge>`,
      :oe:meth:`GetLigandChargeType<OESz::OELigandChargeOptions::GetLigandChargeType>`, and
      :oe:meth:`SetLigandCharge<OESz::OELigandChargeOptions::SetLigandCharge>`

   The :ref:`OETorsionScanOptions <OESz_OETorsionScanOptions>` class defines the following public methods:
    * :oe:meth:`GetDelta<OESz::OETorsionScanOptions::GetDelta>` and
      :oe:meth:`SetDelta<OESz::OETorsionScanOptions::SetDelta>`
    * :oe:meth:`GetForceField<OESz::OETorsionScanOptions::GetForceField>`,
      :oe:meth:`GetForceFieldType<OESz::OETorsionScanOptions::GetForceFieldType>` and
      :oe:meth:`SetForceField<OESz::OETorsionScanOptions::SetForceField>`
    * :oe:meth:`GetMaxIter<OESz::OETorsionScanOptions::GetMaxIter>` and
      :oe:meth:`SetMaxIter<OESz::OETorsionScanOptions::SetMaxIter>`
    * :oe:meth:`GetPenaltyForceConstant<OESz::OETorsionScanOptions::GetPenaltyForceConstant>` and
      :oe:meth:`SetPenaltyForceConstant<OESz::OETorsionScanOptions::SetPenaltyForceConstant>`
    * :oe:meth:`GetSolvationType<OESz::OETorsionScanOptions::GetSolvationType>` and
      :oe:meth:`SetSolvationType<OESz::OETorsionScanOptions::SetSolvationType>`
    * :oe:meth:`GetTolerance<OESz::OETorsionScanOptions::GetTolerance>` and
      :oe:meth:`SetTolerance<OESz::OETorsionScanOptions::SetTolerance>`
    * :oe:meth:`GetUseInternalCoord<OESz::OETorsionScanOptions::GetUseInternalCoord>` and
      :oe:meth:`SetUseInternalCoord<OESz::OETorsionScanOptions::SetUseInternalCoord>`
    * :oe:meth:`GetUserDefinedAngles<OESz::OETorsionScanOptions::GetUserDefinedAngles>` and
      :oe:meth:`SetUserDefinedAngles<OESz::OETorsionScanOptions::SetUserDefinedAngles>`
    * :oe:meth:`GetUseSinglePointPB<OESz::OETorsionScanOptions::GetUseSinglePointPB>` and
      :oe:meth:`SetUseSinglePointPB<OESz::OETorsionScanOptions::SetUseSinglePointPB>`
    * :oe:meth:`GetNumStarts<OESz::OETorsionScanOptions::GetNumStarts>` and
      :oe:meth:`SetNumStarts<OESz::OETorsionScanOptions::SetNumStarts>`
    * :oe:meth:`GetOverlapDiv<OESz::OETorsionScanOptions::GetOverlapDiv>` and
      :oe:meth:`SetOverlapDiv<OESz::OETorsionScanOptions::SetOverlapDiv>`


   .. oe:method:: Constructors

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

         .. oe:api::

            OETorsionScanOptions()
            OETorsionScanOptions(const OETorsionScanOptions &)

      .. oe:language:: python

         .. oe:api:: python

            OETorsionScanOptions() -> OETorsionScanOptions
            OETorsionScanOptions(arg2: OETorsionScanOptions) -> OETorsionScanOptions

      Default and copy constructors.

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

      .. oe:api::

         OETorsionScanOptions &operator=(const OETorsionScanOptions &)

      Assignment operator.


   .. _OESz_OETorsionScanOptions_GetDelta:

   .. oe:method:: GetDelta

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

         .. oe:api::

            double GetDelta() const

      .. oe:language:: python

         .. oe:api:: python

            GetDelta() -> float

      Returns the value of dihedral angle increase (in degrees).


   .. _OESz_OETorsionScanOptions_GetForceField:

   .. oe:method:: GetForceField

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

         .. oe:api::

            const OEMolPotential::OEForceField* GetForceField() const

      .. oe:language:: python

         .. oe:api:: python

            GetForceField() -> OEForceField

      Returns pointer to the user defined force field.


   .. _OESz_OETorsionScanOptions_GetForceFieldType:

   .. oe:method:: GetForceFieldType

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

         .. oe:api::

            unsigned int GetForceFieldType() const

      .. oe:language:: python

         .. oe:api:: python

            GetForceFieldType() -> int

      Returns the type of force field defined.


   .. _OESz_OETorsionScanOptions_GetMaxIter:

   .. oe:method:: GetMaxIter

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

         .. oe:api::

            unsigned GetMaxIter() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxIter() -> int

      Returns the number of maximum iterations during optimization.


   .. _OESz_OETorsionScanOptions_GetPenaltyForceConstant:

   .. oe:method:: GetPenaltyForceConstant

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

         .. oe:api::

            double GetPenaltyForceConstant() const

      .. oe:language:: python

         .. oe:api:: python

            GetPenaltyForceConstant() -> float

      Returns force constant for the dihedral angle constraint used for torsion scan.


   .. _OESz_OETorsionScanOptions_GetSolvationType:

   .. oe:method:: GetSolvationType

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

         .. oe:api::

            unsigned int GetSolvationType() const

      .. oe:language:: python

         .. oe:api:: python

            GetSolvationType() -> int

      Returns the type of solvation model used for torsion scan, see :oe:meth:`OESz::OETorsionScanOptions::SetSolvationType`
      for more details.


   .. _OESz_OETorsionScanOptions_GetTolerance:

   .. oe:method:: GetTolerance

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

         .. oe:api::

            double GetTolerance() const

      .. oe:language:: python

         .. oe:api:: python

            GetTolerance() -> float

      Returns the tolerance during optimization.


   .. _OESz_OETorsionScanOptions_GetUseInternalCoord:

   .. oe:method:: GetUseInternalCoord

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

         .. oe:api::

            bool GetUseInternalCoord() const

      .. oe:language:: python

         .. oe:api:: python

            GetUseInternalCoord() -> bool

      Returns ``true`` if :ref:`SetUseInternalCoord <OESz_OETorsionScanOptions_SetUseInternalCoord>`
      is set to using internal coordinates for optimization while the torsion selected for scanning
      is fixed.

   
   .. _OESz_OETorsionScanOptions_GetUserDefinedAngles:

   .. oe:method:: GetUserDefinedAngles

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

         .. oe:api::

            std::vector<double> GetUserDefinedAngles() const

      .. oe:language:: python

         .. oe:api:: python

            GetUserDefinedAngles() -> OEDoubleVector

      Returns vector of user defined dihedral angles for which torsion scan will be done.


.. _OESz_OETorsionScanOptions_GetUseSinglePointPB:

   .. oe:method:: GetUseSinglePointPB

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

         .. oe:api::

            bool GetUseSinglePointPB() const

      .. oe:language:: python

         .. oe:api:: python

            GetUseSinglePointPB() -> bool

      Returns ``true`` if the :oe:meth:`OESz::OETorsionScanOptions::SetUseSinglePointPB` is set to correcting the
      torsion scan with a PB solvation energy.


.. _OESz_OETorsionScanOptions_GetNumStarts:

   .. oe:method:: GetNumStarts

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

         .. oe:api::

            unsigned GetNumStarts() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumStarts() -> int

      Returns the number of starts for the torsion scan. See :oe:meth:`OESz::OETorsionScanOptions::SetNumStarts` for
      more details


.. _OESz_OETorsionScanOptions_GetOverlapDiv:

   .. oe:method:: GetOverlapDiv

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

         .. oe:api::

            unsigned GetOverlapDiv() const

      .. oe:language:: python

         .. oe:api:: python

            GetOverlapDiv() -> int

      Returns the divisor used for determining the size of the overlaps between starts. 
      See :oe:meth:`OESz::OETorsionScanOptions::SetOverlapDiv` for more details.


.. _OESz_OETorsionScanOptions_SetDelta:

   .. oe:method:: SetDelta

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

         .. oe:api::

            bool SetDelta(double delta)

      .. oe:language:: python

         .. oe:api:: python

            SetDelta(value: float) -> bool

      Determines the number of points in that is :math:`(360.0/delta+1)`  in the
      :math:`[0.0^{\circ}, 360.0^{\circ}]` range for the scan.
      Minimum and maximum values are ``0.1`` and ``60.0`` degrees respectively. The default value
      is ``5.0`` degrees. When the given value of ``delta`` is outside the range, ``false`` is returned.


.. _OESz_OETorsionScanOptions_SetForceField:

   .. oe:method:: SetForceField

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

         .. oe:api::

            bool SetForceField(const OEMolPotential::OEForceField& value)
            bool SetForceField(const std::string& value)
            bool SetForceField(OEPlatform::oeistream& value)
            bool SetForceField(const unsigned value)

      .. oe:language:: python

         .. oe:api:: python

            SetForceField(value: OEForceField) -> bool
            SetForceField(value: int) -> bool
            SetForceField(value: str) -> bool
            SetForceField(value: oeistream) -> bool

      Sets user defined force field which will be used for torsion scan.

   
.. _OESz_OETorsionScanOptions_SetForceFieldType:

   .. oe:method:: SetForceFieldType

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

         .. oe:api::

            bool SetForceFieldType(unsigned int type)

      .. oe:language:: python

         .. oe:api:: python

            SetForceFieldType(ff: int) -> bool

      Selects the force field for the scan. The allowed values for parameter ``type`` are
      :oe:constns:`OESz::OEForceFieldType::MMFF94S` (default), 
      :oe:constns:`OESz::OEForceFieldType::MMFF94`,
      :oe:constns:`OESz::OEForceFieldType::SMIRNOFF99FROSST`, 
      :oe:constns:`OESz::OEForceFieldType::PARSLEY_OPENFF100`,
      :oe:constns:`OESz::OEForceFieldType::PARSLEY_OPENFF111`,
      :oe:constns:`OESz::OEForceFieldType::PARSLEY_OPENFF121`,
      :oe:constns:`OESz::OEForceFieldType::PARSLEY_OPENFF131`,
      :oe:constns:`OESz::OEForceFieldType::SAGE_OPENFF200`, and
      :oe:constns:`OESz::OEForceFieldType::SAGE_OPENFF210`
      Method returns ``false`` if other than the above values are passed.


.. _OESz_OETorsionScanOptions_SetMaxIter:

   .. oe:method:: SetMaxIter

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

         .. oe:api::

            bool SetMaxIter(const unsigned value)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxIter(value: int) -> bool

      Sets the number of maximum iterations for optimization.


.. _OESz_OETorsionScanOptions_SetSolvationType:

   .. oe:method:: SetSolvationType

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

         .. oe:api::

            bool SetSolvationType(unsigned int type)

      .. oe:language:: python

         .. oe:api:: python

            SetSolvationType(value: int) -> bool

      Selects the solvation model used for the scan. The allowed values of ``type`` are:
      :oe:constns:`OESz::OESolventModel::NoSolv` (vacuum) and
      :oe:constns:`OESz::OESolventModel::Sheffield` (aqueous solution, default).
      Method returns ``false`` if invalid solvation model is passed.


.. _OESz_OETorsionScanOptions_SetPenaltyForceConstant:

   .. oe:method:: SetPenaltyForceConstant

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

         .. oe:api::

            bool SetPenaltyForceConstant(double pfc)

      .. oe:language:: python

         .. oe:api:: python

            SetPenaltyForceConstant(value: float) -> bool

      Overwrites a default value (``1e4``) for force constant in dihedral angle constraint 
      used for torsion scan. Although for most molecules a default value works fine, in some
      cases a molecular torsion might be  overconstrained or  underconstrained. This method 
      allows to avoid those two extremes. Method returns ``false`` if invalid value of force
      constant is passed.


.. _OESz_OETorsionScanOptions_SetTolerance:

   .. oe:method:: SetTolerance

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

         .. oe:api::

            bool SetTolerance(const double)

      .. oe:language:: python

         .. oe:api:: python

            SetTolerance(value: float) -> bool

      Sets the tolerance limit for optimization.


.. _OESz_OETorsionScanOptions_SetUseInternalCoord:   

   .. oe:method:: SetUseInternalCoord

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

         .. oe:api::

            bool SetUseInternalCoord(bool useInt)

      .. oe:language:: python

         .. oe:api:: python

            SetUseInternalCoord(value: bool) -> bool

      Overwrites a default method for torsion scan, which  applies a large enough penalty force
      to keep the value of the dihedral angle constant during optimization. When the parameter
      ``useInt`` is set to ``true``, optimization is performed in 3N-5 internal coordinates while
      the selected torsion for which a scan is done is kept frozen.

   
.. _OESz_OETorsionScanOptions_SetUserDefinedAngles:

   .. oe:method:: SetUserDefinedAngles

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

         .. oe:api::

            bool SetUserDefinedAngles(const std::vector<double>& angles)

      .. oe:language:: python

         .. oe:api:: python

            SetUserDefinedAngles(value: OEDoubleVector) -> bool

      Takes a vector of user selected dihedral angles (in deg) for which torsion scan will be
      done. Vector passed as argument should contain at least 2 values, otherwise ``false``
      is returned.

   
.. _OESz_OETorsionScanOptions_SetUseSinglePointPB:

   .. oe:method:: SetUseSinglePointPB

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

         .. oe:api::

            bool SetUseSinglePointPB(bool usePB)

      .. oe:language:: python

         .. oe:api:: python

            SetUseSinglePointPB(value: bool) -> bool

      Corrects the final scan values with a PB solvation energy, when the solvation model
      is set to :oe:constns:`OESz::OESolventModel::Sheffield`
      (see :oe:meth:`OESz::OETorsionScanOptions::SetSolvationType`). Method returns
      ``false`` if the solvation model is not correctly set.


.. _OESz_OETorsionScanOptions_SetNumStarts:

   .. oe:method:: SetNumStarts

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

         .. oe:api::

            bool SetNumStarts(unsigned starts)

      .. oe:language:: python

         .. oe:api:: python

            SetNumStarts(value: int) -> bool

      Sets the number of starts for the torsion scan. The default value is ``2``, meaning scans will start
      at 0 and 180 degrees. The scans are performed both forwards and backwards.
      This setting is not compatible with setting :oe:meth:`OESz::OETorsionScanOptions::SetUserDefinedAngles`,
      and will be ignored in case user defined angles are supplied.

   
.. _OESz_OETorsionScanOptions_SetOverlapDiv:

   .. oe:method:: SetOverlapDiv

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

         .. oe:api::

            bool SetOverlapDiv(unsigned overlapDiv)

      .. oe:language:: python

         .. oe:api:: python

            SetOverlapDiv(value: int) -> bool

      Sets the divisor used for determining the size of the overlaps between starts. If set to zero or one, 
      will perform full 360 forwards and backwards scans for each start, meaning the number of starts will increase
      the computational cost linearly. To prevent the linear increase in cost for additional starts, the overlap
      divisor in combination with a number of starts ``> 1``, will first divide the angle space by the number of starts,
      then to ensure some overlap between the scanned angles will take the remaining space and divide by this 
      value (default value is ``4``). For example with the default values of 2 starts, scans would be performed 
      from ``0->180``, ``0->-180``, ``180->360``, and ``180->0``. The ``180`` degree remainder (if a full scan would 
      have been done) is instead divided by ``4``, which equals ``45`` degrees, which is then added to each 
      scan to ensure overlaps of the curves. The resulting scan will look like ``0->225``, ``0->-225``, 
      ``180->45`` (through ``360``), and ``180->-45``. The larger the overlap divisor the smaller 
      the overlaps between curves.
      This setting is not compatible with setting :oe:meth:`OESz::OETorsionScanOptions::SetUserDefinedAngles`,
      and will be ignored in case user defined angles are supplied.
