%
% $Id$
%
\label{sec:driver}

The DRIVER module is one of two drivers (see Section \ref{sec:stepper}
for documentation on STEPPER) to perform a geometry optimization
function on the molecule defined by input using the \verb+GEOMETRY+
directive (see Section \ref{sec:geom}).  Geometry optimization is
either an energy minimization or a transition state optimization.
The algorithm programmed in DRIVER is a quasi-newton optimization
with line searches and approximate energy Hessian updates.

DRIVER is selected by default out of the two available modules to
perform geometry optimization.  In order to force use of DRIVER (e.g.,
because a previous optimization used STEPPER) provide a DRIVER input
block (below) --- even an empty block will force use of DRIVER.

Optional input for this module is specified within the compound
directive,
\begin{verbatim}
  DRIVER 
    (LOOSE || DEFAULT || TIGHT)
    GMAX <real value>
    GRMS <real value>
    XMAX <real value>
    XRMS <real value>

    EPREC <real eprec default 1e-7>

    TRUST <real trust default 0.3>
    SADSTP <real sadstp default 0.1>

    CLEAR
    REDOAUTOZ

    INHESS <integer inhess default 0>

    (MODDIR || VARDIR) <integer dir default 0>
    (FIRSTNEG || NOFIRSTNEG)

    MAXITER <integer maxiter default 20>

    BSCALE <real BSCALE default 1.0>
    ASCALE <real ASCALE default 0.25>
    TSCALE <real TSCALE default 0.1>
    HSCALE <real HSCALE default 1.0>
   
    PRINT ...

    XYZ [<string xyz default $file_prefix$>]
    NOXYZ

  END
\end{verbatim}

On each optimization step a line search is performed.
To speed up calculations (up to two times), it may be beneficial
to turn off the line search using following directive:
\begin{verbatim}
set driver:linopt 0
\end{verbatim}

\sloppy

\section{Convergence criteria}

\begin{verbatim}
    (LOOSE || DEFAULT || TIGHT)
    GMAX <real value>
    GRMS <real value>
    XMAX <real value>
    XRMS <real value>
\end{verbatim}

 In version 3.3 Gaussian-style convergence criteria have been adopted.
The defaults may be used, or the directives \verb+LOOSE+,
\verb+DEFAULT+, or \verb+TIGHT+ specified to use standard sets of
values, or the individual criteria adjusted.  All criteria are in
atomic units.
\verb+GMAX+ and \verb+GRMS+ control the maximum and root mean square
gradient in the coordinates being used (Z-matrix, redundant internals,
or Cartesian).  \verb+XMAX+ and \verb+XRMS+ control the maximum and
root mean square of the Cartesian step.

\begin{verbatim}
                  LOOSE    DEFAULT    TIGHT
         GMAX   0.0045d0   0.00045   0.000015   
         GRMS   0.0030d0   0.00030   0.00001
         XMAX   0.0054d0   0.00180   0.00006
         XRMS   0.0036d0   0.00120   0.00004
\end{verbatim}

 Note that GMAX and GRMS used for convergence of geometry may significantly vary in 
different coordinate systems such as Z-matrix, redundant internals, or Cartesian. 
The coordinate system is defined in the input file (default is Z-matrix). 
Therefore the choice of coordinate system may slightly affect converged energy. 
Although in most cases XMAX and XRMS are last to converge which are always done 
in Cartesian coordinates, which insures convergence to the same geometry in 
different coordinate systems.


The old criterion may be recovered with the input
\begin{verbatim}
   gmax 0.0008; grms 1; xrms 1; xmax 1
\end{verbatim}

\section{Available precision}

\begin{verbatim}
    EPREC <real eprec default 1e-7>
\end{verbatim}

In performing a line search the optimizer must know the
precision of the energy (this has nothing to
do with convergence criteria).  The default value
of 1e-7 should be adjusted if less, or more, precision
is available.  Note that the default EPREC for DFT
calculations is 5e-6 instead of 1e-7.

\section{Controlling the step length}

\begin{verbatim}
    TRUST <real trust default 0.3>
    SADSTP <real sadstp default 0.1>
\end{verbatim}

A fixed trust radius (\verb+trust+) is used to control the step during
minimizations, and is also used for modes being minimized during
saddle-point searches.  It defaults to 0.3 for minimizations and 0.1
for saddle-point searches.  The parameter \verb+sadstp+ is the trust
radius used for the mode being maximized during a saddle-point search
and defaults to 0.1.

\section{Maximum number of steps}

\begin{verbatim}
    MAXITER <integer maxiter default 20>
\end{verbatim}

By default at most 20 geometry optimization steps will be taken,
but this may be modified with this directive.

\section{Discard restart information}
\begin{verbatim}
    CLEAR
\end{verbatim}

By default Driver reuses Hessian information from a previous
optimization, and, to facilitate a restart also stores which mode is
being followed for a saddle-point search.  This option deletes all
restart data.

\section{Regenerate internal coordinates}

\begin{verbatim}
    REDOAUTOZ
\end{verbatim}

