.. oe:namespace:: OESzmap

.. meta::
   :keywords: OESzmapResults, SzmapResults


.. _OESzmap_OESzmapResults:

.. oe:class:: OESzmapResults

   .. oe:api::


      class OESzmapResults

   A container for the
   results of OESzmap calculations with the
   function :oe:func:`OESzmap::OECalcSzmapResults`.

   .. seealso::

      * :ref:`GetSzmapEnergies<szmap_examples_szmapenergies>` example
      * :ref:`SzmapBestOrientations<szmap_examples_szmapbestorientations>` example


   .. oe:method:: Constructors

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

         .. oe:api::

            OESzmapResults()
            OESzmapResults(const OESzmapResults& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OESzmapResults() -> OESzmapResults
            OESzmapResults(rhs: OESzmapResults) -> OESzmapResults

      Default and copy constructors.
      Typically an empty, default :ref:`OESzmapResults <OESzmap_OESzmapResults>`
      is passed to :oe:func:`OESzmap::OECalcSzmapResults`
      where it is filled with the calculated results.

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-CREATE-SZMAPRESULTS-OBJECT

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-CREATE-SZMAPRESULTS-OBJECT

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`

      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-CREATE-SZMAPRESULTS-OBJECT

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-CREATE-SZMAPRESULTS-OBJECT

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

      .. oe:api::

         OESzmapResults &operator=(const OESzmapResults &rhs)

      Assignment operator.

   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      *True* indicates that :oe:func:`OESzmap::OECalcSzmapResults` was called
      with a valid :ref:`OESzmapEngine <OESzmap_OESzmapEngine>` when this object was created.

   .. oe:method:: Clear

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

         .. oe:api::

            void Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> None

      Resets this object to an uninitialized, empty state.

   .. oe:method:: GetComponent

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

         .. oe:api::

            bool GetComponent(double* compArray, unsigned int componentType) const
            OESystem::OEIterBase<double>* GetComponent(unsigned int componentType) const

      .. oe:language:: python

         .. oe:api:: python

            GetComponent(compArray: OEDoubleArray, componentType: int) -> bool
            GetComponent(componentType: int) -> Iterable[float]

      Returns the calculated values of a particular :oe:constns:`OESzmap::OEComponent`,
      specified by ``componentType``,
      for the 3D point provided to :oe:func:`OESzmap::OECalcSzmapResults`.
      *Component values* for each probe orientation are the low-level data
      used to compose :oe:constns:`OESzmap::OEEnsemble` values
      (see :oe:meth:`OESzmap::OESzmapResults::GetEnsembleValue`).
      The number of values in the output ``compArray`` or the iterator is
      :oe:meth:`OESzmap::OESzmapResults::NumOrientations` and values are returned
      in the same order as the probe orientations.

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-GET-COMPONENT

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-GET-COMPONENT

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`

      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-GET-COMPONENT

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-GET-COMPONENT

      Returns *false* or an empty iterator if the :oe:constns:`OESzmap::OEComponent`
      type is not recognized.

   .. oe:method:: GetCoords

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

         .. oe:api::

            bool GetCoords(float* xyz) const
            bool GetCoords(double* xyz) const

      .. oe:language:: python

         .. oe:api:: python

            GetCoords(xyz: OEFloatArray) -> bool
            GetCoords(xyz: OEDoubleArray) -> bool

      Returns the coordinates of the 3D point where calculations were performed by
      :oe:func:`OESzmap::OECalcSzmapResults` to create this object.

      The point is passed back in a float or double array of size three
      with coordinates in {x,y,z} order.

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-GET-COORDS

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-GET-COORDS

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`

      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-GET-COORDS

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-GET-COORDS

      Returns *false* if this :ref:`OESzmapResults <OESzmap_OESzmapResults>` is uninitialized.

   .. oe:method:: GetEnsembleValue

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

         .. oe:api::

            double GetEnsembleValue(unsigned int ensembleType) const

      .. oe:language:: python

         .. oe:api:: python

            GetEnsembleValue(ensembleType: int) -> float

      Returns the calculated value of a particular :oe:constns:`OESzmap::OEEnsemble`,
      specified by ``ensembleType``,
      for the 3D point provided to :oe:func:`OESzmap::OECalcSzmapResults`.
      *Ensemble values*  are the results of calculations
      over all orientations of the probe.
      In general, these are built by Boltzmann summation of
      various combinations of :oe:constns:`OESzmap::OEComponent` values
      (see :oe:meth:`OESzmap::OESzmapResults::GetComponent`).

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-GET-ENSEMBLE-VALUE

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-GET-ENSEMBLE-VALUE

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`

      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-GET-ENSEMBLE-VALUE

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-GET-ENSEMBLE-VALUE

      Returns 0.0 if the :oe:constns:`OESzmap::OEEnsemble`
      type is not recognized or this :ref:`OESzmapResults <OESzmap_OESzmapResults>` is uninitialized.

   .. oe:method:: GetProbabilities

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

         .. oe:api::

            bool GetProbabilities(double* probArray) const
            OESystem::OEIterBase<double>* GetProbabilities() const

      .. oe:language:: python

         .. oe:api:: python

            GetProbabilities(probArray: OEDoubleArray) -> bool
            GetProbabilities() -> Iterable[double]

      Returns the statistical mechanical probabilities for each probe orientation
      at the 3D point provided to :oe:func:`OESzmap::OECalcSzmapResults`.
      Probability values can be used to Boltzmann weight
      :oe:constns:`OESzmap::OEComponent` values and are used to select which
      probe orientations are returned by :oe:meth:`OESzmap::OESzmapResults::PlaceProbeSet`.
      The number of values in the output ``probArray`` or the iterator is
      :oe:meth:`OESzmap::OESzmapResults::NumOrientations` and values are returned
      in the same order as the probe orientations.

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-GET-PROBABILITIES

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-GET-PROBABILITIES

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`

      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-GET-PROBABILITIES

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-GET-PROBABILITIES

      Returns *false* or an empty iterator if this
      :ref:`OESzmapResults <OESzmap_OESzmapResults>` is uninitialized.

   .. oe:method:: GetProbabilityOrder

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

         .. oe:api::

            bool GetProbabilityOrder(unsigned int* orderArray) const
            OESystem::OEIterBase<unsigned int>* GetProbabilityOrder() const

      .. oe:language:: python

         .. oe:api:: python

            GetProbabilityOrder(orderArray: int) -> bool
            GetProbabilityOrder() -> Iterable[int]

      Returns an array or iterator of indices referring to probe orientations or
      associated :oe:constns:`OESzmap::OEComponent` and probability values,
      sorted in the order of increasing probability
      (see :oe:meth:`OESzmap::OESzmapResults::GetProbabilities`).
      Hence, the first (``orderArray[0]``)
      is the index of the orientation with the greatest probability
      (``probArray[orderArray[0]]``).
      The number of values in the output ``orderArray`` or the iterator is
      :oe:meth:`OESzmap::OESzmapResults::NumOrientations`.

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-GET-ORDER

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-GET-ORDER

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`


      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-GET-ORDER

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-GET-ORDER

      Returns *false* or an empty iterator if this
      :ref:`OESzmapResults <OESzmap_OESzmapResults>` is uninitialized.

   .. oe:method:: NumOrientations

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

         .. oe:api::

            unsigned int NumOrientations() const

      .. oe:language:: python

         .. oe:api:: python

            NumOrientations() -> int

      Returns the number of orientations for the probe molecule used in the calculation.
      Equals the number of values returned by calls to
      :oe:meth:`OESzmap::OESzmapResults::GetComponent`,
      :oe:meth:`OESzmap::OESzmapResults::GetProbabilities`, or
      :oe:meth:`OESzmap::OESzmapResults::GetProbabilityOrder`.

   .. oe:method:: PlaceNewAtom

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

         .. oe:api::

            OEChem::OEAtomBase* PlaceNewAtom(OEChem::OEMolBase& mol,
                                             unsigned int element = OEChem::OEElemNo::O) const

      .. oe:language:: python

         .. oe:api:: python

            PlaceNewAtom(mol: Union[OEGraphMol,OEMol,OEQMol], element: int) -> OEAtomBase

      Adds a new atom to the input molecule with atomic coordinates
      of the 3D point provided to :oe:func:`OESzmap::OECalcSzmapResults`
      when the object was created.

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-PLACE-NEW-ATOM

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-PLACE-NEW-ATOM

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`


      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-PLACE-NEW-ATOM

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-PLACE-NEW-ATOM

      The new atom has been annotated with ensemble values for this point as generic data.
      String versions of the data have been formatted to two decimal places
      for convenient display.

      =========================== ====== ============================================
      Generic Data Tag            Type   Value (energies in kcal/mol)
      =========================== ====== ============================================
      szmap_neut_diff_free_energy double Probe - neutral probe free energy difference
      --------------------------- ------ --------------------------------------------
      szmap_order                 double Fractional entropy loss from electrostatics
      --------------------------- ------ --------------------------------------------
      szmap_vdw                   double Van der Waals energy
      --------------------------- ------ --------------------------------------------
      free-energy                 string Formatted szmap_neut_diff_free_energy
      --------------------------- ------ --------------------------------------------
      order-param                 string Formatted szmap_order
      --------------------------- ------ --------------------------------------------
      vdw                         string Formatted szmap_vdw
      =========================== ====== ============================================

      The atom type can be controlled through the optional ``element`` parameter,
      which defaults to *oxygen.*

      .. _figure_new_atoms:

      .. figure:: ../images/szmaptk-colors-and-energies-on-points.png
         :scale:  75
         :align:  center

         **Atoms Placed at Calculation Points with Generic Data Annotation**

      Returns a pointer to the newly created atom to facilitate further customization.

   .. oe:method:: PlaceProbeMol

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

         .. oe:api::

            bool PlaceProbeMol(OEChem::OEMolBase& outputMol,
                               unsigned int orientation = 0u,
                               bool annotate = true) const

      .. oe:language:: python

         .. oe:api:: python

            PlaceProbeMol(outputMol: Union[OEGraphMol,OEMol,OEQMol],
                          orientation: int = 0, annotate: bool = True) -> bool

      Modifies the ``outputMol`` to be a copy of one probe orientation,
      placed at the 3D point provided to
      :oe:func:`OESzmap::OECalcSzmapResults` when the object was created.
      The probe orientation can be controlled through
      the optional ``orientation`` parameter (the default value of 0 refers to
      the first probe conformation).

      .. oe:source:: SzmapCalcs.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-PLACE-PROBE-MOL

      .. oe:source:: SzmapCalcs.py
         :language: python
         :noindent:
         :frag:     SNIPPET-PLACE-PROBE-MOL

      .. :oe:language:: python

        :ref:`Full listing. <listing-SzmapCalcs.py>`


      .. oe:source:: SzmapCalcs.java
         :language: java
         :noindent:
         :frag:     SNIPPET-PLACE-PROBE-MOL

      .. oe:source:: SzmapCalcs.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-PLACE-PROBE-MOL

      If the optional parameter ``annotate`` is *true* (the default),
      the molecule will be annotated with :oe:constns:`OESzmap::OEComponent`
      data for that orientation. See :oe:meth:`OESzmap::OESzmapResults::PlaceProbeSet`
      for more information on this annotation.

      Returns *false* if this :ref:`OESzmapResults <OESzmap_OESzmapResults>` is uninitialized.

   .. oe:method:: PlaceProbeSet

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

         .. oe:api::

            double PlaceProbeSet(OEChem::OEMCMolBase& probeSet,
                                 double probCutoff, bool clear = true) const
            double PlaceProbeSet(OEChem::OEMCMolBase& probeSet,
                                 unsigned int maxConfs = 0u, bool clear = true) const

      .. oe:language:: python

         .. oe:api:: python

            PlaceProbeSet(probeSet: OEMol, probCutoff: float,
                          clear: bool = True) -> float
            PlaceProbeSet(probeSet: OEMol, maxConfs: int = 0,
                          clear: bool = True) -> float

      Modifies the multi-conformer ``probeSet`` to contain one or more orientations of
      the probe, each placed at the 3D point provided
      to :oe:func:`OESzmap::OECalcSzmapResults` when the object was created.
      The probe set is returned in probability order
      (see :oe:meth:`OESzmap::OESzmapResults::GetProbabilityOrder`).

      There are three ways to select which probe orientations are placed in the ``probeSet``:

      * If just the ``probeSet`` parameter is provided, without other options,
        all probe orientations will be returned.

        .. oe:source:: SzmapCalcs.cpp
           :language: c++
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-ALL

        .. oe:source:: SzmapCalcs.py
           :language: python
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-ALL

        .. :oe:language:: python

            :ref:`Full listing. <listing-SzmapCalcs.py>`


        .. oe:source:: SzmapCalcs.java
           :language: java
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-ALL

        .. oe:source:: SzmapCalcs.cs
           :language: csharp
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-ALL

      * If the real number parameter ``probCutoff`` is used,
        probe orientations will be added until
        the total cumulative probability is at least that amount.
        Cumulative probabilities are > 0.0 and <= 1.0.

        .. oe:source:: SzmapCalcs.cpp
           :language: c++
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-PROB

        .. oe:source:: SzmapCalcs.py
           :language: python
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-PROB

        .. :oe:language:: python

            :ref:`Full listing. <listing-SzmapCalcs.py>`


        .. oe:source:: SzmapCalcs.java
           :language: java
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-PROB

        .. oe:source:: SzmapCalcs.cs
           :language: csharp
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-PROB

      * Finally, if the integer parameter ``maxConfs`` is used,
        no more than number of probe orientations will be returned. A value of
        ``0`` is a special signal to return all orientations.

        .. oe:source:: SzmapCalcs.cpp
           :language: c++
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-COUNT

        .. oe:source:: SzmapCalcs.py
           :language: python
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-COUNT

        .. :oe:language:: python

            :ref:`Full listing. <listing-SzmapCalcs.py>`


        .. oe:source:: SzmapCalcs.java
           :language: java
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-COUNT

        .. oe:source:: SzmapCalcs.cs
           :language: csharp
           :noindent:
           :frag:     SNIPPET-PLACE-PROBE-SET-COUNT

      If the optional parameter ``clear`` is set to *false*, any previous orientations
      in the ``probeSet`` will not be cleared, allowing conformers for multiple 3D points
      as well as multiple orientations to be stored in the ``probeSet``. By default, previous
      orientations *are* cleared away before the new orientations are added.

      Each orientation has been annotated with :oe:constns:`OESzmap::OEComponent`
      data for that orientation.
      In addition, the total *interaction + psolv + wsolv + vdw* energy of each
      is recorded as the energy of the conformation
      (accessible using the ``GetEnergy()`` method of the conformer).
      String versions of the data
      have been formatted to two decimal places for convenient display.
      String data is also
      stored as SD data, so they are included in *VIDA's* spreadsheet
      and can be saved to ``.sd`` files.

      =================== ====== ====== ============================================
      Generic/SD Data Tag Type   SD     Value (energies in kcal/mol)
      =================== ====== ====== ============================================
      szmap_interaction   double *no*   Poisson-Boltzmann probe|context interaction
      ------------------- ------ ------ --------------------------------------------
      szmap_psolv         double *no*   (Protein) context desolvation penalty
      ------------------- ------ ------ --------------------------------------------
      szmap_wsolv         double *no*   (Water) probe desolvation penalty
      ------------------- ------ ------ --------------------------------------------
      szmap_vdw           double *no*   Van der Waals energy
      ------------------- ------ ------ --------------------------------------------
      szmap_probability   double *no*   Boltzmann probability
      ------------------- ------ ------ --------------------------------------------
      total-energy        string *yes*  szmap_interaction + psolv + wsolv + vdw
      ------------------- ------ ------ --------------------------------------------
      interaction         string *yes*  Formatted szmap_interaction
      ------------------- ------ ------ --------------------------------------------
      psolv               string *yes*  Formatted szmap_psolv
      ------------------- ------ ------ --------------------------------------------
      wsolv               string *yes*  Formatted szmap_wsolv
      ------------------- ------ ------ --------------------------------------------
      vdw                 string *yes*  Formatted szmap_vdw
      ------------------- ------ ------ --------------------------------------------
      prob                string *yes*  Formatted szmap_probability
      =================== ====== ====== ============================================

      Returns the cumulative probability of all the orientations returned,
      or 0.0 if this :ref:`OESzmapResults <OESzmap_OESzmapResults>` is uninitialized.

      .. _figure_spreadsheet:

      .. figure:: ../images/szmaptk-spreadsheet-selection.png
         :scale:  75
         :align:  center

         **SD Annotation in the VIDA Spreadsheet**

