.. _chapter_thewayofzap:

*****************************
The Way of Zap
*****************************

There  follow a dozen or so examples of using ZAP. The list is always
growing  because  the toolkit philosophy really does work. Most of the
examples  use  OEInterface to provide consistent command-line argument
handling.

.. _section_partialchargesandatomicaradii:

Partial Charges and Atomic Radii
============================================================================

There are three essential quantities for any PB calculation: coordinates,
dielectric model (including radii), and charge. Coordinates will come from
the atomic coordinates of the input molecule, but partial charges and the
dielectric model deserve some extra attention.

Charges and radii can be calculated at run-time using functions provided by
OEChem or other OpenEye toolkits (AM1-BCC charges from **Quacpac TK** for example).
The dielectric model consists of both the value of the inner and outer
dielectric, as well as how the dielectric adjusts from one to the other. ZAP
uses atomic radii as the basis for its dielectric algorithm. By default, we
recommend using Bondi VdW radii which can be set on a molecule using the
function  OEAssignBondiVdWRadii   Or  you can set specific radii on an
atom-by-atom basis using the OEAtomBase::SetRadius function.

The current recommended value for the inner and outer dielectrics for a
molecule in an aqueous solution are 1.0 and 80.0. Therefore, these are the
default values for the OEZap and OEBind implementations. The historic value
for  the  inner dielectric is 2.0, and this value may be set using the
SetInnerDielectric method. Additionally, the default value for the inner
dielectric of the OEET implementation remains at 2.0 for the time being.

Accurate PB calculations also depend on quality atomic charges. In OEChem,
we provide MMFF94 partial charges as the lowest level of charges that we
consider usable in PB. The examples that follow will use these charges, so
that  they don't depend on any toolkits beside ZAP and OEChem. But for
production use, we recommend AM1-BCC charges

If your input file format can store partial charges and/or radii, you can
use those values instead of calculating them at run time. OEB files can
store radii and partial charges, so they serve as a useful intermediate file
between many OpenEye programs. Note that charges and radii will only be
written to an OEB file if they are present on the molecule when written.

Atomic charges can come in a PDB file, along with atomic radii, in the form
of the extra fields added after the coordinates. This style originated with
DelPhi. Note that to get OEChem to read charges and radii from these fields
in a PDB file, you need to set a specific flavor on the input oemolistream
before reading any molecules from the stream.


.. oe:source:: DelPhiFlavor.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-DelPhiFlavor
   :caption:  Example of using OEChem to read charges and radii from PDB

.. oe:source:: DelPhiFlavor.py
   :language: python
   :noindent:
   :frag:     SNIPPET-DelPhiFlavor
   :caption:  Example of using OEChem to read charges and radii from PDB

.. oe:language:: python

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


.. oe:source:: DelPhiFlavor.java
   :language: java
   :noindent:
   :frag:     SNIPPET-DelPhiFlavor
   :caption:  Example of using OEChem to read charges and radii from PDB

.. oe:source:: DelPhiFlavor.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-DelPhiFlavor
   :caption:  Example of using OEChem to read charges and radii from PDB

.. _section_getagrid:

Grids
============================================================================

ZAP uses regular cubic lattices, or grids, to solve the PB
equation. The examples here illustrate how to retrieve such from the
calculation and to manipulate and store the information held by
each. Typically, grids are not used per se but information is
extracted, such as the potential at particular points in space, as is
illustrated in the next section. However, some programs, such as VIDA,
can read grids and display their properties.  Also, having direct
access to grids allows for manipulations of the potential map that may
not have been anticipated.

This first example shows the simplest method of generating a grid of
potentials using ZAP. We save the grid in OpenEye GRD (\*.grd) format
which is a compact, binary format that can be visualized in
VIDA. Alternatively, the grid can be written into GRASP format
(\*.phi), which means that the grid stored will be 65 cubed
regardless of the size of the grid used in the calculation. A
:math:`65^3` grid is obtained by interpolation to a grid with that
many points that fits over the largest dimension of the grid
calculated.



