.. include:: ../substitutions
.. include:: ../../apps-substitutions

.. _szmap_input_output:

=================================
SZMAP Input and Output
=================================

**SZMAP** takes molecule files as input---usually molecules representing a protein
and a corresponding ligand---and generates an OEBinary file as output.
The molecular input is assumed to have explicit hydrogens and
partial charges. Making sure the input molecules are properly prepared
is *essential* in order to obtain useful results and we recommend using OEDesignUnit
generated with :ref:`chapter_spruce` for this. See the :ref:`szmap_tutorial_intro`
chapter for more information on preparing molecules.

.. note::

   When using OEDesignUnits, note that they potentially include both solvent and
   a bound ligand, depending on the structure. There are two flags that are crucial to keep
   in mind, ``-excludeDUsolvent`` and ``-excludeDUligand``, to control whether those two
   components should be part of the calculation or not.

When **SZMAP** reads input molecules, it checks for missing hydrogens
and missing partial charges and will halt if the protein input does not appear to
be complete; for ligands AM1BCC charges and Zap9 radii are assigned if partial charges are not pre-assigned.
When the ligand(s) are already split out from the protein, :ref:`chapter_molcharge`
may be used to add partial different partial charges to the ligands.
The option :option:`-warn_if_missing_hydrogens` can be used to
prevent halting, but before using it you should analyze the problem to see
if it is due to an error in the input or something else, such as a disagreement with OEChem
as to the proper bond order or charge state for your molecule.
Mistakes in encoding alternate conformation codes can, for example, lead to
very long and very short bonds, with the short ones interpreted as double bonds.
And aromatic or double bonds that are not flat enough can cause OEChem to
interpret them as single bonds.

.. warning::

   If :ref:`chapter_szmap` is given an input *.pdb* file which still contains the
   usual occupancy and B-factor, rather than radii and partial charges,
   any energies it generates will be meaningless.

**SZMAP** output contains
the input molecules along with either one or more computed grids
or with computed values attached to individual atoms. The output file
can be opened in *VIDA* where the results will be displayed in the context of the
input molecules. See the :ref:`szmap_tutorial_intro` and
the chapters describing the :ref:`chapter_watercolor`,
the :ref:`chapter_waterorient` and the :ref:`chapter_colorprops`
for step-by-step information on visualizing the results.

Calculations done at specific coordinates produce a tab-delimited table listing
the results, which can be processed by *Excel* or other programs.

The output file can also be interpreted by the utility programs
:ref:`chapter_szmap_grid`, :ref:`chapter_grid_comp` and :ref:`chapter_szmap_report`.
Although *VIDA* is the best tool for analyzing **SZMAP** results,
:ref:`chapter_szmap_grid` can be used to write out grid data in other formats.
