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