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

.. _freeform_opt_params:

.. program:: freeform

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

Basic Options
^^^^^^^^^^^^^^^^^

.. option:: -out <filename>

   Molecular output file name in any format supported by **OEChem**. The default name is
   ``freeform.oeb``. For free energy estimation of the conformations for the input
   molecule, the output file contains all unique solution conformations structures 
   identified by *freeform*. In the case of solvation free energy estimation, the output
   file contains the lowest energy vacuum conformation for which the PB solvation 
   calculation was actually done.

.. option:: -param <filename>

   Command line options will be read from the specified file. This file may have been
   generated from a previous run or may be constructed de novo. The default name of the
   file is ``freeform.param``. Any parameter in the parameter setup file is superseded
   by the parameter on the command line.

.. option:: -prefix <p>

   Replaces ``freeform`` prefix in .log,  .param, .oeb and .pdf output files with the
   input string ``p``.

.. option:: -report <filename>

   Name of the graphical output file. Currently only PDF and PS formats are allowed.
   The default name is ``freeform.pdf``.

.. option:: -track <filename>

   The molecular input of conformers to be tracked is read from the file name;
   any 3D molecule file format supported by OpenEye is acceptable.
   Of critical importance is that the molecule graph be identical to that specified
   in the :option:`-in` input file, and that atom and bond ordering also be identical.
   For the most common uses of *freeform*, the same input file is specified for
   both the :option:`-in` and :option:`-track` options.


Advanced Options
^^^^^^^^^^^^^^^^^

.. option:: -ensemble

   The ensemble of conformations is read from the :option:`-in` input file instead of being generated
   internally. In both cases of :option:`-calc` option, this ensemble is treated as if
   it already contains all the conformations needed.  In conformer free energy estimation,
   when used together with :option:`-track`, the tracked conformations are included with
   the ensemble.

.. option:: -ewindow

   The `-ewindow` flag sets the energy window (in kcal/mol) used as an energy cutoff in
   the initial conformation generation stage of *freeform*.
   An ewindow of at least 15.0 is encouraged to better cover accessible conformational
   space; increasing `-ewindow` will increase the number of conformers.
   [Default=15.0]

.. option:: -ff <type>

   This option specifies which force field to use in the energy minimizations and
   thermodynamics calculations following the initial conformer search. Choices include
   ``mmff94s``, ``mmff94``, ``smirnoff99frosst``, ``parsley_openff``, and ``sage_openff``.
   Default: ``sage_openff``.

   In addition to the above, this command accepts any SMIRNOFF force field parameter file.

.. option:: -ionic <type>

   By default, a charge state used in calculations corresponds to pH = 7.4 (the value of
   parameter ``type`` is set at ``pH74``). Two remaining values are ``uncharged`` and
   ``input``. The former corresponds to an uncharged ionic state (i.e., no formal charges);
   the latter to the preexisting ionic state determined from the molecule input file.

.. option:: -maxconfs <value>

   The `-maxconfs` flag sets the maximum number of conformations to be generated
   using **OMEGA** for the initial conformation generation stage of *freeform*.
   A large set is desirable to cover the
   conformational space necessary to include all reasonable conformers that might
   contribute to the partition function. When this initial set is minimized, a large
   reduction is expected in the number of unique minima.
   [Default=40000]

.. option:: -rms <value>

   RMS threshold for conformation generation using **OMEGA**. The default value is
   ``calculationDependent`` meaning that the RMS threshold used depends on whether
   "-calc conf" or "-calc solv" is being run. 0.3 |A| is used with
   "-calc conf" and 0.6 |A| with "-calc solv".
   Values ranging from 0 to 5 are accepted.

.. option:: -solvent <type>

   By default, Sheffield solvation is used with dielectric 80.0 to account for aqueous
   solvation of the unbound ensemble; this can be specifically requested by setting
   the parameter ``type`` to ``sheffield``. 
   Setting ``type`` to ``PB`` will result in Poisson-Boltzmann (PB)
   single-point solvation energies being calculated at the Sheffield-based minima.
   The default solvent dielectric for the PB calculation is 80.0, but this can be
   changed with the :option:`-PBsolvent_dielectric` option.
   Setting ``type`` to ``vacuum`` means that no solvation energy will be calculated.

.. option:: -PBsolvent_dielectric <value>

   This option allows the user to change the solvent dielectric used in the PB
   single-point solvation energies requested with :option:`-solvent` ``PB``.
   The default value is 80.0 to approximate aqueous solvation; it can adopt any
   value between 1.0 and 80.0 .

.. option:: -solvcharges <type>

   Selects the type of partial charges to be used for the solvent forces.
   By default, the value of ``type`` is ``calculationDependent``, meaning that the charge type
   used depends on whether "-calc conf" or "-calc solv" is being run. AM1BCC charges that are 
   AM1-optimized (Opt) (constrained to starting geometry) and symmetric by 2D-bond symmetry 
   (Sym) are used for conformer free energy estimation and nonsymmetric (NoSym) AM1-single-point
   (SPt) for solvation free energy calculations. For net-charged species however, MMFF94 charges are
   used for the conformer free energy estimation, even if the flag value selected is different
   than ``mmff94``. The defaults are different because the science behind the solvation free 
   energy calculation [Nicholls-2010]_ was specifically developed using the "NoSymSPt"
   variant of AM1BCC charges, whereas the conformer free energies require the robustness of the
   canonical AM1BCC charging scheme (symmetric charges from a constrained AM1 optimization) 
   towards large changes in conformation over the course of geometry optimization.
   In addition to the default ``calculationDependent``, the other possible values
   of the parameter ``type`` are ``am1bccSymOpt``,
   ``am1bccNoSymOpt``, ``am1bccSymSPt``, ``am1bccNoSymSPt``, ``mmff94``, and ``input``.
   The first four refer to different variants of the AM1BCC charging scheme; the next applies
   MMFF94 charges and the last is used to specify user-defined charges (which are read in from the 
   input structure). If ``input`` is selected, then the value of "-ionic" is automatically
   set to ``input``.