.. oe:source:: zap_grid1.cpp
   :language: c++
   :caption:  Calculating a potential grid
   :refnum:   1

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid1.cpp <../../../../sublibs/tklibs/zap/examples/zap_grid1.cpp>`

.. oe:source:: zap_grid1.py
   :language: python
   :caption:  Calculating a potential grid
   :refnum:   1

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid1.py <../../../../wrappers/python/examples/zap/zap_grid1.py>`

.. oe:source:: ZapGrid1.java
   :language: java 
   :caption:  Calculating a potential grid
   :refnum:   1

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapGrid1.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapGrid1.java>`


.. oe:source:: ZapGrid1.cs
   :language: csharp
   :caption:  Calculating a potential grid
   :refnum:   1

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapGrid1.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapGrid1.cs>`

The next example is an elaboration of the previous simple version where we
add in control of the parameters of the calculation. Options are provided to
set the internal and external (solute and solvent) dielectric constants, the
distance between the molecule and the edges of the grid (boundary spacing or
buffer) and the grid spacing. A smaller grid spacing implies a more dense
and accurate grid, but it does come with a larger memory footprint.

.. oe:source:: zap_grid2.cpp
   :language: c++
   :caption:  Calculating potential grid with optional parameters
   :refnum:   2

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid2.cpp <../../../../sublibs/tklibs/zap/examples/zap_grid2.cpp>`

.. oe:source:: zap_grid2.py
   :language: python
   :caption:  Calculating potential grid with optional parameters
   :refnum:   2

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid2.py <../../../../wrappers/python/examples/zap/zap_grid2.py>`

.. oe:source:: ZapGrid2.java
   :language: java 
   :caption:  Calculating potential grid with optional parameters
   :refnum:   2

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapGrid2.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapGrid2.java>`

.. oe:source:: ZapGrid2.cs
   :language: csharp
   :caption:  Calculating potential grid with optional parameters
   :refnum:   2

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapGrid2.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapGrid2.cs>`

Here we show how to calculate a difference-map, that is to say the potential
difference between a standard, two dielectric, calculation and a single
dielectric calculation (approximating pure Coulombic potentials). These
difference potentials represent the electrostatic response of the solvent to
the charges within the solute molecule. If we mask away everything outside
the molecule, we can see the contributions from the charges inside the
molecule.

.. _calculating_grid_with_params_3:

.. oe:source:: zap_grid3.cpp
   :language: c++
   :caption:  Calculating potential grid with optional parameters
   :refnum:   3

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid3.cpp <../../../../sublibs/tklibs/zap/examples/zap_grid3.cpp>`

.. oe:source:: zap_grid3.py
   :language: python
   :caption:  Calculating potential grid with optional parameters
   :refnum:   3

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid3.py <../../../../wrappers/python/examples/zap/zap_grid3.py>`

.. oe:source:: ZapGrid3.java
   :language: java 
   :caption:  Calculating potential grid with optional parameters
   :refnum:   3

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid3.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapGrid3.java>`

.. oe:source:: ZapGrid3.cs
   :language: csharp
   :caption:  Calculating potential grid with optional parameters
   :refnum:   3

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_grid3.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapGrid3.cs>`

.. _section-atom-potentials:

Atom Potentials
================================================================================

The potentials at any charge, as calculated by PB, can be decomposed into
three forms


#. Induced solvent potential: the potential produced by the polarization
   of the solvent.
#. Inter-charge Coulombic energy: the potential that would be produced
   if the solvent had the same dielectric as the solute molecule from
   all other charges.
#. Self potential: the potential produced by a charge at itself. Of
   course, as mentioned above, this is infinite analytically, but PB
   will produce an "approximation" to this infinity because the grid
   spacing is finite.

This example program shows how to calculate each of these quantities. In
addition to command line flags to control dielectric, grid spacing, etc.,
there are three flags that affect the type of potentials calculated:

*  -calc_type solvent_only
*  -calc_type remove_self
*  -calc_type coulombic

