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

..  program:: szmap

=================================
Optional Parameters
=================================

Input File Options
-------------------

.. option:: -ligand <filename>
   -l <filename>

   [keyless parameter 2]

   If an OEDesignUnit was used as input for the protein, and it contained a ligand
   the ligand from this will be used unless otherwise specified.

   The format can be one that retains partial charges: OEBinary, Tripos .mol2, or
   DelPhi flavor PDB (where there is radii in the occupancy field and
   charge in the B-factor field).

   .. note::

      If no charges are present on the read molecule, AM1BCC charges and Zap9 radii
      are assigned to the molecule.

.. option:: -warn_if_missing_hydrogens

   If specified, missing hydrogens will not terminate the program,
   but will instead generate a warning message. Otherwise, missing
   hydrogens on the ligand or on more than 10 percent of the protein
   heavy atoms will cause :program:`szmap` to fail.

.. option:: -split_lig

   Separate ligand file into individual molecules and run each individually.

Output File Options
-------------------

.. option:: -prefix <prefix>

   Prefix used to name output files. Using ``-prefix FOO``
   will create results in an OEBinary file named ``FOO.oeb.gz``
   (see :option:`-output_mol`). The table produced with :option:`-at_coords`
   will be written to ``FOO.txt`` (see :option:`-table`).
   Additionally, a parameter file named ``FOO.param`` (see :option:`-param`)
   and a log file named ``FOO.log`` (see :option:`-log`).

   [Default=szmap]

.. option:: -output_mol <filename>
   -o <filename>

   [keyless parameter 3]

   OEBinary output file (*.oeb* or *.oeb.gz*), with calculated
   results attached to a copy of the input :option:`-protein`
   and any :option:`-ligand`.

   If not specified, :option:`-prefix` will be used to name the output.

.. option:: -table <filename>

   A tab-delimited table of results from :option:`-at_coords` calculations
   is written to this file.
   If specified, this will override the filename created from :option:`-prefix`.
   Specify ``-table -`` to send to *standard-output*.

.. option:: -std_box <filename>

   Write *standard* (complex) grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges in formats
   that support bonds.
   Use :option:`-box_mol` to select based on
   this file.

.. option:: -lig_box <filename>

   Write *ligand* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges in formats
   that support bonds.
   Use :option:`-box_mol` to select based on
   this file.

.. option:: -apo_box <filename>

   Write *apo* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges in formats
   that support bonds.
   Use :option:`-box_mol` to select based on
   this file.

Selection Options
-----------------

If the input is an OEDesignUnit, then the following flags
can be used to exclude pieces from the structure before the calculation

.. option:: -excludeDUsolvent

   Excludes structural waters from the input design unit

.. option:: -excludeDUligand

   Excludes the bound ligand from the input design unit

If a :option:`-ligand` is provided but none
of the selection method's options are specified,
points are selected around the ligand when grids
are generated, even for
*apo* grids (see :option:`-distance_cutoff`).

.. option:: -at_coords <filename>
   -coords <filename>

   Perform calculations just at the coordinates
   of atoms in any molecules in the file. Write
   those molecules, with the (masked) results attached
   to the atoms, to the output file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   Text formats such as ``.xyz`` are easily modified in a text editor
   to specify an arbitrary set of coordinates.

   The tags that will be used when assigning values to atoms
   are listed in :ref:`chapter_appendix2`.

   A tab-delimited table of calculation results is printed to
   a text file (see :option:`-table`). In the abbreviated column heading,
   ``n_`` stands for neutral and
   ``v_`` stands for vacuum. A mask value of 0 indicates that the
   *intvdw* value is above :option:`-mask_cutoff` and this row of data
   should not be used.


.. option:: -residue_number <number>
   -res <number>

   Select grid points around the selected residue
   (see :option:`-distance_cutoff`).

.. option:: -residue_chain <letter>
   -chain <letter>

   Protein chain used with :option:`-residue_number`.
   Case sensitive. Underscore ('_') stands for blank.

   [Default='_']

.. option:: -residue_insert <letter>
   -inscode <letter>

   Protein insertion code used with :option:`-residue_number`.
   Case sensitive. Underscore ('_') stands for blank.

   [Default='_']

.. option:: -like_std <filename>

   Select points in the same bounding box as the
   *standard* (complex) grids
   from the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -like_lig <filename>

   Select points in the same bounding box as the *ligand* grids
   from the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -like_apo <filename>

   Select points in the same bounding box as the *apo* grids
   from the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -like_box <filename>

   Select points in the same bounding box as the *box_mol*
   in the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -around_mol <filename>
   -around <filename>

   Select points enclosing the atoms in the specified file
   (using :option:`-distance_cutoff` to define how much extra
   space beyond the atoms is include).

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   Text formats such as ``.xyz`` are easily modified in a text editor
   to adjust the region of interest.

