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


.. oe:namespace:: OEProton

.. meta::
  :keywords: OEMultistatepKaModel, OEMultistatepKaModelOptions, pKaModel


.. _OEProton_OEMultistatepKaModel:

.. oe:class:: OEMultistatepKaModel

  .. attention::

    |PRELIMINARY-API|
  
  .. oe:api::

     class OEMultistatepKaModel

  This class provides functionality to assess the atomic pKa of a given molecule and enumerate ionization states at neutral pH.
  The options required for this class can be set using the :ref:`OEMultistatepKaModelOptions <OEProton_OEMultistatepKaModelOptions>` class.

  .. seealso::

     * :ref:`OEMultistatepKaModelOptions <OEProton_OEMultistatepKaModelOptions>` class

    The :ref:`OEMultistatepKaModel <OEProton_OEMultistatepKaModel>` class defines the following public methods:
      
      * :oe:meth:`Init<OEProton::OEMultistatepKaModel::Init>`
      * :oe:meth:`CalculateNumOfMicrostates<OEProton::OEMultistatepKaModel::CalculateNumOfMicrostates>`
      * :oe:meth:`SetAllAtomspKaData<OEProton::OEMultistatepKaModel::SetAllAtomspKaData>`
      * :oe:meth:`GetModelMolecule<OEProton::OEMultistatepKaModel::GetModelMolecule>`
      * :oe:meth:`GetAtompKaRange<OEProton::OEMultistatepKaModel::GetAtompKaRange>`
      * :oe:meth:`GenerateMicrostates<OEProton::OEMultistatepKaModel::GenerateMicrostates>`
      * :oe:meth:`GetMicrostates<OEProton::OEMultistatepKaModel::GetMicrostates>`

      * :oe:meth:`HasAdjTypeAtNeutralpH<OEProton::OEMultistatepKaModel::HasAdjTypeAtNeutralpH>`
      * :oe:meth:`HaspKaRange<OEProton::OEMultistatepKaModel::HaspKaRange>`


  .. oe:method:: Constructors

    Constructors.

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

       .. oe:api::

          OEMultistatepKaModel()
          OEMultistatepKaModel(const OEMultistatepKaModelOptions& opts)
          OEMultistatepKaModel(OEChem::OEMolBase& mol,
                               const OEMultistatepKaModelOptions& opts = OEMultistatepKaModelOptions())

    .. oe:language:: python

       .. oe:api:: python

          OEMultistatepKaModel() -> OEMultistatepKaModel
          OEMultistatepKaModel(opts: OEMultistatepKaModelOptions) -> OEMultistatepKaModel
          OEMultistatepKaModel(mol: Union[OEGraphMol,OEMol,OEQMol],
                               opts: OEMultistatepKaModelOptions = OEMultistatepKaModelOptions()) -> OEMultistatepKaModel

    Copy constructor.

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

       .. oe:api::

          OEMultistatepKaModel(const OEMultistatepKaModel& rhs)

    .. oe:language:: python

       .. oe:api:: python

          OEMultistatepKaModel(rhs: OEMultistatepKaModel) -> OEMultistatepKaModel

    Copy assignment constructor.

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

    .. oe:api::

        OEMultistatepKaModel& operator=(const OEMultistatepKaModel &rhs)
        Assignment operator.


  .. oe:method:: Init

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

       .. oe:api::

          void Init(OEChem::OEMolBase& mol)
          void Init(OEChem::OEMolBase& mol, OEMultistatepKaModelOptions& opts)

    .. oe:language:: python

       .. oe:api:: python

          Init(mol: Union[OEGraphMol,OEMol,OEQMol]) -> None
          Init(mol: Union[OEGraphMol,OEMol,OEQMol],
               opts: OEMultistatepKaModelOptions) -> None

    If a user has initialized the OEMultistatepKaModel instance with default constructor
    (without molecule and options object), they can add a molecule and
    :ref:`OEMultistatepKaModelOptions <OEProton_OEMultistatepKaModelOptions>` instance later by the Init method.

  .. oe:method:: CalculateNumOfMicrostates

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

       .. oe:api::

          int CalculateNumOfMicrostates()

    .. oe:language:: python

       .. oe:api:: python

          CalculateNumOfMicrostates() -> int

    This method calculates the number of microstates possible for given molecule. It uses
    the information (generic pKa data) assessed and set by the method SetAllAtomspKaData. It returns -1 if either
    OEMultistatepKaModel failed to assess all atomic pKa on the molecule (probably due to unknown atoms present), or
    it halted assessing pKa data because the projected number of microstates exceeded the provided limit of microstates to be generated.

  .. oe:method:: GetModelMolecule

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

       .. oe:api::

          const OEChem::OEMolBase& GetModelMolecule()

    .. oe:language:: python

       .. oe:api:: python

          GetModelMolecule() -> OEGraphMol

    This method returns the copy of the internal molecule object from the :ref:`OEMultistatepKaModel <OEProton_OEMultistatepKaModel>` class
    on which all atomic pKa data are assessed and set as generic data.

  .. oe:method:: GetAtompKaRange

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

       .. oe:api::

          unsigned int GetAtompKaRange(const OEChem::OEAtomBase* atom)

    .. oe:language:: python

       .. oe:api:: python

          GetAtompKaRange(atom: OEAtomBase) -> int

    This method allows a user to assess and get the pKa range (
    :oe:const:`OEProton::OEpKaRange::Acidic`, 
    :oe:const:`OEProton::OEpKaRange::Neutral`, 
    :oe:const:`OEProton::OEpKaRange::Basic` or 
    :oe:const:`OEProton::OEpKaRange::Unidentified`) 
    for an individual atom.

  .. oe:method:: GetAtomAdjTypeAtNeutralpH

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

       .. oe:api::

          unsigned int GetAtomAdjTypeAtNeutralpH(const OEChem::OEAtomBase* atom)

    .. oe:language:: python

       .. oe:api:: python

          GetAtomAdjTypeAtNeutralpH(atom: OEAtomBase) -> int

    This method allows a user to assess and get the adjustment type to be done at
    neutral pH (
    :oe:const:`OEProton::OEAdjTypeAtNeutralpH::NoChange`, 
    :oe:const:`OEProton::OEAdjTypeAtNeutralpH::Protonation`, 
    :oe:const:`OEProton::OEAdjTypeAtNeutralpH::Deprotonation`, 
    :oe:const:`OEProton::OEAdjTypeAtNeutralpH::NoChangeAndProtonation`, 
    :oe:const:`OEProton::OEAdjTypeAtNeutralpH::NoChangeAndDeprotonation` 
    ) for an individual atom.

  .. oe:method:: GenerateMicrostates

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

       .. oe:api::

          bool GenerateMicrostates()

    .. oe:language:: python

       .. oe:api:: python

          GenerateMicrostates() -> bool

    This method generates all possible microstates (up to the limit specified by the options class).
    These generated microstates can be accessed by the method
    :oe:meth:`GetMicrostates<OEProton::OEMultistatepKaModel::GetMicrostates>`.
 
  .. oe:method:: GetMicrostates

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

       .. oe:api::

          OESystem::OEIterBase<OEChem::OEMolBase>* GetMicrostates()

    .. oe:language:: python

       .. oe:api:: python

          GetMicrostates() -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]

    Microstates generated by the method :oe:meth:`GenerateMicrostates<OEProton::OEMultistatepKaModel::GenerateMicrostates>`
    can be accessed by this method. It returns an iterator over the generated microstates molecule objects.

  .. oe:method:: HasAdjTypeAtNeutralpH

    .. oe:api::

         HasAdjTypeAtNeutralpH(unsigned AdjTypeAtNeutralpHID)

    This is a predicate functor, which allows a user to filter atoms with the
    desired :oe:constns:`OEProton::OEAdjTypeAtNeutralpH` generic data attached.

  .. oe:method:: HaspKaRange

    .. oe:api::

         HaspKaRange(unsigned pkarangeID)

    This is a predicate functor, which allows a user to filter atoms with the
    desired :oe:constns:`OEProton::OEpKaRange` generic data attached.

  .. oe:method:: SetAllAtomspKaData

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

       .. oe:api::

          bool SetAllAtomspKaData()

    .. oe:language:: python

       .. oe:api:: python

          SetAllAtomspKaData() -> bool

    This method assesses the atomic pKa for all heavy/hetero atoms and sets generic pKa data for these atoms.
    If an OEMultistatepKaModelOptions class object is specified with the parameter processcarbons = true, it
    assesses all heavy atoms. If an OEMultistatepKaModelOptions class object is specified
    with the parameter processcarbons = false, then only hetero atoms are assessed.