With  none  of these flags, the code executes a single PB calculation,
interpolates the potentials from the grid produced, reports the sum of these
potentials multiplied by the charge on the respective atoms and outputs
these potentials and charges in a table. This potential corresponds to
(a)+(b)+(b) above.

Using the -calc_type solvent_only option executes two PB calculations, the
standard calculation plus a second calculation where the external dielectric
has been set to the solute dielectric. The atom potentials are then formed
from  the difference of these two calculations such that the remaining
potential is that produced by the solvent alone. The sum of this set of
atomic potentials multiplied by atomic charges all multiplied by 0.5 is the
electrostatic component of transferring from a media of the same dielectric
as the solute to water. These potentials correspond to (a) above.

The -calc_type remove_self flag for the example program below executes an
internal algorithm in the ZAP toolkit that extracts from each atom potential
that potential produced by that atom, if it is charged. This it removes the
artifactual energy from the grid, i.e. energy that is not actually physical
but  a  manifestation  of the finite resolution of the grids used. The
remaining potential is then that from the solvent and that from all the
other charges, that is (a)+(b) above.

The -calc_type coulombic flag actually prevents any PB calculation. It
merely uses Coulomb's Law to calculate the potential (b), the inner-atomic
Coulombic potential.

.. oe:source:: zap_atompot.cpp
   :language: c++
   :caption:  Calculating atom potentials
   :refnum:   4

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_atompot.cpp <../../../../sublibs/tklibs/zap/examples/zap_atompot.cpp>`

.. oe:source:: zap_atompot.py
   :language: python
   :caption:  Calculating atom potentials
   :refnum:   4


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_atompot.py <../../../../wrappers/python/examples/zap/zap_atompot.py>`


.. oe:source:: ZapAtoms1.java
   :language: java 
   :caption:  Calculating atom potentials
   :refnum:   4

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapAtoms1.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapAtoms1.java>`


.. oe:source:: ZapAtoms1.cs
   :language: csharp
   :caption:  Calculating atom potentials
   :refnum:   4

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapAtoms1.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapAtoms1.cs>`

.. _section_solvation-energies:

Solvation Energies: PBSA
================================================================================

A principle use of PB is to calculate the energy stored in the exterior
dielectric,  for  example the partial alignment of water dipoles. This
corresponds to the difference between a calculation with uniform dielectric
and one with a different external dielectric. In the examples for atom
potentials this would be the sum of the solvent potentials at each atom,
multiplied by the charges on that atom all multiplied by 0.5.

However, we know water also has an energy component due to hydrophobicity,
which is typically estimated as a constant (approximately 10-25 calories per
square Angstrom) multiplied by the accessible area of the molecule. This
value is an open scientific question. We recommend using 10 for vacuum-water
transfer energies and 25 for protein calculations, but ultimately your own
scientific  judgment  should  be used. These examples include an area
calculation.  Taken together these numbers are an approximation of the
transfer  energy from a low dielectric medium (alkane solvent, protein
interior) into water.

The following examples use the OEArea object to calculate the accessible
surface area of the molecule. The area is calculated using the same grid
based Gaussians that ZAP uses. Therefore, it will not give the same results
as triangle summation methods for calculating surface area, which are used
in OESpicoli.

.. oe:source:: zap_solv1.cpp
   :language: c++
   :caption:  Calculating solvation energies
   :refnum:   5

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_solv1.cpp <../../../../sublibs/tklibs/zap/examples/zap_solv1.cpp>`


.. oe:source:: zap_solv1.py
   :language: python
   :caption:  Calculating solvation energies
   :refnum:   5

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_solv1.py <../../../../wrappers/python/examples/zap/zap_solv1.py>`


.. oe:source:: ZapSolv1.java
   :language: java 
   :caption:  Calculating solvation energies
   :refnum:   5

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapSolv1.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapSolv1.java>`


.. oe:source:: ZapSolv1.cs
   :language: csharp
   :caption:  Calculating solvation energies
   :refnum:   5

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapSolv1.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapSolv1.cs>`