.. option:: -box_mol <filename>

   Select points in bounding box defined by atoms in
   the input 'box molecule' file (without a :option:`-distance_cutoff`).

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   Text formats such as ``.xyz`` are easily modified in a text editor
   to adjust the region of interest.

.. option:: -bounding_box <xmin> <ymin> <zmin> <xmax> <ymax> <zmax>
   -bbox  <xmin> <ymin> <zmin> <xmax> <ymax> <zmax>

   Select points in the bounding box defined by
   minimum and maximum coordinate values.

.. option:: -surface_points
   -surf

   Select grid points over the entire surface of the input
   molecule(s).

   .. warning::
      This usually results in very long run times.

.. option:: -distance_cutoff <number>
   -dcutoff <number>

   Maximum distance from atoms of selected points, a margin
   around the focus region.

   [Default=4.0 |A|]

.. option:: -value_cutoff <number>
   -vcutoff <number>

   Minimum *FRED* surface shape score value for selected points.

   [Default=0.05]

.. option:: -restrict_calc <level>

   Control which points are used for calculations. Restricting
   calculations makes :program:`szmap` run faster but make the that
   portion of the results less useful. In particular,
   restricting *apo* calculations may not be worth the
   speed increase because it prevents you from being
   able to analyze the full *apo* pocket.

   ====== ============================================
   Level  Meaning
   ====== ============================================
   none   Calculate full grids
   ------ --------------------------------------------
   ligand Restrict ligand calc to region from complex
   ------ --------------------------------------------
   apo    Restrict apo calc to region from complex
   ------ --------------------------------------------
   both   Restrict ligand & apo to region from complex
   ====== ============================================

   [Default=ligand]

Grid/Coord Options
------------------

If a grid or coord request option
is not specified, all *apo* results
will be generated, and if a ligand is supplied,
all *std*  (complex) results as well.

.. option:: -results_set <type>
   -properties <type>
   -grids <type>

   Defines which sets of properties are included in grid or coordinate
   results.

   ============= ==========================================================
   Type          Output
   ============= ==========================================================
   min           Only the standard (complex) results; minimal grid output;
   full coord    output
   ------------- ----------------------------------------------------------
   default       Both standard and *apo* results, if possible; minimal
   grid output;  full coord output
   ------------- ----------------------------------------------------------
   max           Both standard and *apo* results, if possible; Full grid
   and coord     output
   ============= ==========================================================

   *min* or *default* used for a grid calculation produces the following properties:

   + *neut_diff_free_energy_grid* (or the corresponding *lig* or *apo* grid)
   + *vdw_grid*
   + *order_grid*
   + *mask_grid*

   See :ref:`chapter_appendix1` for lists of properties.

   [Default=default]

.. option:: -stabilization
   -stbl

   Generate *(complex - (ligand + apo-pocket))* values that show where water is
   stabilized or destabilized upon ligand binding. This requires extra calculations
   with the ligand alone.

.. option:: -mask_cutoff <number>

   Points where the minimum interaction + van der Waals energy
   above this cutoff will be set to 0.0 in the output grids.

   [Default=0.0 kcal/mol]

.. option:: -grid_spacing <number>
   -space <number>

   Distance between grid points. We recommend this value be above 0.25 |A|.
   :program:`szmap` creates a grid by first building a temporary grid around the protein and/or ligand molecules
   that contains values of a function describing the space near the molecular surface.
   This temporary grid has the same grid spacing as the final grid, so
   using a very fine grid spacing can generate enormous temporary grids that fill memory.

   [Default=0.5 |A|]

.. option:: -standard_grids
   -std_grids
   -cplx_grids
   -std_coords

   Generate all *standard* (holo-complex) grids or coords. The actual
   grids or coord data will depend on :option:`-results_set`.

.. option:: -lig_grids
   -lig_coords

   Generate all *ligand* grids or coords. The actual
   grids or coord data will depend on :option:`-results_set`.

   The *std* and/or *apo* grids will still be generated as usual even if
   this option is specified.

.. option:: -apo_grids
   -apo_coords

   Generate all *apo* grids or coords. The actual
   grids or coord data will depend on :option:`-results_set`.

.. option:: -point_grid

   Generate the grid of test points where the calculation is done
   (1 = test, 0 otherwise).
   If a ligand is provided, values are for the protein/ligand complex.

.. option:: -lig_point_grid

   Generate the grid of test points where the calculation is done
   (1 = test, 0 otherwise).
   Values are for the ligand without the protein.

.. option:: -apo_point_grid

   Generate the grid of test points where the calculation is done
   (1 = test, 0 otherwise).
   If a ligand is provided, values are for the protein without
   the ligand.

Calculation Options
-------------------

