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

.. oe:namespace:: OESz

.. meta::
   :keywords: OESzybki, Szybki


.. _OESz_OESzybki:

.. oe:class:: OESzybki

   .. oe:api::


      class OESzybki

   The primary interface for molecular force field optimization. Supports
   Cartesian, torsional, and solid-body optimization modes with optional
   protein-ligand constraints, solvation models, and entropy calculations.

   .. oe:method:: Constructors

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

         .. oe:api::

            OESzybki(unsigned int force_field = OEForceFieldType::MMFF94)
            OESzybki(const OESzybkiOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            OESzybki(force_field: int) -> OESzybki
            OESzybki(opts: OESzybkiOptions) -> OESzybki

      The default constructor builds :ref:`OESzybki <OESz_OESzybki>` with the MMFF force field.
      The :ref:`OESzybkiOptions <OESz_OESzybkiOptions>` can be provided as argument with specifying
      many other parameters, including other force fields supported.

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

      .. oe:api::

         OESzybki & operator=(const OESzybki &)

      Assignment operator.



   .. oe:method:: operator()

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

         .. oe:api::

            OESystem::OEIterBase<OESz::OESzybkiResults>* operator()(OEChem::OEMCMolBase& m)
            bool operator()(OEChem::OEMolBase& m, OESz::OESzybkiResults& res)

      .. oe:language:: python

         .. oe:api:: python

            __call__(m: OEMol) -> Iterable[OESzybkiResults]
            __call__(m: Union[OEGraphMol,OEMol,OEQMol], res: OESzybkiResults) -> bool

      The first operator performs geometry optimization on all
      conformers in the passed molecule ``m`` and updates it with
      optimized coordinates. It returns an iterator whose elements are
      :ref:`OESzybkiResults <OESz_OESzybkiResults>` objects. :ref:`OESzybkiResults <OESz_OESzybkiResults>` contains the energy
      values of the relevant potential terms, total energies and
      gradients. The description of the  :ref:`OESzybkiResults <OESz_OESzybkiResults>` structure is given
      below. The second operator performs the same task on a molecule
      in a single conformation. A reference to an instance of
      OESzybkiResults structure has to be passed. If the calculation
      fails the operator returns ``false``.

   .. oe:method:: ClearFixAtoms

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

         .. oe:api::

            void ClearFixAtoms()

      .. oe:language:: python

         .. oe:api:: python

            ClearFixAtoms() -> None

      Removes the ``fix`` constraint on any fixed atoms. After the use of this function, positions of all
      atoms could change upon optimization.

   .. oe:method:: ClearHarmonicConstraints

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

         .. oe:api::

            bool ClearHarmonicConstraints()

      .. oe:language:: python

         .. oe:api:: python

            ClearHarmonicConstraints() -> bool

      Removes harmonic constraints. Returns ``true`` if constraints were removed and ``false`` when the action
      was not necessary because a constraining potential was not present.

   .. oe:method:: ClearTorsionConstraint

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

         .. oe:api::

            bool ClearTorsionConstraint()

      .. oe:language:: python

         .. oe:api:: python

            ClearTorsionConstraint() -> bool

      Removes torsion constraint. Returns ``true`` if constraint is removed and ``false`` when the action was not
      necessary because a constraining potential was not present.

   .. oe:method:: FixAtoms

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

         .. oe:api::

            bool FixAtoms(std::string smarts_pattern)
            bool FixAtoms(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase> &)

      .. oe:language:: python

         .. oe:api:: python

            FixAtoms(smarts_pattern: str) -> bool
            FixAtoms(arg2: OEUnaryAtomPred) -> bool

      Fixes a set of atoms at their initial positions in space. The first function fixes
      a set of atoms which belong to a SMARTS pattern determined by the parameter
      ``smarts_pattern``. It returns ``true`` if the SMARTS string passed is valid, ``false``
      otherwise. The second function fixes only those atoms for which the predicate passed
      is ``true``, and returns ``true`` if the predicate is valid.

   .. oe:method:: GetEntropy(const OEChem::OEMCMolBase&, unsigned int, unsigned int)

      .. oe:api::

         double GetEntropy(const OEChem::OEMCMolBase &m,
                           unsigned int method = OEEntropyMethod::QNewton,
                           unsigned int env = OEEnvType::SolutionSPT)

      Estimates and returns the entropy of a compound in different environments for an ensemble of
      conformations given in the input molecule ``m``. The method does not alter the input set of
      conformations. The default parameter ``method`` specifies that the method of entropy evaluation
      is quasi-Newton. The alternative value for this parameter is
      :oe:const:`OESz::OEEntropyMethod::Analytic`. The last parameter in both methods specifies ligand
      environment. Its default value refers to the ligand in solution where solvation entropy is
      handled by scaled-particle theory (SPT). The remaining possible values of the parameter ``env``
      are: :oe:const:`OESz::OEEnvType::Gas`, :oe:const:`OESz::OEEnvType::Protein` and
      :oe:const:`OESz::OEEnvType::SolutionSA` which specify gas-phase, protein-bound and solution ligand,
      respectively. In the case of :oe:const:`OESz::OEEnvType::SolutionSA` the solvation entropy is
      evaluated with the "Surface Area" model, however we recommend the default which uses SPT.

      .. deprecated:: 1.8.2
         Use overloaded :oe:meth:`OESz::OESzybki::GetEntropy` instead.

   .. oe:method:: GetEntropy

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

         .. oe:api::

            double GetEntropy(OEChem::OEMCMolBase& m,
                              OESzybkiEnsembleResults& r,
                              unsigned int method = OEEntropyMethod::QNewton,
                              unsigned int env = OEEnvType::SolutionSPT)

      .. oe:language:: python

         .. oe:api:: python

            GetEntropy(m: OEMol, r: OESzybkiEnsembleResults, method: int,
                       env: int) -> float

      Estimates and returns the entropy of a compound in different environments for an ensemble of
      conformations given in the input molecule ``m``. The set of optimized unique conformations is
      returned in the first parameter ``m``.  The method takes the reference of the
      :ref:`OESzybkiEnsembleResults <OESz_OESzybkiEnsembleResults>` object ``r`` which carries the entropy results for the
      ensemble. The default parameter ``method`` specifies that the method of vibrational entropy
      evaluation is based on second derivatives matrix (Hessian) which is taken from the final
      step of quasi-Newton optimization. The alternative value for this parameter is
      :oe:const:`OESz::OEEntropyMethod::Analytic`. When the latter is selected, Hessian matrix is
      calculated analytically. The last parameter specifies ligand environment. Its default value
      refers to the ligand in solution where solvation entropy is handled by scaled-particle theory
      (SPT). The remaining possible values of the parameter ``env`` are:
      :oe:const:`OESz::OEEnvType::Gas`, :oe:const:`OESz::OEEnvType::Protein` and
      :oe:const:`OESz::OEEnvType::SolutionSA` which specify gas-phase, protein-bound and solution
      ligand respectively. In the case of :oe:const:`OESz::OEEnvType::SolutionSA` the solvation
      entropy is evaluated with the "Surface Area" model, however we recommend the default which
      uses SPT.

   .. oe:method:: GetFixPattern

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

         .. oe:api::

            const char* GetFixPattern() const

      .. oe:language:: python

         .. oe:api:: python

            GetFixPattern() -> str

      Returns the SMARTS string used for fixing atoms.

   .. oe:method:: GetFixPredicate

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

         .. oe:api::

            const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>* GetFixPredicate() const

      .. oe:language:: python

         .. oe:api:: python

            GetFixPredicate() -> OEUnaryAtomPred

      Returns a pointer to the predicate used to determine which atoms are fixed.

   .. oe:method:: GetHarmonicConstraints

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

         .. oe:api::

            const OESystem::OEUnaryPredicate<OEChem::OEAtomBase> *
            const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>* GetHarmonicConstraints(double& kc,
                                                                                         double& kd) const

      .. oe:language:: python

         .. oe:api:: python

            GetHarmonicConstraints() -> (kc: float, kd: float, pred: OEUnaryAtomPred)

      Provides a method to query for the harmonic constraint used, the force constant ``kc``,
      and distance ``kd``. The function returns a pointer to a predicate which determines which
      atoms are constrained.  If the returned pointer is 0, then no harmonic constraints are used.

   .. oe:method:: GetProtein

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

         .. oe:api::

            bool GetProtein(OEChem::OEMolBase& p) const

      .. oe:language:: python

         .. oe:api:: python

            GetProtein(p: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      Copies the current protein molecule to the passed molecule object ``p``. If the :ref:`OESzybki <OESz_OESzybki>`
      object does not hold a protein molecule, the function will return ``false``.

   .. oe:method:: GetSheffieldParameters

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

         .. oe:api::

            void GetSheffieldParameters(double& a, double& b, double& dc) const

      .. oe:language:: python

         .. oe:api:: python

            GetSheffieldParameters() -> (a: float, b: float, dc: float)

      Returns the Sheffield solvation model parameters which are currently used.

   .. oe:method:: LoadPotentialGrid

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

         .. oe:api::

            void LoadPotentialGrid(const std::string& fname)

      .. oe:language:: python

         .. oe:api:: python

            LoadPotentialGrid(fname: str) -> None

      Reads a pre-calculated potential grid from the file name ``fname``. For a large number of ligands to be
      optimized inside a single protein with the use of the electrostatic model
      :oe:const:`OESz::OEProteinElectrostatics::GridPB` or
      :oe:const:`OESz::OEProteinElectrostatics::GridCoulomb`
      (see function :oe:meth:`OESz::OESzybkiProteinOptions::SetProteinElectrostaticModel`),
      this function offers a significant saving in CPU time.

   .. oe:method:: SavePotentialGrid

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

         .. oe:api::

            void SavePotentialGrid(const std::string& fname)

      .. oe:language:: python

         .. oe:api:: python

            SavePotentialGrid(fname: str) -> None

      Saves potential grid in the file named ``fname``. The potential grid will be generated in protein-ligand
      calculations in which electrostatic model used is :oe:const:`OESz::OEProteinElectrostatics::GridPB` or
      :oe:const:`OESz::OEProteinElectrostatics::GridCoulomb` set with the function
      :oe:meth:`OESz::OESzybkiProteinOptions::SetProteinElectrostaticModel`.

   .. oe:method:: SetHarmonicConstraints

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

         .. oe:api::

            bool SetHarmonicConstraints(double kc, double kd = 0.0,
                                        const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred = OEChem::OEIsHeavy())

      .. oe:language:: python

         .. oe:api:: python

            SetHarmonicConstraints(kc: float, kd: float = 0.0,
                                   pred: OEUnaryAtomPred = OEIsHeavy()) -> bool

      Adds potential term :math:`V=k_c(r - k_d)^2` for every atom for which the passed
      predicate operator returns ``true``. Default predicate imposes
      harmonic potential on
      every heavy atom. Parameter ``kc`` is the force constant :math:`k_c` (in :math:`kcal/(mol |A|^2)`
      and ``kd`` is the constraining
      distance :math:`k_d` in |A|. By default ``kd`` is set to 0. Function returns ``true`` if
      harmonic potential added.

   .. oe:method:: SetProtein

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

         .. oe:api::

            bool SetProtein(const OEChem::OEMolBase& protein)

      .. oe:language:: python

         .. oe:api:: python

            SetProtein(protein: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      Sets the protein molecule for subsequent szybki calculations. The protein
      molecule may be modified by this operation, if needed.  It returns ``false`` if the operation fails, otherwise ``true``.

   .. note::

      To specify charging options for protein-ligand coulombic interactions, use the :oe:meth:`OESz::OESzybkiSolventOptions::SetChargeEngine` method under the :ref:`OESzybkiSolventOptions <OESz_OESzybkiSolventOptions>` class. To work with the pre-existing charges, use the :ref:`OEChargeEngineNoOp <OEProton_OEChargeEngineNoOp>` as the charging engine.

   .. oe:method:: SetSheffieldParameters

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

         .. oe:api::

            void SetSheffieldParameters(double a, double b, double dc = 1.0)

      .. oe:language:: python

         .. oe:api:: python

            SetSheffieldParameters(a: float, b: float, indi: float = 1.0) -> None

      Sheffield solvation energy requires two parameters :math:`a` and :math:`b`:
      :math:`E_{solv} = -\frac{f_\epsilon}{8\pi \epsilon_0}\sum_{i,j}\frac{q_iq_j}{\sqrt{(aR_iR_j + br_{ij}^2)}}`
      where :math:`q_i` and :math:`q_j` are atomic charges, :math:`R_i` and
      :math:`R_j` are vdW radii for atoms :math:`i` and :math:`j`, and :math:`r_{ij}` is the
      interatomic distance. Parameter :math:`f_\epsilon` depends on dielectric constants of the solute
      (:math:`\epsilon`) and the solvent (:math:`\epsilon_{solv}`):
      :math:`f_\epsilon = 1/\epsilon - 1/\epsilon_{solv})`. This function sets both parameters :math:`a` and
      :math:`b` to the required values, as well as the solute dielectric constant (which may not exceed 10).
      If the function not used, the solute dielectric constant is set to 1.0, and the default values
      of :math:`a = 1.553149` and :math:`b = 0.735694` are adopted ([Grant-2007]_).

.. _OESz_OESzybki_SetTorsionConstraint:

   .. oe:method:: SetTorsionConstraint

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

         .. oe:api::

            bool SetTorsionConstraint(const std::string& tor_pattern, double k,
                                      double phi0)
            bool SetTorsionConstraint(const OEChem::OETorsion& tor, double k)

      .. oe:language:: python

         .. oe:api:: python

            SetTorsionConstraint(tor_pattern: str, k: float, phi0: float) -> bool
            SetTorsionConstraint(tor: OETorsion, k: float) -> bool

      The method adds a potential term :math:`V=k_c(cos(phi) -
      cos(phi0))^2` for a torsion. The first method specifies the torsion
      with a SMARTS pattern passed as a string ``tor pattern``. This must be
      in the indexed form which show which atoms forms the torsion. For
      example a valid pattern is ``[C:1][N:2][c:3][s:4]``. ``k`` is the user
      specified force field in kcal/mol, and ``phi0`` is the torsion
      reference dihedral angle in radians. The function returns ``true`` if
      a torsion constraint is added successfully.

      The second method takes an instance of an
      :ref:`OETorsion <OEChem_OETorsion>` object, ``tor``, which defines a single
      torsion to be constrained. ``k`` is the user specified force field in
      kcal/mol. The function returns ``true`` if a constrained torsion is
      added successfully.

   .. oe:method:: UnsetProtein

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

         .. oe:api::

            void UnsetProtein() const

      .. oe:language:: python

         .. oe:api:: python

            UnsetProtein() -> None

      Removes protein context from the :ref:`OESzybki <OESz_OESzybki>` object.