This next solvation example calculates the transfer energy from vacuum to
water.

.. oe:source:: transfer.cpp
   :language: c++
   :caption:  Calculating vacuum-water transfer energies
   :refnum:   6

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`transfer.cpp <../../../../sublibs/tklibs/zap/examples/transfer.cpp>`


.. oe:source:: transfer.py
   :language: python
   :caption:  Calculating vacuum-water transfer energies
   :refnum:   6

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`transfer.py <../../../../wrappers/python/examples/zap/transfer.py>`


.. oe:source:: ZapTransfer.java
   :language: java
   :caption:  Calculating vacuum-water transfer energies
   :refnum:   6

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapTransfer.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapTransfer.java>`


.. oe:source:: ZapTransfer.cs
   :language: csharp
   :caption:  Calculating vacuum-water transfer energies
   :refnum:   6

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapTransfer.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapTransfer.cs>`


.. _section_bindingenergies:

Binding Energies
================================================================================

Binding energies and other binding related properties can be
calculated using the :ref:`OEBind <OEPB_OEBind>` class. The OEBind
class serves two primary purposes: 1) to have a class in place for
users to easily calculate binding related data, and 2) to show how
binding related data may be calculated. OEBind is not particularly
well-suited for extremely efficient calculations required by
simulations. This is because some of the data available from OEBind
may be considered uninteresting for the project and there is no need
to spend time calculating it, or because OEBind calculates the unbound
protein and ligand properties every time, which is unnecessary if the
same protein and ligand appear in multiple calculations. The API
section for OEBind is detailed with regard to implementation, so the
user can see how to create their own class or set of function calls if
needed.

There are two classes that store the results of a binding calculation,
:ref:`OEBindResults <OEPB_OEBindResults>` and :ref:`OESimpleBindResults <OEPB_OESimpleBindResults>`. OEBindResults is a superset of
OESimpleBindResults. For an in-depth understanding of what is
calculated, the electrostatics portion of the algorithm for the
SimpleBind function is shown in the API section.

The following is a sample program for using the OEBind class that is
provided in the distribution.

.. oe:source:: bind.cpp
   :language: c++
   :caption:  Bind example
   :refnum:   7

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`bind.cpp <../../../../sublibs/tklibs/zap/examples/bind.cpp>`


.. oe:source:: bind.py
   :language: python
   :caption:  Bind example
   :refnum:   7

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`bind.py <../../../../wrappers/python/examples/zap/bind.py>`


.. oe:source:: ZapBind.java
   :language: java
   :caption:  Bind example
   :refnum:   7

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapBind.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapBind.java>`


.. oe:source:: ZapBind.cs
   :language: csharp
   :caption:  Bind example
   :refnum:   7

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapBind.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapBind.java>`


.. _section_focusing:

Focusing
================================================================================
Focusing is a way to achieve the desired precision around a target (such as
a  ligand) while maintaining reasonable time and memory limits for the
calculation. The target for focusing is set using the :oe:meth:`OEPB::OEZap::SetFocusTarget`
method.

For a typical ZAP electrostatics calculation, a consistent grid spacing is
used for the entire system, where the default value is 0.5 Angstroms but it
may be set to a custom value using :oe:meth:`OEPB::OEZap::SetGridSpacing`. This method is entirely
appropriate for certain calculations, such as solvation energy calculations
for small molecules. For other types of calculations, such as a binding
energy calculation for a protein and ligand, a consistent grid spacing may
cause the calculation to be either prohibitively expensive or insufficiently
precise around the binding area.

Focusing  alleviates this problem by using a fine grid for the target
volume, and coarser grids away from the target. The grid spacing setting for
ZAP is applied to the target volume, and the grid spacing is doubled for
each addition coarse grid surrounding the target. A quadratic interpolation
is used for the grid intersections. The implementation of the bind uses the
SetFocusTarget() method to set the ligand as the target for focusing.