.. option:: -num_orientations <number>
   -rot <number>

   Number of probe-molecule orientations to sample at each grid point.
   If this number is set to 24, 60, 216, 360, or 648 then the set of rotations
   will be symmetric. Otherwise, they will be random and may have lopsided
   gaps in coverage. For most purposes, 60 is the minimum required for
   reliable energy calculations and 360 generates robust results.

   [Default=60]

.. option:: -dielectric_model <type>
   -model <type>

   Type of surface defining the boundary between
   :option:`-inner_dielectric`
   and :option:`-outer_dielectric`
   values.

   ============== =========================================
   Type           Meaning
   ============== =========================================
   gaussian       Dielectric value changes smoothly over
   a distance of  approximately 2 |A|.
   -------------- -----------------------------------------
   molecular      Dielectric changes abruptly at molecular
   surface
   ============== =========================================

   [Default=gaussian]

.. option:: -inner_dielectric <number>
   -eps_in <number>

   Dielectric value used inside the protein and ligand atom surface
   (see :option:`-dielectric_model`).

   [Default=1.0]

.. option:: -outer_dielectric <number>
   -eps_out <number>

   Dielectric value used outside the protein and ligand atom surface
   (see :option:`-dielectric_model`). This is the dielectric of bulk solvent.

   [Default=80.0]

.. option:: -salt_conc <number>
   -salt <number>

   Salt concentration in Poisson Boltzmann calculation (units: moles/liter).

   [Default=0.05 M]

.. option:: -zap_spacing <number>

   Distance between grid points within the ZAP calculation.
   To avoid excessive memory requirements
   and ensure stability during
   the PB calculation, it is usually best for ZAP spacing
   to be greater than 0.25 |A|.

   [Default=0.5 |A|]

.. option:: -boundary_spacing <number>
   -boundary <number>

   Extra buffer outside the extents of the selection molecule.

   [Default=4.0 |A|]

.. option:: -boundary_radius <number>

   Size of probe for boundary calculation.

   [Default=1.4 |A|]

.. option:: -water_charge <type>

   Which charges are used on the probe water: *scaled* or *am1bcc*.
   *Scaled* means scale AM1BCC charges to match the water dipole.

   [Default=scaled]

.. option:: -vdw_scale <number>

   Scale for van der Waals between probe atoms and other atoms.

   [Default=1.0]

.. option:: -use_apo_from <filename>

   Use the *apo* grids in the *.oeb* results file from
   a previous :program:`szmap` run rather than calculating them.
   This can speed up calculations for a series of ligands
   docked to a single ligand.

   This option is also useful when the *apo* protein and the
   *complex* adopt slightly different states. For example, a
   key amino acid may have an ionized sidechain in the
   *apo* protein and a neutral sidechain in the *complex*.

MPI Options
-------------

These options control how MPI is used. Unless one of these
options is specified, :program:`szmap` will run in single processor mode.

.. option:: -mpi_np <number>

   Run :program:`szmap` calculations in MPI multiprocessor mode using the
   specified number of processors.  If an MPI hostfile is not specified with
   the -mpi_hostfile option all processor will be launched on the local machine.

.. option:: -mpi_hostfile <filename>

   Run :program:`szmap` calculations in MPI multihost mode using the
   specified MPI hostfile.  If an MPI hostfile is not specified all
   processes will be run on the local machine.  The hostfile format
   is a text file with each line specifying a machine and the number
   of processes to launch on it.

   The following example hostfile specified 3 hosts that can run up to
   4, 2 and 5 processes respectively.

   ::

      host1.mydomain.com slots=4
      host2.mydomain.com slots=2
      host3.mydomain.com slots=5

   This example hostfile would typically be used with -mpi_np 11 to make
   use of all the processors (4+2+5=11).

   Note that multiprocessor is only supported on the local machine under
   Windows, and in homogeneous environments for other architectures (i.e.,
   machines with the same operating system environment).


Other Options
---------------

.. option:: -param <filename>

   Defines the control parameter file. This file can contain a collection
   of parameters which can be used instead of writing each parameter to the command-line.
   In addition, the parameter file written by any :program:`szmap` run (see :option:`-prefix`)
   can be used with the :option:`-param` flag in subsequent :program:`szmap` runs. Any
   command given explicitly on the command line will supersede any command found
   in a file specified with the :option:`-param` flag.

.. option:: -logfile <filename>
   -log <filename>

   If specified, this will override the filename created from :option:`-prefix`.
   Specify "-log - " (dash) to send to *standard-output*.

.. option:: -progress <style>

   How to display progress information:

   ======= =========================================
   Style   Output
   ======= =========================================
   none    no progress shown
   ------- -----------------------------------------
   dots    print a period (.) for every point tested
   ------- -----------------------------------------
   percent print percentage complete every 10 points
   ------- -----------------------------------------
   log     print percentage to log file
   ======= =========================================

   [Default=percent]

.. option:: -verbose
   -v

   Print additional information to log during calculations.
