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

.. oe:namespace:: OEProton


.. _OEProton_OEDesignUnitCharges:

.. oe:class:: OEDesignUnitCharges

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::

      class OEDesignUnitCharges : public OEChargeEngineBase

   This charge engine charges each component in the :ref:`OEDesignUnit <OEBio_OEDesignUnit>`.
   The various components can be charged with different charging engines, and the default behavior is
   to do exactly that.
   The default behavior is for the protein engine to use :ref:`OEAmberFF94Charges <OEProton_OEAmberFF94Charges>`
   for the standard protein residues. It uses :ref:`OEAM1BCCCharges <OEProton_OEAM1BCCCharges>` for nonstandard
   residues. The nucleic acid component uses the :ref:`OEMMFF94Charges <OEProton_OEMMFF94Charges>` charges.
   The ligand and or any other heterogen in the system (e.g cofactors), are charged using
   :ref:`OEAM1BCCCharges <OEProton_OEAM1BCCCharges>`.
   The solvent uses :ref:`OEAmberFF94Charges <OEProton_OEAmberFF94Charges>`, but by default uses
   the SZMAP water model, in which case it assigns the charges to match those described in
   :ref:`chapter_water_model`. This is an option that can be turned off.
   Excipients are by default charged using the :ref:`OEMMFF94Charges <OEProton_OEMMFF94Charges>` engine.
   The radii assigned are :oe:const:`OEChem::OERadiiType::BondiVdw`, except in cases where
   AM1 charges have been used, in which case the radii is of the :oe:const:`OEChem::OERadiiType::Zap9`
   type.
   Metals in the system (often in cofactors or otherCofactors) are initially charged with the
   :ref:`OEFormalToPartialCharges <OEProton_OEFormalToPartialCharges>` engine, and in the last step of the calculation,
   the metal charges are spread in the system using the :ref:`OESpreadMetalCharges <OEProton_OESpreadMetalCharges>` as part
   of the finalization stage. Counter ions are charged with the same metal charge engine, but are not subsequently spread.
   The fall back engine is the same for all components; in case an engine fails, the method will try to
   charge a component with the fall back engine, which by default is :ref:`OEMMFF94Charges <OEProton_OEMMFF94Charges>`.

   .. note::

      Currently, there is a hard limit of 100 atoms for molecules being charged with the :ref:`OEAM1BCCCharges <OEProton_OEAM1BCCCharges>` charging engine.

   .. warning::

      It is currently not possible to use :ref:`OEAM1BCCELF10Charges <OEProton_OEAM1BCCELF10Charges>` for the ligand, cofactors, or other
      components. The method requires passing a conformer ensemble of the molecule to charge, which is currently not
      possible with an :ref:`OEDesignUnit <OEBio_OEDesignUnit>`.
      If a user tries to use this type of charging engine, it will be downgraded to AM1BCC with a warning.
      Since the :ref:`OEAM1BCCELF10Charges <OEProton_OEAM1BCCELF10Charges>` is recommended for the molecular dynamics type of simulations,
      we recommend charging the ligand independently and updating it in the DesignUnit using
      :oe:func:`OEBio::OEUpdateDesignUnit`.


   The following methods are publicly inherited from :ref:`OEChargeEngineBase <OEProton_OEChargeEngineBase>`:

   ======================================================================================= ======================================================================================= =======================================================================================
   :oe:meth:`operator!=<OEProton::OEChargeEngineBase::operator!=>`                         :oe:meth:`GetExpectValidMol<OEProton::OEChargeEngineBase::GetExpectValidMol>`           :oe:meth:`SetExpectValidMol<OEProton::OEChargeEngineBase::SetExpectValidMol>`
   :oe:meth:`operator==<OEProton::OEChargeEngineBase::operator==>`                         :oe:meth:`GetName<OEProton::OEChargeEngineBase::GetName>`                               :oe:meth:`SetRepairRequestedHint<OEProton::OEChargeEngineBase::SetRepairRequestedHint>`
   :oe:meth:`GetRepairRequestedHint<OEProton::OEChargeEngineBase::GetRepairRequestedHint>` :oe:meth:`TransferCharge<OEProton::OEChargeEngineBase::TransferCharge>`
   :oe:meth:`CheckCharges<OEProton::OEChargeEngineBase::CheckCharges>`                     :oe:meth:`GetRequirements<OEProton::OEChargeEngineBase::GetRequirements>`
   :oe:meth:`CreateCopy<OEProton::OEChargeEngineBase::CreateCopy>`                         :oe:meth:`IsValid<OEProton::OEChargeEngineBase::IsValid>`
   ======================================================================================= ======================================================================================= =======================================================================================

   .. oe:method:: Constructors

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

         .. oe:api::

            OEDesignUnitCharges()
            OEDesignUnitCharges(const OEDesignUnitCharges& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEDesignUnitCharges() -> OEDesignUnitCharges
            OEDesignUnitCharges(rhs: OEDesignUnitCharges) -> OEDesignUnitCharges

      Default and copy constructors.

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

      .. oe:api::

         OEDesignUnitCharges &operator=(const OEDesignUnitCharges &rhs)

      Assignment operator.

   .. oe:method:: ApplyCharges

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

         .. oe:api::

            bool ApplyCharges(OEBio::OEDesignUnit& du) const

      .. oe:language:: python

         .. oe:api:: python

            ApplyCharges(du: OEDesignUnit) -> bool

      Returns the boolean whether or not charges are able to be applied to the input
      :ref:`OEDesignUnit <OEBio_OEDesignUnit>` argument (`du`).

   .. oe:method:: CreateCopy

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

         .. oe:api::

            OEChargeEngineBase* CreateCopy() const

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEChargeEngineBase

      Creates a copy of the charge engine class. This class does not own the returned memory.

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid(const OEChem::OEMolBase& mol) const
            bool IsValid(const OEBio::OEDesignUnit& du) const

      .. oe:language:: python

         .. oe:api:: python

            IsValid(mol: Union[OEGraphMol,OEMol,OEQMol]) -> bool
            IsValid(du: OEDesignUnit) -> bool

      Returns the boolean whether or not the input :ref:`OEMolBase <OEChem_OEMolBase>` or :ref:`OEDesignUnit <OEBio_OEDesignUnit>` can be assigned partial charges from the charging engine.

   .. oe:method:: SetCoFactorChargeEngine

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

         .. oe:api::

            void SetCoFactorChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetCoFactorChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for the :oe:constns:`OEBio::OEDesignUnitComponents::Cofactors` molecular component.

   .. oe:method:: SetFallbackChargeEngine

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

         .. oe:api::

            void SetFallbackChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetFallbackChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets a backup charge engine for any molecular component where the charge engine cannot be applied.

   .. oe:method:: SetFinalizationChargeEngine

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

         .. oe:api::

            void SetFinalizationChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetFinalizationChargeEngine(chargeEngine: OEChargeEngineBase) -> None

   .. oe:method:: SetLigandChargeEngine

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

         .. oe:api::

            void SetLigandChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetLigandChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for the :oe:constns:`OEBio::OEDesignUnitComponents::Ligand` molecular component.

   .. oe:method:: SetMetalChargeEngine

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

         .. oe:api::

            void SetMetalChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetMetalChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for both the :oe:constns:`OEBio::OEDesignUnitComponents::Metals` and
      :oe:constns:`OEBio::OEDesignUnitComponents::CounterIons` molecular components.

   .. oe:method:: SetNucleicChargeEngine

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

         .. oe:api::

            void SetNucleicChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetNucleicChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for the :oe:constns:`OEBio::OEDesignUnitComponents::Nucleic` molecular component.

   .. oe:method:: SetOtherChargeEngine

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

         .. oe:api::

            void SetOtherChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetOtherChargeEngine(chargeEngine: OEChargeEngineBase) -> None

   .. oe:method:: SetProteinChargeEngine

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

         .. oe:api::

            void SetProteinChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetProteinChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for the :oe:constns:`OEBio::OEDesignUnitComponents::Protein` molecular component.

   .. oe:method:: SetProteinNonStandardChargeEngine

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

         .. oe:api::

            void SetProteinNonStandardChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetProteinNonStandardChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for any nonstandard amino acids in the :oe:constns:`OEBio::OEDesignUnitComponents::Protein` molecular component.

   .. oe:method:: SetSolventChargeEngine

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

         .. oe:api::

            void SetSolventChargeEngine(const OEChargeEngineBase& chargeEngine)

      .. oe:language:: python

         .. oe:api:: python

            SetSolventChargeEngine(chargeEngine: OEChargeEngineBase) -> None

      Sets the charge engine for any solvent molecules in the :oe:constns:`OEBio::OEDesignUnitComponents::Solvent` molecular component.

   .. oe:method:: TransferCharge

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

         .. oe:api::

            bool TransferCharge(OEChem::OEAtomBase* dstAtom,
                                const OEChem::OEAtomBase* srcAtom) const

      .. oe:language:: python

         .. oe:api:: python

            TransferCharge(dstAtom: OEAtomBase, srcAtom: OEAtomBase) -> bool

      Returns the boolean whether or not the transfer of charges from the source atom (`srcAtom`) to the destination atom (`dstAtom`) was successful.

   .. oe:method:: UseSZMAPWaterModel

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

         .. oe:api::

            void UseSZMAPWaterModel(const bool value)

      .. oe:language:: python

         .. oe:api:: python

            UseSZMAPWaterModel(value: bool) -> None

      Sets the boolean of whether or not to use the Szmap water model within the context of charging the system (see :ref:`chapter_szmap_intro` for more information about the water model itself).