The following example program computes the binding energy of a protein and
ligand  twice,  once without focusing and once with the ligand as the
focusing target. The values of the binding energy and the time it took to
calculate them are displayed. For a focused atom potential calculation, the
full electrostatics for the protein and complex would each be computed with
multiple electrostatics calculations. The first calculation would create the
potential grid for the target volume with a grid spacing of 0.5 (assuming
the default spacing is being used). An additional calculation with a grid
spacing of 1.0 would be done on a larger volume volume, and then additional
calculations with grid spacings of 2.0, 4.0, and so on would be done until
the grid is large enough to contain the entire volume of the system.

.. oe:source:: zap_focussing.cpp
   :language: c++
   :caption:  Focusing example
   :refnum:   8

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_focussing.cpp <../../../../sublibs/tklibs/zap/examples/zap_focussing.cpp>`


.. oe:source:: zap_focussing.py
   :language: python
   :caption:  Focusing example
   :refnum:   8

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_focussing.py <../../../../wrappers/python/examples/zap/zap_focussing.py>`


.. oe:source:: ZapFocussing.java
   :language: java
   :caption:  Focusing example
   :refnum:   8

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapFocussing.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapFocussing.java>`


.. oe:source:: ZapFocussing.cs
   :language: csharp
   :caption:  Focusing example
   :refnum:   8


.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapFocussing.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapFocussing.cs>`


.. _section-zap-gradients-forces:

Gradients/Forces
================================================================================
The solvent forces acting on the atoms in a molecule may be calculated using
the :oe:meth:`OEPB::OEZap::CalcForces` method. The components of the forces are set to a float array
of length 3N, where N is the number of atoms. The components of the gradient
are equal in magnitude to the force, but have the opposite sign.

.. oe:source:: zap_forces.cpp
   :language: c++
   :caption:  Calculating solvation forces
   :refnum:   9

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_forces.cpp <../../../../sublibs/tklibs/zap/examples/zap_forces.cpp>`


.. oe:source:: zap_forces.py
   :language: python
   :caption:  Calculating solvation forces
   :refnum:   9

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`zap_forces.py <../../../../wrappers/python/examples/zap/zap_forces.py>`


.. oe:source:: ZapForces.java
   :language: java
   :caption:  Calculating solvation forces
   :refnum:   9

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapForces.java <../../../../wrappers/java/examples/openeye/examples/oezap/ZapForces.java>`


.. oe:source:: ZapForces.cs
   :language: csharp
   :caption:  Calculating solvation forces
   :refnum:   9

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ZapForces.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/ZapForces.cs>`


.. _section-electrostatic-similarity:

Electrostatic Similarity
================================================================================

Electrostatic  similarity  may be calculated using the :ref:`OEET <OEPB_OEET>` class. The
following example program shows how to obtain the electrostatic Tanimoto
between  a  reference molecule and a trial molecule. The electrostatic
Tanimoto is affected by the partial charges of the molecules as well as
the three-dimensional structure, including the tautomer state, spacial
orientation, and conformation. In the example program shown below, MMFF
charges are assigned to the molecules, but it is assumed that they have
already been spatially aligned.

.. oe:source:: calc_et.cpp
   :language: c++
   :caption:  Calculating electrostatic tanimoto
   :refnum:   10

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`calc_et.cpp <../../../../sublibs/tklibs/zap/examples/calc_et.cpp>`


.. oe:source:: calc_et.py
   :language: python
   :caption:  Calculating electrostatic tanimoto
   :refnum:   10

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`calc_et.py <../../../../wrappers/python/examples/zap/calc_et.py>`


.. oe:source:: CalcET.java
   :language: java
   :caption:  Calculating electrostatic tanimoto
   :refnum:   10

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`CalcET.java <../../../../wrappers/java/examples/openeye/examples/oezap/CalcET.java>`


.. oe:source:: CalcET.cs
   :language: csharp
   :caption:  Calculating electrostatic tanimoto
   :refnum:   10


.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`CalcET.cs <../../../../wrappers/csharp/Csharp-Examples/OEZap/CalcET.cs>`

