1Blurb::
2Define how Dakota should run a function evaluation
3
4Description::
5The \c analysis_drivers keyword provides the names of one or more
6executable analysis programs or scripts, a.k.a. "drivers" which
7comprise a function evaluation. The optional and required sub-keywords
8specify how Dakota will manage directories and files, and run the
9driver(s).
10
11<b> Types of Interfaces </b>
12
13Dakota has two recommended ways of running analysis drivers:
14\li as an external processes (\c fork), or
15\li using internal code to couple to the analysis driver (\c direct)
16
17Other options are available for advanced users, and are not as well documented, supported, or tested:
18\li external processes (\c system)
19\li internal coupling (\c python, \c matlab, \c scilab, \c grid)
20
21<b> Use Cases </b>
22
23The internally coupled codes have few options because many of the
24details are already handled with the coupling.  Their behavior is
25described in the \ref interface-analysis_drivers-direct keyword.
26
27For external processes using the \ref interface-analysis_drivers-fork keyword,
28
29A function evaluation may comprise:
30-# <i>A single analysis driver</i>: Function evaluation, including all pre- and
31   post-processing is contained entirely within a single script/executable. <br>
32-# <i>A single analysis driver with filters</i>: Function evaluation is
33   explicitly split into pre-processing (performed by the input filter),
34   analysis, and post-processing (by the output filter).
35-# <i>A single analysis driver with environment variables</i>: Function
36   evaluation is contained within one analysis driver, but it requires
37   environment variables to be set before running.
38-# <i>Multiple analysis drivers</i>: Drivers are run sequentially or concurrently
39   (See the \c asynchronous keyword) and can have any of the above options as
40   well.
41
42For fork and system interfaces, the analysis_driver list contains the
43names of one or more executable programs or scripts taking parameters
44files as input and producing results files as output.  The first field
45in each analysis driver string must be an executable program or script
46for Dakota to spawn to perform the function evaluation.  Drivers
47support:
48
49 - One set of nested quotes, for arguments with spaces
50
51 - Dakota will define special environment variables \c
52   DAKOTA_PARAMETERS_FILE and \c DAKOTA_RESULTS_FILE which can be used
53   in the driver script.
54
55 - Dakota will replace the tokens `{PARAMETERS}` and `{RESULTS}` in an
56   anslysis driver string with the names of the parameters and results
57   files for that analysis/evaluation. Along with the
58   \ref interface-analysis_drivers-fork-verbatim keyword, which prevents
59   Dakota from appending the names of the parameters and reslts files
60   as command line arguments, this feature provides users with greater
61   control over how their analysis drivers are invoked by Dakota.
62
63 - Variable definitions preceding the executable program or script,
64   such as 'MY_VAR=2 run_analysis.sh' are no longer supported.
65
66For details and examples see the Simulation Interface
67Components section of the Interfaces chapter of the User's Manual; for
68details on the filters and environment variables, see the subsection on
69Syntax for Filter and Driver Strings.
70
71Topics::
72Examples::
73
74Examples:
75\verbatim
76  1. analysis_drivers = 'run_simulation_part1.sh' 'run_simulation_part2.sh'
77
78  2. analysis_driver = 'run_simulation.sh -option "option 1"'
79
80  3. analysis_driver = 'simulation.exe -option value -dakota_params $DAKOTA_PARAMETERS_FILE -input sim.in -dakota_results_file $DAKOTA_RESULTS_FILE'
81\endverbatim
82
83Theory::
84
85Faq::
86
87<b>Where will Dakota look for the analysis_driver?</b> Dakota will
88locate analysis_driver programs first in (or relative to) the present
89working directory (".", the
90interface-analysis_drivers-fork-work_directory if used, otherwise the
91directory in which Dakota is started), then the directory from which
92Dakota is started, then using the system $PATH environment variable
93(%Path% on Windows).
94
95<b>Where should the driver be located?</b> When the driver is a script
96it is most commonly placed in the same directory as the Dakota input
97file.  When using a \ref
98interface-analysis_drivers-fork-work_directory, Dakota will also look
99for drivers in the specified working directory, so link_files or
100copy_files may specify the driver to get copied or linked into the
101work directory.  When executable programs are used as drivers, they
102are often elsewhere on the filesystem.  These can be specified using
103absolute paths, or by prepending the PATH environment variable so
104Dakota finds them.
105
106<b>What if Dakota fails to run my analysis_driver?</b> Prepend the
107absolute location of the driver to the PATH environment variable
108before running Dakota, or specify an absolute path to the driver in
109the Dakota input file.
110
111See_Also::
112