
.. include:: ../substitutions

.. oe:namespace:: OEProton

.. meta::
   :keywords: OEAssignCharges, AssignCharges

.. _OEProton_OEAssignCharges:

.. oe:function:: OEAssignCharges

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

      .. oe:api::

         bool OEAssignCharges(OEChem::OEMolBase& mol,
                              const OEChargeEngineBase& chargeEngine)
         bool OEAssignCharges(OEChem::OEMCMolBase& mcMol,
                              const OEChargeEngineBase& chargeEngine)

   .. oe:language:: python

      .. oe:api:: python

         OEAssignCharges(mol: Union[OEGraphMol,OEQMol],
                         chargeEngine: OEChargeEngineBase) -> bool
         OEAssignCharges(mcMol: OEMol, chargeEngine: OEChargeEngineBase) -> bool

   .. note::

      This function is designed to replace the legacy function
      :oe:func:`OEAssignPartialCharges<OEProton::OEAssignPartialCharges>`.

   This function sets the charge of each atom in the
   molecule ``mol`` based on the specific nature of the
   :oe:cls:`chargeEngine<OEProton::OEChargeEngineBase>` object
   passed as the second argument. In general, charge engine implementations place
   scalar partial charges on atoms, but could be implemented to perform
   other roles such as assign multi-pole charges.

   .. oe:source:: AssignChargesDoc.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-MMFF
      :refnum:   1
      :caption:  Assigning MMFF Partial Charges to a Molecule

   .. oe:source:: AssignChargesDoc.py
      :language: python
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-MMFF
      :refnum:   1
      :caption:  Assigning MMFF Partial Charges to a Molecule

   .. oe:source:: AssignChargesDoc.java
      :language: java
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-MMFF
      :refnum:   1
      :caption:  Assigning MMFF Partial Charges to a Molecule

   .. oe:source:: AssignChargesDoc.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-MMFF
      :refnum:   1
      :caption:  Assigning MMFF Partial Charges to a Molecule

   Another example:

   .. oe:source:: AssignChargesDoc.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-PARAM
      :refnum:   2
      :caption:  Assigning Unoptimized AM1 Partial Charges

   .. oe:source:: AssignChargesDoc.py
      :language: python
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-PARAM
      :refnum:   2
      :caption:  Assigning Unoptimized AM1 Partial Charges

   .. oe:source:: AssignChargesDoc.java
      :language: java
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-PARAM
      :refnum:   2
      :caption:  Assigning Unoptimized AM1 Partial Charges

   .. oe:source:: AssignChargesDoc.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-PARAM
      :refnum:   2
      :caption:  Assigning Unoptimized AM1 Partial Charges

   The objects used by this function, derived from the abstract base class
   :ref:`OEChargeEngineBase <OEProton_OEChargeEngineBase>`, can be thought of as "options objects"
   which describe the details of a specific charge model.
   :oe:func:`OEAssignCharges<OEProton::OEAssignCharges>` analyzes these options
   and may need to add explicit hydrogens or perceive residues before assigning
   charges.

   .. oe:source:: AssignChargesDoc.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-METHOD
      :refnum:   3
      :caption:  Assigning Non-symmetrized AM1BCC Partial Charges

   .. oe:source:: AssignChargesDoc.py
      :language: python
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-METHOD
      :refnum:   3
      :caption:  Assigning Non-symmetrized AM1BCC Partial Charges

   .. oe:source:: AssignChargesDoc.java
      :language: java
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-METHOD
      :refnum:   3
      :caption:  Assigning Non-symmetrized AM1BCC Partial Charges

   .. oe:source:: AssignChargesDoc.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-ASSIGN-CHARGES-OPTIONS-METHOD
      :refnum:   3
      :caption:  Assigning Non-symmetrized AM1BCC Partial Charges

   Some prerequisites, such as setting the aromaticity model,
   would alter the input molecule in ways that are incidental to the calculation.
   In this case, a copy of the input molecule is made before the alterations are
   made and the charges are transferred back to the input molecule after the
   calculation. This ensures that only charges, explicit hydrogens,
   residue perception, residue names, and the number of conformations returned
   can change on the input molecule.

   This function returns ``false`` if does not succeed.

   .. seealso::

      * :oe:func:`OEProton::OEAssignPartialCharges` function
      * :ref:`OEChargeEngineBase <OEProton_OEChargeEngineBase>` abstract base class
      * :ref:`section_examples_summary_assigncharges` code example