Deletes Hessian data and regenerates internal coordinates at the
current geometry.  Useful if there has been a large change in the
geometry that has rendered the current set of coordinates invalid or
non-optimal.

\section{Initial Hessian}
\begin{verbatim}
    INHESS <integer inhess default 0>
\end{verbatim}

\begin{itemize}
\item  0 = Default ... use restart data if available, otherwise use diagonal guess.
\item  1 = Use diagonal initial guess.
\item  2 = Use restart data if available, otherwise transform
Cartesian Hessian from previous frequency calculation.
\end{itemize}


In addition, the diagonal elements of the initial Hessian for
internal coordinates may be scaled using separate factors for
bonds, angles and torsions with the following
\begin{verbatim}
    BSCALE <real bscale default 1.0>
    ASCALE <real ascale default 0.25>
    TSCALE <real tscale default 0.1>
\end{verbatim}
These values typically give a two-fold speedup over unit values, based
on about 100 test cases up to 15 atoms using 3-21g and 6-31g* SCF.
However, if doing many optimizations on physically similar systems it
may be worth fine tuning these parameters.

Finally, the entire Hessian from any source may be scaled
by a factor using the directive
\begin{verbatim}
    HSCALE <real hscale default 1.0>
\end{verbatim}
It might be of utility, for instance, when computing an initial
Hessian using SCF to start a large MP2 optimization.  The SCF
vibrational modes are expected to be stiffer than the MP2, so scaling
the initial Hessian by a number less than one might be beneficial.


\section{Mode or variable to follow to saddle point}

\begin{verbatim}
    (MODDIR || VARDIR) <integer dir default 0>
    (FIRSTNEG || NOFIRSTNEG)
\end{verbatim}

When searching for a transition state the program, by default,
will take an initial step uphill and then do mode following
using a fuzzy maximum overlap (the lowest eigen-mode with an
overlap with the previous search direction of 0.7 times the
maximum overlap is selected).  Once a negative eigen-value
is found, that mode is followed regardless of overlap.

The initial uphill step is appropriate if the gradient points roughly
in the direction of the saddle point, such as might be the case if a
constrained optimization was performed at the starting geometry.
Alternatively, the initial search direction may be chosen to be along
a specific internal variable (using the directive
\verb+VARDIR+) or along a specific eigen-mode (using \verb+MODDIR+).
Following a variable might be valuable if the initial gradient is
either very small or very large.  Note that the eigen-modes in the
optimizer have next-to-nothing to do with the output from a frequency
calculation.  You can examine the eigen-modes used by the optimizer
with

\begin{verbatim}
         driver; print hvecs; end
\end{verbatim}

The selection of the first negative mode is usually a good choice if
the search is started in the vicinity of the transition state and the
initial search direction is satisfactory.  However, sometimes the
first negative mode might not be the one of interest (e.g., transverse
to the reaction direction).  If \verb+NOFIRSTNEG+ is specified, the
code will not take the first negative direction and will continue doing
mode-following until that mode goes negative.

\section{Optimization history as XYZ files}

\begin{verbatim}
    XYZ [<string xyz default $fileprefix>]
    NOXYZ
\end{verbatim}

The \verb+XYZ+ directive causes the geometry at each step (but not
intermediate points of a line search) to be output into separate files
in the permanent directory in XYZ format.  The optional string will
prefix the filename.  The \verb+NOXYZ+ directive turns this off.

For example, the input
\begin{verbatim}
    driver; xyz test; end
\end{verbatim}
will cause files test-000.xyz, test-001.xyz, \ldots\ to be created
in the permanent directory.  

The script \verb+rasmolmovie+ in the NWChem \verb+contrib+ directory
can be used to turn these into an animated GIF movie.

\section{Print options}

The UNIX command \verb+"egrep '^@' < output"+ will extract a pretty
table summarizing the optimization.

If you specify the NWChem input
\begin{verbatim}
      scf; print none; end
      driver; print low; end
      task scf optimize
\end{verbatim}
you'll obtain a pleasantly terse output.

For more control, these options for the standard print directive are
recognized
\begin{itemize}
\item \verb+debug+   - prints a large amount of data.  Don't use in parallel.
\item \verb+high+    - print the search direction in internals
\item \verb+default+ - prints geometry for each major step (not during
                the line search), gradient in internals (before
                and after application of constraints)
\item \verb+low+     - prints convergence and energy information.  At 
                convergence prints final geometry, change in internals
                from initial geometry
\end{itemize}
and these specific print options
\begin{itemize}
\item      {\tt finish} (low)      - print geometry data at end of calculation
\item      {\tt bonds}  (default)  - print bonds at end of calculation
\item      {\tt angles} (default)  - print angles at end of calculation
\item      {\tt hvecs}  (never)    - print eigen-values/vectors of the Hessian
\item      {\tt searchdir} (high)  - print the search direction in internals
\item      `{\tt internal gradient}' (default) - print the gradient in internals
\item      {\tt sadmode} (default) - print the mode being followed to the saddle point
\end{itemize}

\fussy