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

.. oe:namespace:: OEBio


.. _OEBio_OEPlaceHydrogensOptions:

.. oe:class:: OEPlaceHydrogensOptions

   .. oe:api::


      class OEPlaceHydrogensOptions : public OESystem::OEOptions

   The `OEPlaceHydrogensOptions` class encapsulates
   properties and resources that determine how
   :oe:func:`OEBio::OEPlaceHydrogens` functions.

   .. seealso::

      * :ref:`section_place_hydrogens` section
      * :oe:func:`OEBio::OEPlaceHydrogens` function


   .. oe:method:: Constructors

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

         .. oe:api::

            OEPlaceHydrogensOptions(bool compatibleAlts = false)
            OEPlaceHydrogensOptions(const OEPlaceHydrogensOptions& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEPlaceHydrogensOptions(compatibleAlts: bool = False) -> OEPlaceHydrogensOptions
            OEPlaceHydrogensOptions(rhs: OEPlaceHydrogensOptions) -> OEPlaceHydrogensOptions

      Constructor and copy constructor. The optional parameter
      ``compatibleAlts`` controls how alternate location codes are interpreted by
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`.

      .. seealso::

         * :oe:meth:`SetAltsMustBeCompatible<OEBio::OEPlaceHydrogensOptions::SetAltsMustBeCompatible>` method
         * :oe:meth:`GetAltsMustBeCompatible<OEBio::OEPlaceHydrogensOptions::GetAltsMustBeCompatible>` method


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

      .. oe:api::

         OEPlaceHydrogensOptions &operator=(const OEPlaceHydrogensOptions &rhs)

      Assignment operator.

   .. oe:method:: GetAddMetadata

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

         .. oe:api::

            bool GetAddMetadata() const

      .. oe:language:: python

         .. oe:api:: python

            GetAddMetadata() -> bool

      Returns ``true`` if metadata describing the results
      will be added to the molecule. The metadata is the string generated by the
      :oe:meth:`OEBio::OEPlaceHydrogensDetails::Describe` method
      and can be accessed by the :oe:func:`OEBio::OEGetPlaceHydrogensMetadata`
      function.

      .. seealso::

         * :oe:func:`OEBio::OEHasPlaceHydrogensMetadata` function
         * :oe:func:`OEBio::OEGetPlaceHydrogensMetadata` function
         * :oe:func:`OEBio::OEClearPlaceHydrogensMetadata` function
         * :ref:`OEPlaceHydrogensDetails <OEBio_OEPlaceHydrogensDetails>` class

   .. oe:method:: GetAltsMustBeCompatible

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

         .. oe:api::

            bool GetAltsMustBeCompatible() const

      .. oe:language:: python

         .. oe:api:: python

            GetAltsMustBeCompatible() -> bool

      Returns ``true`` if alternate location codes are required to be compatible
      (either identical or blank) when atoms interact. If ``true``,
      incompatible atoms do not interact.

      .. seealso::

         * :oe:meth:`Constructors<OEBio::OEPlaceHydrogensOptions::Constructors>`

   .. oe:method:: GetBadClashOverlapDistance

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

         .. oe:api::

            double GetBadClashOverlapDistance() const

      .. oe:language:: python

         .. oe:api:: python

            GetBadClashOverlapDistance() -> float

      Returns the amount of excess van der Waals overlap considered to be
      a "bad" clash.


   .. oe:method:: GetBypassPredicate

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetBypassPredicate() -> OEUnaryAtomPred

      Returns a new copy of the predicate that
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      will use to exclude from analysis all movers having a matching atom.

      .. oe:language:: c++

         To avoid a memory leak in C++, the returned pointer should be
         stored in a variable of the
         :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` template class
         or deallocated with the ``delete`` operator.

      (Default: :oe:cls:`OEIsFalseAtom<OESystem::OEIsFalse>`)

      .. seealso::

         * :oe:meth:`SetBypassPredicate<OEBio::OEPlaceHydrogensOptions::SetBypassPredicate>` method
         * :oe:meth:`GetFlipPredicate<OEBio::OEPlaceHydrogensOptions::GetFlipPredicate>` method
         * :oe:meth:`GetNoFlipPredicate<OEBio::OEPlaceHydrogensOptions::GetNoFlipPredicate>` method


   .. oe:method:: GetFlipBias

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

         .. oe:api::

            double GetFlipBias() const

      .. oe:language:: python

         .. oe:api:: python

            GetFlipBias() -> float

      Returns the score bias against flipping a
      mover. The score bias is determined by the scoring system but can
      be controlled indirectly with the
      :oe:meth:`SetFlipBiasScale<OEBio::OEPlaceHydrogensOptions::SetFlipBiasScale>`
      method.

      .. seealso::

         * :oe:meth:`GetFlipBiasScale<OEBio::OEPlaceHydrogensOptions::GetFlipBiasScale>` method


   .. oe:method:: GetFlipBiasScale

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

         .. oe:api::

            double GetFlipBiasScale() const

      .. oe:language:: python

         .. oe:api:: python

            GetFlipBiasScale() -> float

      Returns the scaling factor for the score bias against flipping a
      mover. The actual score bias is determined by the scoring system.

      .. seealso::

         * :oe:meth:`GetFlipBias<OEBio::OEPlaceHydrogensOptions::GetFlipBias>` method


   .. oe:method:: GetFlipPredicate

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetFlipPredicate() -> OEUnaryAtomPred

      Returns a new copy of the predicate that
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      will use to restrain to the flipped state all flippable movers
      having a matching atom.

      .. oe:language:: c++

         To avoid a memory leak in C++, the returned pointer should be
         stored in a variable of the
         :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` template class
         or deallocated with the ``delete`` operator.

      (Default: :oe:cls:`OEIsFalseAtom<OESystem::OEIsFalse>`)

      .. seealso::

         * :oe:meth:`SetFlipPredicate<OEBio::OEPlaceHydrogensOptions::SetFlipPredicate>` method
         * :oe:meth:`GetBypassPredicate<OEBio::OEPlaceHydrogensOptions::GetBypassPredicate>` method
         * :oe:meth:`GetNoFlipPredicate<OEBio::OEPlaceHydrogensOptions::GetNoFlipPredicate>` method


   .. oe:method:: GetMaxSubstateCutoff

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

         .. oe:api::

            double GetMaxSubstateCutoff() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxSubstateCutoff() -> float

      Max number of substates processed in a single step of the state optimizer.

      .. seealso::

         * :oe:meth:`SetMaxSubstateCutoff<OEBio::OEPlaceHydrogensOptions::SetMaxSubstateCutoff>` method


   .. oe:method:: GetNoFlipPredicate

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetNoFlipPredicate() -> OEUnaryAtomPred

      Returns a new copy of the predicate that
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      will use to restrain to the original (unflipped) state all flippable movers
      having a matching atom.

      .. oe:language:: c++

         To avoid a memory leak in C++, the returned pointer should be
         stored in a variable of the
         :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` template class
         or deallocated with the ``delete`` operator.

      (Default: :oe:cls:`OEIsFalseAtom<OESystem::OEIsFalse>`)

      .. seealso::

         * :oe:meth:`SetNoFlipPredicate<OEBio::OEPlaceHydrogensOptions::SetNoFlipPredicate>` method
         * :oe:meth:`GetBypassPredicate<OEBio::OEPlaceHydrogensOptions::GetBypassPredicate>` method
         * :oe:meth:`GetFlipPredicate<OEBio::OEPlaceHydrogensOptions::GetFlipPredicate>` method


   .. oe:method:: GetStandardizeBondLen

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

         .. oe:api::

            bool GetStandardizeBondLen() const

      .. oe:language:: python

         .. oe:api:: python

            GetStandardizeBondLen() -> bool

      Returns whether the length of bonds to hydrogen atoms are adjusted to
      standard size.


   .. oe:method:: GetWaterProcessing

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

         .. oe:api::

            unsigned GetWaterProcessing() const

      .. oe:language:: python

         .. oe:api:: python

            GetWaterProcessing() -> int

      Returns a constant indicating how waters (and analogs) are processed.

      .. seealso::

         * :oe:constns:`OEBio::OEPlaceHydrogensWaterProcessing` namespace


   .. oe:method:: SetAddMetadata

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

         .. oe:api::

            void SetAddMetadata()

      .. oe:language:: python

         .. oe:api:: python

            SetAddMetadata() -> None

      Controls whether metadata describing the results
      should be added to the molecule. The metadata is the string generated by
      the :oe:meth:`OEBio::OEPlaceHydrogensDetails::Describe` method
      and can be accessed by the :oe:func:`OEBio::OEGetPlaceHydrogensMetadata`
      function.

      (Default: ``true``)

      .. seealso::

         * :oe:func:`OEBio::OEHasPlaceHydrogensMetadata` function
         * :oe:func:`OEBio::OEGetPlaceHydrogensMetadata` function
         * :oe:func:`OEBio::OEClearPlaceHydrogensMetadata` function
         * :ref:`OEPlaceHydrogensDetails <OEBio_OEPlaceHydrogensDetails>` class


   .. oe:method:: SetAltsMustBeCompatible

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

         .. oe:api::

            void SetAltsMustBeCompatible()

      .. oe:language:: python

         .. oe:api:: python

            SetAltsMustBeCompatible() -> None

      Set if alternate location codes are required to be compatible (either
      identical or blank) for atoms to interact. If set to ``true``,
      incompatible atoms will not interact.

      The appropriate setting will depend on how alternate locations are prepared
      in the input molecule. If an :ref:`OEAltLocationFactory <OEBio_OEAltLocationFactory>` was
      used to select the highest occupancy alternate locations, only one location
      remains for each atom so ``compatible`` should be ``false``, it could
      prevent legitimate interactions. The same is true
      if alt information was stripped and only codes ``A`` and *blank* remain
      (the default behavior when a ``.pdb`` file is read with the default flavor).

      If all location codes are retained on input with the
      :oe:const:`ALTLOC<OEChem::OEIFlavor::PDB::ALTLOC>` flavor and not modified,
      then ``compatible`` should be ``true``. This is not perfect, but generally
      works OK. But it is generally recommended that you read ``.pdb`` files using
      the :oe:const:`ALTLOC<OEChem::OEIFlavor::PDB::ALTLOC>` flavor, process it
      with the :oe:cls:`OEAltLocationFactory<OEBio::OEAltLocationFactory>`, and
      leave ``compatible`` set to ``false`` when calling
      :oe:func:`OEBio::OEPlaceHydrogens`.

      (Default: ``false``)

      .. seealso::

         * :oe:meth:`Constructors<OEBio::OEPlaceHydrogensOptions::Constructors>`
         * :oe:const:`OEChem::OEIFlavor::PDB::ALTLOC` flavor
         * :ref:`OEAltLocationFactory <OEBio_OEAltLocationFactory>` class


   .. oe:method:: SetBadClashOverlapDistance

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

         .. oe:api::

            bool SetBadClashOverlapDistance(double overlap)

      .. oe:language:: python

         .. oe:api:: python

            SetBadClashOverlapDistance(value: float) -> bool

      Sets the amount of excess van der Waals overlap considered to be
      a "bad" clash. (Default: 0.4 |A|)


   .. oe:method:: SetBypassPredicate

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

         .. oe:api::

            bool SetBypassPredicate(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred)

      .. oe:language:: python

         .. oe:api:: python

            SetBypassPredicate(value: OEUnaryAtomPred) -> bool

      Stores a predicate that :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      will use to exclude from analysis all movers having a matching atom.
      Useful for groups where a specific orientation has already been established.

      .. note::

         For any given mover, this predicate takes precedence over both the
         :oe:meth:`flip<OEBio::OEPlaceHydrogensOptions::SetFlipPredicate>` and the
         :oe:meth:`noFlip<OEBio::OEPlaceHydrogensOptions::SetNoFlipPredicate>`
         predicates.

      .. seealso::

         * :oe:meth:`GetBypassPredicate<OEBio::OEPlaceHydrogensOptions::GetBypassPredicate>` method
         * :oe:meth:`SetFlipPredicate<OEBio::OEPlaceHydrogensOptions::SetFlipPredicate>` method
         * :oe:meth:`SetNoFlipPredicate<OEBio::OEPlaceHydrogensOptions::SetNoFlipPredicate>` method


   .. oe:method:: SetFlipBiasScale

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

         .. oe:api::

            bool SetFlipBiasScale(double scale)

      .. oe:language:: python

         .. oe:api:: python

            SetFlipBiasScale(value: float) -> bool

      Sets a scaling factor for the score bias against flipping a
      mover. The actual score bias is determined by the scoring system.
      Setting the bias to ``0.0`` will turn off any bias towards
      the input structure. (Default: ``1.0``)

      .. seealso::

         * :oe:meth:`GetFlipBias<OEBio::OEPlaceHydrogensOptions::GetFlipBias>` method


   .. oe:method:: SetFlipPredicate

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

         .. oe:api::

            bool SetFlipPredicate(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred)

      .. oe:language:: python

         .. oe:api:: python

            SetFlipPredicate(value: OEUnaryAtomPred) -> bool

      Stores a predicate that :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      will use to restrain to the flipped state all flippable movers having a matching atom.

      .. note::

         For any given mover, if either the
         :oe:meth:`bypass<OEBio::OEPlaceHydrogensOptions::SetBypassPredicate>`
         predicate or the
         :oe:meth:`noFlip<OEBio::OEPlaceHydrogensOptions::SetNoFlipPredicate>`
         predicate matches, this predicate will be ignored.

      .. seealso::

         * :oe:meth:`GetFlipPredicate<OEBio::OEPlaceHydrogensOptions::GetFlipPredicate>` method
         * :oe:meth:`SetBypassPredicate<OEBio::OEPlaceHydrogensOptions::SetBypassPredicate>` method
         * :oe:meth:`SetNoFlipPredicate<OEBio::OEPlaceHydrogensOptions::SetNoFlipPredicate>` method


   .. oe:method:: SetMaxSubstateCutoff

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

         .. oe:api::

            bool SetMaxSubstateCutoff(double maxStates)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxSubstateCutoff(value: float) -> bool

      Set the maximum number of substates processed in a single step
      of the state optimizer. (Default: 1.0e8)

      .. seealso::

         * :oe:meth:`GetMaxSubstateCutoff<OEBio::OEPlaceHydrogensOptions::GetMaxSubstateCutoff>` method


   .. oe:method:: SetNoFlipPredicate

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

         .. oe:api::

            bool SetNoFlipPredicate(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred)

      .. oe:language:: python

         .. oe:api:: python

            SetNoFlipPredicate(value: OEUnaryAtomPred) -> bool

      Stores a predicate that :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      will use to restrain to the original (unflipped) state all flippable movers
      having a matching atom. Useful in preventing a group from being automatically
      flipped.

      .. note::

         For any given mover, if the
         :oe:meth:`bypass<OEBio::OEPlaceHydrogensOptions::SetBypassPredicate>`
         predicate matches, this predicate will be ignored.
         In addition, this predicate takes precedence over the
         :oe:meth:`flip<OEBio::OEPlaceHydrogensOptions::SetFlipPredicate>`
         predicate.

      .. seealso::

         * :oe:meth:`GetNoFlipPredicate<OEBio::OEPlaceHydrogensOptions::GetNoFlipPredicate>` method
         * :oe:meth:`SetBypassPredicate<OEBio::OEPlaceHydrogensOptions::SetBypassPredicate>` method
         * :oe:meth:`SetFlipPredicate<OEBio::OEPlaceHydrogensOptions::SetFlipPredicate>` method


   .. oe:method:: SetStandardizeBondLen

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

         .. oe:api::

            void SetStandardizeBondLen()

      .. oe:language:: python

         .. oe:api:: python

            SetStandardizeBondLen() -> None

      Sets whether the length of bonds to hydrogen atoms are adjusted to
      standard size. (Default: ``true``)


   .. oe:method:: SetWaterProcessing

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

         .. oe:api::

            bool SetWaterProcessing(unsigned process)

      .. oe:language:: python

         .. oe:api:: python

            SetWaterProcessing(value: int) -> bool

      Sets how waters (and analogs) are processed. (Default:
      :oe:const:`OEBio::OEPlaceHydrogensWaterProcessing::Default`)

      .. seealso::

         * :oe:constns:`OEBio::OEPlaceHydrogensWaterProcessing` namespace
