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

.. oe:namespace:: OESpruce

..  _OESpruce_OEBuildSidechains:

.. oe:function:: OEBuildSidechains

   .. attention::

      |TWOLANGUAGE|

   These functions build out partial sidechains using a rotamer library. The rotamer chosen is the one with the best interaction energy
   with the surrounding environment without taking solvent effects into account. If multiple sidechains are built
   that interact with one another, the energy chosen is the best collective interaction energy. The functions will
   return false if a sidechain can not be built due to clashes, but will still return a structure with all the ones it could build.

   .. note::

      Explicit hydrogens are not added to the structure during the build processes, therefore no partial charges are assigned. 

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

      .. oe:api::

         bool OEBuildSidechains(OEChem::OEMolBase& mol,
                                const OESpruce::OESidechainBuilderOptions& opts = OESpruce::OESidechainBuilderOptions())

   .. oe:language:: python

      .. oe:api:: python

         OEBuildSidechains(du: OEDesignUnit,
                           opts: OESidechainBuilderOptions = OESidechainBuilderOptions()) -> bool
         OEBuildSidechains(mol: Union[OEGraphMol,OEMol,OEQMol],
                           opts: OESidechainBuilderOptions = OESidechainBuilderOptions()) -> bool

   This function takes a molecule and builds any partial sidechain of standard protein residues determined using the
   :oe:func:`OESpruce::OEGetPartialResidues` function. An options class defining a rotamer library from the
   :oe:constns:`OEBio::OERotamerLibrary` namespace can be set, otherwise the default library from that namespace is chosen.
   Additionally, in the options the number of rotamers used can be reduced by picking a rotamer coverage below the default 100%.
   The percentage is calculated cumulatively, so the most probably rotamer is tested first,
   up to the rotamer that takes it above the percentage limit. The options class also defines the behavior of removing water molecules
   that clash with the built sidechain.

   .. oe:api: IGNORE

      bool OEBuildSidechains(OEBio::OEDesignUnit &du,
                             const OESpruce::OESidechainBuilderOptions& opts=OESpruce::OESidechainBuilderOptions())
   .. oe:language:: c++ java csharp

      .. oe:api::

         bool OEBuildSidechains(OEChem::OEMolBase& mol,
                                const std::vector<OEChem::OEResidue>& residues,
                                const OESpruce::OESidechainBuilderOptions& opts = OESpruce::OESidechainBuilderOptions())

   .. oe:language:: python

      .. oe:api:: python

         OEBuildSidechains(du: OEDesignUnit, residues: OEResidueVector,
                           opts: OESidechainBuilderOptions = OESidechainBuilderOptions()) -> bool
         OEBuildSidechains(mol: Union[OEGraphMol,OEMol,OEQMol],
                           residues: OEResidueVector,
                           opts: OESidechainBuilderOptions = OESidechainBuilderOptions()) -> bool

   This function works identically to the above function, but only builds the residues identified in the
   vector residues.

   .. oe:api: IGNORE

      bool OEBuildSidechains(OEBio::OEDesignUnit &du,
                             const std::vector<OEChem::OEResidue>& residues,
                             const OESpruce::OESidechainBuilderOptions& opts=OESpruce::OESidechainBuilderOptions())

   The input ``mol`` must have 3D coordinates assigned.

   .. seealso::

      * :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>` class
      * :oe:constns:`OEBio::OERotamerLibrary` namespace
      * :oe:func:`OESpruce::OEGetPartialResidues` function
