.. include:: ../toolkit-substitutions

.. _working_with_szmap:

********************************************************************************
Working with Szmap TK
********************************************************************************

The *Szmap TK* has a simple API,
consisting of a few basic :ref:`szmap_part_api`
and a couple of objects to configure
the calculations
(:ref:`OESzmapEngine <OESzmap_OESzmapEngine>` and
:ref:`OESzmapEngineOptions <OESzmap_OESzmapEngineOptions>`)
and hold calculated results
(:ref:`OESzmapResults <OESzmap_OESzmapResults>`).

Preparing Protein and Ligand Molecules
======================================

To perform the necessary electrostatics calculations,
a protein or any other molecular context
being analyzed with *SZMAP* must already
have all hydrogens explicitly represented as well as have charges and radii assigned 
before it can be used. This is done automatically as part of protein preparation 
with **Spruce TK** (see :oe:func:`OESpruce::OEMakeDesignUnits`).
Charges can also be assigned using **Quacpac TK** (see :oe:func:`OEProton::OEAssignCharges`).

Calculating Energies
====================

To calculate probe energies, we initialize
a :ref:`OESzmapEngine <OESzmap_OESzmapEngine>` with a molecular
context, test if the point of interest is clashing,
and if not, calculate the energies. In the example below,
the energies at each ligand atom coordinate
are returned in a :ref:`OESzmapResults <OESzmap_OESzmapResults>`
object, which is accessed for specific values.
Alternatively, :oe:func:`OESzmap::OECalcSzmapValue` could
be used to get a single :oe:constns:`OESzmap::OEEnsemble`
value directly.

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

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

.. :oe:language:: python

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


..  oe:language:: python

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


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

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

The five :oe:constns:`OESzmap::OEEnsemble` values
in the example above are the primary ones
for understanding solvent/ligand competition.

.. seealso::

   * :ref:`GetSzmapEnergies<szmap_examples_szmapenergies>` example

Generating Probe Orientations
=============================

In addition to energy calculations, the *Szmap TK*
can be used to generate 3D conformations of probe
molecules at calculated points, annotated
with :oe:constns:`OESzmap::OEComponent`
energies for each conformation. In the example below,
individual atoms are also generated at calculation
points, each annotated with :oe:constns:`OESzmap::OEEnsemble`
values.

.. oe:source:: SzmapCalcs.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-GENERATE-SZMAP-PROBES

.. oe:source:: SzmapCalcs.py
   :language: python
   :noindent:
   :frag:     SNIPPET-GENERATE-SZMAP-PROBES

.. :oe:language:: python

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


.. oe:source:: SzmapCalcs.java
   :language: java
   :noindent:
   :frag:     SNIPPET-GENERATE-SZMAP-PROBES

.. oe:source:: SzmapCalcs.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-GENERATE-SZMAP-PROBES

.. _figure_orientations_and_points:

.. figure:: images/szmaptk-labeled-orientations.png
   :scale:  75
   :align:  center

   **High Probability Probe Orientations and Points with Generic Data Annotation**

.. seealso::

   * :ref:`SzmapBestOrientations<szmap_examples_szmapbestorientations>` example