Blurb::
Define how Dakota should run a function evaluation

Description:: 
The \c analysis_drivers keyword provides the names of one or more
executable analysis programs or scripts, a.k.a. "drivers" which
comprise a function evaluation. The optional and required sub-keywords
specify how Dakota will manage directories and files, and run the
driver(s).

<b> Types of Interfaces </b>

Dakota has two recommended ways of running analysis drivers: 
\li as an external processes (\c fork), or 
\li using internal code to couple to the analysis driver (\c direct)

Other options are available for advanced users, and are not as well documented, supported, or tested:
\li external processes (\c system)
\li internal coupling (\c python, \c matlab, \c scilab, \c grid)

<b> Use Cases </b>

The internally coupled codes have few options because many of the
details are already handled with the coupling.  Their behavior is
described in the \ref interface-analysis_drivers-direct keyword.

For external processes using the \ref interface-analysis_drivers-fork keyword, 

A function evaluation may comprise:
-# <i>A single analysis driver</i>: Function evaluation, including all pre- and 
   post-processing is contained entirely within a single script/executable. <br>
-# <i>A single analysis driver with filters</i>: Function evaluation is 
   explicitly split into pre-processing (performed by the input filter), 
   analysis, and post-processing (by the output filter).
-# <i>A single analysis driver with environment variables</i>: Function 
   evaluation is contained within one analysis driver, but it requires
   environment variables to be set before running.
-# <i>Multiple analysis drivers</i>: Drivers are run sequentially or concurrently
   (See the \c asynchronous keyword) and can have any of the above options as
   well.

For fork and system interfaces, the analysis_driver list contains the
names of one or more executable programs or scripts taking parameters
files as input and producing results files as output.  The first field
in each analysis driver string must be an executable program or script
for Dakota to spawn to perform the function evaluation.  Drivers
support: 

 - One set of nested quotes, for arguments with spaces 
 
 - Dakota will define special environment variables \c
   DAKOTA_PARAMETERS_FILE and \c DAKOTA_RESULTS_FILE which can be used
   in the driver script.
 
 - Dakota will replace the tokens `{PARAMETERS}` and `{RESULTS}` in an 
   anslysis driver string with the names of the parameters and results
   files for that analysis/evaluation. Along with the 
   \ref interface-analysis_drivers-fork-verbatim keyword, which prevents
   Dakota from appending the names of the parameters and reslts files
   as command line arguments, this feature provides users with greater
   control over how their analysis drivers are invoked by Dakota.

 - Variable definitions preceding the executable program or script,
   such as 'MY_VAR=2 run_analysis.sh' are no longer supported.

For details and examples see the Simulation Interface
Components section of the Interfaces chapter of the User's Manual; for
details on the filters and environment variables, see the subsection on
Syntax for Filter and Driver Strings.

Topics::	
Examples::

Examples:
\verbatim
  1. analysis_drivers = 'run_simulation_part1.sh' 'run_simulation_part2.sh'

  2. analysis_driver = 'run_simulation.sh -option "option 1"'

  3. analysis_driver = 'simulation.exe -option value -dakota_params $DAKOTA_PARAMETERS_FILE -input sim.in -dakota_results_file $DAKOTA_RESULTS_FILE'
\endverbatim

Theory::

Faq::

<b>Where will Dakota look for the analysis_driver?</b> Dakota will
locate analysis_driver programs first in (or relative to) the present
working directory (".", the
interface-analysis_drivers-fork-work_directory if used, otherwise the
directory in which Dakota is started), then the directory from which
Dakota is started, then using the system $PATH environment variable
(%Path% on Windows).

<b>Where should the driver be located?</b> When the driver is a script
it is most commonly placed in the same directory as the Dakota input
file.  When using a \ref
interface-analysis_drivers-fork-work_directory, Dakota will also look
for drivers in the specified working directory, so link_files or
copy_files may specify the driver to get copied or linked into the
work directory.  When executable programs are used as drivers, they
are often elsewhere on the filesystem.  These can be specified using
absolute paths, or by prepending the PATH environment variable so
Dakota finds them.

<b>What if Dakota fails to run my analysis_driver?</b> Prepend the
absolute location of the driver to the PATH environment variable
before running Dakota, or specify an absolute path to the driver in
the Dakota input file.

See_Also::	
