SAND2014-5015

Unlimited Release
July 2014
Updated November 6, 2015

Dakota, A Multilevel Parallel Object-Oriented Framework for

Design Optimization, Parameter Estimation, Uncertainty
Quantification, and Sensitivity Analysis:
Version 6.3 Reference Manual
Brian M. Adams, Mohamed S. Ebeida, Michael S. Eldred, John D. Jakeman,
Laura P. Swiler, J. Adam Stephens, Dena M. Vigil, Timothy M. Wildey
Optimization and Uncertainty Quantification Department
William J. Bohnhoff
Radiation Transport Department
Keith R. Dalbey
Mission Analysis and Simulation Department
John P. Eddy
System Readiness and Sustainment Technologies Department
Russell W. Hooper
Multiphysics Applications Department
Kenneth T. Hu
Validation and Uncertainty Quantification Department
Lara E. Bauman, Patricia D. Hough
Quantitative Modeling and Analysis Department
Sandia National Laboratories
P.O. Box 5800
Albuquerque, New Mexico 87185
Ahmad Rushdi
Institute for Computational and Engineering Sciences
The University of Texas at Austin
P.O. Box 4.102
Austin, TX 78712

Abstract
The Dakota (Design Analysis Kit for Optimization and Terascale Applications) toolkit provides a flexible
and extensible interface between simulation codes and iterative analysis methods. Dakota contains algorithms
for optimization with gradient and nongradient-based methods; uncertainty quantification with sampling, reliability, and stochastic expansion methods; parameter estimation with nonlinear least squares methods; and sensitivity/variance analysis with design of experiments and parameter study methods. These capabilities may be used
on their own or as components within advanced strategies such as surrogate-based optimization, mixed integer
nonlinear programming, or optimization under uncertainty. By employing object-oriented design to implement
abstractions of the key components required for iterative systems analyses, the Dakota toolkit provides a flexible
and extensible problem-solving environment for design and performance analysis of computational models on
high performance computers.
This report serves as a reference manual for the commands specification for the Dakota software, providing
input overviews, option descriptions, and example specifications.

Contents
1

Main Page
1.1 How to Use this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Running Dakota
2.1 Usage . . . . . . . . . . .
2.2 Examples . . . . . . . . .
2.3 Execution Phases . . . . .
2.4 Restarting Dakota Studies .
2.5 The Dakota Restart Utility

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

7
7
9
9
10
10
11
12

Test Problems
17
3.1 Textbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Rosenbrock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Dakota Input Specification

4.1 Dakota NIDR . . . . .
4.2 Input Spec Overview .
4.3 Sample Input Files . .
4.4 Input Spec Summary .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

21
21
21
23
27

Topics Area
5.1 admin . . . . .
5.2 dakota IO . . .
5.3 dakota concepts
5.4 models . . . . .
5.5 variables . . . .
5.6 responses . . .
5.7 interface . . . .
5.8 methods . . . .
5.9 advanced topics
5.10 packages . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

75
75
76
87
110
114
120
121
124
141
145

Keywords Area
6.1 environment
6.2 method . .
6.3 model . . .
6.4 variables . .
6.5 interface . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

157
158
190
1819
1964
2112

.
.
.
.
.

.
.
.
.
.

CONTENTS
6.6

responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165

Bibliographic References

2256

Chapter 1

Main Page
The Dakota (Design Analysis Kit for Optimization and Terascale Applications) toolkit provides a flexible, extensible interface between analysis codes and iteration methods.
Author
Brian M. Adams, Lara E. Bauman, William J. Bohnhoff, Keith R. Dalbey, John P. Eddy, Mohamed S. Ebeida,
Michael S. Eldred, Russell W. Hooper, Patricia D. Hough, Kenneth T. Hu, John D. Jakeman, Ahmad Rushdi,
Laura P. Swiler, J. Adam Stephens, Dena M. Vigil, Timothy M. Wildey
The Reference Manual documents all the input keywords that can appear in a Dakota input file to configure a
Dakota study. Its organization closely mirrors the structure of dakota.input.summary. For more information see Dakota Input Specification. For information on software structure, refer to the Developers Manual [3],
and for a tour of Dakota features and capabilities, including a tutorial, refer to the Users Manual (Adams et al.,
2010) [4].

1.1

How to Use this Manual

To learn how to run Dakota from the command line, see Running Dakota
To learn to how to restart Dakota studies, see Restarting Dakota Studies
To learn about the Dakota restart utility, see The Dakota Restart Utility
To find more information about a specific keyword
1. Use the search box at the top right (currently only finds keyword names)
2. Browse the Keywords tree on the left navigation pane
3. Look at the Dakota Input Specification
4. Navigate through the keyword pages, starting from the Keywords Area
To find more information about a Dakota related topic
1. Browse the Topics Area on the left navigation pane
2. Navigate through the topics pages, starting from the Topics Area
A small number of examples are included (see Sample Input Files) along with a description of the test problems (see Test Problems).
A bibliography for the Reference Manual is provided in Bibliographic References
7

CHAPTER 1. MAIN PAGE

Chapter 2

Running Dakota
The Dakota executable file is named dakota (dakota.exe on Windows) and is most commonly run from a
terminal or command prompt.

2.1

Usage

If the dakota command is entered at the command prompt without any arguments, a usage message similar to
the following appears:
usage: dakota [options and <args>]
-help (Print this summary)
-version (Print Dakota version number)
-input <$val> (REQUIRED Dakota input file $val)
-output <$val> (Redirect Dakota standard output to file $val)
-error <$val> (Redirect Dakota standard error to file $val)
-parser <$val> (Parsing technology: nidr[strict][:dumpfile])
-no_input_echo (Do not echo Dakota input file)
-check (Perform input checks)
-pre_run [$val] (Perform pre-run (variables generation) phase)
-run [$val] (Perform run (model evaluation) phase)
-post_run [$val] (Perform post-run (final results) phase)
-read_restart [$val] (Read an existing Dakota restart file $val)
-stop_restart <$val> (Stop restart file processing at evaluation $val)
-write_restart [$val] (Write a new Dakota restart file $val)

Of these command line options, only input is required, and the -input switch can be omitted if the input
file name is the final item appearing on the command line (see Examples); all other command-line inputs are
optional.
help prints the usage message above.
version prints version information for the executable.
check invokes a dry-run mode in which the input file is processed and checked for errors, but the study is
not performed.
input provides the name of the Dakota input file.
output and error options provide file names for redirection of the Dakota standard output (stdout) and
standard error (stderr), respectively.
9

10

CHAPTER 2. RUNNING DAKOTA

The parser option is for debugging and will not be further described here.
By default, Dakota will echo the input file to the output stream, but no input echo can override this
behavior.
read restart and write restart commands provide the names of restart databases to read from
and write to, respectively.
stop restart command limits the number of function evaluations read from the restart database (the
default is all the evaluations) for those cases in which some evaluations were erroneous or corrupted. Restart
management is an important technique for retaining data from expensive engineering applications.
-pre run, -run, and -post run instruct Dakota to run one or more execution phases, excluding others.
The commands must be followed by filenames as described in Execution Phases.

Command line switches can be abbreviated so long as the abbreviation is unique, so the following are valid,
unambiguous specifications: -h, -v, -c, -i, -o, -e, -s, -w, -re, -pr, -ru, and -po and can be used in place
of the longer forms of the command line options.
For information on restarting Dakota, see Restarting Dakota Studies and The Dakota Restart Utility.

2.2

Examples

To run Dakota with a particular input file, the following syntax can be used:
dakota -i dakota.in

or more simply
dakota dakota.in

This will echo the standard output (stdout) and standard error (stderr) messages to the terminal. To redirect
stdout and stderr to separate files, the -o and -e command line options may be used:
dakota -i dakota.in -o dakota.out -e dakota.err

or
dakota -o dakota.out -e dakota.err dakota.in

Alternatively, any of a variety of Unix redirection variants can be used. Refer to[7] for more information on
Unix redirection. The simplest of these redirects stdout to another file:
dakota dakota.in > dakota.out

2.3

Execution Phases

Dakota has three execution phases: pre-run, run, and post-run.

pre-run can be used to generate variable sets
run (core run) invokes the simulation to evaluate variables, producing responses
post-run accepts variable/response sets and analyzes the results (for example, calculate correlations
from a set of samples). Currently only two modes are supported and only for sampling, parameter study,
and DACE methods:
(1) pre-run only with optional tabular output of variables:
dakota -i dakota.in -pre_run [::myvariables.dat]

(2) post-run only with required tabular input of variables/responses:

dakota -i dakota.in -post_run myvarsresponses.dat::

2.4. RESTARTING DAKOTA STUDIES

2.4

11

Restarting Dakota Studies

Dakota is often used to solve problems that require repeatedly running computationally expensive simulation
codes. In some cases you may want to repeat an optimization study, but with a tighter final convergence tolerance.
This would be costly if the entire optimization analysis had to be repeated. Interruptions imposed by computer usage policies, power outages, and system failures could also result in costly delays. However, Dakota automatically
records the variable and response data from all function evaluations so that new executions of Dakota can pick up
where previous executions left off. The Dakota restart file (dakota.rst by default) archives the tabulated interface evaluations in a binary format. The primary restart commands at the command line are -read restart,
-write restart, and -stop restart.

2.4.1

Writing Restart Files

To write a restart file using a particular name, the -write restart command line input (may be abbreviated
as -w) is used:
dakota -i dakota.in -write_restart my_restart_file

If no -write restart specification is used, then Dakota will still write a restart file, but using the default
name dakota.rst instead of a user-specified name.
To turn restart recording off, the user may use the restart file keyword, in the interface block. This can
increase execution speed and reduce disk storage requirements, but at the expense of a loss in the ability to recover
and continue a run that terminates prematurely. This option is not recommended when function evaluations are
costly or prone to failure. Please note that using the deactivate restart file specification will result in a
zero length restart file with the default name dakota.rst, which can overwrite an exiting file.

2.4.2

Using Restart Files

To restart Dakota from a restart file, the -read restart command line input (may be abbreviated as -r) is
used:
dakota -i dakota.in -read_restart my_restart_file

If no -read restart specification is used, then Dakota will not read restart information from any file (i.e.,
the default is no restart processing).
To read in only a portion of a restart file, the -stop restart control (may be abbreviated as -s) is used to
specify the number of entries to be read from the database. Note that this integer value corresponds to the restart
record processing counter (as can be seen when using the print utility (see The Dakota Restart Utility) which
may differ from the evaluation numbers used in the previous run if, for example, any duplicates were detected
(since these duplicates are not recorded in the restart file). In the case of a -stop restart specification, it is
usually desirable to specify a new restart file using -write restart so as to remove the records of erroneous
or corrupted function evaluations. For example, to read in the first 50 evaluations from dakota.rst:
dakota -i dakota.in -r dakota.rst -s 50 -w dakota_new.rst

The dakota new.rst file will contain the 50 processed evaluations from dakota.rst as well as any
new evaluations. All evaluations following the 50th in dakota.rst have been removed from the latest restart
record.

2.4.3

Appending to a Restart File

If the -write restart and -read restart specifications identify the same file (including the case where
-write restart is not specified and -read restart identifies dakota.rst), then new evaluations will
be appended to the existing restart file.

12

CHAPTER 2. RUNNING DAKOTA

2.4.4

Working with multiple Restart Files

If the -write restart and -read restart specifications identify different files, then the evaluations read
from the file identified by -read restart are first written to the -write restart file. Any new evaluations are then appended to the -write restart file. In this way, restart operations can be chained together
indefinitely with the assurance that all of the relevant evaluations are present in the latest restart file.

2.4.5

How it Works

Dakotas restart algorithm relies on its duplicate detection capabilities. Processing a restart file populates the list of
function evaluations that have been performed. Then, when the study is restarted, it is started from the beginning
(not a warm start) and many of the function evaluations requested by the iterator are intercepted by the duplicate
detection code. This approach has the primary advantage of restoring the complete state of the iteration (including
the ability to correctly detect subsequent duplicates) for all methods/iterators without the need for iterator-specific
restart code. However, the possibility exists for numerical round-off error to cause a divergence between the
evaluations performed in the previous and restarted studies. This has been rare in practice.

2.5

The Dakota Restart Utility

The Dakota restart utility program provides a variety of facilities for managing restart files from Dakota executions. The executable program name is dakota restart util and it has the following options, as shown by
the usage message returned when executing the utility without any options:

Usage:
dakota_restart_util command <arg1> [<arg2> <arg3> ...] --options
dakota_restart_util print <restart_file>
dakota_restart_util to_neutral <restart_file> <neutral_file>
dakota_restart_util from_neutral <neutral_file> <restart_file>
dakota_restart_util to_tabular <restart_file> <text_file> [--custom_annotated [header] [eval_id] [interface_i
dakota_restart_util remove <double> <old_restart_file> <new_restart_file>
dakota_restart_util remove_ids <int_1> ... <int_n> <old_restart_file> <new_restart_file>
dakota_restart_util cat <restart_file_1> ... <restart_file_n> <new_restart_file>
options:
--help
show dakota_restart_util help message
--custom_annotated arg tabular file options: header, eval_id, interface_id

Several of these functions involve format conversions. In particular, the binary format used for restart files can
be converted to ASCII text and printed to the screen, converted to and from a neutral file format, or converted to
a tabular format for importing into 3rd-party graphics programs. In addition, a restart file with corrupted data can
be repaired by value or id, and multiple restart files can be combined to create a master database.

2.5.1

Print Command

The print option is useful to show contents of a restart file, since the binary format is not convenient for direct
inspection. The restart data is printed in full precision, so that exact matching of points is possible for restarted
runs or corrupted data removals. For example, the following command
dakota_restart_util print
dakota.rst

results in output similar to the following:

-----------------------------------------Restart record
1 (evaluation id
1):
-----------------------------------------Parameters:
1.8000000000000000e+00 intake_dia

2.5. THE DAKOTA RESTART UTILITY

13

1.0000000000000000e+00 flatness
Active response data:
Active set vector = { 3 3 3 3 }
-2.4355973813420619e+00 obj_fn
-4.7428486677140930e-01 nln_ineq_con_1
-4.5000000000000001e-01 nln_ineq_con_2
1.3971143170299741e-01 nln_ineq_con_3
[ -4.3644298963447897e-01 1.4999999999999999e-01 ] obj_fn gradient
[ 1.3855136437818300e-01 0.0000000000000000e+00 ] nln_ineq_con_1 gradient
[ 0.0000000000000000e+00 1.4999999999999999e-01 ] nln_ineq_con_2 gradient
[ 0.0000000000000000e+00 -1.9485571585149869e-01 ] nln_ineq_con_3 gradient
-----------------------------------------Restart record
2 (evaluation id
2):
-----------------------------------------Parameters:
2.1640000000000001e+00 intake_dia
1.7169994018008317e+00 flatness
Active response data:
Active set vector = { 3 3 3 3 }
-2.4869127192988878e+00 obj_fn
6.9256958799989843e-01 nln_ineq_con_1
-3.4245008972987528e-01 nln_ineq_con_2
8.7142207937157910e-03 nln_ineq_con_3
[ -4.3644298963447897e-01 1.4999999999999999e-01 ] obj_fn gradient
[ 2.9814239699997572e+01 0.0000000000000000e+00 ] nln_ineq_con_1 gradient
[ 0.0000000000000000e+00 1.4999999999999999e-01 ] nln_ineq_con_2 gradient
[ 0.0000000000000000e+00 -1.6998301774282701e-01 ] nln_ineq_con_3 gradient
...<snip>...
Restart file processing completed: 11 evaluations retrieved.

2.5.2

Neutral File Format

A Dakota restart file can be converted to a neutral file format using a command like the following:
dakota_restart_util to_neutral dakota.rst dakota.neu

which results in a report similar to the following:

Writing neutral file dakota.neu
Restart file processing completed: 11 evaluations retrieved.

Similarly, a neutral file can be returned to binary format using a command like the following:
dakota_restart_util from_neutral dakota.neu dakota.rst

which results in a report similar to the following:

Reading neutral file dakota.neu
Writing new restart file dakota.rst
Neutral file processing completed: 11 evaluations retrieved.

The contents of the generated neutral file are similar to the following (from the first two records for the
Cylinder example in[4]).
6 7 2 1.8000000000000000e+00 intake_dia 1.0000000000000000e+00 flatness 0 0 0 0
NULL 4 2 1 0 3 3 3 3 1 2 obj_fn nln_ineq_con_1 nln_ineq_con_2 nln_ineq_con_3
-2.4355973813420619e+00 -4.7428486677140930e-01 -4.5000000000000001e-01
1.3971143170299741e-01 -4.3644298963447897e-01 1.4999999999999999e-01
1.3855136437818300e-01 0.0000000000000000e+00 0.0000000000000000e+00

14

CHAPTER 2. RUNNING DAKOTA

1.4999999999999999e-01 0.0000000000000000e+00 -1.9485571585149869e-01 1
6 7 2 2.1640000000000001e+00 intake_dia 1.7169994018008317e+00 flatness 0 0 0 0
NULL 4 2 1 0 3 3 3 3 1 2 obj_fn nln_ineq_con_1 nln_ineq_con_2 nln_ineq_con_3
-2.4869127192988878e+00 6.9256958799989843e-01 -3.4245008972987528e-01
8.7142207937157910e-03 -4.3644298963447897e-01 1.4999999999999999e-01
2.9814239699997572e+01 0.0000000000000000e+00 0.0000000000000000e+00
1.4999999999999999e-01 0.0000000000000000e+00 -1.6998301774282701e-01 2

This format is not intended for direct viewing (print should be used for this purpose). Rather, the neutral
file capability has been used in the past for managing portability of restart data across platforms (recent use of
more portable binary formats has largely eliminated this need) or for advanced repair of restart records (in cases
where the remove command was insufficient).

2.5.3

Tabular Format

Conversion of a binary restart file to a tabular format enables convenient import of this data into 3rd-party postprocessing tools such as Matlab, TECplot, Excel, etc. This facility is nearly identical to the output activated by
the tabular data keyword in the Dakota input file specification, but with two important differences:
1. No function evaluations are suppressed as they are with tabular data (i.e., any internal finite difference
evaluations are included).
2. The conversion can be performed later, i.e., for Dakota runs executed previously.
An example command for converting a restart file to tabular format is:
dakota_restart_util to_tabular dakota.rst dakota.m

which results in a report similar to the following:

Writing tabular text file dakota.m
Restart file processing completed: 10 evaluations tabulated.

The contents of the generated tabular file are similar to the following (from the example in the Restart section
of[4]). Note that while evaluations resulting from numerical derivative offsets would be reported (as described
above), derivatives returned as part of the evaluations are not reported (since they do not readily fit within a
compact tabular format):
%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
4
NO_ID
5
NO_ID
6
NO_ID
7
NO_ID
8
NO_ID
9
NO_ID
10
NO_ID
...

x1
0.9
0.90009
0.89991
0.9
0.9
0.58256179
0.5826200462
0.5825035339
0.58256179
0.58256179

x2
1.1
1.1
1.1
1.10011
1.09989
0.4772224441
0.4772224441
0.4772224441
0.4772701663
0.4771747219

obj_fn nln_ineq_con_1 nln_ineq_con_2

0.0002
0.26
0.76
0.0001996404857
0.2601620081
0.759955
0.0002003604863
0.2598380081
0.760045
0.0002004407265
0.259945
0.7602420121
0.0001995607255
0.260055
0.7597580121
0.1050555937
0.1007670171 -0.06353963386
0.1050386469
0.1008348962 -0.06356876195
0.1050725476
0.1006991449 -0.06351050577
0.1050283245
0.100743156 -0.06349408333
0.1050828704
0.1007908783 -0.06358517983

Controlling tabular format: The command-line option --custom annotated gives control of headers
in the resulting tabular file. It supports options
header: include %-commented header row with labels
eval id: include leading column with evaluation ID
interface id: include leading column with interface ID

2.5. THE DAKOTA RESTART UTILITY

15

For example, to recover Dakota 6.0 tabular format, which contained a header row, leading column with evaluation
ID, but no interface ID:
dakota_restart_util to_tabular dakota.rst dakota.m --custom_annotated header eval_id

Resulting in
%eval_id
1
2
3
...

2.5.4

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

Concatenation of Multiple Restart Files

In some instances, it is useful to combine restart files into a single master function evaluation database. For
example, when constructing a data fit surrogate model, data from previous studies can be pulled in and reused to
create a combined data set for the surrogate fit. An example command for concatenating multiple restart files is:
dakota_restart_util cat dakota.rst.1 dakota.rst.2 dakota.rst.3 dakota.rst.all

which results in a report similar to the following:

Writing new restart file dakota.rst.all
dakota.rst.1 processing completed: 10 evaluations retrieved.
dakota.rst.2 processing completed: 110 evaluations retrieved.
dakota.rst.3 processing completed: 65 evaluations retrieved.

The dakota.rst.all database now contains 185 evaluations and can be read in for use in a subsequent
Dakota study using the -read restart option to the dakota executable.

2.5.5

Removal of Corrupted Data

On occasion, a simulation or computer system failure may cause a corruption of the Dakota restart file. For
example, a simulation crash may result in failure of a post-processor to retrieve meaningful data. If 0s (or other
erroneous data) are returned from the users analysis driver, then this bad data will get recorded in the
restart file. If there is a clear demarcation of where corruption initiated (typical in a process with feedback, such
as gradient-based optimization), then use of the -stop restart option for the dakota executable can be
effective in continuing the study from the point immediately prior to the introduction of bad data. If, however,
there are interspersed corruptions throughout the restart database (typical in a process without feedback, such as
sampling), then the remove and remove ids options of dakota restart util can be useful.
An example of the command syntax for the remove option is:
dakota_restart_util remove 2.e-04 dakota.rst dakota.rst.repaired

which results in a report similar to the following:

Writing new restart file dakota.rst.repaired
Restart repair completed: 65 evaluations retrieved, 2 removed, 63 saved.

where any evaluations in dakota.rst having an active response function value that matches 2.e-04 within
machine precision are discarded when creating dakota.rst.repaired.
An example of the command syntax for the remove ids option is:
dakota_restart_util remove_ids 12 15 23 44 57 dakota.rst dakota.rst.repaired

which results in a report similar to the following:

Writing new restart file dakota.rst.repaired
Restart repair completed: 65 evaluations retrieved, 5 removed, 60 saved.

16

CHAPTER 2. RUNNING DAKOTA

where evaluation ids 12, 15, 23, 44, and 57 have been discarded when creating dakota.rst.repaired.
An important detail is that, unlike the -stop restart option which operates on restart record numbers, the
remove ids option operates on evaluation ids. Thus, removal is not necessarily based on the order of appearance
in the restart file. This distinction is important when removing restart records for a run that contained either
asynchronous or duplicate evaluations, since the restart insertion order and evaluation ids may not correspond in
these cases (asynchronous evaluations have ids assigned in the order of job creation but are inserted in the restart
file in the order of job completion, and duplicate evaluations are not recorded which introduces offsets between
evaluation id and record number). This can also be important if removing records from a concatenated restart file,
since the same evaluation id could appear more than once. In this case, all evaluation records with ids matching
the remove ids list will be removed.
If neither of these removal options is sufficient to handle a particular restart repair need, then the fallback
position is to resort to direct editing of a neutral file to perform the necessary modifications.

Chapter 3

Test Problems
This page contains additional information about two test problems that are used in Dakota examples throughout
the Dakota manuals Textbook and Rosenbrock.
Many of these examples are also used as code verification tests. The examples are run periodically and the
results are checked against known solutions. This ensures that the algorithms are correctly implemented.
Additional test problems are described in the Users Manual.

3.1

Textbook

The two-variable version of the textbook test problem provides a nonlinearly constrained optimization test case.
It is formulated as:

minimize f = (x1 1)4 + (x2 1)4

x2
subject to g1 = x21
0
2
x
1
g2 = x22
0
2
0.5 x1 5.8
2.9 x2 2.9

Contours of this test problem are illustrated in the next two figures.
17

(textbookform)

18

CHAPTER 3. TEST PROBLEMS

Figure 3.1: Contours of the textbook problem on the [-3,4] x [-3,4] domain. The feasible region lies at the
intersection of the two constraints g 1 (solid) and g 2 (dashed).

Figure 3.2: Contours of the textbook problem zoomed into an area containing the constrained optimum point (x 1,x 2) = (0.5,0.5). The feasible region lies at the intersection of the two constraints g 1 (solid) and g 2 (dashed).

For the textbook test problem, the unconstrained minimum occurs at (x1 , x2 ) = (1, 1). However, the inclusion
of the constraints moves the minimum to (x1 , x2 ) = (0.5, 0.5). Equation textbookform presents the 2-dimensional

3.1. TEXTBOOK

19

form of the textbook problem. An extended formulation is stated as

minimize f =

n
X

(xi 1)4

i=1

x2
0
2
x1
g2 = x22
0
2
0.5 x1 5.8

subject to g1 = x21

(tbe)

2.9 x2 2.9
where n is the number of design variables. The objective function is designed to accommodate an arbitrary
number of design variables in order to allow flexible testing of a variety of data sets. Contour plots for the n = 2
case have been shown previously.
For the optimization problem given in Equation tbe, the unconstrained solution
(num nonlinear inequality constraints set to zero) for two design variables is:
x1

1.0

x2

1.0

0.0

with

The solution for the optimization problem constrained by g1 \ (num nonlinear inequality constraints
set to one) is:
x1

0.763

x2

1.16

with
f

0.00388

g1

0.0 (active)

The solution for the optimization problem constrained by g1 and g2 \ (num nonlinear inequality constraints set to two) is:
x1

0.500

x2

0.500

with
f

0.125

g1
g2

0.0 (active)

0.0 (active)

Note that as constraints are added, the design freedom is restricted (the additional constraints are active at the
solution) and an increase in the optimal objective function is observed.

20

CHAPTER 3. TEST PROBLEMS

3.2

Rosenbrock

The Rosenbrock function[34] is a well-known test problem for optimization algorithms. The standard formulation
includes two design variables, and computes a single objective function. This problem can also be posed as a
least-squares optimization problem with two residuals to be minimzed because the objective function is the sum
of squared terms.
Standard Formulation
The standard two-dimensional formulation can be stated as
minimize f = 100(x2 x21 )2 + (1 x1 )2

(rosenstd)

Surface and contour plots for this function are shown in the Dakota Users Manual.
The optimal solution is:
x1

1.0

x2

1.0

0.0

with

A Least-Squares Optimization Formulation

This test problem may also be used to exercise least-squares solution methods by recasting the standard problem formulation into:
minimize f = (f1 )2 + (f2 )2
(rosenls)
where
f1 = 10(x2 x21 )

(rosenr1)

f2 = 1 x1

(rosenr2)

and
are residual terms.
The included analysis driver can handle both formulations. In the Dakota/test directory, the rosenbrock
executable (compiled from Dakota Source/test/rosenbrock.cpp) checks the number of response functions passed in the parameters file and returns either an objective function (as computed from Equation rosenstd)
for use with optimization methods or two least squares terms (as computed from Equations rosenr1 -rosenr2 ) for
use with least squares methods. Both cases support analytic gradients of the function set with respect to the design
variables. See the Users Manual for examples of both cases (search for Rosenbrock).

Chapter 4

Dakota Input Specification

4.1

Dakota NIDR

Valid Dakota input is dictated governed by the NIDR[30] input specification file, dakota.input.nspec. This
file is used by a code generator to create parsing system components that are compiled into Dakota. Therefore,
dakota.input.nspec and its derived summary, dakota.input.summary, are the definitive source for input syntax,
capability options, and optional and required capability sub-parameters for any given Dakota version.
Beginning users may find dakota.input.summary overwhelming or confusing and will likely derive more benefit from adapting example input files to a particular problem. Some examples can be found here: Sample Input
Files. Advanced users can master the many input specification possibilities by understanding the structure of the
input specification file.

4.2

Input Spec Overview

Refer to the dakota.input.summary file, in Input Spec Summary, for current input specifications.
The summary describes every keyword including:
Whether it is required or optional
Whether it takes ARGUMENTS (always required) Additional notes about ARGUMENTS can be found
here: Specifying Arguments.
Whether it has an ALIAS, or synonym
Which additional keywords can be specified to change its behavior
Additional details and descriptions are described in Keywords Area
For additional details on NIDR specification logic and rules, refer to[30] (Gay, 2008).

4.2.1

Common Specification Mistakes

Spelling mistakes and omission of required parameters are the most common errors. Some causes of errors are
more obscure:
Documentation of new capability sometimes lags its availability in source and executables, especially stable
releases. When parsing errors occur that the documentation cannot explain, reference to the particular input
specification used in building the executable, which is installed alongside the executable, will often resolve
the errors.
21

22

CHAPTER 4. DAKOTA INPUT SPECIFICATION

If you want to compare results with those obtained using an earlier version of Dakota (prior to 4.1), your
input file for the earlier version must use backslashes to indicate continuation lines for Dakota keywords.
For example, rather than
# Comment about the following "responses" keyword...
responses,
objective_functions = 1
# Comment within keyword "responses"
analytic_gradients
# Another comment within keyword "responses"
no_hessians

you would need to write

# Comment about the following "responses" keyword...
responses,
\
objective_functions = 1
\
# Comment within keyword "responses"
\
analytic_gradients
\
# Another comment within keyword "responses"
\
no_hessians

with no white space (blanks or tabs) after the \ character.

In most cases, the NIDR system provides error messages that help the user isolate errors in Dakota input files.

4.2.2

Specifying Arguments

Some keywords, such as those providing bounds on variables, have an associated list of values or strings, referred
to as arguments.
When the same value should be repeated several times in a row, you can use the notation Nvalue instead of
repeating the value N times.
For example
lower_bounds
upper_bounds

-2.0
2.0

-2.0
2.0

-2.0
2.0

could also be written

lower_bounds
upper_bounds

3*-2.0
3* 2.0

(with optional spaces around the ).

Another possible abbreviation is for sequences: L:S:U (with optional spaces around the : ) is expanded to L
L+S L+2S ... U, and L:U (with no second colon) is treated as L:1:U.
For example, in one of the test examples distributed with Dakota (test case 2 of test/dakota uq textbook sop lhs.in ),
histogram_point = 2
abscissas
= 50. 60. 70.
30. 40. 50.
counts
= 10 20 30 20
10 20 30 20

80. 90.
60. 70.
10
10

could also be written

histogram_point = 2
abscissas
= 50 : 10 : 90
30 : 10 : 70
counts
= 10:10:30 20 10
10:10:30 20 10

4.3. SAMPLE INPUT FILES

23

Count and sequence abbreviations can be used together. For example

response_levels =
0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0

can be abbreviated
response_levels =
2*0.0:0.1:1.0

4.3

Sample Input Files

A Dakota input file is a collection of fields from the dakota.input.summary file that describe the problem to be
solved by Dakota. Several examples follow.
Sample 1: Optimization
The following sample input file shows single-method optimization of the Textbook Example (see Textbook)
using DOTs modified method of feasible directions. A similar file is available as Dakota/examples/users/textbookopt conmin.in.
# Dakota Input File: textbook_opt_conmin.in
environment
graphics
tabular_data
tabular_data_file = textbook_opt_conmin.dat
method
# dot_mmfd #DOT performs better but may not be available
conmin_mfd
max_iterations = 50
convergence_tolerance = 1e-4
variables
continuous_design = 2
initial_point 0.9 1.1
upper_bounds
5.8 2.9
lower_bounds
0.5 -2.9
descriptors
x1 x2
interface
direct
analysis_driver =

text_book

responses
objective_functions = 1
nonlinear_inequality_constraints = 2
numerical_gradients
method_source dakota
interval_type central
fd_gradient_step_size = 1.e-4
no_hessians

Sample 2: Least Squares (Calibration)

The following sample input file shows a nonlinear least squares (calibration) solution of the Rosenbrock Example (see Rosenbrock) using the NL2SOL method. A similar file is available as Dakota/examples/users/rosenopt nls.in
# Dakota Input File: rosen_opt_nls.in
environment

24

CHAPTER 4. DAKOTA INPUT SPECIFICATION

graphics
tabular_data
tabular_data_file = rosen_opt_nls.dat
method
max_iterations = 100
convergence_tolerance = 1e-4
nl2sol
model
single
variables
continuous_design = 2
initial_point -1.2
1.0
lower_bounds
-2.0
-2.0
upper_bounds
2.0
2.0
descriptors
x1
"x2"
interface
analysis_driver = rosenbrock
direct
responses
calibration_terms = 2
analytic_gradients
no_hessians

Sample 3: Nondeterministic Analysis

The following sample input file shows Latin Hypercube Monte Carlo sampling using the Textbook Example
(see Textbook). A similar file is available as Dakota/test/dakota uq textbook lhs.in.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
sample_type lhs
variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations = 12.4, 29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
= 12., 30.
betas
= 250., 590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs = 3
4
abscissas = 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12 0
descriptors = TF1h TF2h
histogram_point_uncertain = 1
num_pairs = 2
abscissas = 3 4

4.3. SAMPLE INPUT FILES

25

counts
= 1 1
descriptors = TF3h
interface,
fork asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Sample 4: Parameter Study

The following sample input file shows a 1-D vector parameter study using the Textbook Example (see Textbook). It makes use of the default environment and model specifications, so they can be omitted. A similar file is
available in the test directory as Dakota/examples/users/rosen ps vector.in.
# Dakota Input File: rosen_ps_vector.in
environment
graphics
tabular_data
tabular_data_file = rosen_ps_vector.dat
method
vector_parameter_study
final_point = 1.1 1.3
num_steps = 10
variables
continuous_design = 2
initial_point -0.3
descriptors
x1

0.2
"x2"

interface
analysis_driver = rosenbrock
direct
responses
objective_functions = 1
no_gradients
no_hessians

Sample 5: Hybrid Strategy

The following sample input file shows a hybrid environment using three methods. It employs a genetic algorithm, pattern search, and full Newton gradient-based optimization in succession to solve the Textbook Example
(see Textbook). A similar file is available as Dakota/examples/users/textbook hybrid strat.in.
environment
graphics
hybrid sequential
method_list = PS PS2 NLP
method
id_method = PS
model_pointer = M1
coliny_pattern_search stochastic
seed = 1234
initial_delta = 0.1
threshold_delta = 1.e-4
solution_accuracy = 1.e-10

26
exploratory_moves basic_pattern
#verbose output
method
id_method = PS2
model_pointer = M1
max_function_evaluations = 10
coliny_pattern_search stochastic
seed = 1234
initial_delta = 0.1
threshold_delta = 1.e-4
solution_accuracy = 1.e-10
exploratory_moves basic_pattern
#verbose output
method
id_method = NLP
model_pointer = M2
optpp_newton
gradient_tolerance = 1.e-12
convergence_tolerance = 1.e-15
#verbose output
model
id_model = M1
single
variables_pointer = V1
interface_pointer = I1
responses_pointer = R1
model
id_model = M2
single
variables_pointer = V1
interface_pointer = I1
responses_pointer = R2
variables
id_variables = V1
continuous_design = 2
initial_point 0.6 0.7
upper_bounds
5.8 2.9
lower_bounds
0.5 -2.9
descriptors
x1 x2
interface
id_interface = I1
direct
analysis_driver= text_book
responses
id_responses = R1
objective_functions = 1
no_gradients
no_hessians
responses
id_responses = R2
objective_functions = 1
analytic_gradients
analytic_hessians

CHAPTER 4. DAKOTA INPUT SPECIFICATION

4.4. INPUT SPEC SUMMARY

27

Additional example input files, as well as the corresponding output and graphics, are provided in the Tutorial
chapter of the Users Manual [4] (Adams et al., 2010).

4.4

Input Spec Summary

This file is derived automatically from dakota.input.nspec, which is used in the generation of parser system files
that are compiled into the Dakota executable. Therefore, these files are the definitive source for input syntax,
capability options, and associated data inputs. Refer to the Developers Manual information on how to modify the
input specification and propagate the changes through the parsing system.
Key features of the input specification and the associated user input files include:
In the input specification, required individual specifications simply appear, optional individual and group
specifications are enclosed in [], required group specifications are enclosed in (), and either-or relationships
are denoted by the | symbol. These symbols only appear in dakota.input.nspec; they must not appear in
actual user input files.
Keyword specifications (i.e., environment, method, model, variables, interface, and responses)
begin with the keyword possibly preceded by white space (blanks, tabs, and newlines) both in the input
specifications and in user input files. For readability, keyword specifications may be spread across several
lines. Earlier versions of Dakota (prior to 4.1) required a backslash character (\) at the ends of intermediate
lines of a keyword. While such backslashes are still accepted, they are no longer required.
Some of the keyword components within the input specification indicate that the user must supply INTEGER, REAL, STRING, INTEGERLIST, REALLIST, or STRINGLIST data as part of the specification. In
a user input file, the "=" is optional, data in a LIST can be separated by commas or whitespace, and the
STRING data are enclosed in single or double quotes (e.g., text book or text book).
In user input files, input is largely order-independent (except for entries in lists of data), case insensitive,
and white-space insensitive. Although the order of input shown in the Sample Input Files generally follows
the order of options in the input specification, this is not required.
In user input files, specifications may be abbreviated so long as the abbreviation is unique. For example,
the npsol sqp specification within the method keyword could be abbreviated as npsol, but dot sqp
should not be abbreviated as dot since this would be ambiguous with other DOT method specifications.
In both the input specification and user input files, comments are preceded by #.
ALIAS refers to synonymous keywords, which often exist for backwards compatability. Users are encouraged to use the most current keyword.
KEYWORD01 environment
[ check ]
[ output_file STRING ]
[ error_file STRING ]
[ read_restart STRING
[ stop_restart INTEGER >= 0 ]
]
[ write_restart STRING ]
[ pre_run
[ input STRING ]
[ output STRING
[ annotated
|
( custom_annotated

28

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
]
[ run
[ input STRING ]
[ output STRING ]
]
[ post_run
[ input STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ output STRING ]
]
[ graphics ]
[ tabular_data ALIAS tabular_graphics_data
[ tabular_data_file ALIAS tabular_graphics_file STRING ]
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ output_precision INTEGER >= 0 ]
[ results_output
[ results_output_file STRING ]
]
[ top_method_pointer ALIAS method_pointer STRING ]

KEYWORD12 method
[ id_method STRING ]
[ output
debug
| verbose
| normal
| quiet
| silent
]
[ final_solutions INTEGER >= 0 ]
( hybrid
( sequential ALIAS uncoupled
( method_name_list STRINGLIST
[ model_pointer_list STRING ]
)
| method_pointer_list STRINGLIST
)

4.4. INPUT SPEC SUMMARY

|
( embedded ALIAS coupled
( global_method_name STRING
[ global_model_pointer STRING ]
)
| global_method_pointer STRING
( local_method_name STRING
[ local_model_pointer STRING ]
)
| local_method_pointer STRING
[ local_search_probability REAL ]
)
|
( collaborative
( method_name_list STRINGLIST
[ model_pointer_list STRING ]
)
| method_pointer_list STRINGLIST
)
[ iterator_servers INTEGER > 0 ]
[ iterator_scheduling
master
| peer
]
[ processors_per_iterator INTEGER > 0 ]
)
|
( multi_start
( method_name STRING
[ model_pointer STRING ]
)
| method_pointer STRING
[ random_starts INTEGER
[ seed INTEGER ]
]
[ starting_points REALLIST ]
[ iterator_servers INTEGER > 0 ]
[ iterator_scheduling
master
| peer
]
[ processors_per_iterator INTEGER > 0 ]
)
|
( pareto_set
( method_name ALIAS opt_method_name STRING
[ model_pointer ALIAS opt_model_pointer STRING ]
)
| method_pointer ALIAS opt_method_pointer STRING
[ random_weight_sets INTEGER
[ seed INTEGER ]
]
[ weight_sets ALIAS multi_objective_weight_sets REALLIST ]
[ iterator_servers INTEGER > 0 ]
[ iterator_scheduling
master
| peer
]
[ processors_per_iterator INTEGER > 0 ]
)
|
( branch_and_bound

29

30

CHAPTER 4. DAKOTA INPUT SPECIFICATION

method_pointer STRING
|
( method_name STRING
[ model_pointer STRING ]
)
[ scaling ]
)
|
( surrogate_based_local
method_pointer ALIAS approx_method_pointer STRING
| method_name ALIAS approx_method_name STRING
model_pointer ALIAS approx_model_pointer STRING
[ soft_convergence_limit INTEGER ]
[ truth_surrogate_bypass ]
[ trust_region
[ initial_size REAL ]
[ minimum_size REAL ]
[ contract_threshold REAL ]
[ expand_threshold REAL ]
[ contraction_factor REAL ]
[ expansion_factor REAL ]
]
[ approx_subproblem
original_primary
| single_objective
| augmented_lagrangian_objective
| lagrangian_objective
original_constraints
| linearized_constraints
| no_constraints
]
[ merit_function
penalty_merit
| adaptive_penalty_merit
| lagrangian_merit
| augmented_lagrangian_merit
]
[ acceptance_logic
tr_ratio
| filter
]
[ constraint_relax
homotopy
]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ constraint_tolerance REAL ]
)
|
( surrogate_based_global
method_pointer ALIAS approx_method_pointer STRING
| method_name ALIAS approx_method_name STRING
model_pointer ALIAS approx_model_pointer STRING
[ replace_points ]
[ max_iterations INTEGER >= 0 ]
)
|
( dot_frcg
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ constraint_tolerance REAL ]
[ speculative ]

4.4. INPUT SPEC SUMMARY

[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
dot_mmfd
dot_bfgs
dot_slp
dot_sqp

|
|
|
|
|
( dot
frcg
| mmfd
| bfgs
| slp
| sqp
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ constraint_tolerance REAL ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
|
( conmin_frcg
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ constraint_tolerance REAL ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
| conmin_mfd
|

31

32

CHAPTER 4. DAKOTA INPUT SPECIFICATION

( conmin
frcg
| mfd
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ constraint_tolerance REAL ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
|
( dl_solver STRING
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( npsol_sqp
[ verify_level INTEGER ]
[ function_precision REAL ]
[ linesearch_tolerance REAL ]
[ convergence_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ constraint_tolerance REAL ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
| nlssol_sqp
|
( stanford
npsol
| nlssol

4.4. INPUT SPEC SUMMARY

[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
)

verify_level INTEGER ]
function_precision REAL ]
linesearch_tolerance REAL ]
convergence_tolerance REAL ]
max_iterations INTEGER >= 0 ]
constraint_tolerance REAL ]
speculative ]
max_function_evaluations INTEGER >= 0 ]
scaling ]
linear_inequality_constraint_matrix REALLIST ]
linear_inequality_lower_bounds REALLIST ]
linear_inequality_upper_bounds REALLIST ]
linear_inequality_scale_types STRINGLIST ]
linear_inequality_scales REALLIST ]
linear_equality_constraint_matrix REALLIST ]
linear_equality_targets REALLIST ]
linear_equality_scale_types STRINGLIST ]
linear_equality_scales REALLIST ]
model_pointer STRING ]

|
( nlpql_sqp
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( optpp_cg
[ max_step REAL ]
[ gradient_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
|
( optpp_q_newton
| optpp_fd_newton
| optpp_g_newton
| optpp_newton

33

34

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ search_method
value_based_line_search
| gradient_based_line_search
| trust_region
| tr_pds
]
[ merit_function
el_bakry
| argaez_tapia
| van_shanno
]
[ steplength_to_boundary REAL ]
[ centering_parameter REAL ]
[ max_step REAL ]
[ gradient_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]
[ linear_inequality_scale_types STRINGLIST ]
[ linear_inequality_scales REALLIST ]
[ linear_equality_constraint_matrix REALLIST ]
[ linear_equality_targets REALLIST ]
[ linear_equality_scale_types STRINGLIST ]
[ linear_equality_scales REALLIST ]
[ model_pointer STRING ]
)
|
( optpp_pds
[ search_scheme_size INTEGER ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( asynch_pattern_search ALIAS coliny_apps
[ initial_delta REAL ]
[ contraction_factor REAL ]
[ threshold_delta REAL ]
[ solution_target ALIAS solution_accuracy REAL ]
[ synchronization
blocking
| nonblocking
]
[ merit_function
merit_max
| merit_max_smooth
| merit1
| merit1_smooth
| merit2
| merit2_smooth
| merit2_squared
]
[ constraint_penalty REAL ]
[ smoothing_factor REAL ]
[ linear_inequality_constraint_matrix REALLIST ]

4.4. INPUT SPEC SUMMARY

[
[
[
[
[
[
[
[
[
[
[
[
)

linear_inequality_lower_bounds REALLIST ]
linear_inequality_upper_bounds REALLIST ]
linear_inequality_scale_types STRINGLIST ]
linear_inequality_scales REALLIST ]
linear_equality_constraint_matrix REALLIST ]
linear_equality_targets REALLIST ]
linear_equality_scale_types STRINGLIST ]
linear_equality_scales REALLIST ]
constraint_tolerance REAL ]
max_function_evaluations INTEGER >= 0 ]
scaling ]
model_pointer STRING ]

|
( mesh_adaptive_search
[ function_precision REAL ]
[ seed INTEGER > 0 ]
[ history_file STRING ]
[ display_format STRING ]
[ variable_neighborhood_search REAL ]
[ neighbor_order INTEGER > 0 ]
[ display_all_evaluations ]
[ max_iterations INTEGER >= 0 ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( moga
[ fitness_type
layer_rank
| domination_count
]
[ replacement_type
elitist
| roulette_wheel
| unique_roulette_wheel
|
( below_limit REAL
[ shrinkage_fraction ALIAS shrinkage_percentage REAL ]
)
]
[ niching_type
radial REALLIST
| distance REALLIST
|
( max_designs REALLIST
[ num_designs INTEGER >= 2 ]
)
]
[ convergence_type
metric_tracker
[ percent_change REAL ]
[ num_generations INTEGER >= 0 ]
]
[ postprocessor_type
orthogonal_distance REALLIST
]
[ max_iterations INTEGER >= 0 ]
[ linear_inequality_constraint_matrix REALLIST ]
[ linear_inequality_lower_bounds REALLIST ]
[ linear_inequality_upper_bounds REALLIST ]

35

36

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[
[
[
[
[
[
[
[
[
[
[
[

[
[
[
)

linear_inequality_scale_types STRINGLIST ]
linear_inequality_scales REALLIST ]
linear_equality_constraint_matrix REALLIST ]
linear_equality_targets REALLIST ]
linear_equality_scale_types STRINGLIST ]
linear_equality_scales REALLIST ]
max_function_evaluations INTEGER >= 0 ]
scaling ]
population_size INTEGER >= 0 ]
log_file STRING ]
print_each_pop ]
initialization_type
simple_random
| unique_random
| flat_file STRING
]
crossover_type
multi_point_binary INTEGER
| multi_point_parameterized_binary INTEGER
| multi_point_real INTEGER
|
( shuffle_random
[ num_parents INTEGER > 0 ]
[ num_offspring INTEGER > 0 ]
)
[ crossover_rate REAL ]
]
mutation_type
bit_random
| replace_uniform
|
( offset_normal
| offset_cauchy
| offset_uniform
[ mutation_scale REAL ]
)
[ mutation_rate REAL ]
]
seed INTEGER > 0 ]
convergence_tolerance REAL ]
model_pointer STRING ]

|
( soga
[ fitness_type
merit_function
[ constraint_penalty REAL ]
]
[ replacement_type
elitist
| favor_feasible
| roulette_wheel
| unique_roulette_wheel
]
[ convergence_type
( best_fitness_tracker
[ percent_change REAL ]
[ num_generations INTEGER >= 0 ]
)
|
( average_fitness_tracker
[ percent_change REAL ]

4.4. INPUT SPEC SUMMARY

[ num_generations INTEGER >= 0 ]
)
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[

[
[
[
)

]
max_iterations INTEGER >= 0 ]
linear_inequality_constraint_matrix REALLIST ]
linear_inequality_lower_bounds REALLIST ]
linear_inequality_upper_bounds REALLIST ]
linear_inequality_scale_types STRINGLIST ]
linear_inequality_scales REALLIST ]
linear_equality_constraint_matrix REALLIST ]
linear_equality_targets REALLIST ]
linear_equality_scale_types STRINGLIST ]
linear_equality_scales REALLIST ]
max_function_evaluations INTEGER >= 0 ]
scaling ]
population_size INTEGER >= 0 ]
log_file STRING ]
print_each_pop ]
initialization_type
simple_random
| unique_random
| flat_file STRING
]
crossover_type
multi_point_binary INTEGER
| multi_point_parameterized_binary INTEGER
| multi_point_real INTEGER
|
( shuffle_random
[ num_parents INTEGER > 0 ]
[ num_offspring INTEGER > 0 ]
)
[ crossover_rate REAL ]
]
mutation_type
bit_random
| replace_uniform
|
( offset_normal
| offset_cauchy
| offset_uniform
[ mutation_scale REAL ]
)
[ mutation_rate REAL ]
]
seed INTEGER > 0 ]
convergence_tolerance REAL ]
model_pointer STRING ]

|
( coliny_pattern_search
[ constant_penalty ]
[ no_expansion ]
[ expand_after_success INTEGER ]
[ pattern_basis
coordinate
| simplex
]
[ stochastic ]
[ total_pattern_size INTEGER ]
[ exploratory_moves
multi_step

37

38

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[
[
[
[
[
[
[
[
[
[
[
[
[
)

| adaptive_pattern
| basic_pattern
]
synchronization
blocking
| nonblocking
]
contraction_factor REAL ]
constraint_penalty REAL ]
initial_delta REAL ]
threshold_delta REAL ]
solution_target ALIAS solution_accuracy REAL ]
seed INTEGER > 0 ]
show_misc_options ]
misc_options STRINGLIST ]
max_iterations INTEGER >= 0 ]
convergence_tolerance REAL ]
max_function_evaluations INTEGER >= 0 ]
scaling ]
model_pointer STRING ]

|
( coliny_solis_wets
[ contract_after_failure INTEGER ]
[ no_expansion ]
[ expand_after_success INTEGER ]
[ constant_penalty ]
[ contraction_factor REAL ]
[ constraint_penalty REAL ]
[ initial_delta REAL ]
[ threshold_delta REAL ]
[ solution_target ALIAS solution_accuracy REAL ]
[ seed INTEGER > 0 ]
[ show_misc_options ]
[ misc_options STRINGLIST ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( coliny_cobyla
[ initial_delta REAL ]
[ threshold_delta REAL ]
[ solution_target ALIAS solution_accuracy REAL ]
[ seed INTEGER > 0 ]
[ show_misc_options ]
[ misc_options STRINGLIST ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( coliny_direct
[ division
major_dimension
| all_dimensions
]
[ global_balance_parameter REAL ]

4.4. INPUT SPEC SUMMARY

[
[
[
[
[
[
[
[
[
[
[
[
[
)

local_balance_parameter REAL ]
max_boxsize_limit REAL ]
min_boxsize_limit REAL ]
constraint_penalty REAL ]
solution_target ALIAS solution_accuracy REAL ]
seed INTEGER > 0 ]
show_misc_options ]
misc_options STRINGLIST ]
max_iterations INTEGER >= 0 ]
convergence_tolerance REAL ]
max_function_evaluations INTEGER >= 0 ]
scaling ]
model_pointer STRING ]

|
( coliny_ea
[ population_size INTEGER > 0 ]
[ initialization_type
simple_random
| unique_random
| flat_file STRING
]
[ fitness_type
linear_rank
| merit_function
]
[ replacement_type
random INTEGER
| chc INTEGER
| elitist INTEGER
[ new_solutions_generated INTEGER ]
]
[ crossover_rate REAL ]
[ crossover_type
two_point
| blend
| uniform
]
[ mutation_rate REAL ]
[ mutation_type
replace_uniform
|
( offset_normal
| offset_cauchy
| offset_uniform
[ mutation_scale REAL ]
[ mutation_range INTEGER ]
)
[ non_adaptive ]
]
[ constraint_penalty REAL ]
[ solution_target ALIAS solution_accuracy REAL ]
[ seed INTEGER > 0 ]
[ show_misc_options ]
[ misc_options STRINGLIST ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|

39

40

CHAPTER 4. DAKOTA INPUT SPECIFICATION

( coliny_beta
beta_solver_name STRING
[ solution_target ALIAS solution_accuracy REAL ]
[ seed INTEGER > 0 ]
[ show_misc_options ]
[ misc_options STRINGLIST ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( nl2sol
[ function_precision REAL ]
[ absolute_conv_tol REAL ]
[ x_conv_tol REAL ]
[ singular_conv_tol REAL ]
[ singular_radius REAL ]
[ false_conv_tol REAL ]
[ initial_trust_radius REAL ]
[ covariance INTEGER ]
[ regression_diagnostics ]
[ convergence_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ speculative ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( nonlinear_cg
[ misc_options STRINGLIST ]
[ convergence_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( ncsu_direct
[ solution_target ALIAS solution_accuracy REAL ]
[ min_boxsize_limit REAL ]
[ volume_boxsize_limit REAL ]
[ convergence_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( genie_opt_darts
| genie_direct
[ seed INTEGER > 0 ]
[ max_function_evaluations INTEGER >= 0 ]
[ scaling ]
[ model_pointer STRING ]
)
|
( efficient_global
[ gaussian_process ALIAS kriging
surfpack
| dakota

4.4. INPUT SPEC SUMMARY

]
[ use_derivatives ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ seed INTEGER > 0 ]
[ max_iterations INTEGER >= 0 ]
[ model_pointer STRING ]
)
|
( polynomial_chaos ALIAS nond_polynomial_chaos
[ p_refinement
uniform
|
( dimension_adaptive
sobol
| decay
| generalized
)
]
[ askey
| wiener ]
( quadrature_order INTEGERLIST
[ dimension_preference REALLIST ]
[ nested
| non_nested ]
)
|
( sparse_grid_level INTEGERLIST
[ restricted
| unrestricted ]
[ dimension_preference REALLIST ]
[ nested
| non_nested ]
)
| cubature_integrand INTEGER
|
( expansion_order INTEGERLIST
[ dimension_preference REALLIST ]
[ basis_type
tensor_product
| total_order

41

42

CHAPTER 4. DAKOTA INPUT SPECIFICATION

|
( adapted
[ advancements INTEGER ]
[ soft_convergence_limit INTEGER ]
)
]
( collocation_points INTEGERLIST
| collocation_ratio REAL
[ ratio_order REAL ]
[ ( least_squares
[ svd
| equality_constrained ]
)
|
( orthogonal_matching_pursuit ALIAS omp
[ noise_tolerance REALLIST ]
]
| basis_pursuit ALIAS bp
|
( basis_pursuit_denoising ALIAS bpdn
[ noise_tolerance REALLIST ]
]
|
( least_angle_regression ALIAS lars
[ noise_tolerance REALLIST ]
]
|
( least_absolute_shrinkage ALIAS lasso
[ noise_tolerance REALLIST ]
[ l2_penalty REAL ]
]
[ cross_validation ]
[ use_derivatives ]
[ tensor_grid ]
[ reuse_points ALIAS reuse_samples ]
)
|
( expansion_samples INTEGERLIST
[ reuse_points ALIAS reuse_samples ]
[ incremental_lhs ]
)
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( orthogonal_least_interpolation ALIAS least_interpolation ALIAS oli
collocation_points INTEGERLIST
[ cross_validation ]
[ tensor_grid INTEGERLIST ]
[ reuse_points ALIAS reuse_samples ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated

4.4. INPUT SPEC SUMMARY

|
[

[
|
[
[

[
[
[
[
[

|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
import_expansion_file STRING
variance_based_decomp
[ interaction_order INTEGER > 0 ]
[ drop_tolerance REAL ]
]
diagonal_covariance
full_covariance ]
normalized ]
sample_type
lhs
| random
]
probability_refinement ALIAS sample_refinement
import
| adapt_import
| mm_adapt_import
[ refinement_samples INTEGER ]
]
import_approx_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
export_expansion_file STRING ]
fixed_seed ]
max_iterations INTEGER >= 0 ]
convergence_tolerance REAL ]
reliability_levels REALLIST
[ num_reliability_levels INTEGERLIST ]
]
response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute

43

44

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[
[
[
)

probabilities
| reliabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
distribution
cumulative
| complementary
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
rng
mt19937
| rnum2
]
samples INTEGER ]
seed INTEGER > 0 ]
model_pointer STRING ]

|
( stoch_collocation ALIAS nond_stoch_collocation
[ ( p_refinement
uniform
|
( dimension_adaptive
sobol
| generalized
)
)
|
( h_refinement
uniform
|
( dimension_adaptive
sobol
| generalized
)
| local_adaptive
]
[ piecewise
| askey
| wiener ]
quadrature_order INTEGERLIST
|
( sparse_grid_level INTEGERLIST
[ restricted
| unrestricted ]
[ nodal
| hierarchical ]
)
[ dimension_preference REALLIST ]
[ use_derivatives ]
[ nested
| non_nested ]

4.4. INPUT SPEC SUMMARY

[ variance_based_decomp
[ interaction_order INTEGER > 0 ]
[ drop_tolerance REAL ]
]
[ diagonal_covariance
| full_covariance ]
[ sample_type
lhs
| random
]
[ probability_refinement ALIAS sample_refinement
import
| adapt_import
| mm_adapt_import
[ refinement_samples INTEGER ]
]
[ import_approx_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ fixed_seed ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ reliability_levels REALLIST
[ num_reliability_levels INTEGERLIST ]
]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| reliabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
[ distribution
cumulative
| complementary
]
[ probability_levels REALLIST

45

46

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[
[
[
)

[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
rng
mt19937
| rnum2
]
samples INTEGER ]
seed INTEGER > 0 ]
model_pointer STRING ]

|
( sampling ALIAS nond_sampling
[ sample_type
random
| lhs
|
( incremental_lhs
| incremental_random
previous_samples INTEGER
)
]
[ variance_based_decomp
[ drop_tolerance REAL ]
]
[ backfill ]
[ principal_components
[ percent_variance_explained REAL ]
]
[ fixed_seed ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ reliability_levels REALLIST
[ num_reliability_levels INTEGERLIST ]
]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| reliabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
[ distribution
cumulative
| complementary
]
[ probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
[ gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
[ rng
mt19937
| rnum2

4.4. INPUT SPEC SUMMARY

]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( importance_sampling ALIAS nond_importance_sampling
import
| adapt_import
| mm_adapt_import
[ refinement_samples INTEGER ]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ distribution
cumulative
| complementary
]
[ probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
[ gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
[ rng
mt19937
| rnum2
]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( gpais ALIAS gaussian_process_adaptive_importance_sampling
[ emulator_samples INTEGER ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]

47

48

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ eval_id ]
[ interface_id ]
]

[
[

[
[
[
)

|
( freeform
]
response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
max_iterations INTEGER >= 0 ]
distribution
cumulative
| complementary
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
rng
mt19937
| rnum2
]
samples INTEGER ]
seed INTEGER > 0 ]
model_pointer STRING ]

|
( adaptive_sampling ALIAS nond_adaptive_sampling
[ emulator_samples INTEGER ]
[ fitness_metric
predicted_variance
| distance
| gradient
]
[ batch_selection
naive
| distance_penalty
| topology
| constant_liar
]
[ batch_size INTEGER ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]

4.4. INPUT SPEC SUMMARY

]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
[ misc_options STRINGLIST ]
[ max_iterations INTEGER >= 0 ]
[ distribution
cumulative
| complementary
]
[ probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
[ gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
[ rng
mt19937
| rnum2
]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( pof_darts ALIAS nond_pof_darts
[ lipschitz
local
| global
]
[ emulator_samples INTEGER ]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
[ distribution

49

50

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[
[
[
)

cumulative
| complementary
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
rng
mt19937
| rnum2
]
samples INTEGER ]
seed INTEGER > 0 ]
model_pointer STRING ]

|
( rkd_darts ALIAS nond_rkd_darts
[ lipschitz
local
| global
]
[ emulator_samples INTEGER ]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
[ distribution
cumulative
| complementary
]
[ probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
[ gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
[ rng
mt19937
| rnum2
]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( efficient_subspace ALIAS nond_efficient_subspace
[ emulator_samples INTEGER ]
[ batch_size INTEGER ]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ distribution
cumulative

4.4. INPUT SPEC SUMMARY

[
[
[
)

| complementary
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
rng
mt19937
| rnum2
]
samples INTEGER ]
seed INTEGER > 0 ]
model_pointer STRING ]

|
( global_evidence ALIAS nond_global_evidence
[ sbo
| ego
[ gaussian_process ALIAS kriging
surfpack
| dakota
]
[ use_derivatives ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
]
| ea
| lhs ]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]

51

52

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ distribution
cumulative
| complementary
]
[ probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
[ gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
[ rng
mt19937
| rnum2
]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( global_interval_est ALIAS nond_global_interval_est
[ sbo
| ego
[ gaussian_process ALIAS kriging
surfpack
| dakota
]
[ use_derivatives ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
]
| ea
| lhs ]
[ rng
mt19937
| rnum2
]
[ max_iterations INTEGER >= 0 ]
[ convergence_tolerance REAL ]
[ max_function_evaluations INTEGER >= 0 ]
[ samples INTEGER ]
[ seed INTEGER > 0 ]

4.4. INPUT SPEC SUMMARY

[ model_pointer STRING ]
)
|
( bayes_calibration ALIAS nond_bayes_calibration
( queso
[ emulator
( gaussian_process ALIAS kriging
surfpack
| dakota
[ emulator_samples INTEGER ]
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( pce
sparse_grid_level INTEGERLIST
|
( expansion_order INTEGERLIST
collocation_ratio REAL
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( collocation_points INTEGERLIST
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
)
|

53

54

CHAPTER 4. DAKOTA INPUT SPECIFICATION

( sc
sparse_grid_level INTEGERLIST
)
[ use_derivatives ]
]
[ logit_transform ]
[ export_chain_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ dram
| delayed_rejection
| adaptive_metropolis
| metropolis_hastings
| multilevel ]
[ rng
mt19937
| rnum2
]
[ pre_solve
sqp
| nip
]
[ proposal_covariance
( derivatives
[ proposal_updates INTEGER ]
)
| prior
|
( values REALLIST
diagonal
| matrix
)
|
( filename STRING
diagonal
| matrix
)
]
)
|
( gpmsa
emulator_samples INTEGER
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]

4.4. INPUT SPEC SUMMARY

[
|
|
|
|
[

dram
delayed_rejection
adaptive_metropolis
metropolis_hastings
multilevel ]
rng
mt19937
| rnum2
]
[ pre_solve
sqp
| nip
]
[ proposal_covariance
( derivatives
[ proposal_updates INTEGER ]
)
| prior
|
( values REALLIST
diagonal
| matrix
)
|
( filename STRING
diagonal
| matrix
)
]
)
|
( wasabi
[ emulator
( gaussian_process ALIAS kriging
surfpack
| dakota
[ emulator_samples INTEGER ]
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( pce
sparse_grid_level INTEGERLIST
|
( expansion_order INTEGERLIST
collocation_ratio REAL
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated

55

56

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( collocation_points INTEGERLIST
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
)
|
( sc
sparse_grid_level INTEGERLIST
)
[ use_derivatives ]
]
( data_distribution
( gaussian
means REALLIST
( covariance REALLIST
diagonal
| matrix
)
)
| obs_data_filename STRING
)
[ posterior_density_export_filename STRING ]
[ posterior_samples_export_filename STRING ]
[ posterior_samples_import_filename STRING ]
[ generate_posterior_samples
evaluate_posterior_density
]
)
|
( dream
[ chains INTEGER >= 3 ]
[ num_cr INTEGER >= 1 ]
[ crossover_chain_pairs INTEGER >= 0 ]
[ gr_threshold REAL > 0.0 ]
[ jump_step INTEGER >= 0 ]
[ emulator
( gaussian_process ALIAS kriging
surfpack
| dakota
[ emulator_samples INTEGER ]
[ posterior_adaptive ]

4.4. INPUT SPEC SUMMARY

[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( pce
sparse_grid_level INTEGERLIST
|
( expansion_order INTEGERLIST
collocation_ratio REAL
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( collocation_points INTEGERLIST
[ posterior_adaptive ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
)
|
( sc
sparse_grid_level INTEGERLIST
)
[ use_derivatives ]
]
)
[ standardized_space ]
[ calibrate_error_multipliers
one
| per_experiment
| per_response

57

58

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[
[
[
[
[
)

| both
[ hyperprior_alphas REALLIST
hyperprior_betas REALLIST
]
]
convergence_tolerance REAL ]
max_iterations INTEGER >= 0 ]
samples INTEGER ]
seed INTEGER > 0 ]
model_pointer STRING ]

|
( dace
grid
| random
| oas
| lhs
| oa_lhs
| box_behnken
| central_composite
[ main_effects ]
[ quality_metrics ]
[ variance_based_decomp
[ drop_tolerance REAL ]
]
[ fixed_seed ]
[ symbols INTEGER ]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( fsu_cvt
[ latinize ]
[ quality_metrics ]
[ variance_based_decomp
[ drop_tolerance REAL ]
]
[ fixed_seed ]
[ trial_type
grid
| halton
| random
]
[ num_trials INTEGER ]
[ max_iterations INTEGER >= 0 ]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( psuade_moat
[ partitions INTEGERLIST ]
[ samples INTEGER ]
[ seed INTEGER > 0 ]
[ model_pointer STRING ]
)
|
( local_evidence ALIAS nond_local_evidence
[ sqp
| nip ]
[ response_levels REALLIST

4.4. INPUT SPEC SUMMARY

[
)

[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series
| parallel
]
]
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
distribution
cumulative
| complementary
]
model_pointer STRING ]

|
( local_interval_est ALIAS nond_local_interval_est
[ sqp
| nip ]
[ convergence_tolerance REAL ]
[ model_pointer STRING ]
)
|
( local_reliability ALIAS nond_local_reliability
[ mpp_search
x_taylor_mean
| u_taylor_mean
| x_taylor_mpp
| u_taylor_mpp
| x_two_point
| u_two_point
| no_approx
[ sqp
| nip ]
[ integration
first_order
| second_order
[ probability_refinement ALIAS sample_refinement
import
| adapt_import
| mm_adapt_import
[ refinement_samples INTEGER ]
[ seed INTEGER > 0 ]
]
]
]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| reliabilities
| gen_reliabilities
[ system
series
| parallel

59

60

CHAPTER 4. DAKOTA INPUT SPECIFICATION

]

[
[
[

[
)

]
]
reliability_levels REALLIST
[ num_reliability_levels INTEGERLIST ]
]
max_iterations INTEGER >= 0 ]
convergence_tolerance REAL ]
distribution
cumulative
| complementary
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
model_pointer STRING ]

|
( global_reliability ALIAS nond_global_reliability
x_gaussian_process ALIAS x_kriging
| u_gaussian_process ALIAS u_kriging
[ surfpack
| dakota ]
[ import_build_points_file ALIAS import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ use_derivatives ]
[ seed INTEGER > 0 ]
[ rng
mt19937
| rnum2
]
[ response_levels REALLIST
[ num_response_levels INTEGERLIST ]
[ compute
probabilities
| gen_reliabilities
[ system
series

4.4. INPUT SPEC SUMMARY

[
[
[

[
)

| parallel
]
]
]
max_iterations INTEGER >= 0 ]
convergence_tolerance REAL ]
distribution
cumulative
| complementary
]
probability_levels REALLIST
[ num_probability_levels INTEGERLIST ]
]
gen_reliability_levels REALLIST
[ num_gen_reliability_levels INTEGERLIST ]
]
model_pointer STRING ]

|
( fsu_quasi_mc
halton
| hammersley
[ latinize ]
[ quality_metrics ]
[ variance_based_decomp
[ drop_tolerance REAL ]
]
[ samples INTEGER ]
[ fixed_sequence ]
[ sequence_start INTEGERLIST ]
[ sequence_leap INTEGERLIST ]
[ prime_base INTEGERLIST ]
[ max_iterations INTEGER >= 0 ]
[ model_pointer STRING ]
)
|
( vector_parameter_study
final_point REALLIST
| step_vector REALLIST
num_steps INTEGER
[ model_pointer STRING ]
)
|
( list_parameter_study
list_of_points REALLIST
|
( import_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
)
[ model_pointer STRING ]
)
|
( centered_parameter_study

61

62

CHAPTER 4. DAKOTA INPUT SPECIFICATION

step_vector REALLIST
steps_per_variable ALIAS deltas_per_variable INTEGERLIST
[ model_pointer STRING ]
)
|
( multidim_parameter_study
partitions INTEGERLIST
[ model_pointer STRING ]
)
|
( richardson_extrap
estimate_order
| converge_order
| converge_qoi
[ refinement_rate REAL ]
[ convergence_tolerance REAL ]
[ max_iterations INTEGER >= 0 ]
[ model_pointer STRING ]
)

KEYWORD model
[ id_model STRING ]
[ variables_pointer STRING ]
[ responses_pointer STRING ]
[ hierarchical_tagging ]
( single
[ interface_pointer STRING ]
)
|
( surrogate
[ id_surrogates INTEGERLIST ]
( global
( gaussian_process ALIAS kriging
( dakota
[ point_selection ]
[ trend
constant
| linear
| reduced_quadratic
]
)
|
( surfpack
[ trend
constant
| linear
| reduced_quadratic
| quadratic
]
[ optimization_method STRING ]
[ max_trials INTEGER > 0 ]
[ nugget REAL > 0
| find_nugget INTEGER ]
[ correlation_lengths REALLIST ]
[ export_model
[ filename_prefix STRING ]
( formats
[ text_archive ]
[ binary_archive ]
[ algebraic_file ]
[ algebraic_console ]
)

4.4. INPUT SPEC SUMMARY

]
)
)
|
( mars
[ max_bases INTEGER ]
[ interpolation
linear
| cubic
]
[ export_model
[ filename_prefix STRING ]
( formats
[ text_archive ]
[ binary_archive ]
)
]
)
|
( moving_least_squares
[ basis_order ALIAS poly_order INTEGER >= 0 ]
[ weight_function INTEGER ]
[ export_model
[ filename_prefix STRING ]
( formats
[ text_archive ]
[ binary_archive ]
)
]
)
|
( neural_network
[ max_nodes ALIAS nodes INTEGER ]
[ range REAL ]
[ random_weight INTEGER ]
[ export_model
[ filename_prefix STRING ]
( formats
[ text_archive ]
[ binary_archive ]
[ algebraic_file ]
[ algebraic_console ]
)
]
)
|
( radial_basis
[ bases INTEGER ]
[ max_pts INTEGER ]
[ min_partition INTEGER ]
[ max_subsets INTEGER ]
[ export_model
[ filename_prefix STRING ]
( formats
[ text_archive ]
[ binary_archive ]
[ algebraic_file ]
[ algebraic_console ]
)
]
)
|

63

64

CHAPTER 4. DAKOTA INPUT SPECIFICATION

( polynomial
basis_order INTEGER >= 0
| linear
| quadratic
| cubic
[ export_model
[ filename_prefix STRING ]
( formats
[ text_archive ]
[ binary_archive ]
[ algebraic_file ]
[ algebraic_console ]
)
]
)
[ domain_decomposition
[ cell_type STRING ]
[ support_layers INTEGER ]
[ discontinuity_detection
jump_threshold REAL
| gradient_threshold REAL
]
]
[ total_points INTEGER
| minimum_points
| recommended_points ]
[ dace_method_pointer STRING
| actual_model_pointer STRING ]
[ reuse_points ALIAS reuse_samples
all
| region
| none
]
[ import_build_points_file ALIAS import_points_file ALIAS samples_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
[ export_approx_points_file ALIAS export_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
]
[ use_derivatives ]
[ correction
zeroth_order
| first_order
| second_order
additive

4.4. INPUT SPEC SUMMARY

| multiplicative
| combined
]
[ metrics ALIAS diagnostics STRINGLIST
[ cross_validation
[ folds INTEGER
| percent REAL ]
]
[ press ]
]
[ import_challenge_points_file ALIAS challenge_points_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ eval_id ]
[ interface_id ]
]
|
( freeform
[ active_only ]
]
)
|
( multipoint
tana
actual_model_pointer STRING
)
|
( local
taylor_series
actual_model_pointer STRING
)
|
( hierarchical
low_fidelity_model_pointer STRING
high_fidelity_model_pointer STRING
( correction
zeroth_order
| first_order
| second_order
additive
| multiplicative
| combined
)
)
)
|
( nested
[ optional_interface_pointer STRING
[ optional_interface_responses_pointer STRING ]
]
( sub_method_pointer STRING
[ iterator_servers INTEGER > 0 ]
[ iterator_scheduling
master
| peer
]
[ processors_per_iterator INTEGER > 0 ]
[ primary_variable_mapping STRINGLIST ]
[ secondary_variable_mapping STRINGLIST ]
[ primary_response_mapping REALLIST ]

65

66

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ secondary_response_mapping REALLIST ]
)
)

KEYWORD12 variables
[ id_variables STRING ]
[ active
all
| design
| uncertain
| aleatory
| epistemic
| state
]
[ mixed
| relaxed ]
[ continuous_design INTEGER > 0
[ initial_point ALIAS cdv_initial_point REALLIST ]
[ lower_bounds ALIAS cdv_lower_bounds REALLIST ]
[ upper_bounds ALIAS cdv_upper_bounds REALLIST ]
[ scale_types ALIAS cdv_scale_types STRINGLIST ]
[ scales ALIAS cdv_scales REALLIST ]
[ descriptors ALIAS cdv_descriptors STRINGLIST ]
]
[ discrete_design_range INTEGER > 0
[ initial_point ALIAS ddv_initial_point INTEGERLIST ]
[ lower_bounds ALIAS ddv_lower_bounds INTEGERLIST ]
[ upper_bounds ALIAS ddv_upper_bounds INTEGERLIST ]
[ descriptors ALIAS ddv_descriptors STRINGLIST ]
]
[ discrete_design_set
[ integer INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values INTEGERLIST
[ categorical STRINGLIST
[ adjacency_matrix INTEGERLIST ]
]
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
[ string INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values STRINGLIST
[ adjacency_matrix INTEGERLIST ]
[ initial_point STRINGLIST ]
[ descriptors STRINGLIST ]
]
[ real INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values REALLIST
[ categorical STRINGLIST
[ adjacency_matrix INTEGERLIST ]
]
[ initial_point REALLIST ]
[ descriptors STRINGLIST ]
]
]
[ normal_uncertain INTEGER > 0
means ALIAS nuv_means REALLIST
std_deviations ALIAS nuv_std_deviations REALLIST
[ lower_bounds ALIAS nuv_lower_bounds REALLIST ]
[ upper_bounds ALIAS nuv_upper_bounds REALLIST ]

4.4. INPUT SPEC SUMMARY

[ initial_point REALLIST ]
[ descriptors ALIAS nuv_descriptors STRINGLIST ]
]
lognormal_uncertain INTEGER > 0
( lambdas ALIAS lnuv_lambdas REALLIST
zetas ALIAS lnuv_zetas REALLIST
)
|
( means ALIAS lnuv_means REALLIST
std_deviations ALIAS lnuv_std_deviations REALLIST
| error_factors ALIAS lnuv_error_factors REALLIST
)
[ lower_bounds ALIAS lnuv_lower_bounds REALLIST ]
[ upper_bounds ALIAS lnuv_upper_bounds REALLIST ]
[ initial_point REALLIST ]
[ descriptors ALIAS lnuv_descriptors STRINGLIST ]
]
uniform_uncertain INTEGER > 0
lower_bounds ALIAS uuv_lower_bounds REALLIST
upper_bounds ALIAS uuv_upper_bounds REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS uuv_descriptors STRINGLIST ]
]
loguniform_uncertain INTEGER > 0
lower_bounds ALIAS luuv_lower_bounds REALLIST
upper_bounds ALIAS luuv_upper_bounds REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS luuv_descriptors STRINGLIST ]
]
triangular_uncertain INTEGER > 0
modes ALIAS tuv_modes REALLIST
lower_bounds ALIAS tuv_lower_bounds REALLIST
upper_bounds ALIAS tuv_upper_bounds REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS tuv_descriptors STRINGLIST ]
]
exponential_uncertain INTEGER > 0
betas ALIAS euv_betas REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS euv_descriptors STRINGLIST ]
]
beta_uncertain INTEGER > 0
alphas ALIAS buv_alphas REALLIST
betas ALIAS buv_betas REALLIST
lower_bounds ALIAS buv_lower_bounds REALLIST
upper_bounds ALIAS buv_upper_bounds REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS buv_descriptors STRINGLIST ]
]
gamma_uncertain INTEGER > 0
alphas ALIAS gauv_alphas REALLIST
betas ALIAS gauv_betas REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS gauv_descriptors STRINGLIST ]
]
gumbel_uncertain INTEGER > 0
alphas ALIAS guuv_alphas REALLIST
betas ALIAS guuv_betas REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS guuv_descriptors STRINGLIST ]
]
frechet_uncertain INTEGER > 0

67

68

CHAPTER 4. DAKOTA INPUT SPECIFICATION

alphas ALIAS fuv_alphas REALLIST

betas ALIAS fuv_betas REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS fuv_descriptors STRINGLIST ]
]
weibull_uncertain INTEGER > 0
alphas ALIAS wuv_alphas REALLIST
betas ALIAS wuv_betas REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS wuv_descriptors STRINGLIST ]
]
histogram_bin_uncertain INTEGER > 0
[ pairs_per_variable ALIAS num_pairs INTEGERLIST ]
abscissas ALIAS huv_bin_abscissas REALLIST
ordinates ALIAS huv_bin_ordinates REALLIST
| counts ALIAS huv_bin_counts REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS huv_bin_descriptors STRINGLIST ]
]
poisson_uncertain INTEGER > 0
lambdas REALLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
binomial_uncertain INTEGER > 0
probability_per_trial ALIAS prob_per_trial REALLIST
num_trials INTEGERLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
negative_binomial_uncertain INTEGER > 0
probability_per_trial ALIAS prob_per_trial REALLIST
num_trials INTEGERLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
geometric_uncertain INTEGER > 0
probability_per_trial ALIAS prob_per_trial REALLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
hypergeometric_uncertain INTEGER > 0
total_population INTEGERLIST
selected_population INTEGERLIST
num_drawn INTEGERLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
histogram_point_uncertain
[ integer INTEGER > 0
[ pairs_per_variable ALIAS num_pairs INTEGERLIST ]
abscissas INTEGERLIST
counts REALLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
[ string INTEGER > 0
[ pairs_per_variable ALIAS num_pairs INTEGERLIST ]
abscissas STRINGLIST
counts REALLIST
[ initial_point STRINGLIST ]
[ descriptors STRINGLIST ]

4.4. INPUT SPEC SUMMARY

[
[

69

]
[ real INTEGER > 0
[ pairs_per_variable ALIAS num_pairs INTEGERLIST ]
abscissas REALLIST
counts REALLIST
[ initial_point REALLIST ]
[ descriptors STRINGLIST ]
]
]
uncertain_correlation_matrix REALLIST ]
continuous_interval_uncertain ALIAS interval_uncertain INTEGER > 0
[ num_intervals ALIAS iuv_num_intervals INTEGERLIST ]
[ interval_probabilities ALIAS interval_probs ALIAS iuv_interval_probs REALLIST ]
lower_bounds REALLIST
upper_bounds REALLIST
[ initial_point REALLIST ]
[ descriptors ALIAS iuv_descriptors STRINGLIST ]
]
discrete_interval_uncertain ALIAS discrete_uncertain_range INTEGER > 0
[ num_intervals INTEGERLIST ]
[ interval_probabilities ALIAS interval_probs ALIAS range_probabilities ALIAS range_probs REALLIST ]
lower_bounds INTEGERLIST
upper_bounds INTEGERLIST
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
discrete_uncertain_set
[ integer INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values INTEGERLIST
[ set_probabilities ALIAS set_probs REALLIST ]
[ categorical STRINGLIST ]
[ initial_point INTEGERLIST ]
[ descriptors STRINGLIST ]
]
[ string INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values STRINGLIST
[ set_probabilities ALIAS set_probs REALLIST ]
[ initial_point STRINGLIST ]
[ descriptors STRINGLIST ]
]
[ real INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values REALLIST
[ set_probabilities ALIAS set_probs REALLIST ]
[ categorical STRINGLIST ]
[ initial_point REALLIST ]
[ descriptors STRINGLIST ]
]
]
continuous_state INTEGER > 0
[ initial_state ALIAS csv_initial_state REALLIST ]
[ lower_bounds ALIAS csv_lower_bounds REALLIST ]
[ upper_bounds ALIAS csv_upper_bounds REALLIST ]
[ descriptors ALIAS csv_descriptors STRINGLIST ]
]
discrete_state_range INTEGER > 0
[ initial_state ALIAS dsv_initial_state INTEGERLIST ]
[ lower_bounds ALIAS dsv_lower_bounds INTEGERLIST ]
[ upper_bounds ALIAS dsv_upper_bounds INTEGERLIST ]
[ descriptors ALIAS dsv_descriptors STRINGLIST ]

70

CHAPTER 4. DAKOTA INPUT SPECIFICATION

]
[ discrete_state_set
[ integer INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values INTEGERLIST
[ categorical STRINGLIST ]
[ initial_state INTEGERLIST ]
[ descriptors STRINGLIST ]
]
[ string INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values STRINGLIST
[ initial_state STRINGLIST ]
[ descriptors STRINGLIST ]
]
[ real INTEGER > 0
[ elements_per_variable ALIAS num_set_values INTEGERLIST ]
elements ALIAS set_values REALLIST
[ categorical STRINGLIST ]
[ initial_state REALLIST ]
[ descriptors STRINGLIST ]
]
]

KEYWORD12 interface
[ id_interface STRING ]
[ algebraic_mappings STRING ]
[ analysis_drivers STRINGLIST
[ analysis_components STRINGLIST ]
[ input_filter STRING ]
[ output_filter STRING ]
( system
| fork
[ parameters_file STRING ]
[ results_file STRING ]
[ allow_existing_results ]
[ verbatim ]
[ aprepro ALIAS dprepro ]
[ labeled ]
[ file_tag ]
[ file_save ]
[ work_directory
[ named STRING ]
[ directory_tag ALIAS dir_tag ]
[ directory_save ALIAS dir_save ]
[ link_files STRINGLIST ]
[ copy_files STRINGLIST ]
[ replace ]
]
)
|
( direct
[ processors_per_analysis INTEGER > 0 ]
)
| matlab
|
( python
[ numpy ]
)
| scilab
| grid
[ failure_capture

4.4. INPUT SPEC SUMMARY

[
[

[
[
[

71

abort
| retry INTEGER
| recover REALLIST
| continuation
]
[ deactivate
[ active_set_vector ]
[ evaluation_cache ]
[ strict_cache_equality
[ cache_tolerance REAL ]
]
[ restart_file ]
]
]
asynchronous
[ evaluation_concurrency INTEGER > 0 ]
[ local_evaluation_scheduling
dynamic
| static
]
[ analysis_concurrency INTEGER > 0 ]
]
evaluation_servers INTEGER > 0 ]
evaluation_scheduling
master
|
( peer
dynamic
| static
)
]
processors_per_evaluation INTEGER > 0 ]
analysis_servers INTEGER > 0 ]
analysis_scheduling
master
| peer
]

KEYWORD12 responses
[ id_responses STRING ]
[ descriptors ALIAS response_descriptors STRINGLIST ]
( objective_functions ALIAS num_objective_functions INTEGER >= 0
[ sense STRINGLIST ]
[ primary_scale_types ALIAS objective_function_scale_types STRINGLIST ]
[ primary_scales ALIAS objective_function_scales REALLIST ]
[ weights ALIAS multi_objective_weights REALLIST ]
[ nonlinear_inequality_constraints ALIAS num_nonlinear_inequality_constraints INTEGER >= 0
[ lower_bounds ALIAS nonlinear_inequality_lower_bounds REALLIST ]
[ upper_bounds ALIAS nonlinear_inequality_upper_bounds REALLIST ]
[ scale_types ALIAS nonlinear_inequality_scale_types STRINGLIST ]
[ scales ALIAS nonlinear_inequality_scales REALLIST ]
]
[ nonlinear_equality_constraints ALIAS num_nonlinear_equality_constraints INTEGER >= 0
[ targets ALIAS nonlinear_equality_targets REALLIST ]
[ scale_types ALIAS nonlinear_equality_scale_types STRINGLIST ]
[ scales ALIAS nonlinear_equality_scales REALLIST ]
]
[ scalar_objectives ALIAS num_scalar_objectives INTEGER >= 0 ]
[ field_objectives ALIAS num_field_objectives INTEGER >= 0
lengths INTEGERLIST
[ num_coordinates_per_field INTEGERLIST ]
[ read_field_coordinates ]

72

CHAPTER 4. DAKOTA INPUT SPECIFICATION

]
)
|
( calibration_terms ALIAS least_squares_terms ALIAS num_least_squares_terms INTEGER >= 0
[ scalar_calibration_terms INTEGER >= 0 ]
[ field_calibration_terms INTEGER >= 0
lengths INTEGERLIST
[ num_coordinates_per_field INTEGERLIST ]
[ read_field_coordinates ]
]
[ primary_scale_types ALIAS calibration_term_scale_types ALIAS least_squares_term_scale_types STRINGLIST ]
[ primary_scales ALIAS calibration_term_scales ALIAS least_squares_term_scales REALLIST ]
[ weights ALIAS calibration_weights ALIAS least_squares_weights REALLIST ]
[ ( calibration_data
[ num_experiments INTEGER >= 0 ]
[ num_config_variables INTEGER >= 0 ]
[ variance_type STRINGLIST ]
[ scalar_data_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ exp_id ]
]
|
( freeform
]
[ interpolate ]
)
|
( calibration_data_file ALIAS least_squares_data_file STRING
[ annotated
|
( custom_annotated
[ header ]
[ exp_id ]
]
|
( freeform
[ num_experiments INTEGER >= 0 ]
[ num_config_variables INTEGER >= 0 ]
[ variance_type STRINGLIST ]
]
[ nonlinear_inequality_constraints ALIAS num_nonlinear_inequality_constraints INTEGER >= 0
[ lower_bounds ALIAS nonlinear_inequality_lower_bounds REALLIST ]
[ upper_bounds ALIAS nonlinear_inequality_upper_bounds REALLIST ]
[ scale_types ALIAS nonlinear_inequality_scale_types STRINGLIST ]
[ scales ALIAS nonlinear_inequality_scales REALLIST ]
]
[ nonlinear_equality_constraints ALIAS num_nonlinear_equality_constraints INTEGER >= 0
[ targets ALIAS nonlinear_equality_targets REALLIST ]
[ scale_types ALIAS nonlinear_equality_scale_types STRINGLIST ]
[ scales ALIAS nonlinear_equality_scales REALLIST ]
]
)
|
( response_functions ALIAS num_response_functions INTEGER >= 0
[ scalar_responses ALIAS num_scalar_responses INTEGER >= 0 ]
[ field_responses ALIAS num_field_responses INTEGER >= 0
lengths INTEGERLIST
[ num_coordinates_per_field INTEGERLIST ]
[ read_field_coordinates ]

4.4. INPUT SPEC SUMMARY

]
)
no_gradients
| analytic_gradients
|
( mixed_gradients
id_numerical_gradients INTEGERLIST
id_analytic_gradients INTEGERLIST
[ method_source ]
[ ( dakota
[ ignore_bounds ]
[ relative
| absolute
| bounds ]
)
| vendor ]
[ interval_type ]
[ forward
| central ]
[ fd_step_size ALIAS fd_gradient_step_size REALLIST ]
)
|
( numerical_gradients
[ method_source ]
[ ( dakota
[ ignore_bounds ]
[ relative
| absolute
| bounds ]
)
| vendor ]
[ interval_type ]
[ forward
| central ]
[ fd_step_size ALIAS fd_gradient_step_size REALLIST ]
)
no_hessians
|
( numerical_hessians
[ fd_step_size ALIAS fd_hessian_step_size REALLIST ]
[ relative
| absolute
| bounds ]
[ forward
| central ]
)
|
( quasi_hessians
( bfgs
[ damped ]
)
| sr1
)
| analytic_hessians
|
( mixed_hessians
[ id_numerical_hessians INTEGERLIST
[ fd_step_size ALIAS fd_hessian_step_size REALLIST ]
]
[ relative
| absolute
| bounds ]

73

74

CHAPTER 4. DAKOTA INPUT SPECIFICATION

[ forward
| central ]
[ id_quasi_hessians INTEGERLIST
( bfgs
[ damped ]
)
| sr1
]
[ id_analytic_hessians INTEGERLIST ]
)

Chapter 5

Topics Area
This page introduces the user to the topics used to organize keywords.
admin
dakota IO
dakota concepts
models
variables
responses
interface
methods
advanced topics
packages

5.1

admin

Description
This is only for management while ref man is under construction

Related Topics
empty
problem
not yet reviewed
75

76

CHAPTER 5. TOPICS AREA

Related Keywords
5.1.1

empty

Description
This topic tracks the keywords which do not have content in the reference manual

Related Topics
Related Keywords
5.1.2

problem

Description
empty

Related Topics
Related Keywords
5.1.3

not yet reviewed

Description
Not yet reviewed.

Related Topics
Related Keywords

5.2

dakota IO

Description
Keywords and Concepts relating inputs to Dakota and outputs from Dakota

Related Topics
dakota inputs
dakota output
file formats

Related Keywords
error file : Base filename for error redirection
output file : Base filename for output redirection
input : Base filename for post-run mode data input

5.2. DAKOTA IO

77

output : Base filename for post-run mode data output

input : Base filename for pre-run mode data input
output : Base filename for pre-run mode data output
read restart : Base filename for restart file read
stop restart : Evaluation ID number at which to stop reading restart file
input : Base filename for run mode data input
output : Base filename for run mode data output
write restart : Base filename for restart file write

5.2.1

dakota inputs

Description
empty

Related Topics
block
data import capabilities

Related Keywords
5.2.2

block

Description
A block is the highest level of keyword organization in Dakota. There are currently 6 blocks in the Dakota input
spec:

Related Topics
block identifier
block pointer

Related Keywords
environment : Top-level settings for Dakota execution
interface : Specifies how function evaluations will be performed in order to map the variables into the
responses.
method : Begins Dakota method selection and behavioral settings.
model : Specifies how variables are mapped into a set of responses
responses : Description of the model output data returned to Dakota upon evaluation of an interface.
variables : Specifies the parameter set to be iterated by a particular method.

78

CHAPTER 5. TOPICS AREA

block identifier

Description
empty

Related Topics
Related Keywords
id interface : Name the interface block; helpful when there are multiple
id method : Name the method block; helpful when there are multiple
id model : Give the model block an identifying name, in case of multiple model blocks
id responses : Name the response block, helpful when there are multiple
block pointer

Description
See block pointer for details about pointers.

Related Topics
Related Keywords
top method pointer : Identify which method leads the Dakota study
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method

5.2. DAKOTA IO
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer list : Associate models with method names
method pointer list : Pointers to methods to execute sequantially or collaboratively
global model pointer : Pointer to model used by global method
global method pointer : Pointer to global method
local model pointer : Pointer to model used by local method
local method pointer : Pointer to local method
model pointer list : Associate models with method names
method pointer list : Pointers to methods to execute sequantially or collaboratively
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method

79

80

CHAPTER 5. TOPICS AREA

model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to run from each starting point
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to optimization or least-squares sub-method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method

5.2. DAKOTA IO
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
optional interface pointer : Pointer to interface that provides non-nested responses
optional interface responses pointer : Pointer to responses block that defines non-nested responses
sub method pointer : The sub method pointer specifies the method block for the sub-iterator
responses pointer : Specify which reponses block will be used by this model block
interface pointer : Interface block pointer for the single model type
dace method pointer : Specify a method to gather training data
high fidelity model pointer : Pointer to high fidelity model
low fidelity model pointer : Pointer to low fidelity model
actual model pointer : Pointer to specify a truth model, from which to construct a surrogate
actual model pointer : Pointer to specify a truth model, from which to construct a surrogate
variables pointer : Specify which variables block will be included with this model block
id variables : Name the variables block; helpful when there are multiple

5.2.3

data import capabilities

Description
empty

Related Topics
Related Keywords
5.2.4

dakota output

Description
empty

81

82

CHAPTER 5. TOPICS AREA

Related Topics
Related Keywords
graphics : Display a 2D graphics window of variables and responses
output precision : Control the output precision
results output : (Experimental) Write a summary file containing the final results
results output file : The base file name of the results file
tabular data : Write a tabular results file with variable and response history
tabular data file : File name for tabular data output
output : Control how much method information is written to the screen and output file

5.2.5

file formats

Description
See sections Inputs to Dakota and Outputs from Dakota in the Dakota Users Manual[4].

Related Topics
Related Keywords
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
aprepro : Write parameters files in APREPRO syntax
labeled : Requires correct function value labels in results file
aprepro : Write parameters files in APREPRO syntax
labeled : Requires correct function value labels in results file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format

5.2. DAKOTA IO
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file

83

84

CHAPTER 5. TOPICS AREA

annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format

5.2. DAKOTA IO
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format

85

86

CHAPTER 5. TOPICS AREA

annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file

5.3. DAKOTA CONCEPTS

annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
active only : Import only active variables from tabular data file
annotated : Selects annotated tabular file format
custom annotated : Selects custom-annotated tabular file format
freeform : Selects freeform file format
annotated : Selects annotated tabular file format for experiment data
custom annotated : Selects custom-annotated tabular file format for experiment data
freeform : Selects free-form tabular file format for experiment data
annotated : Selects annotated tabular file format for experiment data
custom annotated : Selects custom-annotated tabular file format for experiment data
freeform : Selects free-form tabular file format for experiment data

5.3

dakota concepts

Description
Miscallaneous concepts related to Dakota operation

Related Topics
method independent controls
block
strategies
command line options
restarts
pointers

87

88

CHAPTER 5. TOPICS AREA

Related Keywords
5.3.1

method independent controls

Description
The <method independent controls> are those controls which are valid for a variety of methods. In
some cases, these controls are abstractions which may have slightly different implementations from one method
to the next. While each of these controls is not valid for every method, the controls are valid for enough methods
that it was reasonable to consolidate the specifications.

Related Topics
linear constraints

Related Keywords
max iterations : Stopping criterion based on number of iterations
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
max function evaluations : Stopping criteria based on number of function evaluations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations

5.3. DAKOTA CONCEPTS

89

max iterations : Stopping criterion based on number of iterations

scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
max function evaluations : Stopping criteria based on number of function evaluations
scaling : Turn on scaling for variables, responses, and constraints

90

CHAPTER 5. TOPICS AREA

constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients

5.3. DAKOTA CONCEPTS

91

constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
max iterations : Stopping criterion based on number of iterations
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
final solutions : Number of designs returned as the best solutions
max iterations : Stopping criterion based on number of iterations
max iterations : Stopping criterion based on number of iterations
max function evaluations : Stopping criteria based on number of function evaluations
scaling : Turn on scaling for variables, responses, and constraints
max function evaluations : Stopping criteria based on number of function evaluations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
max iterations : Stopping criterion based on number of iterations
id method : Name the method block; helpful when there are multiple
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
max function evaluations : Stopping criteria based on number of function evaluations

92

CHAPTER 5. TOPICS AREA

max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics

5.3. DAKOTA CONCEPTS

max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations

93

94

CHAPTER 5. TOPICS AREA

max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
output : Control how much method information is written to the screen and output file
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max function evaluations : Stopping criteria based on number of function evaluations
max iterations : Stopping criterion based on number of iterations
scaling : Turn on scaling for variables, responses, and constraints
speculative : Compute speculative gradients
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations
max iterations : Stopping criterion based on number of iterations
constraint tolerance : The maximum allowable value of constraint violation still considered to be feasible
convergence tolerance : Stopping criterion based on convergence of the objective function or statistics
max iterations : Stopping criterion based on number of iterations

5.3.2

linear constraints

Description
Many methods use linear equality or inequality constraints.

5.3. DAKOTA CONCEPTS

Related Topics
Related Keywords
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities

95

96

CHAPTER 5. TOPICS AREA

linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints

5.3. DAKOTA CONCEPTS

linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled

97

98

CHAPTER 5. TOPICS AREA

linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities

5.3. DAKOTA CONCEPTS

linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints

99

100

CHAPTER 5. TOPICS AREA

linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled

5.3. DAKOTA CONCEPTS

101

linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint
linear equality constraint matrix : Define coefficients of the linear equalities
linear equality scale types : Specify how each linear equality constraint is scaled
linear equality scales : Define the characteristic values to scale linear equalities
linear equality targets : Define target values for the linear equality constraints
linear inequality constraint matrix : Define coefficients of the linear inequality constraints
linear inequality lower bounds : Define lower bounds for the linear inequality constraint
linear inequality scale types : Specify how each linear inequality constraint is scaled
linear inequality scales : Define the characteristic values to scale linear inequalities
linear inequality upper bounds : Define upper bounds for the linear inequality constraint

5.3.3

block

Description
A block is the highest level of keyword organization in Dakota. There are currently 6 blocks in the Dakota input
spec:

Related Topics
block identifier
block pointer

102

CHAPTER 5. TOPICS AREA

Related Keywords
environment : Top-level settings for Dakota execution
interface : Specifies how function evaluations will be performed in order to map the variables into the
responses.
method : Begins Dakota method selection and behavioral settings.
model : Specifies how variables are mapped into a set of responses
responses : Description of the model output data returned to Dakota upon evaluation of an interface.
variables : Specifies the parameter set to be iterated by a particular method.
block identifier

Description
empty

Related Topics
Related Keywords
id interface : Name the interface block; helpful when there are multiple
id method : Name the method block; helpful when there are multiple
id model : Give the model block an identifying name, in case of multiple model blocks
id responses : Name the response block, helpful when there are multiple
block pointer

Description
See block pointer for details about pointers.

Related Topics
Related Keywords
top method pointer : Identify which method leads the Dakota study
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method

5.3. DAKOTA CONCEPTS

model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer list : Associate models with method names
method pointer list : Pointers to methods to execute sequantially or collaboratively
global model pointer : Pointer to model used by global method

103

104

CHAPTER 5. TOPICS AREA

global method pointer : Pointer to global method
local model pointer : Pointer to model used by local method
local method pointer : Pointer to local method
model pointer list : Associate models with method names
method pointer list : Pointers to methods to execute sequantially or collaboratively
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to run from each starting point
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to optimization or least-squares sub-method
model pointer : Identifier for model block to be used by a method

5.3. DAKOTA CONCEPTS

model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
optional interface pointer : Pointer to interface that provides non-nested responses
optional interface responses pointer : Pointer to responses block that defines non-nested responses
sub method pointer : The sub method pointer specifies the method block for the sub-iterator
responses pointer : Specify which reponses block will be used by this model block
interface pointer : Interface block pointer for the single model type
dace method pointer : Specify a method to gather training data
high fidelity model pointer : Pointer to high fidelity model
low fidelity model pointer : Pointer to low fidelity model
actual model pointer : Pointer to specify a truth model, from which to construct a surrogate
actual model pointer : Pointer to specify a truth model, from which to construct a surrogate
variables pointer : Specify which variables block will be included with this model block
id variables : Name the variables block; helpful when there are multiple

5.3.4

strategies

Description
empty

Related Topics
advanced strategies

105

106

CHAPTER 5. TOPICS AREA

Related Keywords
5.3.5

advanced strategies

Description
empty

Related Topics
Related Keywords
5.3.6

command line options

Description
empty

Related Topics
Related Keywords
check : Invoke Dakota in input check mode
error file : Base filename for error redirection
output file : Base filename for output redirection
post run : Invoke Dakota with post-run mode active
pre run : Invoke Dakota with pre-run mode active
read restart : Base filename for restart file read
run : Invoke Dakota with run mode active
write restart : Base filename for restart file write

5.3.7

restarts

Description
empty

Related Topics
Related Keywords
5.3.8

pointers

Description
For all pointer specifications, if a pointer string is specified and no corresponding id string is available, Dakota
will exit with an error message.
If the pointer is optional and no pointer string is specified, then the last specification parsed will be used.
It is appropriate to omit optional cross-referencing whenever the relationships are unambiguous due to the
presence of only one specification.

5.3. DAKOTA CONCEPTS

Related Topics
block pointer
objective function pointer

Related Keywords
5.3.9

block pointer

Description
See block pointer for details about pointers.

Related Topics
Related Keywords
top method pointer : Identify which method leads the Dakota study
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method

107

108

CHAPTER 5. TOPICS AREA

model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer list : Associate models with method names
method pointer list : Pointers to methods to execute sequantially or collaboratively
global model pointer : Pointer to model used by global method
global method pointer : Pointer to global method
local model pointer : Pointer to model used by local method
local method pointer : Pointer to local method
model pointer list : Associate models with method names
method pointer list : Pointers to methods to execute sequantially or collaboratively
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method

5.3. DAKOTA CONCEPTS

method pointer : Pointer to sub-method to run from each starting point
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to optimization or least-squares sub-method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
method pointer : Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem
model pointer : Identifier for model block to be used by a method
model pointer : Identifier for model block to be used by a method

109

110

CHAPTER 5. TOPICS AREA

optional interface pointer : Pointer to interface that provides non-nested responses
optional interface responses pointer : Pointer to responses block that defines non-nested responses
sub method pointer : The sub method pointer specifies the method block for the sub-iterator
responses pointer : Specify which reponses block will be used by this model block
interface pointer : Interface block pointer for the single model type
dace method pointer : Specify a method to gather training data
high fidelity model pointer : Pointer to high fidelity model
low fidelity model pointer : Pointer to low fidelity model
actual model pointer : Pointer to specify a truth model, from which to construct a surrogate
actual model pointer : Pointer to specify a truth model, from which to construct a surrogate
variables pointer : Specify which variables block will be included with this model block
id variables : Name the variables block; helpful when there are multiple

5.3.10

objective function pointer

Description
See block pointer for details about pointers.

Related Topics
Related Keywords
id analytic gradients : Identify which analytical gradient corresponds to which response
id numerical gradients : Identify which numerical gradient corresponds to which response
id analytic hessians : Identify which analytical Hessian corresponds to which response
id numerical hessians : Identify which numerical-Hessian corresponds to which response
id quasi hessians : Identify which quasi-Hessian corresponds to which response

5.4

models

Description
Keywords and Concepts relating to the model block

5.4. MODELS

Related Topics
surrogate models
recast models
multifidelity models
reduced order models
nested models
advanced model recursion

Related Keywords
5.4.1

surrogate models

Description
empty

Related Topics
surrogate based optimization methods

Related Keywords
point selection : Enable greedy selection of well-spaced build points
export model : Exports surrogate model in user-selected format
filename prefix : User-customizable portion of exported model filenames
formats : Formats for surrogate model export
algebraic console : Export surrogate model in algebraic format to the console
algebraic file : Export surrogate model in algebraic format to a file
binary archive : Export surrogate model to a binary archive file
text archive : Export surrogate model to a plain-text archive file
export model : Exports surrogate model in user-selected format
filename prefix : User-customizable portion of exported model filenames
formats : Formats for surrogate model export
binary archive : Export surrogate model to a binary archive file
text archive : Export surrogate model to a plain-text archive file
metrics : Compute surrogate quality metrics
cross validation : Perform k-fold cross validation

111

112

CHAPTER 5. TOPICS AREA

export model : Exports surrogate model in user-selected format
filename prefix : User-customizable portion of exported model filenames
formats : Formats for surrogate model export
binary archive : Export surrogate model to a binary archive file
text archive : Export surrogate model to a plain-text archive file
export model : Exports surrogate model in user-selected format
filename prefix : User-customizable portion of exported model filenames
formats : Formats for surrogate model export
algebraic console : Export surrogate model in algebraic format to the console
algebraic file : Export surrogate model in algebraic format to a file
binary archive : Export surrogate model to a binary archive file
text archive : Export surrogate model to a plain-text archive file
max nodes : Maximum number of hidden layer nodes
random weight : (Inactive) Random weight control
range : Range for neural network random weights
export model : Exports surrogate model in user-selected format
filename prefix : User-customizable portion of exported model filenames
formats : Formats for surrogate model export
algebraic console : Export surrogate model in algebraic format to the console
algebraic file : Export surrogate model in algebraic format to a file
binary archive : Export surrogate model to a binary archive file
text archive : Export surrogate model to a plain-text archive file
bases : Initial number of radial basis functions
export model : Exports surrogate model in user-selected format
filename prefix : User-customizable portion of exported model filenames
formats : Formats for surrogate model export
algebraic console : Export surrogate model in algebraic format to the console
algebraic file : Export surrogate model in algebraic format to a file
binary archive : Export surrogate model to a binary archive file
text archive : Export surrogate model to a plain-text archive file

5.4. MODELS
max pts : Maximum number of RBF CVT points
max subsets : Number of trial RBF subsets
min partition : (Inactive) Minimum RBF partition
reuse points : Surrogate model training data reuse control

5.4.2

surrogate based optimization methods

Description
empty

Related Topics
Related Keywords
efficient global : Global Surrogate Based Optimization, a.k.a. EGO
surrogate based global : Global Surrogate Based Optimization
surrogate based local : Local Surrogate Based Optimization

5.4.3

recast models

Description
empty

Related Topics
Related Keywords
5.4.4

multifidelity models

Description
empty

Related Topics
Related Keywords
5.4.5

reduced order models

Description
empty

113

114

CHAPTER 5. TOPICS AREA

Related Topics
Related Keywords
5.4.6

nested models

Description
empty

Related Topics
Related Keywords
5.4.7

advanced model recursion

Description
empty

Related Topics
hybrid and recursions logic

Related Keywords
hybrid and recursions logic

Description
empty

Related Topics
Related Keywords

5.5

variables

Description
Keywords and concepts relating to the variables block

Related Topics
variable domain
variable type

5.5. VARIABLES

115

Related Keywords
5.5.1

variable domain

Description
Dakota variables can be grouped by their valid domains.
1. Mixed: continuous and discrete variables are treated separately
2. Relaxed: noncategorical discrete variables are relaxed and treated as continuous variables (categorical variables are non-relaxable and remain discrete)
Refer to mixed and relaxed for additional information.

Related Topics
continuous variables
discrete variables

Related Keywords
5.5.2

continuous variables

Description
This page collects information related to the topic of continuous design, uncertain, and state variables.

Related Topics
Related Keywords
beta uncertain : Aleatory uncertain variable - beta
continuous design : Continuous design variables; each defined by a real interval
continuous interval uncertain : Epistemic uncertain variable - values from one or more continuous intervals
continuous state : Continuous state variables
exponential uncertain : Aleatory uncertain variable - exponential
frechet uncertain : Aleatory uncertain variable - Frechet
gamma uncertain : Aleatory uncertain variable - gamma
gumbel uncertain : Aleatory uncertain variable - gumbel
histogram bin uncertain : Aleatory uncertain variable - continuous histogram
lognormal uncertain : Aleatory uncertain variable - lognormal
loguniform uncertain : Aleatory uncertain variable - loguniform
normal uncertain : Aleatory uncertain variable - normal (Gaussian)

116

CHAPTER 5. TOPICS AREA

triangular uncertain : Aleatory uncertain variable - triangular
uniform uncertain : Aleatory uncertain variable - uniform
weibull uncertain : Aleatory uncertain variable - Weibull

5.5.3

discrete variables

Description
This page discusses discrete design, uncertain, and state variables (which have discrete in their keyword name)
as they have similar specifications. These include:
1. Integer ranges
2. Sets of integers
3. Sets of reals
4. Sets of strings and each is described below.
In addition, some aleatory uncertain variables, e.g., binomial uncertain, are discrete integer-valued random
variables specified using parameters. These are described on their individual keyword pages.
Sets
Sets of integers, reals, and strings have similar specifications, though different value types.
The variables are specified using three keywords:
Variable declaration keyword - specifies the number of variables being defined
elements per variable - a list of positive integers specifying how many set members each variable
admits
Length = # of variables
elements - a list of the permissible integer values in ALL sets, concatenated together.
Length = sum of elements per variable, or an integer multiple of number of variables
The order is very important here.
The list is partitioned according to the values of elements per variable, and each partition is
assigned to a variable.
The ordering of elements per variable, and the partitions of elements must match the strings
from descriptors
For string variables, each string element value must be quoted and may contain alphanumeric, dash, underscore, and colon. White space, quote characters, and backslash/metacharacters are not permitted.
Examples are given on the pages:
discrete design set integer
discrete design set real
discrete design set string
discrete uncertain set integer

5.5. VARIABLES

117

discrete uncertain set real

discrete uncertain set string
Range
For discrete variables defined by range(s), the lower bounds and upper bounds restrict the permisible
values. For design variables, this constrains the feasible design space and is frequently used to prevent nonphysical
designs. This is a discrete interval variable that may take any integer value within bounds (e.g., [1, 4], allowing
values of 1, 2, 3, or 4). For some variable types, each variable is can be defined by multiple ranges.
Examples are given on the pages:
discrete interval uncertain

Related Topics
Related Keywords
binomial uncertain : Aleatory uncertain discrete variable - binomial
discrete design range : Discrete design variables; each defined by an integer interval
discrete design set : Set-valued discrete design variables
integer : Integer-valued discrete design variables
real : Real-valued discrete design variables
string : String-valued discrete design set variables
discrete interval uncertain : Epistemic uncertain variable - values from one or more discrete intervals
discrete state range : Discrete state variables; each defined by an integer interval
discrete state set : Set-valued discrete state variables
integer : Discrete state variables, each defined by a set of permissible integers
real : Discrete state variables, each defined by a set of permissible real numbers
string : String-valued discrete state set variables
discrete uncertain set : Set-valued discrete uncertain variables
integer : Discrete, epistemic uncertain variable - integers within a set
real : Discrete, epistemic uncertain variable - real numbers within a set
string : Discrete, epistemic uncertain variable - strings within a set
geometric uncertain : Aleatory uncertain discrete variable - geometric
histogram point uncertain : Aleatory uncertain variable - discrete histogram
hypergeometric uncertain : Aleatory uncertain discrete variable - hypergeometric
negative binomial uncertain : Aleatory uncertain discrete variable - negative binomial
poisson uncertain : Aleatory uncertain discrete variable - Poisson

118

CHAPTER 5. TOPICS AREA

5.5.4

variable type

Description
Dakota variables can be grouped by their type, including all, design, uncertain, aleatory, epistemic,
or state. There are certain situations where the user may want to explicitly control the subset of variables that is
considered active for a certain Dakota method, and override the default alignments between methods and variable
types. Refer to active for additional information.

Related Topics
design variables
aleatory uncertain variables
epistemic uncertain variables
state variables

Related Keywords
5.5.5

design variables

Description
Design variables are those variables which are modified for the purposes of computing an optimal design.
The most common type of design variables encountered in engineering applications are of the continuous type.
These variables may assume any real value within their bounds. All but a handful of the optimization algorithms
in Dakota support continuous design variables exclusively.

Related Topics
Related Keywords
continuous design : Continuous design variables; each defined by a real interval
discrete design range : Discrete design variables; each defined by an integer interval
discrete design set : Set-valued discrete design variables
integer : Integer-valued discrete design variables
real : Real-valued discrete design variables
string : String-valued discrete design set variables

5.5.6

aleatory uncertain variables

Description
Aleatory uncertainty is also known as inherent variability, irreducible uncertainty, or randomness.
Aleatory uncertainty is predominantly charaterized using probability theory. This is the only option implemented in Dakota.

5.5. VARIABLES

119

Related Topics
Related Keywords
beta uncertain : Aleatory uncertain variable - beta
binomial uncertain : Aleatory uncertain discrete variable - binomial
exponential uncertain : Aleatory uncertain variable - exponential
frechet uncertain : Aleatory uncertain variable - Frechet
gamma uncertain : Aleatory uncertain variable - gamma
geometric uncertain : Aleatory uncertain discrete variable - geometric
gumbel uncertain : Aleatory uncertain variable - gumbel
histogram bin uncertain : Aleatory uncertain variable - continuous histogram
histogram point uncertain : Aleatory uncertain variable - discrete histogram
hypergeometric uncertain : Aleatory uncertain discrete variable - hypergeometric
lognormal uncertain : Aleatory uncertain variable - lognormal
loguniform uncertain : Aleatory uncertain variable - loguniform
negative binomial uncertain : Aleatory uncertain discrete variable - negative binomial
normal uncertain : Aleatory uncertain variable - normal (Gaussian)
poisson uncertain : Aleatory uncertain discrete variable - Poisson
triangular uncertain : Aleatory uncertain variable - triangular
uniform uncertain : Aleatory uncertain variable - uniform
weibull uncertain : Aleatory uncertain variable - Weibull

5.5.7

epistemic uncertain variables

Description
Epistemic uncertainty is uncertainty due to lack of knowledge.
In Dakota, epistemic uncertainty is characterized by interval analysis or the Dempster-Shafer theory of evidence.
Note that epistemic uncertainty can also be modeled with probability density functions - similarly to aleatory
uncertainty Dakota does not support this capability.

120

CHAPTER 5. TOPICS AREA

Related Topics
Related Keywords
continuous interval uncertain : Epistemic uncertain variable - values from one or more continuous intervals
discrete interval uncertain : Epistemic uncertain variable - values from one or more discrete intervals
discrete uncertain set : Set-valued discrete uncertain variables
integer : Discrete, epistemic uncertain variable - integers within a set
real : Discrete, epistemic uncertain variable - real numbers within a set
string : Discrete, epistemic uncertain variable - strings within a set

5.5.8

state variables

Description
State variables provide a convenient mechanism for managing additional model parameterizations such as mesh
density, simulation convergence tolerances, and time step controls.
Only parameter studies and design of experiments methods will iterate on state variables.
The initial state is used as the only value for the state variable for all other methods, unless active
state is invoked.
If a method iterates on a state variable, the variable is treated as a design variable with the given bounds, or as
a uniform uncertain variable with the given bounds.
If the state variable is defined only by its bounds, and the method does NOT iterate on state variables, then the
initial state must be inferred.

Related Topics
Related Keywords
continuous state : Continuous state variables
discrete state range : Discrete state variables; each defined by an integer interval
discrete state set : Set-valued discrete state variables
integer : Discrete state variables, each defined by a set of permissible integers
real : Discrete state variables, each defined by a set of permissible real numbers
string : String-valued discrete state set variables

5.6

responses

Description
Keywords and concepts relating to the responses block

5.7. INTERFACE

121

Related Topics
response types

Related Keywords
5.6.1

response types

Description
The specification must be one of three types:
1. objective and constraint functions
2. calibration (least squares) terms and constraint functions
3. a generic response functions specification.
These correspond to (a) optimization, (b) deterministic (least squares) or stochastic (Bayesian) inversion, and
(c) general-purpose analyzer methods such as parameter studies, DACE, and UQ methods, respectively. Refer to
responses for additional details and examples.

Related Topics
Related Keywords

5.7

interface

Description
Keywords and Concepts relating to the interface block, which is used to connect Dakota to external analysis
codes (simulations, etc.)

Related Topics
simulation file management
workflow management
advanced simulation interfaces

Related Keywords
5.7.1

simulation file management

Description
empty

122

CHAPTER 5. TOPICS AREA

Related Topics
Related Keywords
5.7.2

workflow management

Description
empty

Related Topics
Related Keywords
5.7.3

advanced simulation interfaces

Description
empty

Related Topics
simulation failure
concurrency and parallelism

Related Keywords
simulation failure

Description
empty

Related Topics
Related Keywords
concurrency and parallelism

Description
empty

Related Topics
Related Keywords
processors per analysis : Specify the number of processors per analysis when Dakota is run in parallel
analysis scheduling : Specify the scheduling of concurrent analyses when Dakota is run in parallel
master : Specify a dedicated master partition for parallel analysis scheduling
peer : Specify a peer partition for parallel analysis scheduling

5.7. INTERFACE

123

analysis servers : Specify the number of analysis servers when Dakota is run in parallel
asynchronous : Specify analysis driver concurrency, when Dakota is run in serial
analysis concurrency : Limit the number of analysis drivers within an evaluation that Dakota will schedule
evaluation concurrency : Determine how many concurrent evaluations Dakota will schedule
local evaluation scheduling : Control how local asynchronous jobs are scheduled
master : Specify a dedicated master partition for parallel evaluation scheduling
peer : Specify a peer partition for parallel evaluation scheduling
dynamic : Specify dynamic scheduling in a peer partition when Dakota is run in parallel.
static : Specify static scheduling in a peer partition when Dakota is run in parallel.
evaluation servers : Specify the number of evaluation servers when Dakota is run in parallel
processors per evaluation : Specify the number of processors per evaluation server when Dakota is run in
parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel

124

CHAPTER 5. TOPICS AREA

5.8

methods

Description
Keywords and Concepts relating to the method block, including discussion of the different methods and algorithms availabe in Dakota

Related Topics
parameter studies
sensitivity analysis and design of experiments
uncertainty quantification
optimization and calibration

Related Keywords
5.8.1

parameter studies

Description
Parameter studies employ deterministic designs to explore the effect of parametric changes within simulation
models, yielding one form of sensitivity analysis. They can help assess simulation characteristics such as smoothness, multi-modality, robustness, and nonlinearity, which affect the choice of algorithms and controls in follow-on
optimization and UQ studies.
Dakotas parameter study methods compute response data sets at a selection of points in the parameter space.
These points may be specified as a vector, a list, a set of centered vectors, or a multi-dimensional grid. Capability
overviews and examples of the different types of parameter studies are provided in the Users Manual [4].
With the exception of output verbosity (a setting of silent will suppress some parameter study diagnostic
output), Dakotas parameter study methods do not make use of the method independent controls. Therefore, the
parameter study documentation which follows is limited to the method dependent controls for the vector, list,
centered, and multidimensional parameter study methods.

Related Topics
Related Keywords
centered parameter study : Samples variables along points moving out from a center point
list parameter study : Samples variables as a specified values
multidim parameter study : Samples variables on full factorial grid of study points
partitions : Samples variables on full factorial grid of study points
vector parameter study : Samples variables along a user-defined vector

5.8.2

sensitivity analysis and design of experiments

Description
empty

5.8. METHODS

125

Related Topics
design and analysis of computer experiments
sampling

Related Keywords
5.8.3

design and analysis of computer experiments

Description
Design and Analysis of Computer Experiments (DACE) methods compute response data sets at a selection of
points in the parameter space. Three libraries are provided for performing these studies: DDACE, FSUDace,
and PSUADE. The design of experiments methods do not currently make use of any of the method independent
controls.

Related Topics
Related Keywords
dace : Design and Analysis of Computer Experiments
fsu cvt : Design of Computer Experiments - Centroidal Voronoi Tessellation
fsu quasi mc : Design of Computer Experiments - Quasi-Monte Carlo sampling
hammersley : Use Hammersley sequences
psuade moat : Morris One-at-a-Time

5.8.4

sampling

Description
Sampling techniques are selected using the sampling method selection. This method generates sets of samples
according to the probability distributions of the uncertain variables and maps them into corresponding sets of
response functions, where the number of samples is specified by the samples integer specification. Means,
standard deviations, coefficients of variation (COVs), and 95% confidence intervals are computed for the response
functions. Probabilities and reliabilities may be computed for response levels specifications, and response
levels may be computed for either probability levels or reliability levels specifications (refer
to the Method Commands chapter in the Dakota Reference Manual[5] for additional information).
Currently, traditional Monte Carlo (MC) and Latin hypercube sampling (LHS) are supported by Dakota and
are chosen by specifying sample type as random or lhs. In Monte Carlo sampling, the samples are selected
randomly according to the user-specified probability distributions. Latin hypercube sampling is a stratified sampling technique for which the range of each uncertain variable is divided into Ns segments of equal probability,
where Ns is the number of samples requested. The relative lengths of the segments are determined by the nature
of the specified probability distribution (e.g., uniform has segments of equal width, normal has small segments
near the mean and larger segments in the tails). For each of the uncertain variables, a sample is selected randomly
from each of these equal probability segments. These Ns values for each of the individual parameters are then
combined in a shuffling operation to create a set of Ns parameter vectors with a specified correlation structure.
A feature of the resulting sample set is that every row and column in the hypercube of partitions has exactly one
sample. Since the total number of samples is exactly equal to the number of partitions used for each uncertain

126

CHAPTER 5. TOPICS AREA

variable, an arbitrary number of desired samples is easily accommodated (as compared to less flexible approaches
in which the total number of samples is a product or exponential function of the number of intervals for each
variable, i.e., many classical design of experiments methods).
Advantages of sampling-based methods include their relatively simple implementation and their independence
from the scientific disciplines involved in the analysis. The main drawback of these techniques is the large number
of function evaluations needed to generate converged statistics, which can render such an analysis computationally
very expensive, if not intractable, for real-world engineering applications. LHS techniques, in general, require
fewer samples than traditional Monte Carlo for the same accuracy in statistics, but they still can be prohibitively
expensive. For further information on the method and its relationship to other sampling techniques, one is referred
to the works by McKay, et al.[59], Iman and Shortencarier[53], and Helton and Davis[46]. Note that under certain
separability conditions associated with the function to be sampled, Latin hypercube sampling provides a more
accurate estimate of the mean value than does random sampling. That is, given an equal number of samples, the
LHS estimate of the mean will have less variance than the mean value obtained through random sampling.

Related Topics
Related Keywords
importance sampling : Importance sampling
sampling : Randomly samples variables according to their distributions

5.8.5

uncertainty quantification

Description
Dakota provides a variety of methods for propagating both aleatory and epistemic uncertainty.
At a high level, uncertainty quantification (UQ) or nondeterministic analysis is the process of characterizing input uncertainties, forward propagating these uncertainties through a computational model, and performing
statistical or interval assessments on the resulting responses. This process determines the effect of uncertainties
and assumptions on model outputs or results. In Dakota, uncertainty quantification methods specifically focus on
the forward propagation part of the process, where probabilistic or interval information on parametric inputs are
mapped through the computational model to assess statistics or intervals on outputs. For an overview of these
approaches for engineering applications, consult[42].
UQ is related to sensitivity analysis in that the common goal is to gain an understanding of how variations in
the parameters affect the response functions of the engineering design problem. However, for UQ, some or all
of the components of the parameter vector, are considered to be uncertain as specified by particular probability
distributions (e.g., normal, exponential, extreme value), or other uncertainty structures. By assigning specific
distributional structure to the inputs, distributional structure for the outputs (i.e, response statistics) can be inferred.
This migrates from an analysis that is more {qualitative} in nature, in the case of sensitivity analysis, to an analysis
that is more rigorously {quantitative}.
UQ methods are often distinguished by their ability to propagate aleatory or epistemic input uncertainty characterizations, where aleatory uncertainties are irreducible variabilities inherent in nature and epistemic uncertainties are reducible uncertainties resulting from a lack of knowledge. Since sufficient data is generally available
for aleatory uncertainties, probabilistic methods are commonly used for computing response distribution statistics
based on input probability distribution specifications. Conversely, for epistemic uncertainties, any use of probability distributions is based on subjective knowledge rather than objective data, and we may alternatively explore
nonprobabilistic methods based on interval specifications.
Dakota contains capabilities for performing nondeterministic analysis with both types of input uncertainty.
These UQ methods have been developed by Sandia Labs, in conjunction with collaborators in academia[31],[32],[21],[79].

5.8. METHODS

127

The aleatory UQ methods in Dakota include various sampling-based approaches (e.g., Monte Carlo and Latin
Hypercube sampling), local and global reliability methods, and stochastic expansion (polynomial chaos expansions and stochastic collocation) approaches. The epistemic UQ methods include local and global interval analysis
and Dempster-Shafer evidence theory. These are summarized below and then described in more depth in subsequent sections of this chapter. Dakota additionally supports mixed aleatory/epistemic UQ via interval-valued
probability, second-order probability, and Dempster-Shafer theory of evidence. These involve advanced model
recursions and are described in Section.
Dakota contains capabilities for performing nondeterministic analysis with both types of input uncertainty.
These UQ methods have been developed by Sandia Labs, in conjunction with collaborators in academia[31],[32],[21],[79].
The aleatory UQ methods in Dakota include various sampling-based approaches (e.g., Monte Carlo and Latin
Hypercube sampling), local and global reliability methods, and stochastic expansion (polynomial chaos expansions and stochastic collocation) approaches. The epistemic UQ methods include local and global interval analysis
and Dempster-Shafer evidence theory. These are summarized below and then described in more depth in subsequent sections of this chapter. Dakota additionally supports mixed aleatory/epistemic UQ via interval-valued
probability, second-order probability, and Dempster-Shafer theory of evidence. These involve advanced model
recursions and are described in Section.
The choice of uncertainty quantification method depends on how the input uncertainty is characterized, the
computational budget, and the desired output accuracy. The recommendations for UQ methods are summarized
in Tableand are discussed in the remainder of the section.
TODO: Put table in Doxygen if still needed

Related Topics
aleatory uncertainty quantification methods
epistemic uncertainty quantification methods
variable support

Related Keywords
adaptive sampling : (Experimental) Build a GP surrogate and refine it adaptively
efficient subspace : (Experimental) efficient subspace method (ESM)
global interval est : Interval analysis using global optimization methods
global reliability : Global reliability methods
gpais : Gaussian Process Adaptive Importance Sampling
importance sampling : Importance sampling
local interval est : Interval analysis using local optimization
local reliability : Local reliability method
mpp search : Specify which MPP search option to use
pof darts : Probability-of-Failure (POF) darts is a novel method for estimating the probability of failure
based on random sphere-packing.
rkd darts : Recursive k-d (RKD) Darts: Recursive Hyperplane Sampling for Numerical Integration of HighDimensional Functions.
sampling : Randomly samples variables according to their distributions

128

CHAPTER 5. TOPICS AREA

5.8.6

aleatory uncertainty quantification methods

Description
Aleatory uncertainty is also known as inherent variability, irreducible uncertainty, or randomness.
Aleatory uncertainty is typically charaterized using probability theory.

Related Topics
sampling
reliability methods
stochastic expansion methods

Related Keywords
importance sampling : Importance sampling
sampling

Description
Sampling techniques are selected using the sampling method selection. This method generates sets of samples
according to the probability distributions of the uncertain variables and maps them into corresponding sets of
response functions, where the number of samples is specified by the samples integer specification. Means,
standard deviations, coefficients of variation (COVs), and 95% confidence intervals are computed for the response
functions. Probabilities and reliabilities may be computed for response levels specifications, and response
levels may be computed for either probability levels or reliability levels specifications (refer
to the Method Commands chapter in the Dakota Reference Manual[5] for additional information).
Currently, traditional Monte Carlo (MC) and Latin hypercube sampling (LHS) are supported by Dakota and
are chosen by specifying sample type as random or lhs. In Monte Carlo sampling, the samples are selected
randomly according to the user-specified probability distributions. Latin hypercube sampling is a stratified sampling technique for which the range of each uncertain variable is divided into Ns segments of equal probability,
where Ns is the number of samples requested. The relative lengths of the segments are determined by the nature
of the specified probability distribution (e.g., uniform has segments of equal width, normal has small segments
near the mean and larger segments in the tails). For each of the uncertain variables, a sample is selected randomly
from each of these equal probability segments. These Ns values for each of the individual parameters are then
combined in a shuffling operation to create a set of Ns parameter vectors with a specified correlation structure.
A feature of the resulting sample set is that every row and column in the hypercube of partitions has exactly one
sample. Since the total number of samples is exactly equal to the number of partitions used for each uncertain
variable, an arbitrary number of desired samples is easily accommodated (as compared to less flexible approaches
in which the total number of samples is a product or exponential function of the number of intervals for each
variable, i.e., many classical design of experiments methods).
Advantages of sampling-based methods include their relatively simple implementation and their independence
from the scientific disciplines involved in the analysis. The main drawback of these techniques is the large number
of function evaluations needed to generate converged statistics, which can render such an analysis computationally
very expensive, if not intractable, for real-world engineering applications. LHS techniques, in general, require
fewer samples than traditional Monte Carlo for the same accuracy in statistics, but they still can be prohibitively
expensive. For further information on the method and its relationship to other sampling techniques, one is referred
to the works by McKay, et al.[59], Iman and Shortencarier[53], and Helton and Davis[46]. Note that under certain

5.8. METHODS

129

separability conditions associated with the function to be sampled, Latin hypercube sampling provides a more
accurate estimate of the mean value than does random sampling. That is, given an equal number of samples, the
LHS estimate of the mean will have less variance than the mean value obtained through random sampling.

Related Topics
Related Keywords
importance sampling : Importance sampling
sampling : Randomly samples variables according to their distributions
reliability methods

Description
Reliability methods provide an alternative approach to uncertainty quantification which can be less computationally demanding than sampling techniques. Reliability methods for uncertainty quantification are based on
probabilistic approaches that compute approximate response function distribution statistics based on specified uncertain variable distributions. These response statistics include response mean, response standard deviation, and
cumulative or complementary cumulative distribution functions (CDF/CCDF). These methods are often more efficient at computing statistics in the tails of the response distributions (events with low probability) than sampling
based approaches since the number of samples required to resolve a low probability can be prohibitive.
The methods all answer the fundamental question: Given a set of uncertain input variables, X, and a scalar
response function, g, what is the probability that the response function is below or above a certain level, z? The
former can be written as P [g(X) z] = Fg (
z ) where Fg (
z ) is the cumulative distribution function (CDF) of the
uncertain response g(X) over a set of response levels. The latter can be written as P [g(X) > z] and defines the
complementary cumulative distribution function (CCDF).
This probability calculation involves a multi-dimensional integral over an irregularly shaped domain of interest, D, where g(X) < z as displayed in Figure figUQ05 for the case of two variables. The reliability methods
all involve the transformation of the user-specified uncertain variables, X, with probability density function,
p(x1 , x2 ), which can be non-normal and correlated, to a space of independent Gaussian random variables, u,
possessing a mean value of zero and unit variance (i.e., standard normal variables). The region of interest, D, is
also mapped to the transformed space to yield, Du , where g(U) < z as shown in Figure figUQ06. The Nataf
transformation[17], which is identical to the Rosenblatt transformation[72] in the case of independent random
variables, is used in Dakota to accomplish this mapping. This transformation is performed to make the probability
calculation more tractable. In the transformed space, probability contours are circular in nature as shown in Figure
figUQ06 unlike in the original uncertain variable space, Figure figUQ05 . Also, the multi-dimensional integrals
can be approximated by simple functions of a single parameter, , called the reliability index. is the minimum
Euclidean distance from the origin in the transformed space to the response surface. This point is also known as
the most probable point (MPP) of failure. Note, however, the methodology is equally applicable for generic functions, not simply those corresponding to failure criteria; this nomenclature is due to the origin of these methods
within the disciplines of structural safety and reliability. Note that there are local and global reliability methods.
The majority of the methods available are local, meaning that a local optimization formulation is used to locate
one MPP. In contrast, global methods can find multiple MPPs if they exist.

Related Topics
Related Keywords
global reliability : Global reliability methods

130

CHAPTER 5. TOPICS AREA

u gaussian process : Create GP surrogate in u-space
x gaussian process : Create GP surrogate in x-space
local reliability : Local reliability method
mpp search : Specify which MPP search option to use
integration : Integration approach
first order : First-order integration scheme
probability refinement : Allow refinement of probability and generalized reliability results using importance sampling
second order : Second-order integration scheme
no approx : Perform MPP search on original response functions (use no approximation)
u taylor mean : Form Taylor series approximation in u-space at variable means
u taylor mpp : U-space Taylor series approximation with iterative updates
u two point : Predict MPP using Two-point Adaptive Nonlinear Approximation in u-space
x taylor mean : Form Taylor series approximation in x-space at variable means
x taylor mpp : X-space Taylor series approximation with iterative updates
x two point : Predict MPP using Two-point Adaptive Nonlinear Approximation in x-space
probability refinement : Allow refinement of probability and generalized reliability results using importance sampling
probability refinement : Allow refinement of probability and generalized reliability results using importance sampling

stochastic expansion methods

Description
The development of these techniques mirrors that of deterministic finite element analysis utilizing the notions of
projection, orthogonality, and weak convergence[31],[32]. Rather than estimating point probabilities, they form an
approximation to the functional relationship between response functions and their random inputs, which provides
a more complete uncertainty representation for use in multi-code simulations. Expansion methods include polynomial chaos expansions (PCE), which employ multivariate orthogonal polynomials that are tailored to representing
particular input probability distributions, and stochastic collocation (SC), which employs multivariate interpolation polynomials. For PCE, expansion coefficients may be evaluated using a spectral projection approach (based
on sampling, tensor-product quadrature, Smolyak sparse grid, or cubature methods for numerical integration) or a
regression approach (least squares or compressive sensing). For SC, interpolants are formed over tensor-product
or sparse grids and may be local or global, value-based or gradient-enhanced, and nodal or hierarchical. In global
value-based cases (Lagrange polynomials), the barycentric formulation is used[10],[56],[49] to improve numerical efficiency and stability. Both sets of methods provide analytic response moments and variance-based metrics;
however, CDF/CCDF probabilities are evaluated numerically by sampling on the expansion.

5.8. METHODS

131

Related Topics
Related Keywords
5.8.7

epistemic uncertainty quantification methods

Description
Epistemic uncertainty is uncertainty due to lack of knowledge.
In Dakota, epistemic uncertainty analysis is performed using interval analysis or Dempster-Shafer theory of
evidence.
Note that epistemic uncertainty can also be modeled probabilistically. It would be more accurate to call this
class of method, non-probabilistic uncertainty quantification, but the name persists for historical reasons.

Related Topics
interval estimation
evidence theory

Related Keywords
global evidence : Evidence theory with evidence measures computed with global optimization methods
global interval est : Interval analysis using global optimization methods
local evidence : Evidence theory with evidence measures computed with local optimization methods
local interval est : Interval analysis using local optimization
interval estimation

Description
In interval analysis, one assumes that nothing is known about an epistemic uncertain variable except that its value
lies somewhere within an interval. In this situation, it is NOT assumed that the value has a uniform probability
of occuring within the interval. Instead, the interpretation is that any value within the interval is a possible value
or a potential realization of that variable. In interval analysis, the uncertainty quantification problem is one of
determining the resulting bounds on the output (defining the output interval) given interval bounds on the inputs.
Again, any output response that falls within the output interval is a possible output with no frequency information
assigned to it.
We have the capability to perform interval analysis using either global interval est or local interval est. In the global approach, one uses either a global optimization method or a sampling method to
assess the bounds. global interval est allows the user to specify either lhs, which performs Latin Hypercube Sampling and takes the minimum and maximum of the samples as the bounds (no optimization is performed)
or ego. In the case of ego, the efficient global optimization method is used to calculate bounds. The ego method
is described in Section . If the problem is amenable to local optimization methods (e.g. can provide derivatives
or use finite difference method to calculate derivatives), then one can use local methods to calculate these bounds.
local interval est allows the user to specify either sqp which is sequential quadratic programming, or
nip which is a nonlinear interior point method.
Note that when performing interval analysis, it is necessary to define interval uncertain variables as described
in Section . For interval analysis, one must define only one interval per input variable, in contrast with DempsterShafer evidence theory, where an input can have several possible intervals. Interval analysis can be considered a

132

CHAPTER 5. TOPICS AREA

special case of Dempster-Shafer evidence theory where each input is defined by one input interval with a basic
probability assignment of one. In Dakota, however, the methods are separate and semantic differences exist in
the output presentation. If you are performing a pure interval analysis, we recommend using either global interval est or local interval est instead of global evidence or local evidence, for reasons of simplicity. An example of interval estimation is found in the Dakota/examples/users/cantileveruq global interval.in, and also in Section .
Note that we have kept separate implementations of interval analysis and Dempster-Shafer evidence theory because our users often want to couple interval analysis on an outer loop with an aleatory,
probabilistic analysis on aninner loop for nested, second-order probability calculations. See Section for additional details on these nested approaches. These interval methods can also be used as the outer loop
within an interval-valued probability analysis for propagating mixed aleatory and epistemic uncertainty refer to
Section for additional details.
Interval analysis is often used to model epistemic uncertainty. In interval analysis, the uncertainty quantification problem is one of determining the resulting bounds on the output (defining the output interval) given interval
bounds on the inputs.
We can do interval analysis using either %global interval est or local interval est. In the
global approach, one uses either a global optimization method or a sampling method to assess the bounds, whereas
the local method uses gradient information in a derivative-based optimization approach.
An example of interval estimation is shown in Figure , with example results in Figure . This example is
a demonstration of calculating interval bounds for three outputs of the cantilever beam problem. The cantilever
beam problem is described in detail in Section . Given input intervals of [1,10] on beam width and beam thickness,
we can see that the interval estimate of beam weight is approximately [1,100].
:examples:interval out
-----------------------------------------------------------------Min and Max estimated values for each response function:
weight: Min = 1.0000169352e+00 Max = 9.9999491948e+01
stress: Min = -9.7749994284e-01 Max = 2.1499428450e+01
displ: Min = -9.9315672724e-01 Max = 6.7429714485e+01
-----------------------------------------------------------------

Related Topics
Related Keywords
global interval est : Interval analysis using global optimization methods
local interval est : Interval analysis using local optimization
evidence theory

Description
This section discusses Dempster-Shafer evidence theory. In this approach, one does not assign a probability
distribution to each uncertain input variable. Rather, one divides each uncertain input variable into one or more
intervals. The input parameters are only known to occur within intervals: nothing more is assumed.
Each interval is defined by its upper and lower bounds, and a Basic Probability Assignment (BPA) associated
with that interval. The BPA represents a probability of that uncertain variable being located within that interval.
The intervals and BPAs are used to construct uncertainty measures on the outputs called belief and plausibility. Belief represents the smallest possible probability that is consistent with the evidence, while plausibility
represents the largest possible probability that is consistent with the evidence. For more information about the
Dempster-Shafer theory of evidence, see [66] and[47].

5.8. METHODS

133

Similar to the interval approaches, one may use global or local methods to determine plausbility and belief
measures for the outputs.
Usage Notes
Note that to calculate the plausibility and belief cumulative distribution functions, one has to look at all
combinations of intervals for the uncertain variables. Within each interval cell combination, the minimum and
maximum value of the objective function determine the belief and plausibility, respectively. In terms of implementation, global methods use LHS sampling or global optimization to calculate the minimum and maximum
values of the objective function within each interval cell, while local methods use gradient-based optimization
methods to calculate these minima and maxima.
Finally, note that many non-deterministic keywords apply to the evidence methods, but one needs to be careful
about the interpretation and translate probabilistic measures to epistemic ones. For example, if the user specifies
distribution of type complementary, a complementary plausibility and belief function will be generated for the
evidence methods (as opposed to a complementary distribution function in the sampling case). If the user specifies a set of responses levels, both the belief and plausibility will be calculated for each response level. Likewise,
if the user specifies a probability level, the probability level will be interpreted both as a belief and plausibility,
and response levels corresponding to the belief and plausibility levels will be calculated. Finally, if generalized reliability levels are specified, either as inputs (gen reliability levels) or outputs (response levels
with compute gen reliabilities), then these are directly converted to/from probability levels and the
same probability-based mappings described above are performed.

Related Topics
Related Keywords
global evidence : Evidence theory with evidence measures computed with global optimization methods
local evidence : Evidence theory with evidence measures computed with local optimization methods

5.8.8

variable support

Description
Different nondeterministic methods have differing support for uncertain variable distributions. Tables 5.37, 5.38,
and 5.39 summarize the uncertain variables that are available for use by the different methods, where a - indicates that the distribution is not supported by the method, a U means the uncertain input variables of this type
must be uncorrelated, a C denotes that correlations are supported involving uncertain input variables of this
type, and an A means the appropriate variables must be specified as active in the variables specification block.
For example, if one wants to support sampling or a stochastic expansion method over both continuous uncertain
and continuous state variables, the specification active all must be listed in the variables specification block.
Additional notes include:
we have four variants for stochastic expansions (SE), listed as Wiener, Askey, Extended, and Piecewise
which draw from different sets of basis polynomials. The term stochastic expansion indicates polynomial
chaos and stochastic collocation collectively, although the Piecewise option is only currently supported for
stochastic collocation. Refer to polynomial chaos and stoch collocation for additional information on these
three options.
methods supporting the epistemic interval distributions have differing approaches: sampling and the lhs
option of global interval est model the interval basic probability assignments (BPAs) as continuous histogram bin distributions for purposes of generating samples; local interval est and the ego
option of global interval est ignore the BPA details and models these variables as simple bounded

134

CHAPTER 5. TOPICS AREA

regions defined by the cell extremes; and local evidence and global evidence model the interval
specifications as true BPAs.

Related Topics
Related Keywords
5.8.9

optimization and calibration

Description
Optimization algorithms work to minimize (or maximize) an objective function, typically calculated by the user
simulation code, subject to constraints on design variables and responses. Available approaches in Dakota include
well-tested, proven gradient-based, derivative-free local, and global methods for use in science and engineering
design applications. Dakota also offers more advanced algorithms, e.g., to manage multi-objective optimization or
perform surrogate-based minimization. This chapter summarizes optimization problem formulation, standard algorithms available in Dakota (mostly through included third-party libraries, see Section 6.5 of[4]), some advanced
capabilities, and offers usage guidelines.
Optimization Formulations
This section provides a basic introduction to the mathematical formulation of optimization, problems. The primary
goal of this section is to introduce terms relating to these topics, and is not intended to be a description of theory
or numerical algorithms. For further details, consult[8] ,[34],[41],[65], and [84].
A general optimization problem is formulated as follows:

minimize:

f (x)
x <n

subject to:

gL g(x) gU
h(x) = ht

(5.1)

aL Ai x aU
Ae x = at
xL x xU
where vector and matrix terms are marked in bold typeface. In this formulation, x = [x1 , x2 , . . . , xn ] is an
n-dimensional vector of real-valued design variables or design parameters. The n-dimensional vectors, xL and
xU , are the lower and upper bounds, respectively, on the design parameters. These bounds define the allowable
values for the elements of x, and the set of all allowable values is termed the design space or the parameter space.
A design point or a sample point is a particular set of values within the parameter space.
The optimization goal is to minimize the objective function, f (x), while satisfying the constraints. Constraints
can be categorized as either linear or nonlinear and as either inequality or equality. The nonlinear inequality
constraints}, g(x), are 2-sided, in that they have both lower and upper bounds, gL and gU , respectively. The
nonlinear equality constraints, h(x), have target values specified by ht . The linear inequality constraints create
a linear system Ai x, where Ai is the coefficient matrix for the linear system. These constraints are also 2-sided
as they have lower and upper bounds, aL and aU , respectively. The linear equality constraints create a linear
system Ae x, where Ae is the coefficient matrix for the linear system and at are the target values. The constraints
partition the parameter space into feasible and infeasible regions. A design point is said to be feasible if and only

5.8. METHODS

135

if it satisfies all of the constraints. Correspondingly, a design point is said to be infeasible if it violates one or
more of the constraints.
Many different methods exist to solve the optimization problem given in Section 6.1 of[4], all of which iterate
on x in some manner. That is, an initial value for each parameter in x is chosen, the response quantities, f (x),
g(x), h(x), are computed, often by running a simulation, and some algorithm is applied to generate a new x that
will either reduce the objective function, reduce the amount of infeasibility, or both. To facilitate a general presentation of these methods, three criteria will be used in the following discussion to differentiate them: optimization
problem type, search goal, and search method.
The optimization problem type can be characterized both by the types of constraints present in the problem
and by the linearity or nonlinearity of the objective and constraint functions. For constraint categorization, a hierarchy of complexity exists for optimization algorithms, ranging from simple bound constraints, through linear
constraints, to full nonlinear constraints. By the nature of this increasing complexity, optimization problem categorizations are inclusive of all constraint types up to a particular level of complexity. That is, an unconstrained
problem has no constraints, a bound-constrained problem has only lower and upper bounds on the design parameters, a linearly-constrained problem has both linear and bound constraints, and a nonlinearly-constrained
problem may contain the full range of nonlinear, linear, and bound constraints. If all of the linear and nonlinear
constraints are equality constraints, then this is referred to as an equality-constrained problem, and if all of the
linear and nonlinear constraints are inequality constraints, then this is referred to as an inequality-constrained
problem. Further categorizations can be made based on the linearity of the objective and constraint functions. A
problem where the objective function and all constraints are linear is called a linear programming (LP) problem.
These types of problems commonly arise in scheduling, logistics, and resource allocation applications. Likewise,
a problem where at least some of the objective and constraint functions are nonlinear is called a nonlinear programming (NLP) problem. These NLP problems predominate in engineering applications and are the primary
focus of Dakota.
The search goal refers to the ultimate objective of the optimization algorithm, i.e., either global or local
optimization. In global optimization, the goal is to find the design point that gives the lowest feasible objective
function value over the entire parameter space. In contrast, in local optimization, the goal is to find a design point
that is lowest relative to a nearby region of the parameter space. In almost all cases, global optimization will be
more computationally expensive than local optimization. Thus, the user must choose an optimization algorithm
with an appropriate search scope that best fits the problem goals and the computational budget.
The search method refers to the approach taken in the optimization algorithm to locate a new design point
that has a lower objective function or is more feasible than the current design point. The search method can be
classified as either gradient-based or nongradient-based. In a gradient-based algorithm, gradients of the response
functions are computed to find the direction of improvement. Gradient-based optimization is the search method
that underlies many efficient local optimization methods. However, a drawback to this approach is that gradients
can be computationally expensive, inaccurate, or even nonexistent. In such situations, nongradient-based search
methods may be useful. There are numerous approaches to nongradient-based optimization. Some of the more
well known of these include pattern search methods (nongradient-based local techniques) and genetic algorithms
(nongradient-based global techniques).
Because of the computational cost of running simulation models, surrogate-based optimization (SBO) methods are often used to reduce the number of actual simulation runs. In SBO, a surrogate or approximate model is
constructed based on a limited number of simulation runs. The optimization is then performed on the surrogate
model. Dakota has an extensive framework for managing a variety of local, multipoint, global, and hierarchical
surrogates for use in optimization. Finally, sometimes there are multiple objectives that one may want to optimize
simultaneously instead of a single scalar objective. In this case, one may employ multi-objective methods that are
described in Section 6.3.1 of[4].
This overview of optimization approaches underscores that no single optimization method or algorithm works
best for all types of optimization problems. Section 6.4 of[4] offers guidelines for choosing a Dakota optimization
algorithm best matched to your specific optimization problem.

136

CHAPTER 5. TOPICS AREA

Constraint Considerations Dakotas input commands permit the user to specify two-sided nonlinear inequality
constraints of the form gLi gi (x) gUi , as well as nonlinear equality constraints of the form hj (x) = htj .
Some optimizers (e.g., npsol , optpp , soga, and moga methods) can handle these constraint forms directly, whereas other optimizers (e.g., asynch pattern search, dot , and conmin , mesh adaptivesearch) require Dakota to perform an internal conversion of all constraints to one-sided inequality constraints
of the form gi (x) 0. In the latter case, the two-sided inequality constraints are treated as gi (x) gUi 0
and gLi gi (x) 0 and the equality constraints are treated as hj (x) htj 0 and htj hj (x) 0. The
situation is similar for linear constraints: asynch pattern search, npsol , optpp , soga, and moga
methods support them directly, whereas dot and conmin methods do not. For linear inequalities of the form
aLi aTi x aUi and linear equalities of the form aTi x = atj , the nonlinear constraint arrays in dot and
conmin methods are further augmented to include aTi x aUi 0 and aLi aTi x 0 in the inequality
case and aTi x atj 0 and atj aTi x 0 in the equality case. Awareness of these constraint augmentation procedures can be important for understanding the diagnostic data returned from the dot and conmin
methods. Other optimizers fall somewhere in between. nlpql methods support nonlinear equality constraints
hj (x) = 0 and nonlinear one-sided inequalities gi (x) 0, but does not natively support linear constraints. Constraint mappings are used with NLPQL for both linear and nonlinear cases. Most coliny methods now support
two-sided nonlinear inequality constraints and nonlinear constraints with targets, but do not natively support linear
constraints.
When gradient and Hessian information is used in the optimization, derivative components are most commonly computed with respect to the active continuous variables, which in this case are the continuous design
variables. This differs from parameter study methods (for which all continuous variables are active) and from
nondeterministic analysis methods (for which the uncertain variables are active). Refer to Chapter 11 of[4] for
additional information on derivative components and active continuous variables.
Optimizing with Dakota: Choosing a Method
This section summarizes the optimization methods available in Dakota. We group them according to search
method and search goal and establish their relevance to types of problems. For a summary of this discussion, see
Section 6.4 of[4].
Gradient-Based Local Methods Gradient-based optimizers are best suited for efficient navigation to a local
minimum in the vicinity of the initial point. They are not intended to find global optima in nonconvex design
spaces. For global optimization methods, see Section 6.2.3 of[4]. Gradient-based optimization methods are
highly efficient, with the best convergence rates of all of the local optimization methods, and are the methods of
choice when the problem is smooth, unimodal, and well-behaved. However, these methods can be among the least
robust when a problem exhibits nonsmooth, discontinuous, or multimodal behavior. The derivative-free methods
described in Section 6.2.2 of[4] are more appropriate for problems with these characteristics.
Gradient accuracy is a critical factor for gradient-based optimizers, as inaccurate derivatives will often lead to
failures in the search or pre-mature termination of the method. Analytic gradients and Hessians are ideal but often
unavailable. If analytic gradient and Hessian information can be provided by an application code, a full Newton
method will achieve quadratic convergence rates near the solution. If only gradient information is available and
the Hessian information is approximated from an accumulation of gradient data, the superlinear convergence rates
can be obtained. It is most often the case for engineering applications, however, that a finite difference method
will be used by the optimization algorithm to estimate gradient values. Dakota allows the user to select the step
size for these calculations, as well as choose between forward-difference and central-difference algorithms. The
finite difference step size should be selected as small as possible, to allow for local accuracy and convergence, but
not so small that the steps are in the noise. This requires an assessment of the local smoothness of the response
functions using, for example, a parameter study method. Central differencing will generally produce more reliable
gradients than forward differencing but at roughly twice the expense.

5.8. METHODS

137

Gradient-based methods for nonlinear optimization problems can be described as iterative processes in which
a sequence of subproblems, usually which involve an approximation to the full nonlinear problem, are solved until
the solution converges to a local optimum of the full problem. The optimization methods available in Dakota fall
into several categories, each of which is characterized by the nature of the subproblems solved at each iteration.

Related Topics
local optimization methods
global optimization methods
bayesian calibration
nonlinear least squares
advanced optimization

Related Keywords
dl solver : (Experimental) Dynamically-loaded solver

5.8.10

local optimization methods

Description
empty

Related Topics
unconstrained
constrained
sequential quadratic programming

Related Keywords
coliny cobyla : Constrained Optimization BY Linear Approximations (COBYLA)
nlpql sqp : Sequential Quadratic Program
nonlinear cg : (Experimental) nonlinear conjugate gradient optimization
npsol sqp : Sequential Quadratic Program
optpp cg : A conjugate gradient optimization method
optpp fd newton : Finite Difference Newton optimization method
optpp g newton : Newton method based least-squares calbration
optpp newton : Newton method based optimization
optpp q newton : Quasi-Newton optimization method

138

CHAPTER 5. TOPICS AREA

unconstrained

Description
empty

Related Topics
Related Keywords
constrained

Description
empty

Related Topics
Related Keywords
coliny cobyla : Constrained Optimization BY Linear Approximations (COBYLA)
sequential quadratic programming

Description
Sequential Quadratic Programming (SQP) algorithms are a class of mathematical programming problems used to
solve nonlinear optimization problems with nonlinera constraints. These methods are a generalization of Newtons
method: each iteration involves minimizing a quadratic model of the problem. These subproblems are formulated
as minimizing a quadratic approximation of the Lagrangian subject to linearized constraints. Only gradient information is required; Hessians are approximated by low-rank updates defined by the step taken at each iteration. It
is important to note that while the solution found by an SQP method will respect the constraints, the intermediate
iterates may not. SQP methods available in Dakota are dot sqp, nlpql sqp, nlssol sqp, and npsol sqp. The particular implementation in nlpql sqp uses a variant with distributed and non-monotone line search.
Thus, this variant is designed to be more robust in the presence of inaccurate or noisy gradients common in many
engineering applications.

Related Topics
Related Keywords
nlpql sqp : Sequential Quadratic Program
nlssol sqp : Sequential Quadratic Program for nonlinear least squares
npsol sqp : Sequential Quadratic Program

5.8.11

global optimization methods

Description
empty

5.8. METHODS

139

Related Topics
Related Keywords
asynch pattern search : Pattern search, derivative free optimization method
coliny direct : DIviding RECTangles method
coliny ea : Evolutionary Algorithm
coliny pattern search : Pattern search, derivative free optimization method
efficient global : Global Surrogate Based Optimization, a.k.a. EGO
ncsu direct : DIviding RECTangles method
soga : Single-objective Genetic Algorithm (a.k.a Evolutionary Algorithm)

5.8.12

bayesian calibration

Description
See the discussion of Bayesian Calibration in the Dakota Users Manual [4].

Related Topics
Related Keywords
bayes calibration : Bayesian calibration
dream : DREAM (DiffeRential Evolution Adaptive Metropolis)
chains : Number of chains in DREAM
crossover chain pairs : Number of chains used in crossover.
gr threshold : Convergence tolerance for the Gelman-Rubin statistic
jump step : Number of generations a long jump step is taken
num cr : Number of candidate points for each crossover.
gpmsa : (Experimental) Gaussian Process Models for Simulation Analysis (GPMSA) Markov Chain Monte
Carlo algorithm with Gaussian Process Surrogate
adaptive metropolis : Use the Adaptive Metropolis MCMC algorithm
delayed rejection : Use the Delayed Rejection MCMC algorithm
dram : Use the DRAM MCMC algorithm
metropolis hastings : Use the Metropolis-Hastings MCMC algorithm
multilevel : Use the multilevel MCMC algorithm.
proposal covariance : Defines the technique used to generate the MCMC proposal covariance.
derivatives : Use derivatives to inform the MCMC proposal covariance.

140

CHAPTER 5. TOPICS AREA

prior : Uses the covariance of the prior distributions to define the MCMC proposal covariance.
queso : Markov Chain Monte Carlo algorithms from the QUESO package
adaptive metropolis : Use the Adaptive Metropolis MCMC algorithm
delayed rejection : Use the Delayed Rejection MCMC algorithm
dram : Use the DRAM MCMC algorithm
metropolis hastings : Use the Metropolis-Hastings MCMC algorithm
multilevel : Use the multilevel MCMC algorithm.
proposal covariance : Defines the technique used to generate the MCMC proposal covariance.
derivatives : Use derivatives to inform the MCMC proposal covariance.
prior : Uses the covariance of the prior distributions to define the MCMC proposal covariance.

5.8.13

nonlinear least squares

Description
Dakotas least squares branch currently contains three methods for solving nonlinear least squares problems:
NL2SOL, a trust-region method that adaptively chooses between two Hessian approximations (Gauss-Newton and Gauss-Newton plus a quasi-Newton approximation to the rest of the Hessian)
NLSSOL, a sequential quadratic programming (SQP) approach that is from the same algorithm family as
NPSOL
Gauss-Newton, which supplies the Gauss-Newton Hessian approximation to the full-Newton optimizers
from OPT++.
The important difference of these algorithms from general-purpose optimization methods is that the response set
is defined by calibration terms (e.g. separate terms for each residual), rather than an objective function. Thus, a
finer granularity of data is used by least squares solvers as compared to that used by optimizers. This allows the
exploitation of the special structure provided by a sum of squares objective function.

Related Topics
Related Keywords
nl2sol : Trust-region method for nonlinear least squares
nlssol sqp : Sequential Quadratic Program for nonlinear least squares

5.8.14

advanced optimization

Description
empty

5.9. ADVANCED TOPICS

Related Topics
scaling
multiobjective methods
surrogate based optimization methods

Related Keywords
scaling

Description
empty

Related Topics
Related Keywords
multiobjective methods

Description
empty

Related Topics
Related Keywords
surrogate based optimization methods

Description
empty

Related Topics
Related Keywords
efficient global : Global Surrogate Based Optimization, a.k.a. EGO
surrogate based global : Global Surrogate Based Optimization
surrogate based local : Local Surrogate Based Optimization

5.9

advanced topics

Description
Advanced Dakota capabilities

141

142

CHAPTER 5. TOPICS AREA

Related Topics
advanced strategies
advanced model recursion
advanced simulation interfaces
advanced optimization

Related Keywords
5.9.1

advanced strategies

Description
empty

Related Topics
Related Keywords
5.9.2

advanced model recursion

Description
empty

Related Topics
hybrid and recursions logic

Related Keywords
hybrid and recursions logic

Description
empty

Related Topics
Related Keywords
5.9.3

advanced simulation interfaces

Description
empty

Related Topics
simulation failure
concurrency and parallelism

5.9. ADVANCED TOPICS

143

Related Keywords
simulation failure

Description
empty

Related Topics
Related Keywords
concurrency and parallelism

Description
empty

Related Topics
Related Keywords
processors per analysis : Specify the number of processors per analysis when Dakota is run in parallel
analysis scheduling : Specify the scheduling of concurrent analyses when Dakota is run in parallel
master : Specify a dedicated master partition for parallel analysis scheduling
peer : Specify a peer partition for parallel analysis scheduling
analysis servers : Specify the number of analysis servers when Dakota is run in parallel
asynchronous : Specify analysis driver concurrency, when Dakota is run in serial
analysis concurrency : Limit the number of analysis drivers within an evaluation that Dakota will schedule
evaluation concurrency : Determine how many concurrent evaluations Dakota will schedule
local evaluation scheduling : Control how local asynchronous jobs are scheduled
master : Specify a dedicated master partition for parallel evaluation scheduling
peer : Specify a peer partition for parallel evaluation scheduling
dynamic : Specify dynamic scheduling in a peer partition when Dakota is run in parallel.
static : Specify static scheduling in a peer partition when Dakota is run in parallel.
evaluation servers : Specify the number of evaluation servers when Dakota is run in parallel
processors per evaluation : Specify the number of processors per evaluation server when Dakota is run in
parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling

144

CHAPTER 5. TOPICS AREA

iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel
iterator scheduling : Specify the scheduling of concurrent iterators when Dakota is run in parallel
master : Specify a dedicated master partition for parallel iterator scheduling
peer : Specify a peer partition for parallel iterator scheduling
iterator servers : Specify the number of iterator servers when Dakota is run in parallel
processors per iterator : Specify the number of processors per iterator server when Dakota is run in parallel

5.9.4

advanced optimization

Description
empty

Related Topics
scaling
multiobjective methods
surrogate based optimization methods

Related Keywords
scaling

Description
empty

5.10. PACKAGES

145

Related Topics
Related Keywords
multiobjective methods

Description
empty

Related Topics
Related Keywords
surrogate based optimization methods

Description
empty

Related Topics
Related Keywords
efficient global : Global Surrogate Based Optimization, a.k.a. EGO
surrogate based global : Global Surrogate Based Optimization
surrogate based local : Local Surrogate Based Optimization

5.10

packages

Description
This topic organizes information about the different software packages (libraries) that are integrated into Dakota

Related Topics
package coliny
package conmin
package ddace
package dot
package fsudace
package hopspack
package jega
package nlpql
package npsol

146

CHAPTER 5. TOPICS AREA

package optpp
package psuade
package queso
package scolib

Related Keywords
5.10.1

package coliny

Description
SCOLIB (formerly known as COLINY) is a collection of nongradient-based optimizers that support the Common
Optimization Library INterface (COLIN). SCOLIB optimizers currently include coliny cobyla, colinydirect, coliny ea, coliny pattern search and coliny solis wets. (Yes, the input spec still has
coliny prepended to the method name.) Additional SCOLIB information is available from https://software.sandia.gov/trac/acro.
SCOLIB solvers now support bound constraints and general nonlinear constraints. Supported nonlinear constraints include both equality and two-sided inequality constraints. SCOLIB solvers do not yet support linear
constraints. Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty times the sum of squares of the constraint violations to the objective function. Specific exceptions to
this method for handling constraint violations are noted below. (The default value of constraint penalty
is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default value is 1.0.)
The method independent controls for max iterations and max function evaluations limit the
number of major iterations and the number of function evaluations that can be performed during a SCOLIB optimization, respectively. The convergence tolerance control defines the threshold value on relative change
in the objective function that indicates convergence. The output verbosity specification controls the amount
of information generated by SCOLIB: the silent, quiet, and normal settings correspond to minimal reporting from SCOLIB, whereas the verbose setting corresponds to a higher level of information, and debug
outputs method initialization and a variety of internal SCOLIB diagnostics. The majority of SCOLIBs methods perform independent function evaluations that can directly take advantage of Dakotas parallel capabilities.
Only coliny solis wets, coliny cobyla, and certain configurations of coliny pattern search
are inherently serial. The parallel methods automatically utilize parallel logic when the Dakota configuration
supports parallelism. Lastly, neither speculative gradients nor linear constraints are currently supported with
SCOLIB.
Some SCOLIB methods exploit parallelism through the use of Dakotas concurrent function evaluations. The
nature of the algorithms, however, limits the amount of concurrency that can be exploited. The maximum amount
of evaluation concurrency that can be leveraged by the various methods is as follows:
COBYLA: one
DIRECT: twice the number of variables
Evolutionary Algorithms: size of the population
Pattern Search: size of the search pattern
Solis-Wets: one

5.10. PACKAGES

147

All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
Each of the SCOLIB methods supports the solution target control, which defines a convergence criterion in which the optimizer will terminate if it finds an objective function value lower than the specified target.

Related Topics
Related Keywords
coliny beta : (Experimental) Coliny beta solver
coliny cobyla : Constrained Optimization BY Linear Approximations (COBYLA)
coliny direct : DIviding RECTangles method
coliny ea : Evolutionary Algorithm
coliny pattern search : Pattern search, derivative free optimization method
coliny solis wets : Simple greedy local search method

5.10.2

package conmin

Description
The CONMIN library[83] is a public domain library of nonlinear programming optimizers, specifically the
Fletcher-Reeves conjugate gradient (Dakotas conmin frcg method) method for unconstrained optimization,
and the method of feasible directions (Dakotas conmin mfd method) for constrained optimization. As CONMIN was a predecessor to the DOT commercial library, the algorithm controls are very similar.

Related Topics
Related Keywords
conmin : Access to methods in the CONMIN library
frcg : A conjugate gradient optimization method
mfd : Method of feasible directions

5.10.3

package ddace

Description
The Distributed Design and Analysis of Computer Experiments (DDACE) library provides the following DACE techniques: grid sampling (grid), pure random sampling (random), orthogonal array sampling (oas),

148

CHAPTER 5. TOPICS AREA

latin hypercube sampling (lhs), orthogonal array latin hypercube sampling (oa lhs), Box-Behnken (box behnken), and central composite design (central composite).
It is worth noting that there is some overlap in sampling techniques with those available from the nondeterministic branch. The current distinction is that the nondeterministic branch methods are designed to sample
within a variety of probability distributions for uncertain variables, whereas the design of experiments methods
treat all variables as having uniform distributions. As such, the design of experiments methods are well-suited
for performing parametric studies and for generating data sets used in building global approximations, but are not
currently suited for assessing the effect of uncertainties characterized with probability distribution. If a design of
experiments over both design/state variables (treated as uniform) and uncertain variables (with probability distributions) is desired, then sampling can support this with active all specified in the Variables specification
block.

Related Topics
Related Keywords
dace : Design and Analysis of Computer Experiments

5.10.4

package dot

Description
The DOT library [85] contains nonlinear programming optimizers, specifically the Broyden-Fletcher-Goldfarb-Shanno (Dakotas dot bfgs method) and Fletcher-Reeves conjugate gradient (Dakotas dot frcg method)
methods for unconstrained optimization, and the modified method of feasible directions (Dakotas dot mmfd
method), sequential linear programming (Dakotas dot slp method), and sequential quadratic programming
(Dakotas dot sqp method) methods for constrained optimization.

Related Topics
Related Keywords
dot : Access to methods in the DOT package
bfgs : A conjugate gradient optimization method
frcg : A conjugate gradient optimization method
mmfd : Method of feasible directions
slp : Sequential Linear Programming
sqp : Sequential Quadratic Program

5.10.5

package fsudace

Description
The Florida State University Design and Analysis of Computer Experiments (FSUDace) library provides the
following DACE techniques: quasi-Monte Carlo sampling (fsu quasi mc) based on the Halton sequence
(halton) or the Hammersley sequence (hammersley), and Centroidal Voronoi Tessellation (fsu cvt).

5.10. PACKAGES

149

Related Topics
Related Keywords
quality metrics : Calculate metrics to assess the quality of quasi-Monte Carlo samples
fsu cvt : Design of Computer Experiments - Centroidal Voronoi Tessellation
quality metrics : Calculate metrics to assess the quality of quasi-Monte Carlo samples
halton : Generate samples from a Halton sequence
fsu quasi mc : Design of Computer Experiments - Quasi-Monte Carlo sampling
halton : Generate samples from a Halton sequence
hammersley : Use Hammersley sequences
quality metrics : Calculate metrics to assess the quality of quasi-Monte Carlo samples

5.10.6

package hopspack

Description
The HOPSPACK software [69] contains the asynchronous parallel pattern search (APPS) algorithm [37]. It can
handle unconstrained problems as well as those with bound constraints, linear constraints, and general nonlinear
constraints.
HOPSPACK is available to the public under the GNU LGPL and the source code is included with Dakota. HOPSPACK-specific software documentation is available from https://software.sandia.gov/trac/hopspack.

Related Topics
Related Keywords
asynch pattern search : Pattern search, derivative free optimization method

5.10.7

package jega

Description
The JEGA library[19] contains two global optimization methods. The first is a Multi-objective Genetic Algorithm
(MOGA) which performs Pareto optimization. The second is a Single-objective Genetic Algorithm (SOGA)
which performs optimization on a single objective function. Both methods support general constraints and a
mixture of real and discrete variables. The JEGA library was written by John Eddy, currently a member of the
technical staff in the System Readiness and Sustainment Technologies department at Sandia National Laboratories
in Albuquerque. These algorithms are accessed as moga and soga within Dakota.

Related Topics
Related Keywords
moga : Multi-objective Genetic Algorithm (a.k.a Evolutionary Algorithm)
soga : Single-objective Genetic Algorithm (a.k.a Evolutionary Algorithm)

150

CHAPTER 5. TOPICS AREA

5.10.8

package nlpql

Description
The NLPQL library is a commercially-licensed library containing a sequential quadratic programming (SQP) optimizer, specified as Dakotas nlpql sqp method, for constrained optimization. The particular implementation
used is NLPQLP [74], a variant with distributed and non-monotone line search.

Related Topics
Related Keywords
nlpql sqp : Sequential Quadratic Program

5.10.9

package npsol

Description
The NPSOL library[33] contains a sequential quadratic programming (SQP) implementation (the npsol sqp
method). SQP is a nonlinear programming optimizer for constrained minimization.

Related Topics
Related Keywords
npsol sqp : Sequential Quadratic Program

5.10.10

package optpp

Description
The OPT++ library[60] contains primarily gradient-based nonlinear programming optimizers for unconstrained,
bound-constrained, and nonlinearly constrained minimization: Polak-Ribiere conjugate gradient (Dakotas optppcg method), quasi-Newton (Dakotas optpp q newton method), finite difference Newton (Dakotas optppfd newton method), and full Newton (Dakotas optpp newton method).
The conjugate gradient method is strictly unconstrained, and each of the Newton-based methods are automatically bound to the appropriate OPT++ algorithm based on the user constraint specification (unconstrained,
bound-constrained, or generally-constrained). In the generally-constrained case, the Newton methods use a nonlinear interior-point approach to manage the constraints. The library also contains a direct search algorithm, PDS
(parallel direct search, Dakotas optpp pds method), which supports bound constraints.
Controls
1. max iterations
2. max function evaluations
3. convergence tolerance
4. output
5. speculative

5.10. PACKAGES

151

Concurrency
OPT++s gradient-based methods are not parallel algorithms and cannot directly take advantage of concurrent
function evaluations. However, if numerical gradients with method source dakota is specified, a
parallel Dakota configuration can utilize concurrent evaluations for the finite difference gradient computations.
Constraints
Linear constraint specifications are supported by each of the Newton methods (optpp newton, optpp qnewton, optpp fd newton, and optpp g newton)
optpp cg must be unconstrained
optpp pds can be, at most, bound-constrained.

Related Topics
Related Keywords
optpp cg : A conjugate gradient optimization method
optpp fd newton : Finite Difference Newton optimization method
optpp g newton : Newton method based least-squares calbration
optpp newton : Newton method based optimization
optpp pds : Simplex-based derivative free optimization method
optpp q newton : Quasi-Newton optimization method

5.10.11

package psuade

Description
The Problem Solving Environment for Uncertainty Analysis and Design Exploration (PSUADE) is a Lawrence
Livermore National Laboratory tool for metamodeling, sensitivity analysis, uncertainty quantification, and optimization. Its features include non-intrusive and parallel function evaluations, sampling and analysis methods, an
integrated design and analysis framework, global optimization, numerical integration, response surfaces (MARS
and higher order regressions), graphical output with Pgplot or Matlab, and fault tolerance [81].

Related Topics
Related Keywords
psuade moat : Morris One-at-a-Time

5.10.12

package queso

Description
QUESO stands for Quantification of Uncertainty for Estimation, Simulation, and Optimization. It supports
Bayesian calibration methods. It is developed at The University of Texas at Austin.

152

CHAPTER 5. TOPICS AREA

Related Topics
Related Keywords
bayes calibration : Bayesian calibration
gpmsa : (Experimental) Gaussian Process Models for Simulation Analysis (GPMSA) Markov Chain Monte
Carlo algorithm with Gaussian Process Surrogate
queso : Markov Chain Monte Carlo algorithms from the QUESO package

5.10.13

package scolib

Description
SCOLIB (formerly known as COLINY) is a collection of nongradient-based optimizers that support the Common
Optimization Library INterface (COLIN). SCOLIB optimizers currently include coliny cobyla, colinydirect, coliny ea, coliny pattern search and coliny solis wets. (Yes, the input spec still has
coliny prepended to the method name.) Additional SCOLIB information is available from https://software.sandia.gov/trac/acro.
SCOLIB solvers now support bound constraints and general nonlinear constraints. Supported nonlinear constraints include both equality and two-sided inequality constraints. SCOLIB solvers do not yet support linear
constraints. Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty times the sum of squares of the constraint violations to the objective function. Specific exceptions to
this method for handling constraint violations are noted below. (The default value of constraint penalty
is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default value is 1.0.)
The method independent controls for max iterations and max function evaluations limit the
number of major iterations and the number of function evaluations that can be performed during a SCOLIB optimization, respectively. The convergence tolerance control defines the threshold value on relative change
in the objective function that indicates convergence. The output verbosity specification controls the amount
of information generated by SCOLIB: the silent, quiet, and normal settings correspond to minimal reporting from SCOLIB, whereas the verbose setting corresponds to a higher level of information, and debug
outputs method initialization and a variety of internal SCOLIB diagnostics. The majority of SCOLIBs methods perform independent function evaluations that can directly take advantage of Dakotas parallel capabilities.
Only coliny solis wets, coliny cobyla, and certain configurations of coliny pattern search
are inherently serial. The parallel methods automatically utilize parallel logic when the Dakota configuration
supports parallelism. Lastly, neither speculative gradients nor linear constraints are currently supported with
SCOLIB.
Some SCOLIB methods exploit parallelism through the use of Dakotas concurrent function evaluations. The
nature of the algorithms, however, limits the amount of concurrency that can be exploited. The maximum amount
of evaluation concurrency that can be leveraged by the various methods is as follows:
COBYLA: one
DIRECT: twice the number of variables
Evolutionary Algorithms: size of the population
Pattern Search: size of the search pattern
Solis-Wets: one

5.10. PACKAGES

153

All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
Each of the SCOLIB methods supports the solution target control, which defines a convergence criterion in which the optimizer will terminate if it finds an objective function value lower than the specified target.

Related Topics
Related Keywords
coliny beta : (Experimental) Coliny beta solver
coliny cobyla : Constrained Optimization BY Linear Approximations (COBYLA)
coliny direct : DIviding RECTangles method
coliny ea : Evolutionary Algorithm
coliny pattern search : Pattern search, derivative free optimization method
coliny solis wets : Simple greedy local search method

154

CHAPTER 5. TOPICS AREA

Distribution
Type

Sampling

Local
Reliability

Normal

Global Wiener Askey

ReliSE
SE
ability
C
C
C

Extended PieceSE
wise
SE

Local
Interval

Local
Global EviInter- dence
val

Global
Evidence

C
Bounded
Normal
LogC
normal
C
Bounded
Lognormal
UniC
form
Logu- C
niform
Trian- C
gular
Expo- C
nential
Beta
C
C
Gamma
Gum- C
bel
C
Frechet
C
Weibull
ConC
tinuous
Histogram
Bin

U
C

U
C

U
C

U
U

U
U

U
-

Table 5.1: Summary of Distribution Types supported by Nondeterministic Methods, Part I (Continuous Aleatory
Types)

5.10. PACKAGES

155

Distribution
Type

Sampling

Local
Reliability

Poisson
Binomial
Negative
Binomial
Geometric
Hypergeometric
Discrete
Histogram
Point

Global Wiener Askey

ReliSE
SE
ability
-

Extended Piecewise
SE
SE

Local
Interval

Local
Global EviInter- dence
val

Global
Evidence

Table 5.2: Summary of Distribution Types supported by Nondeterministic Methods, Part II (Discrete Aleatory
Types)

156

CHAPTER 5. TOPICS AREA

Distribution
Type

Sampling

Local
Reliability

Interval
Continuous
Design
Discrete
Design
Range,
Int
Set,
Real
Set
Continuous
State
Discrete
State
Range,
Int
Set,
Real
Set

Global Wiener Askey

ReliSE
SE
ability
U,A
U,A
U,A

Extended PieceSE
wise
SE

Local
Interval

Local
Global EviInter- dence
val

Global
Evidence

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

U,A

Table 5.3: Summary of Distribution Types supported by Nondeterministic Methods, Part III (Epistemic, Design,
and State Types)

Chapter 6

Keywords Area
This page lists the six blocks. From here, you can navigate to every keyword.
environment
method
model
variables
interface
responses
Introduction to Dakota Keywords
In Dakota, the environment manages execution modes and I/O streams and defines the top-level iterator. Generally speaking, an iterator contains a model and a model contains a set of variables, an interface, and a set of
responses. An iterator repeatedly operates on the model to map the variables into responses using the interface.
Each of these six components (environment, method, model, variables, interface, and responses) are separate
specifications in the users input file, and as a whole, determine the study to be performed during an execution of
the Dakota software.
A Dakota execution is limited to a single environment, but may involve multiple methods and multiple models.
In particular, advanced iterators (i.e., meta- and component-based iterators) and advanced models (i.e., nested and
surrogate models) may specialize to include recursions with additional sub-iterators and sub-models. Since each
model may contain its own variables, interface, and responses, there may be multiple specifications of the method,
model, variables, interface, and responses sections.
Keyword Pages
Every Dakota keyword has its own page in this manual. The page describes:
Whether the keyword takes ARGUMENTS, and the data type Additional notes about ARGUMENTS can be
found here: Specifying Arguments.
Whether it has an ALIAS
Which additional keywords can be specified to change its behavior
Which of these additional keywords are required or optional
Additional information about how to use the keyword in an input file
157

158

CHAPTER 6. KEYWORDS AREA

6.1

environment

Keywords Area
environment
Top-level settings for Dakota execution

Topics
This keyword is related to the topics:
block

Specification
Alias: none
Argument(s): none
Default: no environment
Required/Optional
Optional

Description of
Group

Dakota Keyword
check

Dakota Keyword
Description
Invoke Dakota in
input check mode

Optional

output file

Base filename for

output redirection

Optional

error file

Base filename for

error redirection

Optional

read restart

Base filename for

restart file read

Optional

write restart

Base filename for

restart file write

Optional

pre run

Invoke Dakota
with pre-run mode
active

Optional

run

Invoke Dakota
with run mode
active

6.1. ENVIRONMENT

159
Optional

post run

Invoke Dakota
with post-run
mode active

Optional

graphics

Optional

tabular data

Display a 2D
graphics window
of variables and
responses
Write a tabular
results file with
variable and
response history

Optional

output precision

Control the output

precision

Optional

results output

(Experimental)
Write a summary
file containing the
final results

Optional

top method pointer

Identify which
method leads the
Dakota study

Description
The environment section in a Dakota input file is optional. It specifies the top-level solution environment, optionally including run modes, output controls, and identification of the primary iterative method (top methodpointer). The output-related keywords address graphics, generation of tabular and results data, and precision
of numerical output.
Run Mode Defaults
Dakota run phases include check, pre run, run, and post run. The default behavior is to pre run,
run, and post run, though any or all of these may be specified to select specific run phases. Specifying check
will cause Dakota to exit before any selected run modes.

6.1.1

check

Keywords Area
environment
check
Invoke Dakota in input check mode

Topics
This keyword is related to the topics:
command line options

160

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: no check; proceed to run

Description
When specified, Dakota input will be parsed and the problem instantiated. Dakota will exit reporting whether any
errors were found.

6.1.2

output file

Keywords Area
environment
output file
Base filename for output redirection

Topics
This keyword is related to the topics:
dakota IO
command line options

Specification
Alias: none
Argument(s): STRING
Default: output to console, not file

Description
Specify a base filename to which Dakota output will be directed. Output will (necessarily) be redirected after the
input file is parsed. This option is overridden by any command-line -output option.
Default Behavior
Output to console (screen).

6.1.3

error file

Keywords Area
environment
error file
Base filename for error redirection

6.1. ENVIRONMENT

161

Topics
This keyword is related to the topics:
dakota IO
command line options

Specification
Alias: none
Argument(s): STRING
Default: errors to console, not file

Description
Specify a base filename to which Dakota errors will be directed. Errors will (necessarily) be redirected after the
input file is parsed. This option is overridden by any command-line -error option.
Default Behavior
Errors to console (screen).

6.1.4

read restart

Keywords Area
environment
read restart
Base filename for restart file read

Topics
This keyword is related to the topics:
dakota IO
command line options

Specification
Alias: none
Argument(s): STRING
Default: no restart read
Required/Optional
Optional

Description of
Group

Dakota Keyword
stop restart

Dakota Keyword
Description
Evaluation ID
number at which to
stop reading restart
file

162

CHAPTER 6. KEYWORDS AREA

Description
Specify a base filename for the restart file Dakota should read. This option is overridden by any command-line
-read restart option.
Default Behavior
No restart file is read.
stop restart
Keywords Area
environment
read restart
stop restart
Evaluation ID number at which to stop reading restart file

Topics
This keyword is related to the topics:
dakota IO

Specification
Alias: none
Argument(s): INTEGER
Default: read all records

Description
This option is overridden by any command-line -stop restart option.

6.1.5

write restart

Keywords Area
environment
write restart
Base filename for restart file write

Topics
This keyword is related to the topics:
dakota IO
command line options

6.1. ENVIRONMENT

163

Specification
Alias: none
Argument(s): STRING
Default: dakota.rst

Description
Specify a base filename for the restart file Dakota should write. This option is overridden by any command-line
-write restart option.

6.1.6

pre run

Keywords Area
environment
pre run
Invoke Dakota with pre-run mode active

Topics
This keyword is related to the topics:
command line options

Specification
Alias: none
Argument(s): none
Default: pre-run, run, post-run all executed
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
input

output

Dakota Keyword
Description
Base filename for
pre-run mode data
input
Base filename for
pre-run mode data
output

Description
When specified, Dakota execution will include the pre-run mode, which sets up methods and often generates
parameter sets to evaluate. This mode is currently useful for parameter study, DACE, and Monte Carlo sampling
methods.
Default Behavior
When no run modes are specified, Dakota will perform pre-run, run, and post-run phases.

164

CHAPTER 6. KEYWORDS AREA

input
Keywords Area
environment
pre run
input
Base filename for pre-run mode data input

Topics
This keyword is related to the topics:
dakota IO

Specification
Alias: none
Argument(s): STRING
Default: no pre-run specific input read

Description
(For future expansion; not currently used by any methods.) Specify a base filename from which Dakota will read
any pre-run input data. This option is overridden by any command-line -pre run arguments.
output
Keywords Area
environment
pre run
output
Base filename for pre-run mode data output

Topics
This keyword is related to the topics:
dakota IO

Specification
Alias: none
Argument(s): STRING
Default: no pre-run specific output written

6.1. ENVIRONMENT

165
Required/Optional

Description of
Group

Optional(Choose
One)

tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
Specify a base filename to which Dakota will write any pre-run output data (typically parameter sets to be evaluated). This option is overridden by any command-line -pre run arguments.
Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
environment
pre run
output
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

166

CHAPTER 6. KEYWORDS AREA

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
environment
pre run
output
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.1. ENVIRONMENT

167

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

168

CHAPTER 6. KEYWORDS AREA

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
environment
pre run
output
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
environment
pre run
output
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

6.1. ENVIRONMENT

Description
See description of parent custom annotated
interface id
Keywords Area
environment
pre run
output
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
environment
pre run
output
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

169

170

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

6.1.7

run

Keywords Area
environment
run
Invoke Dakota with run mode active

Topics
This keyword is related to the topics:
command line options

Specification
Alias: none
Argument(s): none
Default: pre-run, run, post-run all executed

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.1. ENVIRONMENT

171
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
input

output

Dakota Keyword
Description
Base filename for
run mode data
input
Base filename for
run mode data
output

Description
When specified, Dakota execution will include the run mode, which invokes interfaces to map parameters to
responses.
Default Behavior
When no run modes are specified, Dakota will perform pre-run, run, and post-run phases.
input
Keywords Area
environment
run
input
Base filename for run mode data input

Topics
This keyword is related to the topics:
dakota IO

Specification
Alias: none
Argument(s): STRING
Default: no run specific input read

Description
(For future expansion; not currently used by any methods.) Specify a base filename from which Dakota will
read any run input data, such as parameter sets to evaluate. This option is overridden by any command-line -run
arguments.

172

CHAPTER 6. KEYWORDS AREA

output
Keywords Area
environment
run
output
Base filename for run mode data output

Topics
This keyword is related to the topics:
dakota IO

Specification
Alias: none
Argument(s): STRING
Default: no run specific output written

Description
(For future expansion; not currently used by any methods.) Specify a base filename to which Dakota will write
any run output data (typically parameter, response pairs). This option is overridden by any command-line -run
arguments.

6.1.8

post run

Keywords Area
environment
post run
Invoke Dakota with post-run mode active

Topics
This keyword is related to the topics:
command line options

Specification
Alias: none
Argument(s): none
Default: pre-run, run, post-run all executed

6.1. ENVIRONMENT

173
Required/Optional
Optional

Description of
Group

Dakota Keyword
input

Optional

output

Dakota Keyword
Description
Base filename for
post-run mode data
input
Base filename for
post-run mode data
output

Description
When specified, Dakota execution will include the post-run mode, which analyzes parameter/response data sets
and computes final results.. This mode is currently useful for parameter study, DACE, and Monte Carlo sampling
methods.
Default Behavior
When no run modes are specified, Dakota will perform pre-run, run, and post-run phases.
input
Keywords Area
environment
post run
input
Base filename for post-run mode data input

Topics
This keyword is related to the topics:
dakota IO

Specification
Alias: none
Argument(s): STRING
Default: no post-run specific input read
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

174

CHAPTER 6. KEYWORDS AREA

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
Specify a base filename from which Dakota will read any post-run input data, such as parameter/response data on
which to calulate final statistics. This option is overridden by any command-line -post run arguments.
Usage Tips
Dakota imports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
environment
post run
input
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

6.1. ENVIRONMENT

175

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
environment
post run
input
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

176

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

6.1. ENVIRONMENT
%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

177
x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
environment
post run
input
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
environment
post run
input
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

178

CHAPTER 6. KEYWORDS AREA

Description
See description of parent custom annotated
interface id
Keywords Area
environment
post run
input
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
environment
post run
input
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

6.1. ENVIRONMENT

179

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

output
Keywords Area
environment
post run
output
Base filename for post-run mode data output

Topics
This keyword is related to the topics:
dakota IO

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

180

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: no post-run specific output written

Description
(For future expansion; not currently used by any methods.) Specify a base filename to which Dakota will write
any post-run output data. This option is overridden by any command-line -post run arguments.

6.1.9

graphics

Keywords Area
environment
graphics
Display a 2D graphics window of variables and responses

Topics
This keyword is related to the topics:
dakota output

Specification
Alias: none
Argument(s): none
Default: graphics off

Description
For most studies, the graphics flag activates a 2D graphics window containing history plots for the variables
and response functions in the study. This window is updated in an event loop with approximately a 2 second cycle
time. Some study types such as surrogate-based optimization or local reliability specialize the use of the graphics
window.
There is no dependence between the graphics flag and the tabular data flag; they may be used independently or concurrently.

See Also
These keywords may also be of interest:
tabular data

6.1. ENVIRONMENT

6.1.10

181

tabular data

Keywords Area
environment
tabular data
Write a tabular results file with variable and response history

Topics
This keyword is related to the topics:
dakota output

Specification
Alias: tabular graphics data
Argument(s): none
Default: no tabular data output
Required/Optional
Optional

Optional(Choose
One)

Description of
Group

Dakota Keyword
tabular data file

tabular format
(Group 1)

Dakota Keyword
Description
File name for
tabular data output

annotated

Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
Specifying the tabular data flag writes to a data file the same variable and response function history data
plotted when using the graphics flag. Within the generated data file, the variables and response functions
appear as columns and each function evaluation provides a new table row. This capability is most useful for
post-processing of Dakota results with third-party graphics tools such as MatLab, Excel, Tecplot, etc.
There is no dependence between the graphics flag and the tabular data flag; they may be used independently or concurrently.
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform

182

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
graphics
tabular data file
Keywords Area
environment
tabular data
tabular data file
File name for tabular data output

Topics
This keyword is related to the topics:
dakota output

Specification
Alias: tabular graphics file
Argument(s): STRING
Default: dakota tabular.dat

Description
Specifies a name to use for the tabular data file, overriding the default dakota tabular.dat.
annotated
Keywords Area
environment
tabular data
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

6.1. ENVIRONMENT

183

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
environment
tabular data
custom annotated
Selects custom-annotated tabular file format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

184

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:

6.1. ENVIRONMENT

185

environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
environment
tabular data
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
environment
tabular data
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

186

CHAPTER 6. KEYWORDS AREA

Description
See description of parent custom annotated
interface id
Keywords Area
environment
tabular data
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
environment
tabular data
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

6.1. ENVIRONMENT

187

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

6.1.11

output precision

Keywords Area
environment
output precision
Control the output precision

Topics
This keyword is related to the topics:
dakota output

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

188

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 10

Description
The precision of numeric output precision can be set dwith output precision, with an upper limit of 16.
When not specified, most Dakota output will default to a precision of 10, though filesystem interfaces and pre-run
output use higher precision for accuracy and better results reproducibility.

6.1.12

results output

Keywords Area
environment
results output
(Experimental) Write a summary file containing the final results

Topics
This keyword is related to the topics:
dakota output

Specification
Alias: none
Argument(s): none
Default: no results output
Required/Optional
Optional

Description of
Group

Dakota Keyword
results output file

Dakota Keyword
Description
The base file name
of the results file

Description
Final results from a Dakota study can be output to dakota results.txt by specifying results output (optionally
specifying an alternate file name with results output filename). The current experimental text file format
is hierarchical and a precursor to planned output to structured text formats such as XML or YAML, and binary
formats such as HDF5. The contents, organization, and format of results files are all under active development
and are subject to change.

6.1. ENVIRONMENT
results output file
Keywords Area
environment
results output
results output file
The base file name of the results file

Topics
This keyword is related to the topics:
dakota output

Specification
Alias: none
Argument(s): STRING
Default: dakota results.txt

Description
Default file name is dakota results.txt

6.1.13

top method pointer

Keywords Area
environment
top method pointer
Identify which method leads the Dakota study

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: method pointer
Argument(s): STRING
Default: see discussion

189

190

CHAPTER 6. KEYWORDS AREA

Description
An optional top method pointer specification may be used to point to a particular method specification that
will lead the Dakota analysis. The associated string must be a method identifier specified via id method. If topmethod pointer is not used, then it will be inferred as decribed below (no top method pointer within
an environment specification is treated the same as no environment specification).
Default Behavior
The top method pointer keyword is typically used in Dakota studies consisting of more than one method
block to clearly indicate which is the leading method. This method provides the starting point for the iteration.
The corresponding method specification may recurse with additional sub-method pointers in the case of metaiteration (see method) or may specify a single method without recursion. Either case will ultimately result in
identification of one or more model specifications using model pointer, which again may or may not involve
further recursion (see nested and surrogate for recursion cases). Each of the model specifications identify the
variables and responses specifications (using variables pointer and responses pointer) that are used to build the
model, and depending on the type of model, may also identify an interface specification (for example, using
interface pointer). If one of these specifications does not provide an optional pointer, then that component will be
constructed using the last specification parsed.
When the environment block is omitted, the top level method will be inferred as follows: When a single
method is specified, there is no ambiguity and the sole method will be the top method. When multiple methods are
specified, the top level method will be deduced from the hierarchical relationships implied by method pointers. If
this inference is not well defined (e.g., there are multiple method specifications without any pointer relationship),
then the default behavior is to employ the last method specification parsed.

Examples
Specify that the optimization method is the outermost method in an optimization under uncertainty study
environment
top_method_pointer OPTIMIZATION_METHOD
method
id_method UQ_METHOD
...
method
id_method OPTIMIZATION_METHOD
...

See Also
These keywords may also be of interest:
id method

6.2

method

Keywords Area
method
Begins Dakota method selection and behavioral settings.

Topics
This keyword is related to the topics:
block

6.2. METHOD

191

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
id method

Optional

output

Optional

final solutions

hybrid

multi start

pareto set
branch and bound

Required(Choose
One)

Group 1

Dakota Keyword
Description
Name the method
block; helpful
when there are
multiple
Control how much
method
information is
written to the
screen and output
file
Number of designs
returned as the best
solutions
Strategy in which a
set of methods
synergistically
seek an optimal
design
Multi-Start
Optimization
Method
Pareto set
optimization
(Experimental
Capability) Solves
a mixed integer
nonlinear
optimization
problem

192

CHAPTER 6. KEYWORDS AREA

surrogate based local
surrogate based global
dot frcg

dot mmfd
dot bfgs

dot slp
dot sqp
dot

conmin frcg

conmin mfd
conmin

dl solver

npsol sqp
nlssol sqp

Local Surrogate
Based
Optimization
Global Surrogate
Based
Optimization
A conjugate
gradient
optimization
method
Method of feasible
directions
A conjugate
gradient
optimization
method
Sequential Linear
Programming
Sequential
Quadratic Program
Access to methods
in the DOT
package
A conjugate
gradient
optimization
method
Method of feasible
directions
Access to methods
in the CONMIN
library
(Experimental)
Dynamicallyloaded
solver
Sequential
Quadratic Program
Sequential
Quadratic Program
for nonlinear least
squares

6.2. METHOD

193
stanford

nlpql sqp
optpp cg

optpp q newton

optpp fd newton

optpp g newton

optpp newton
optpp pds

asynch pattern search

mesh adaptive search

moga

soga

Select methods
from the Stanford
package
Sequential
Quadratic Program
A conjugate
gradient
optimization
method
Quasi-Newton
optimization
method
Finite Difference
Newton
optimization
method
Newton method
based least-squares
calbration
Newton method
based optimization
Simplex-based
derivative free
optimization
method
Pattern search,
derivative free
optimization
method
Finds optimal
variable values
using adaptive
mesh-based search
Multi-objective
Genetic Algorithm
(a.k.a Evolutionary
Algorithm)
Single-objective
Genetic Algorithm
(a.k.a Evolutionary
Algorithm)

194

CHAPTER 6. KEYWORDS AREA

coliny pattern search

coliny solis wets

coliny cobyla

coliny direct

coliny ea
coliny beta

nl2sol

nonlinear cg

ncsu direct

genie opt darts

genie direct

Pattern search,
derivative free
optimization
method
Simple greedy
local search
method
Constrained
Optimization BY
Linear
Approximations
(COBYLA)
DIviding
RECTangles
method
Evolutionary
Algorithm
(Experimental)
Coliny beta solver
Trust-region
method for
nonlinear least
squares
(Experimental)
nonlinear
conjugate gradient
optimization
DIviding
RECTangles
method
Voronoi-based
high-dimensional
global Lipschitzian
optimization
Classical
high-dimensional
global Lipschitzian
optimization
Classical
high-dimensional
global Lipschitzian
optimization

6.2. METHOD

195
efficient global

polynomial chaos

Global Surrogate
Based
Optimization,
a.k.a. EGO
Uncertainty
quantification
using polynomial
chaos expansions

stoch collocation

Uncertainty
quantification with
stochastic
collocation

sampling

Randomly samples
variables according
to their
distributions

importance sampling
gpais

Importance
sampling
Gaussian Process
Adaptive
Importance
Sampling
(Experimental)
Build a GP
surrogate and
refine it adaptively
Probability-of-Failure (POF) darts
is a novel method
for estimating the
probability of
failure based on
random
sphere-packing.

adaptive sampling

pof darts

196

CHAPTER 6. KEYWORDS AREA

rkd darts

Recursive k-d
(RKD) Darts:
Recursive
Hyperplane
Sampling for
Numerical
Integration of
High-Dimensional
Functions.

efficient subspace

(Experimental)
efficient subspace
method (ESM)

global evidence

Evidence theory
with evidence
measures
computed with
global optimization
methods
Interval analysis
using global
optimization
methods
Bayesian
calibration

global interval est

bayes calibration

dace

fsu cvt

psuade moat
local evidence

Design and
Analysis of
Computer
Experiments
Design of
Computer
Experiments Centroidal Voronoi
Tessellation
Morris
One-at-a-Time
Evidence theory
with evidence
measures
computed with
local optimization
methods

6.2. METHOD

197
local interval est

local reliability
global reliability
fsu quasi mc

vector parameter study

Interval analysis
using local
optimization
Local reliability
method
Global reliability
methods
Design of
Computer
Experiments Quasi-Monte Carlo
sampling
Samples variables
along a
user-defined vector

list parameter study

Samples variables
as a specified
values

centered parameter study

Samples variables
along points
moving out from a
center point

multidim parameter study

Samples variables
on full factorial
grid of study points

richardson extrap

Estimate order of
convergence of a
response as model
fidelity increases

Description
The method keyword signifies the start of a block in the Dakota input file. Said block contains the various
keywords necessary to specify a method and to control its behavior.
Method Block Requirements
At least one method block must appear in the Dakota input file. Multiple method blocks may be needed to
fully define advanced analysis approaches.
Each method block must specify one method and, optionally, any associated keywords that govern the behavior of the method.
The Methods
Each method block must select one method.
Starting with Dakota v6.0, the methods are grouped into two types: standard methods and multi-component
methods.
The standard methods are stand-alone and self-contained in the sense that they only require a model to perform
a study. They do not call other methods. While methods such as polynomial chaos and efficientglobal internally utilize multiple iterator and surrogate model components, these components are generally

198

CHAPTER 6. KEYWORDS AREA

hidden from user control due to restrictions on modularity; thus, these methods are stand-alone.
The multi-component group of methods provides a higher level meta-algorithm that points to other methods
and models that support sub-iteration. For example, in a sequential hybrid method, the hybrid method specification must identify a list of subordinate methods, and the meta-algorithm executes these methods in sequence
and transfers information between them. Surrogate-based minimizers provide another example in that they point
both to other methods (e.g. what optimization method is used to solve the approximate subproblem) as well as to
models (e.g. what type of surrogate model is employed). Multi-component methods generally provide some level
of plug and play modularity, through their flexible support of a variety of method and model selections.
Component-Based Iterator Commands
Component-based iterator specifications include hybrid, multi-start, pareto set, surrogate-based local, surrogatebased global, and branch and bound methods. Whereas a standard iterator specification only needs an optional
model pointer string (specified with model pointer), component-based iterator specifications can include
method pointer, method name, and model pointer specifications in order to define the components employed in
the meta-iteration. In particular, these specifications identify one or more methods (by pointer or by name) to
specify the subordinate iterators that will be used in the top-level algorithm. Identifying a sub-iterator by name
instead of by pointer is a lightweight option that relaxes the need for a separate method specification for the subiterator; however, a model pointer may be required in this case to provide the specification connectivity normally
supported by the method pointer. Refer to these individual method descriptions for specific requirements for these
advanced methods.
Method Independent Controls
In addition to the method, there are 10 optional keywords, which are referred to as method independent
controls. These controls are valid for enough methods that it was reasonable to pull them out of the method
dependent blocks and consolidate the specifications, however, they are NOT universally respected by all methods.

Examples
Several examples follow. The first example shows a minimal specification for an optimization method.
method
dot_sqp

This example uses all of the defaults for this method.

A more sophisticated example would be
method,
id_method = NLP1
dot_sqp
max_iterations = 50
convergence_tolerance = 1e-4
output verbose
model_pointer = M1

This example demonstrates the use of identifiers and pointers as well as some method independent and method
dependent controls for the sequential quadratic programming (SQP) algorithm from the DOT library. The maxiterations, convergence tolerance, and output settings are method independent controls, in that
they are defined for a variety of methods (see dot for usage of these controls).
The next example shows a specification for a least squares method.
method
optpp_g_newton
max_iterations = 10
convergence_tolerance = 1.e-8
search_method trust_region
gradient_tolerance = 1.e-6

6.2. METHOD

199

Some of the same method independent controls are present along with several method dependent controls (searchmethod and gradient tolerance) which are only meaningful for OPT++ methods (see package optpp).
The next example shows a specification for a nondeterministic method with several method dependent controls
(refer to sampling).
method
sampling
samples = 100
seed = 12345
sample_type lhs
response_levels = 1000. 500.

The last example shows a specification for a parameter study method where, again, each of the controls are
method dependent (refer to vector parameter study).
method
vector_parameter_study
step_vector = 1. 1. 1.
num_steps = 10

6.2.1

id method

Keywords Area
method
id method
Name the method block; helpful when there are multiple

Topics
This keyword is related to the topics:
block identifier
method independent controls

Specification
Alias: none
Argument(s): STRING
Default: strategy use of last method parsed

Description
The method identifier string is supplied with id method and is used to provide a unique identifier string for
use with environment or meta-iterator specifications (refer to environment). It is appropriate to omit a method
identifier string if only one method is included in the input file, since the single method to use is unambiguous in
this case.

200

CHAPTER 6. KEYWORDS AREA

6.2.2

output

Keywords Area
method
output
Control how much method information is written to the screen and output file

Topics
This keyword is related to the topics:
dakota output
method independent controls

Specification
Alias: none
Argument(s): none
Default: normal
Required/Optional

Description of
Group

Dakota Keyword
debug

Required(Choose
One)

output level
(Group 1)

verbose
normal
quiet
silent

Dakota Keyword
Description
Level 5 of 5 maximum
Level 4 of 5 - more
than normal
Level 3 of 5 default
Level 2 of 5 - less
than normal
Level 1 of 5 minimum

Description
Choose from a total of five output levels during the course of a Dakota study. If there is no user specification for
output verbosity, then the default setting is normal.
Specific mappings are as follows:
silent (i.e., really quiet): silent iterators, silent model, silent interface, quiet approximation, quiet file
operations
quiet: quiet iterators, quiet model, quiet interface, quiet approximation, quiet file operations
normal: normal iterators, normal model, normal interface, quiet approximation, quiet file operations
verbose: verbose iterators, normal model, verbose interface, verbose approximation, verbose file operations
debug (i.e., really verbose): debug iterators, normal model, debug interface, verbose approximation, verbose file operations

6.2. METHOD

201

Note that iterators and interfaces utilize the full granularity in verbosity, whereas models, approximations, and file
operations do not. With respect to iterator verbosity, different iterators implement this control in slightly different
ways (as described below in the method independent controls descriptions for each iterator), however the meaning
is consistent.
For models, interfaces, approximations, and file operations, quiet suppresses parameter and response set reporting and silent further suppresses function evaluation headers and scheduling output. Similarly, verbose
adds file management, approximation evaluation, and global approximation coefficient details, and debug further
adds diagnostics from nonblocking schedulers.
debug
Keywords Area
method
output
debug
Level 5 of 5 - maximum

Specification
Alias: none
Argument(s): none

Description
This is described on output
verbose
Keywords Area
method
output
verbose
Level 4 of 5 - more than normal

Specification
Alias: none
Argument(s): none

Description
This is described on output

202

CHAPTER 6. KEYWORDS AREA

normal
Keywords Area
method
output
normal
Level 3 of 5 - default

Specification
Alias: none
Argument(s): none

Description
This is described on output
quiet
Keywords Area
method
output
quiet
Level 2 of 5 - less than normal

Specification
Alias: none
Argument(s): none

Description
This is described on output
silent
Keywords Area
method
output
silent
Level 1 of 5 - minimum

6.2. METHOD

203

Specification
Alias: none
Argument(s): none

Description
This is described on output

6.2.3

final solutions

Keywords Area
method
final solutions
Number of designs returned as the best solutions

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
The final solutions controls the number of final solutions returned by the iterator as the best solutions.
For most optimizers, this is one, but some optimizers can produce multiple solutions (e.g. genetic algorithms).
When using a hybrid strategy, the number of final solutions dictates how many solutions are passed from
one method to another.

Examples
In the case of sampling methods, if one specifies 100 samples (for example) but also specifies final solutions
= 5, the five best solutions (in order of lowest response function value) are returned.

6.2.4

hybrid

Keywords Area
method
hybrid
Strategy in which a set of methods synergistically seek an optimal design

204

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
sequential

embedded

collaborative

Optional

iterator servers

Optional

iterator scheduling

Optional

processors per iterator

Dakota Keyword
Description
Methods are run
one at a time, in
sequence
A subordinate
local method
provides periodic
refinements to a
top-level global
method
Multiple methods
run concurrently
and share
information
Specify the
number of iterator
servers when
Dakota is run in
parallel
Specify the
scheduling of
concurrent iterators
when Dakota is run
in parallel
Specify the
number of
processors per
iterator server
when Dakota is run
in parallel

Description
In a hybrid minimization method (hybrid), a set of methods synergistically seek an optimal design. The relationships among the methods are categorized as:
collaborative
embedded
sequential
The goal in each case is to exploit the strengths of different optimization and nonlinear least squares algorithms
at different stages of the minimization process. Global + local hybrids (e.g., genetic algorithms combined with
nonlinear programming) are a common example in which the desire for identification of a global optimum is
balanced with the need for efficient navigation to a local optimum.

6.2. METHOD

205

sequential
Keywords Area
method
hybrid
sequential
Methods are run one at a time, in sequence

Specification
Alias: uncoupled
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
method name list

method pointer list

Dakota Keyword
Description
List of Dakota
methods to
sequentially or
collaboratively run
Pointers to
methods to execute
sequantially or
collaboratively

Description
In the sequential approach, methods are run one at a time, in sequence. The best solutions from one method
are used to initialize the next method.
The sequence of methods (i.e. iterators) to run are specified using either a method pointer list or a
method name list (with optional model pointer list). Any number of iterators may be specified.
Method switching is managed through the separate convergence controls of each method. The number of
solutions transferred between methods is specified by the particular method through its final solutions method
control.
For example, if one sets up a two-level study with a first method that generates multiple solutions such as a
genetic algorithm, followed by a second method that is initialized only at a single point such as a gradient-based
algorithm, it is possible to take the multiple solutions generated by the first method and create several instances
of the second method, each one with a different initial starting point.
The logic governing the transfer of multiple solutions between methods is as follows:
if one solution is returned from method A, then one solution is transferred to method B.
If multiple solutions are returned from method A, and method B can accept multiple solutions as input
(for example, as a genetic algorithm population), then one instance of method B is initialized with multiple
solutions.
If multiple solutions are returned from method A but method B only can accept one initial starting point,
then method B is run several times, each one with a separate starting point from the results of method A.

206

CHAPTER 6. KEYWORDS AREA

method name list

Keywords Area
method
hybrid
sequential
method name list
List of Dakota methods to sequentially or collaboratively run

Specification
Alias: none
Argument(s): STRINGLIST
Required/Optional
Optional

Description of
Group

Dakota Keyword
model pointer list

Dakota Keyword
Description
Associate models
with method
names

Description
method name list specifies a list of Dakota methods (e.g. soga, conmin frcg) that will be run by a hybrid
sequential or hybrid collaborative method. The methods are executed with default options. The
optional model pointer list may be used to associate a model with each method.
model pointer list
Keywords Area
method
hybrid
sequential
method name list
model pointer list
Associate models with method names

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

6.2. METHOD

207

Description
Using the optional keyword model pointer list, models can be assigned to methods specified in the methodname list. Models are referred to by name (i.e. by their id model labels). The length of the model pointer list must be either 1 or match the length of the method name list. If the former, the same
model will be used for all methods, and if the latter, methods and models will be paired in the order that they
appear in the two lists.
method pointer list
Keywords Area
method
hybrid
sequential
method pointer list
Pointers to methods to execute sequantially or collaboratively

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRINGLIST

Description
method pointer list specifies by name the methods that are to be executed by a hybrid sequential
or hybrid collaborative method. Its argument is a list of strings that refer to method blocks by name (i.e.
to their id method labels).
embedded
Keywords Area
method
hybrid
embedded
A subordinate local method provides periodic refinements to a top-level global method

Specification
Alias: coupled
Argument(s): none

208

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Required(Choose
One)

Description of
Group
Group 1

Group 2

Dakota Keyword
global method name
global method pointer
local method name

local method pointer

local search probability

Optional

Dakota Keyword
Description
Specify the global
method by Dakota
name
Pointer to global
method
Specify the local
method by Dakota
name
Pointer to local
method
Probability of
executing local
searches

Description
In the embedded approach, a tightly-coupled hybrid is employed in which a subordinate local method provides
periodic refinements to a top-level global method.
Global and local method strings supplied with the global method pointer and local method pointer specifications identify the two methods to be used. Alternatively, Dakota method names (e.g. soga)
can be supplied using the global method name and local method name keywords, which each have optional model pointer specifications. The local search probability setting is an optional specification for
supplying the probability (between 0.0 and 1.0) of employing local search to improve estimates within the global
search.
global method name
Keywords Area
method
hybrid
embedded
global method name
Specify the global method by Dakota name

Specification
Alias: none
Argument(s): STRING
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

209
Optional

global model pointer

Pointer to model
used by global
method

Description
global method name is used to specify the global method in a hybrid embedded optimization by Dakota
name (e.g. soga). The name of the method is provided as a string. The method is executed with default options.
global model pointer
Keywords Area
method
hybrid
embedded
global method name
global model pointer
Pointer to model used by global method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
global model pointer can be used to specify a model for use with the Dakota method named by the
global method name specification. The argument is a string that refers to the id model label of the desired
model.
global method pointer
Keywords Area
method
hybrid
embedded
global method pointer
Pointer to global method

210

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
The global method pointer identifies the method block to use as the global method in a hybrid embedded
optimization using its id method label.
local method name
Keywords Area
method
hybrid
embedded
local method name
Specify the local method by Dakota name

Specification
Alias: none
Argument(s): STRING
Required/Optional
Optional

Description of
Group

Dakota Keyword
local model pointer

Dakota Keyword
Description
Pointer to model
used by local
method

Description
local method name is used to specify the local method in a hybrid embedded optimization by Dakota
name (e.g. conmin mfd). The name of the method is provided as a string. The method is executed with default
options.
local model pointer
Keywords Area
method
hybrid

6.2. METHOD

211

embedded
local method name
local model pointer
Pointer to model used by local method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
local model pointer can be used to specify a model for use with the Dakota method named by the localmethod name specification. The argument is a string that refers to the id model label of the desired model.
local method pointer
Keywords Area
method
hybrid
embedded
local method pointer
Pointer to local method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
The local method pointer identifies the method block to use as the local method in a hybrid embedded
optimization using its id method

212

CHAPTER 6. KEYWORDS AREA

local search probability

Keywords Area
method
hybrid
embedded
local search probability
Probability of executing local searches

Specification
Alias: none
Argument(s): REAL

Description
The local search probability setting is an optional specification for supplying the probability (between
0.0 and 1.0) of employing local search to improve estimates within the global search. Its default value is 0.1.
collaborative
Keywords Area
method
hybrid
collaborative
Multiple methods run concurrently and share information

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
method name list

Dakota Keyword
Description
List of Dakota
methods to
sequentially or
collaboratively run

6.2. METHOD

213
method pointer list

Pointers to
methods to execute
sequantially or
collaboratively

Description
In the collaborative approach, multiple methods work together and share solutions while executing concurrently.
A list of method strings specifies the pool of iterators to be used. Any number of iterators may be specified.
The method collaboration logic follows that of either the Agent-Based Optimization or HOPSPACK codes and is
currently under development and not available at this time.
method name list
Keywords Area
method
hybrid
collaborative
method name list
List of Dakota methods to sequentially or collaboratively run

Specification
Alias: none
Argument(s): STRINGLIST
Required/Optional
Optional

Description of
Group

Dakota Keyword
model pointer list

Dakota Keyword
Description
Associate models
with method
names

Description
method name list specifies a list of Dakota methods (e.g. soga, conmin frcg) that will be run by a hybrid
sequential or hybrid collaborative method. The methods are executed with default options. The
optional model pointer list may be used to associate a model with each method.
model pointer list
Keywords Area
method
hybrid
collaborative
method name list
model pointer list
Associate models with method names

214

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
Using the optional keyword model pointer list, models can be assigned to methods specified in the methodname list. Models are referred to by name (i.e. by their id model labels). The length of the model pointer list must be either 1 or match the length of the method name list. If the former, the same
model will be used for all methods, and if the latter, methods and models will be paired in the order that they
appear in the two lists.
method pointer list
Keywords Area
method
hybrid
collaborative
method pointer list
Pointers to methods to execute sequantially or collaboratively

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRINGLIST

Description
method pointer list specifies by name the methods that are to be executed by a hybrid sequential
or hybrid collaborative method. Its argument is a list of strings that refer to method blocks by name (i.e.
to their id method labels).

6.2. METHOD

215

iterator servers
Keywords Area
method
hybrid
iterator servers
Specify the number of iterator servers when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator servers specification supports user override of the automatic parallel configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.
iterator scheduling
Keywords Area
method
hybrid
iterator scheduling
Specify the scheduling of concurrent iterators when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

216

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
master

peer

Dakota Keyword
Description
Specify a
dedicated master
partition for
parallel iterator
scheduling
Specify a peer
partition for
parallel iterator
scheduling

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator scheduling specification supports user override of the automatic parallel
configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.
master
Keywords Area
method
hybrid
iterator scheduling
master
Specify a dedicated master partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a dedicated master partition.
In a dedicated master partition, one processor (the master) dynamically schedules work on the iterator servers.
This reduces the number of processors available to create servers by 1.

6.2. METHOD

217

peer
Keywords Area
method
hybrid
iterator scheduling
peer
Specify a peer partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a peer partition. In a peer partition, all processors are available to be assigned to iterator servers. Note that unlike the case of evaluation scheduling, it is not possible to specify static or dynamic.
processors per iterator
Keywords Area
method
hybrid
processors per iterator
Specify the number of processors per iterator server when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

218

CHAPTER 6. KEYWORDS AREA

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional processors per iterator specification supports user override of the automatic
parallel configuration for the number of processors in each iterator server. That is, if the automatic configuration is undesirable for some reason, the user can enforce a desired server size at the iterator parallelism level.
Currently, hybrid, multi start, and pareto set component-based iterators support concurrency in their
sub-iterators. Refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual[4] for additional
information.

6.2.5

multi start

Keywords Area
method
multi start
Multi-Start Optimization Method

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
method name

method pointer

Optional

random starts

Optional

starting points

Optional

iterator servers

Dakota Keyword
Description
Specify
sub-method by
name
Pointer to
sub-method to run
from each starting
point
Number of random
starting points
List of
user-specified
starting points
Specify the
number of iterator
servers when
Dakota is run in
parallel

6.2. METHOD

219
Optional

iterator scheduling

Optional

processors per iterator

Specify the
scheduling of
concurrent iterators
when Dakota is run
in parallel
Specify the
number of
processors per
iterator server
when Dakota is run
in parallel

Description
In the multi-start iteration method (multi start), a series of iterator runs are performed for different values
of parameters in the model. A common use is for multi-start optimization (i.e., different local optimization runs
from different starting points for the design variables), but the concept and the code are more general. Multi-start
iteration is implemented within the MetaIterator branch of the Iterator hierarchy within the ConcurrentMetaIterator class. Additional information on the multi-start algorithm is available in the Users Manual[4].
The multi start meta-iterator must specify a sub-iterator using either a method pointer or a methodname plus optional model pointer. This iterator is responsible for completing a series of iterative analyses
from a set of different starting points. These starting points can be specified as follows: (1) using random starts, for which the specified number of starting points are selected randomly within the variable bounds,
(2) using starting points, in which the starting values are provided in a list, or (3) using both random starts and starting points, for which the combined set of points will be used. In aggregate, at least one
starting point must be specified. The most common example of a multi-start algorithm is multi-start optimization,
in which a series of optimizations are performed from different starting values for the design variables. This can
be an effective approach for problems with multiple minima.
method name
Keywords Area
method
multi start
method name
Specify sub-method by name

Specification
Alias: none
Argument(s): STRING
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

220

CHAPTER 6. KEYWORDS AREA

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The method name keyword is used to specify a sub-method by Dakota method name (e.g. npsol sqp) rather
than block pointer. The method will be executed using its default settings. The optional model pointer
specification can be used to associate a model block with the method.
model pointer
Keywords Area
method
multi start
method name
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

6.2. METHOD

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

method pointer
Keywords Area
method
multi start
method pointer
Pointer to sub-method to run from each starting point

221

222

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
The method pointer keyword is used to specify a pointer to the sub-method block that will be run from each
starting point.
random starts
Keywords Area
method
multi start
random starts
Number of random starting points

Specification
Alias: none
Argument(s): INTEGER
Required/Optional
Optional

Description of
Group

Dakota Keyword
seed

Dakota Keyword
Description
Seed of the random
number generator

Description
The multi start meta-iterator must specify a sub-iterator using either a method pointer or a methodname plus optional model pointer. This iterator is responsible for completing a series of iterative analyses
from a set of different starting points. These starting points can be specified as follows: (1) using random starts, for which the specified number of starting points are selected randomly within the variable bounds,
(2) using starting points, in which the starting values are provided in a list, or (3) using both random starts and starting points, for which the combined set of points will be used.

6.2. METHOD

223

seed
Keywords Area
method
multi start
random starts
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

starting points
Keywords Area
method
multi start
starting points
List of user-specified starting points

224

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST

Description
The multi start meta-iterator must specify a sub-iterator using either a method pointer or a methodname plus optional model pointer. This iterator is responsible for completing a series of iterative analyses
from a set of different starting points. These starting points can be specified as follows: (1) using random starts, for which the specified number of starting points are selected randomly within the variable bounds,
(2) using starting points, in which the starting values are provided in a list, or (3) using both random starts and starting points, for which the combined set of points will be used.
iterator servers
Keywords Area
method
multi start
iterator servers
Specify the number of iterator servers when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator servers specification supports user override of the automatic parallel configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.
iterator scheduling
Keywords Area
method
multi start

6.2. METHOD

225

iterator scheduling
Specify the scheduling of concurrent iterators when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
master

peer

Dakota Keyword
Description
Specify a
dedicated master
partition for
parallel iterator
scheduling
Specify a peer
partition for
parallel iterator
scheduling

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator scheduling specification supports user override of the automatic parallel
configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.
master
Keywords Area
method
multi start
iterator scheduling
master
Specify a dedicated master partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

226

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a dedicated master partition.
In a dedicated master partition, one processor (the master) dynamically schedules work on the iterator servers.
This reduces the number of processors available to create servers by 1.
peer
Keywords Area
method
multi start
iterator scheduling
peer
Specify a peer partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a peer partition. In a peer partition, all processors are available to be assigned to iterator servers. Note that unlike the case of evaluation scheduling, it is not possible to specify static or dynamic.
processors per iterator
Keywords Area
method
multi start
processors per iterator
Specify the number of processors per iterator server when Dakota is run in parallel

6.2. METHOD

227

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional processors per iterator specification supports user override of the automatic
parallel configuration for the number of processors in each iterator server. That is, if the automatic configuration is undesirable for some reason, the user can enforce a desired server size at the iterator parallelism level.
Currently, hybrid, multi start, and pareto set component-based iterators support concurrency in their
sub-iterators. Refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual[4] for additional
information.

6.2.6

pareto set

Keywords Area
method
pareto set
Pareto set optimization

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
method name

method pointer

Dakota Keyword
Description
Specify
sub-method by
name
Pointer to
optimization or
least-squares
sub-method

228

CHAPTER 6. KEYWORDS AREA

Optional
Optional

random weight sets

weight sets

Optional

iterator servers

Optional

iterator scheduling

Optional

processors per iterator

Number of random
weighting sets
List of
user-specified
weighting sets
Specify the
number of iterator
servers when
Dakota is run in
parallel
Specify the
scheduling of
concurrent iterators
when Dakota is run
in parallel
Specify the
number of
processors per
iterator server
when Dakota is run
in parallel

Description
In the pareto set minimization method (pareto set), a series of optimization or least squares calibration runs
are performed for different weightings applied to multiple objective functions. This set of optimal solutions
defines a Pareto set, which is useful for investigating design trade-offs between competing objectives. The code
is similar enough to the multi start technique that both algorithms are implemented in the same ConcurrentMetaIterator class.
The pareto set specification must identify an optimization or least squares calibration method using either
a method pointer or a method name plus optional model pointer. This minimizer is responsible for
computing a set of optimal solutions from a set of response weightings (multi-objective weights or least squares
term weights). These weightings can be specified as follows: (1) using random weight sets, in which case
weightings are selected randomly within [0,1] bounds, (2) using weight sets, in which the weighting sets are
specified in a list, or (3) using both random weight sets and weight sets, for which the combined set
of weights will be used. In aggregate, at least one set of weights must be specified. The set of optimal solutions
is called the pareto set, which can provide valuable design trade-off information when there are competing
objectives.
method name
Keywords Area
method
pareto set
method name
Specify sub-method by name

6.2. METHOD

229

Specification
Alias: opt method name
Argument(s): STRING
Required/Optional
Optional

Description of
Group

Dakota Keyword
model pointer

Dakota Keyword
Description
Identifier for
model block to be
used by a method

Description
The method name keyword is used to specify a sub-method by Dakota method name (e.g. npsol sqp) rather
than block pointer. The method will be executed using its default settings. The optional model pointer
specification can be used to associate a model block with the method.
model pointer
Keywords Area
method
pareto set
method name
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: opt model pointer
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

230

CHAPTER 6. KEYWORDS AREA

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

method pointer
Keywords Area
method
pareto set
method pointer
Pointer to optimization or least-squares sub-method

6.2. METHOD

231

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: opt method pointer
Argument(s): STRING

Description
The method pointer keyword is used to specify a pointer to an optimization or least-squares sub-method that
is responsible for computing a set of optimal solutions for a set of response weightings.
random weight sets
Keywords Area
method
pareto set
random weight sets
Number of random weighting sets

Specification
Alias: none
Argument(s): INTEGER
Required/Optional
Optional

Description of
Group

Dakota Keyword
seed

Dakota Keyword
Description
Seed of the random
number generator

Description
The pareto set specification must identify an optimization or least squares calibration method using either
a method pointer or a method name plus optional model pointer. This minimizer is responsible for
computing a set of optimal solutions from a set of response weightings (multi-objective weights or least squares
term weights). These weightings can be specified as follows: (1) using random weight sets, in which case
weightings are selected randomly within [0,1] bounds, (2) using weight sets, in which the weighting sets are
specified in a list, or (3) using both random weight sets and weight sets, for which the combined set
of weights will be used. In aggregate, at least one set of weights must be specified. The set of optimal solutions
is called the pareto set, which can provide valuable design trade-off information when there are competing
objectives.

232

CHAPTER 6. KEYWORDS AREA

seed
Keywords Area
method
pareto set
random weight sets
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

weight sets
Keywords Area
method
pareto set
weight sets
List of user-specified weighting sets

6.2. METHOD

233

Specification
Alias: multi objective weight sets
Argument(s): REALLIST

Description
The pareto set specification must identify an optimization or least squares calibration method using either
a method pointer or a method name plus optional model pointer. This minimizer is responsible for
computing a set of optimal solutions from a set of response weightings (multi-objective weights or least squares
term weights). These weightings can be specified as follows: (1) using random weight sets, in which case
weightings are selected randomly within [0,1] bounds, (2) using weight sets, in which the weighting sets are
specified in a list, or (3) using both random weight sets and weight sets, for which the combined set
of weights will be used. In aggregate, at least one set of weights must be specified. The set of optimal solutions
is called the pareto set, which can provide valuable design trade-off information when there are competing
objectives.
iterator servers
Keywords Area
method
pareto set
iterator servers
Specify the number of iterator servers when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator servers specification supports user override of the automatic parallel configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.

234

CHAPTER 6. KEYWORDS AREA

iterator scheduling
Keywords Area
method
pareto set
iterator scheduling
Specify the scheduling of concurrent iterators when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
master

peer

Dakota Keyword
Description
Specify a
dedicated master
partition for
parallel iterator
scheduling
Specify a peer
partition for
parallel iterator
scheduling

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator scheduling specification supports user override of the automatic parallel
configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.
master
Keywords Area
method
pareto set
iterator scheduling
master
Specify a dedicated master partition for parallel iterator scheduling

6.2. METHOD

235

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a dedicated master partition.
In a dedicated master partition, one processor (the master) dynamically schedules work on the iterator servers.
This reduces the number of processors available to create servers by 1.
peer
Keywords Area
method
pareto set
iterator scheduling
peer
Specify a peer partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a peer partition. In a peer partition, all processors are available to be assigned to iterator servers. Note that unlike the case of evaluation scheduling, it is not possible to specify static or dynamic.

236

CHAPTER 6. KEYWORDS AREA

processors per iterator

Keywords Area
method
pareto set
processors per iterator
Specify the number of processors per iterator server when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional processors per iterator specification supports user override of the automatic
parallel configuration for the number of processors in each iterator server. That is, if the automatic configuration is undesirable for some reason, the user can enforce a desired server size at the iterator parallelism level.
Currently, hybrid, multi start, and pareto set component-based iterators support concurrency in their
sub-iterators. Refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual[4] for additional
information.

6.2.7

branch and bound

Keywords Area
method
branch and bound
(Experimental Capability) Solves a mixed integer nonlinear optimization problem

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

237
Required(Choose
One)

Optional

Group 1

method pointer

Pointer to
sub-method to
apply to a
surrogate or
branch-and-bound
sub-problem

method name

Specify
sub-method by
name
Turn on scaling for
variables,
responses, and
constraints

scaling

Description
The branch-and-bound optimization methods solves mixed integer nonlinear optimization problems. It does so by
partitioning the parameter space according to some criteria along the integer or discrete variables. It then relaxes
(i.e., treats all variables as continuous) the sub-problems created by the partitions and solves each sub-problem
with a continuous nonlinear optimization method. Results of the sub-problems are combined in such a way that
yields the solution to the original optimization problem.
Default Behavior
Branch-and-bound expects all discrete variables to be relaxable. If your problem has categorical or otherwise
non-relaxable discrete variables, then this is not the optimization method you are looking for.
Expected Output
The optimal solution and associated parameters will be printed to the screen output.
Usage Tips
The user must choose a nonlinear optimization method to solve the sub- problems. We recommend choosing
a method that would be chosen to solve a continuous problem that has similar form to the mixed integer problem.

Examples
environment
method_pointer = BandB
method
id_method = BandB
branch_and_bound
output verbose
method_pointer = SubNLP
method
id_method = SubNLP
coliny_ea
seed = 12345
max_iterations = 100
max_function_evaluations = 100
variables,
continuous_design = 3
initial_point
-1.0
upper_bounds
10.0
lower_bounds
-10.0

1.5
2.0
10.0 10.0
-10.0 -10.0

238

CHAPTER 6. KEYWORDS AREA

descriptors
x1 x2 x3
discrete_design_range = 2
initial_point
2
2
lower_bounds
1
1
upper_bounds
4
9
descriptors
y1
y2
interface,
fork
analysis_driver = text_book
responses,
objective_functions = 1
nonlinear_inequality_constraints = 2
numerical_gradients
no_hessians

method pointer
Keywords Area
method
branch and bound
method pointer
Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
The method pointer keyword is used to specify a pointer to an optimization or least-squares sub-method to
apply in the context of what could be described as hierarchical methods. In surrogate-based methods, the submethod is applied to the surrogate model. In the branch-and-bound method, the sub-method is applied to the
relaxed sub-problems.
Any model pointer identified in the sub-method specification is ignored. Instead, the parent method is
responsible for selecting the appropriate model to use as specified by its model pointer. In surrogate-based
methods, it is a surrogate model defined using its model pointer. In branch-and-bound methods, it is the
relaxed model that is constructed internally from the original model.

6.2. METHOD

239

method name
Keywords Area
method
branch and bound
method name
Specify sub-method by name

Specification
Alias: none
Argument(s): STRING
Required/Optional
Optional

Description of
Group

Dakota Keyword
model pointer

Dakota Keyword
Description
Identifier for
model block to be
used by a method

Description
The method name keyword is used to specify a sub-method by Dakota method name (e.g. npsol sqp) rather
than block pointer. The method will be executed using its default settings. The optional model pointer
specification can be used to associate a model block with the method.
model pointer
Keywords Area
method
branch and bound
method name
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

240

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

241

response_functions = 3
no_gradients
no_hessians

scaling
Keywords Area
method
branch and bound
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored

242

CHAPTER 6. KEYWORDS AREA

2. value - multiplicative scaling

3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

6.2. METHOD

6.2.8

243

surrogate based local

Keywords Area
method
surrogate based local
Local Surrogate Based Optimization

Topics
This keyword is related to the topics:
surrogate based optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
method pointer

method name

Required

model pointer

Optional

soft convergence limit

Optional

truth surrogate bypass

Dakota Keyword
Description
Pointer to
sub-method to
apply to a
surrogate or
branch-and-bound
sub-problem
Specify
sub-method by
name
Identifier for
model block to be
used by a method
Limit number of
iterations w/ little
improvement
Bypass lower level
surrogates when
performing truth
verifications on a
top level surrogate

244

CHAPTER 6. KEYWORDS AREA

Optional

trust region

Optional

approx subproblem

Optional

merit function

Optional

acceptance logic

Optional

constraint relax

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

The maximum
allowable value of
constraint violation
still considered to
be feasible

Use trust region

search method
Identify functions
to be included in
surrogate merit
function
Select type of
penalty or merit
function
Set criteria for
trusted surrogate
Enable constraint
relaxation
Stopping criterion
based on number
of iterations

Description
In surrogate-based optimization (SBO) and surrogate-based nonlinear least squares (SBNLS), minimization occurs using a set of one or more approximations, defined from a surrogate model, that are built and periodically
updated using data from a truth model. The surrogate model can be a global data fit (e.g., regression or interpolation of data generated from a design of computer experiments), a multipoint approximation, a local Taylor
Series expansion, or a model hierarchy approximation (e.g., a low-fidelity simulation model), whereas the truth
model involves a high-fidelity simulation model. The goals of surrogate-based methods are to reduce the total
number of truth model simulations and, in the case of global data fit surrogates, to smooth noisy data with an
easily navigated analytic function.
In the surrogate-based local method, a trust region approach is used to manage the minimization process to
maintain acceptable accuracy between the surrogate model and the truth model (by limiting the range over which
the surrogate model is trusted). The process involves a sequence of minimizations performed on the surrogate
model and bounded by the trust region. At the end of each approximate minimization, the candidate optimum
point is validated using the truth model. If sufficient decrease has been obtained in the truth model, the trust region
is re-centered around the candidate optimum point and the trust region will either shrink, expand, or remain the
same size depending on the accuracy with which the surrogate model predicted the truth model decrease. If
sufficient decrease has not been attained, the trust region center is not updated and the entire trust region shrinks
by a user-specified factor. The cycle then repeats with the construction of a new surrogate model, a minimization,
and another test for sufficient decrease in the truth model. This cycle continues until convergence is attained.

6.2. METHOD

245

Theory
For surrogate based local problems with nonlinear constraints, a number of algorithm formulations exist as
described in[23] and as summarized in the Advanced Examples section of the Models chapter of the Users
Manual[4].

See Also
These keywords may also be of interest:
efficient global
surrogate based global
method pointer
Keywords Area
method
surrogate based local
method pointer
Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: approx method pointer
Argument(s): STRING

Description
The method pointer keyword is used to specify a pointer to an optimization or least-squares sub-method to
apply in the context of what could be described as hierarchical methods. In surrogate-based methods, the submethod is applied to the surrogate model. In the branch-and-bound method, the sub-method is applied to the
relaxed sub-problems.
Any model pointer identified in the sub-method specification is ignored. Instead, the parent method is
responsible for selecting the appropriate model to use as specified by its model pointer. In surrogate-based
methods, it is a surrogate model defined using its model pointer. In branch-and-bound methods, it is the
relaxed model that is constructed internally from the original model.

246

CHAPTER 6. KEYWORDS AREA

method name
Keywords Area
method
surrogate based local
method name
Specify sub-method by name

Specification
Alias: approx method name
Argument(s): STRING

Description
The method name keyword is used to specify a sub-method by Dakota method name (e.g. npsol sqp) rather
than block pointer. The method will be executed using its default settings. The optional model pointer
specification can be used to associate a model block with the method.
model pointer
Keywords Area
method
surrogate based local
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: approx model pointer
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

247

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

248

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

soft convergence limit

Keywords Area
method
surrogate based local
soft convergence limit
Limit number of iterations w/ little improvement

Specification
Alias: none
Argument(s): INTEGER
Default: 5

Description
soft convergence limit (a soft convergence control for the surrogate based local iterations which limits
the number of consecutive iterations with improvement less than the convergence tolerance)
truth surrogate bypass
Keywords Area
method
surrogate based local
truth surrogate bypass
Bypass lower level surrogates when performing truth verifications on a top level surrogate

Specification
Alias: none
Argument(s): none
Default: no bypass

Description
truth surrogate bypass (a flag for bypassing all lower level surrogates when performing truth verifications on a top level surrogate).

6.2. METHOD

249

trust region
Keywords Area
method
surrogate based local
trust region
Use trust region search method

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
initial size

Optional

minimum size

Optional

contract threshold

Optional

expand threshold

Optional

contraction factor

Optional

expansion factor

Dakota Keyword
Description
Trust region initial
size (relative to
bounds)
Trust region
minimum size
Shrink trust region
if trust region ratio
is below this value
Expand trust
region if trust
region ratio is
above this value
Amount by which
step length is
rescaled
Trust region
expansion factor

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual
decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The
command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values
below this threshold cause the trust region to shrink for the next surrogate based local iteration. The command
expand threshold determines the trust region value above which the trust region will expand for the next
surrogate based local iteration.

250

CHAPTER 6. KEYWORDS AREA

initial size
Keywords Area
method
surrogate based local
trust region
initial size
Trust region initial size (relative to bounds)

Specification
Alias: none
Argument(s): REAL
Default: 0.4

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
minimum size
Keywords Area
method
surrogate based local
trust region
minimum size
Trust region minimum size

Specification
Alias: none
Argument(s): REAL
Default: 1.e-6

6.2. METHOD

251

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
contract threshold
Keywords Area
method
surrogate based local
trust region
contract threshold
Shrink trust region if trust region ratio is below this value

Specification
Alias: none
Argument(s): REAL
Default: 0.25

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.

252

CHAPTER 6. KEYWORDS AREA

expand threshold
Keywords Area
method
surrogate based local
trust region
expand threshold
Expand trust region if trust region ratio is above this value

Specification
Alias: none
Argument(s): REAL
Default: 0.75

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
contraction factor
Keywords Area
method
surrogate based local
trust region
contraction factor
Amount by which step length is rescaled

Specification
Alias: none
Argument(s): REAL
Default: 0.25

6.2. METHOD

253

Description
For pattern search methods, contraction factor specifies the amount by which step length is rescaled after
unsuccesful iterates, must be strictly between 0 and 1.
For methods that can expand the step length, the expansion is 1/ contraction factor
expansion factor
Keywords Area
method
surrogate based local
trust region
expansion factor
Trust region expansion factor

Specification
Alias: none
Argument(s): REAL
Default: 2.0

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
approx subproblem
Keywords Area
method
surrogate based local
approx subproblem
Identify functions to be included in surrogate merit function

254

Specification
Alias: none
Argument(s): none
Default: original primary original constraints

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

255
Required/Optional

Description of
Group

Required(Choose
One)

objective
formulation
(Group 1)

Dakota Keyword
original primary

single objective

augmented lagrangian objective

lagrangian objective

Required(Choose
One)

constraint
formulation
(Group 2)

original constraints
linearized constraints
no constraints

Dakota Keyword
Description
Construct
approximations of
all primary
functions
Construct
approximation a
single objective
functions only
Augmented
Lagrangian
approximate
subproblem
formulation
Lagrangian
approximate
subproblem
formulation
Use the constraints
directly
Use linearized
approximations to
the constraints
Dont use
constraints

Description
First, the primary functions (that is, the objective functions or calibration terms) in the approximate subproblem
can be selected to be surrogates of the original primary functions (original primary), a single objective function (single objective) formed from the primary function surrogates, or either an augmented Lagrangian
merit function (augmented lagrangian objective) or a Lagrangian merit function (lagrangian objective) formed from the primary and secondary function surrogates. The former option may imply the
use of a nonlinear least squares method, a multiobjective optimization method, or a single objective optimization method to solve the approximate subproblem, depending on the definition of the primary functions. The
latter three options all imply the use of a single objective optimization method regardless of primary function
definition. Second, the surrogate constraints in the approximate subproblem can be selected to be surrogates of
the original constraints (original constraints) or linearized approximations to the surrogate constraints
(linearized constraints), or constraints can be omitted from the subproblem (no constraints).
original primary
Keywords Area
method
surrogate based local
approx subproblem
original primary

256

CHAPTER 6. KEYWORDS AREA

Construct approximations of all primary functions

Specification
Alias: none
Argument(s): none

Description
For SBL problems with nonlinear constraints, a number of algorithm formulations exist as described in[23] and
as summarized in the Advanced Examples section of the Models chapter of the Users Manual[4]. First, the
primary functions (that is, the objective functions or calibration terms) in the approximate subproblem can
be selected to be surrogates of the original primary functions (original primary), a single objective function (single objective) formed from the primary function surrogates, or either an augmented Lagrangian
merit function (augmented lagrangian objective) or a Lagrangian merit function (lagrangian objective) formed from the primary and secondary function surrogates. The former option may imply the
use of a nonlinear least squares method, a multiobjective optimization method, or a single objective optimization
method to solve the approximate subproblem, depending on the definition of the primary functions. The latter
three options all imply the use of a single objective optimization method regardless of primary function definition.
single objective
Keywords Area
method
surrogate based local
approx subproblem
single objective
Construct approximation a single objective functions only

Specification
Alias: none
Argument(s): none

Description
For SBL problems with nonlinear constraints, a number of algorithm formulations exist as described in[23] and
as summarized in the Advanced Examples section of the Models chapter of the Users Manual[4]. First, the
primary functions (that is, the objective functions or calibration terms) in the approximate subproblem can
be selected to be surrogates of the original primary functions (original primary), a single objective function (single objective) formed from the primary function surrogates, or either an augmented Lagrangian
merit function (augmented lagrangian objective) or a Lagrangian merit function (lagrangian objective) formed from the primary and secondary function surrogates. The former option may imply the
use of a nonlinear least squares method, a multiobjective optimization method, or a single objective optimization
method to solve the approximate subproblem, depending on the definition of the primary functions. The latter
three options all imply the use of a single objective optimization method regardless of primary function definition.

6.2. METHOD

257

augmented lagrangian objective

Keywords Area
method
surrogate based local
approx subproblem
augmented lagrangian objective
Augmented Lagrangian approximate subproblem formulation

Specification
Alias: none
Argument(s): none

Description
For SBL problems with nonlinear constraints, a number of algorithm formulations exist as described in[23] and
as summarized in the Advanced Examples section of the Models chapter of the Users Manual[4]. First, the
primary functions (that is, the objective functions or calibration terms) in the approximate subproblem can
be selected to be surrogates of the original primary functions (original primary), a single objective function (single objective) formed from the primary function surrogates, or either an augmented Lagrangian
merit function (augmented lagrangian objective) or a Lagrangian merit function (lagrangian objective) formed from the primary and secondary function surrogates. The former option may imply the
use of a nonlinear least squares method, a multiobjective optimization method, or a single objective optimization
method to solve the approximate subproblem, depending on the definition of the primary functions. The latter
three options all imply the use of a single objective optimization method regardless of primary function definition.
lagrangian objective
Keywords Area
method
surrogate based local
approx subproblem
lagrangian objective
Lagrangian approximate subproblem formulation

Specification
Alias: none
Argument(s): none

258

CHAPTER 6. KEYWORDS AREA

Description
For SBL problems with nonlinear constraints, a number of algorithm formulations exist as described in[23] and
as summarized in the Advanced Examples section of the Models chapter of the Users Manual[4]. First, the
primary functions (that is, the objective functions or calibration terms) in the approximate subproblem can
be selected to be surrogates of the original primary functions (original primary), a single objective function (single objective) formed from the primary function surrogates, or either an augmented Lagrangian
merit function (augmented lagrangian objective) or a Lagrangian merit function (lagrangian objective) formed from the primary and secondary function surrogates. The former option may imply the
use of a nonlinear least squares method, a multiobjective optimization method, or a single objective optimization
method to solve the approximate subproblem, depending on the definition of the primary functions. The latter
three options all imply the use of a single objective optimization method regardless of primary function definition.
original constraints
Keywords Area
method
surrogate based local
approx subproblem
original constraints
Use the constraints directly

Specification
Alias: none
Argument(s): none

Description
The surrogate constraints in the approximate subproblem can be selected to be surrogates of the original constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints).
linearized constraints
Keywords Area
method
surrogate based local
approx subproblem
linearized constraints
Use linearized approximations to the constraints

6.2. METHOD

259

Specification
Alias: none
Argument(s): none

Description
The surrogate constraints in the approximate subproblem can be selected to be surrogates of the original constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints).
no constraints
Keywords Area
method
surrogate based local
approx subproblem
no constraints
Dont use constraints

Specification
Alias: none
Argument(s): none

Description
The surrogate constraints in the approximate subproblem can be selected to be surrogates of the original constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints).
merit function
Keywords Area
method
surrogate based local
merit function
Select type of penalty or merit function

Specification
Alias: none
Argument(s): none
Default: augmented lagrangian merit

260

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Required(Choose
One)

merit function
(Group 1)

Dakota Keyword
penalty merit
adaptive penalty merit
lagrangian merit

augmented lagrangian merit

Dakota Keyword
Description
Use penalty merit
function
Use adaptive
penalty merit
function
Use first-order
Lagrangian merit
function
Use combined
penalty and
zeroth-order
Lagrangian merit
function

Description
Following optimization of the approximate subproblem, the candidate iterate is evaluated using a merit function,
which can be selected to be a simple penalty function with penalty ramped by surrogate based local iteration
number (penalty merit), an adaptive penalty function where the penalty ramping may be accelerated in order to avoid rejecting good iterates which decrease the constraint violation (adaptive penalty merit), a
Lagrangian merit function which employs first-order Lagrange multiplier updates (lagrangian merit), or an
augmented Lagrangian merit function which employs both a penalty parameter and zeroth-order Lagrange multiplier updates (augmented lagrangian merit). When an augmented Lagrangian is selected for either the
subproblem objective or the merit function (or both), updating of penalties and multipliers follows the approach
described in[16].
penalty merit
Keywords Area
method
surrogate based local
merit function
penalty merit
Use penalty merit function

Specification
Alias: none
Argument(s): none

Description
Second, the surrogate constraints in the approximate subproblem can be selected to be surrogates of the original
constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints). Following optimization of the approximate subproblem, the candidate iterate is evaluated using a merit function, which can be

6.2. METHOD

261

selected to be a simple penalty function with penalty ramped by SBL iteration number (penalty merit), an
adaptive penalty function where the penalty ramping may be accelerated in order to avoid rejecting good iterates which decrease the constraint violation (adaptive penalty merit), a Lagrangian merit function which
employs first-order Lagrange multiplier updates (lagrangian merit), or an augmented Lagrangian merit
function which employs both a penalty parameter and zeroth-order Lagrange multiplier updates (augmentedlagrangian merit). When an augmented Lagrangian is selected for either the subproblem objective or the
merit function (or both), updating of penalties and multipliers follows the approach described in[16].
adaptive penalty merit
Keywords Area
method
surrogate based local
merit function
adaptive penalty merit
Use adaptive penalty merit function

Specification
Alias: none
Argument(s): none

Description
Second, the surrogate constraints in the approximate subproblem can be selected to be surrogates of the original
constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints). Following optimization of the approximate subproblem, the candidate iterate is evaluated using a merit function, which can be
selected to be a simple penalty function with penalty ramped by SBL iteration number (penalty merit), an
adaptive penalty function where the penalty ramping may be accelerated in order to avoid rejecting good iterates which decrease the constraint violation (adaptive penalty merit), a Lagrangian merit function which
employs first-order Lagrange multiplier updates (lagrangian merit), or an augmented Lagrangian merit
function which employs both a penalty parameter and zeroth-order Lagrange multiplier updates (augmentedlagrangian merit). When an augmented Lagrangian is selected for either the subproblem objective or the
merit function (or both), updating of penalties and multipliers follows the approach described in[16].
lagrangian merit
Keywords Area
method
surrogate based local
merit function
lagrangian merit
Use first-order Lagrangian merit function

262

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
Second, the surrogate constraints in the approximate subproblem can be selected to be surrogates of the original
constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints). Following optimization of the approximate subproblem, the candidate iterate is evaluated using a merit function, which can be
selected to be a simple penalty function with penalty ramped by SBL iteration number (penalty merit), an
adaptive penalty function where the penalty ramping may be accelerated in order to avoid rejecting good iterates which decrease the constraint violation (adaptive penalty merit), a Lagrangian merit function which
employs first-order Lagrange multiplier updates (lagrangian merit), or an augmented Lagrangian merit
function which employs both a penalty parameter and zeroth-order Lagrange multiplier updates (augmentedlagrangian merit). When an augmented Lagrangian is selected for either the subproblem objective or the
merit function (or both), updating of penalties and multipliers follows the approach described in[16].
augmented lagrangian merit
Keywords Area
method
surrogate based local
merit function
augmented lagrangian merit
Use combined penalty and zeroth-order Lagrangian merit function

Specification
Alias: none
Argument(s): none

Description
Second, the surrogate constraints in the approximate subproblem can be selected to be surrogates of the original
constraints (original constraints) or linearized approximations to the surrogate constraints (linearizedconstraints), or constraints can be omitted from the subproblem (no constraints). Following optimization of the approximate subproblem, the candidate iterate is evaluated using a merit function, which can be
selected to be a simple penalty function with penalty ramped by SBL iteration number (penalty merit), an
adaptive penalty function where the penalty ramping may be accelerated in order to avoid rejecting good iterates which decrease the constraint violation (adaptive penalty merit), a Lagrangian merit function which
employs first-order Lagrange multiplier updates (lagrangian merit), or an augmented Lagrangian merit
function which employs both a penalty parameter and zeroth-order Lagrange multiplier updates (augmentedlagrangian merit). When an augmented Lagrangian is selected for either the subproblem objective or the
merit function (or both), updating of penalties and multipliers follows the approach described in[16].

6.2. METHOD

263

acceptance logic
Keywords Area
method
surrogate based local
acceptance logic
Set criteria for trusted surrogate

Specification
Alias: none
Argument(s): none
Default: filter
Required/Optional
Required(Choose
One)

Description of
Group
acceptance logic
(Group 1)

Dakota Keyword
tr ratio

filter

Dakota Keyword
Description
Surrogate-Based
Local iterate
acceptance logic
Surrogate-Based
Local iterate
acceptance logic

Description
Following calculation of the merit function for the new iterate, the iterate is accepted or rejected and the trust
region size is adjusted for the next surrogate based local iteration. Iterate acceptance is governed either by a trust
region ratio (tr ratio) formed from the merit function values or by a filter method (filter); however, trust
region resizing logic is currently based only on the trust region ratio. For infeasible iterates, constraint relaxation
can be used for balancing constraint satisfaction and progress made toward an optimum.
tr ratio
Keywords Area
method
surrogate based local
acceptance logic
tr ratio
Surrogate-Based Local iterate acceptance logic

Specification
Alias: none
Argument(s): none

264

CHAPTER 6. KEYWORDS AREA

Description
Following calculation of the merit function for the new iterate, the iterate is accepted or rejected and the trust
region size is adjusted for the next SBL iteration. Iterate acceptance is governed either by a trust region ratio (trratio) formed from the merit function values or by a filter method (filter); however, trust region resizing
logic is currently based only on the trust region ratio. For infeasible iterates, constraint relaxation can be used for
balancing constraint satisfaction and progress made toward an optimum. The command constraint relax
followed by a method name specifies the type of relaxation to be used. Currently, homotopy[68] is the only
available method for constraint relaxation, and this method is dependent on the presence of the NPSOL library
within the Dakota executable.
filter
Keywords Area
method
surrogate based local
acceptance logic
filter
Surrogate-Based Local iterate acceptance logic

Specification
Alias: none
Argument(s): none

Description
Following calculation of the merit function for the new iterate, the iterate is accepted or rejected and the trust
region size is adjusted for the next SBL iteration. Iterate acceptance is governed either by a trust region ratio (trratio) formed from the merit function values or by a filter method (filter); however, trust region resizing
logic is currently based only on the trust region ratio. For infeasible iterates, constraint relaxation can be used for
balancing constraint satisfaction and progress made toward an optimum. The command constraint relax
followed by a method name specifies the type of relaxation to be used. Currently, homotopy[68] is the only
available method for constraint relaxation, and this method is dependent on the presence of the NPSOL library
within the Dakota executable.
constraint relax
Keywords Area
method
surrogate based local
constraint relax
Enable constraint relaxation

6.2. METHOD

265

Specification
Alias: none
Argument(s): none
Default: no relaxation
Required/Optional
Required

Description of
Group

Dakota Keyword
homotopy

Dakota Keyword
Description
Surrogate-Based
local constraint
relaxation method
for infeasible
iterates

Description
The command constraint relax followed by a method name specifies the type of relaxation to be used.
Currently, homotopy [68] is the only available method for constraint relaxation, and this method is dependent
on the presence of the NPSOL library within the Dakota executable.
homotopy
Keywords Area
method
surrogate based local
constraint relax
homotopy
Surrogate-Based local constraint relaxation method for infeasible iterates

Specification
Alias: none
Argument(s): none

Description
Currently, homotopy[68] is the only available method for constraint relaxation, and this method is dependent on
the presence of the NPSOL library within the Dakota executable.
max iterations
Keywords Area
method
surrogate based local
max iterations
Stopping criterion based on number of iterations

266

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
surrogate based local
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.

6.2. METHOD

267

Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
surrogate based local
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003

268

CHAPTER 6. KEYWORDS AREA

NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations

6.2.9

surrogate based global

Keywords Area
method
surrogate based global
Global Surrogate Based Optimization

Topics
This keyword is related to the topics:
surrogate based optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
method pointer

method name

Required

model pointer

Optional

replace points

Dakota Keyword
Description
Pointer to
sub-method to
apply to a
surrogate or
branch-and-bound
sub-problem
Specify
sub-method by
name
Identifier for
model block to be
used by a method
(Recommended)
Replace points in
the surrogate
training set, instead
of appending

6.2. METHOD

269
Optional

max iterations

Stopping criterion
based on number
of iterations

Description
The surrogate based global specification must identify:
a sub-method, using either method pointer or method name
model pointer must be used to identify a surrogate model
surrogate based global works in an iterative scheme where optimization is performed on a global surrogate using the same bounds during each iteration.
In one iteration, the optimal solutions of the surrogate model are found, and then a selected set of these
optimal surrogate solutions are passed to the next iteration.
At the next iteration, these surrogate points are evaluated with the truth model, and then these points are
added back to the set of points upon which the next surrogate is constructed.
In this way, the optimization acts on a more accurate surrogate during each iteration, presumably driving to
optimality quickly.
Method Independent Controls
max iterations is used as a stopping critierion (see note below)
Notes
We have some cautionary notes before using the surrogate-based global method:
This approach has no guarantee of convergence.
One might first try a single minimization method coupled with a surrogate model prior to using the surrogatebased global method. This is essentially equivalent to setting max iterations to 1 and will allow one
to get a sense of what surrogate types are the most accurate to use for the problem.
Also note that one can specify that surrogates be built for all primary functions and constraints or for only
a subset of these functions and constraints. This allows one to use a truth model directly for some of the
response functions, perhaps due to them being much less expensive than other functions.
We initially recommend a small number of maximum iterations, such as 3-5, to get a sense of how the
optimization is evolving as the surrogate gets updated. If it appears to be changing significantly, then a
larger number (used in combination with restart) may be needed.

Theory
In surrogate-based optimization (SBO) and surrogate-based nonlinear least squares (SBNLS), minimization occurs using a set of one or more approximations, defined from a surrogate model, that are built and periodically
updated using data from a truth model. The surrogate model can be a global data fit (e.g., regression or interpolation of data generated from a design of computer experiments), a multipoint approximation, a local Taylor
Series expansion, or a model hierarchy approximation (e.g., a low-fidelity simulation model), whereas the truth
model involves a high-fidelity simulation model. The goals of surrogate-based methods are to reduce the total

270

CHAPTER 6. KEYWORDS AREA

number of truth model simulations and, in the case of global data fit surrogates, to smooth noisy data with an
easily navigated analytic function.
It was originally designed for MOGA (a multi-objective genetic algorithm). Since genetic algorithms often
need thousands or tens of thousands of points to produce optimal or near-optimal solutions, the use of surrogates
can be helpful for reducing the truth model evaluations. Instead of creating one set of surrogates for the individual
objectives and running the optimization algorithm on the surrogate once, the idea is to select points along the
(surrogate) Pareto frontier, which can be used to supplement the existing points.
In this way, one does not need to use many points initially to get a very accurate surrogate. The surrogate
becomes more accurate as the iterations progress.

See Also
These keywords may also be of interest:
efficient global
surrogate based local
method pointer
Keywords Area
method
surrogate based global
method pointer
Pointer to sub-method to apply to a surrogate or branch-and-bound sub-problem

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: approx method pointer
Argument(s): STRING

Description
The method pointer keyword is used to specify a pointer to an optimization or least-squares sub-method to
apply in the context of what could be described as hierarchical methods. In surrogate-based methods, the submethod is applied to the surrogate model. In the branch-and-bound method, the sub-method is applied to the
relaxed sub-problems.
Any model pointer identified in the sub-method specification is ignored. Instead, the parent method is
responsible for selecting the appropriate model to use as specified by its model pointer. In surrogate-based
methods, it is a surrogate model defined using its model pointer. In branch-and-bound methods, it is the
relaxed model that is constructed internally from the original model.

6.2. METHOD

271

method name
Keywords Area
method
surrogate based global
method name
Specify sub-method by name

Specification
Alias: approx method name
Argument(s): STRING

Description
The method name keyword is used to specify a sub-method by Dakota method name (e.g. npsol sqp) rather
than block pointer. The method will be executed using its default settings. The optional model pointer
specification can be used to associate a model block with the method.
model pointer
Keywords Area
method
surrogate based global
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: approx model pointer
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

272

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

273

response_functions = 3
no_gradients
no_hessians

replace points
Keywords Area
method
surrogate based global
replace points
(Recommended) Replace points in the surrogate training set, instead of appending

Specification
Alias: none
Argument(s): none
Default: Points appended, not replaced

Description
The user has the option of appending the optimal points from the surrogate model to the current set of truth
points or using the optimal points from the surrogate model to replace the optimal set of points from the previous
iteration. Although appending to the set is the default behavior, at this time we strongly recommend using the
option replace points because it appears to be more accurate and robust.
max iterations
Keywords Area
method
surrogate based global
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

274

CHAPTER 6. KEYWORDS AREA

Description
The maximum number of iterations (default: 100). See also max function evaluations.

6.2.10

dot frcg

Keywords Area
method
dot frcg
A conjugate gradient optimization method

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

275
Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
This is a duplicated keyword. Please use dot instead.
We here provide a caution regarding dot frcg. In DOT Version 4.20, we have noticed inconsistent behavior
of this algorithm across different versions of Linux. Our best assessment is that it is due to different treatments of
uninitialized variables. As we do not know the intention of the code authors and maintaining DOT source code
is outside of the Dakota project scope, we have not made nor are we recommending any code changes to address
this. However, all users who use dot frcg in DOT Version 4.20 should be aware that results may not be reliable.

276

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
frcg
max iterations
Keywords Area
method
dot frcg
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
dot frcg
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

277

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
dot frcg
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

278

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: Library default

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
dot frcg
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

6.2. METHOD

279

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
dot frcg
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

280

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
dot frcg
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values

6.2. METHOD

281

The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

282

CHAPTER 6. KEYWORDS AREA

linear inequality constraint matrix

Keywords Area
method
dot frcg
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dot frcg
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

283

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dot frcg
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

284

CHAPTER 6. KEYWORDS AREA

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
dot frcg
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

6.2. METHOD

285

auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
dot frcg
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

286

CHAPTER 6. KEYWORDS AREA

value - required
auto - optional

If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
dot frcg
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

6.2. METHOD

287

linear equality targets

Keywords Area
method
dot frcg
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dot frcg
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

288

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dot frcg
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

289

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
dot frcg
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

290

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

291

response_functions = 3
no_gradients
no_hessians

6.2.11

dot mmfd

Keywords Area
method
dot mmfd
Method of feasible directions

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

292

CHAPTER 6. KEYWORDS AREA

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicated keyword. Please use dot instead.

See Also
These keywords may also be of interest:

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

6.2. METHOD

293

mmfd
max iterations
Keywords Area
method
dot mmfd
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
dot mmfd
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

294

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
dot mmfd
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

6.2. METHOD

295

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
dot mmfd
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

296

CHAPTER 6. KEYWORDS AREA

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
dot mmfd
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

6.2. METHOD

297

scaling
Keywords Area
method
dot mmfd
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

298

CHAPTER 6. KEYWORDS AREA

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

6.2. METHOD

299

linear inequality constraint matrix

Keywords Area
method
dot mmfd
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dot mmfd
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

300

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dot mmfd
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

6.2. METHOD

301

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
dot mmfd
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

302

CHAPTER 6. KEYWORDS AREA

auto - automatic scaling If a single string is specified it will apply to all constraints.

Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
dot mmfd
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

6.2. METHOD

303

value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
dot mmfd
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

304

CHAPTER 6. KEYWORDS AREA

linear equality targets

Keywords Area
method
dot mmfd
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dot mmfd
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

305

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dot mmfd
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

306

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
dot mmfd
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

307

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

308

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.12

dot bfgs

Keywords Area
method
dot bfgs
A conjugate gradient optimization method

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

309
Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicated keyword. Please use dot instead.

See Also
These keywords may also be of interest:

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

310

CHAPTER 6. KEYWORDS AREA

bfgs

max iterations
Keywords Area
method
dot bfgs
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
dot bfgs
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

311

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
dot bfgs
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

312

CHAPTER 6. KEYWORDS AREA

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
dot bfgs
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

6.2. METHOD

313

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
dot bfgs
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

314

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
dot bfgs
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

315

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

316

CHAPTER 6. KEYWORDS AREA

linear inequality constraint matrix

Keywords Area
method
dot bfgs
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dot bfgs
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

317

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dot bfgs
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

318

CHAPTER 6. KEYWORDS AREA

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
dot bfgs
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

6.2. METHOD

319

auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
dot bfgs
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

320

CHAPTER 6. KEYWORDS AREA

value - required
auto - optional

If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
dot bfgs
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

6.2. METHOD

321

linear equality targets

Keywords Area
method
dot bfgs
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dot bfgs
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

322

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dot bfgs
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

323

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
dot bfgs
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

324

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

325

response_functions = 3
no_gradients
no_hessians

6.2.13

dot slp

Keywords Area
method
dot slp
Sequential Linear Programming

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

326

CHAPTER 6. KEYWORDS AREA

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicated keyword. Please use dot instead.

See Also
These keywords may also be of interest:

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

6.2. METHOD

327

slp
max iterations
Keywords Area
method
dot slp
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
dot slp
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

328

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
dot slp
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

6.2. METHOD

329

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
dot slp
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

330

CHAPTER 6. KEYWORDS AREA

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
dot slp
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

6.2. METHOD

331

scaling
Keywords Area
method
dot slp
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

332

CHAPTER 6. KEYWORDS AREA

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

6.2. METHOD

333

linear inequality constraint matrix

Keywords Area
method
dot slp
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dot slp
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

334

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dot slp
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

6.2. METHOD

335

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
dot slp
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

336

CHAPTER 6. KEYWORDS AREA

auto - automatic scaling If a single string is specified it will apply to all constraints.

Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
dot slp
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

6.2. METHOD

337

value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
dot slp
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

338

CHAPTER 6. KEYWORDS AREA

linear equality targets

Keywords Area
method
dot slp
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dot slp
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

339

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dot slp
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

340

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
dot slp
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

341

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

342

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.14

dot sqp

Keywords Area
method
dot sqp
Sequential Quadratic Program

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

343
Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicated keyword. Please use dot instead.

See Also
These keywords may also be of interest:

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

344

CHAPTER 6. KEYWORDS AREA

sqp

max iterations
Keywords Area
method
dot sqp
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
dot sqp
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

345

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
dot sqp
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

346

CHAPTER 6. KEYWORDS AREA

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
dot sqp
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

6.2. METHOD

347

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
dot sqp
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

348

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
dot sqp
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

349

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

350

CHAPTER 6. KEYWORDS AREA

linear inequality constraint matrix

Keywords Area
method
dot sqp
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dot sqp
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

351

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dot sqp
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

352

CHAPTER 6. KEYWORDS AREA

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
dot sqp
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

6.2. METHOD

353

auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
dot sqp
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

354

CHAPTER 6. KEYWORDS AREA

value - required
auto - optional

If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
dot sqp
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

6.2. METHOD

355

linear equality targets

Keywords Area
method
dot sqp
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dot sqp
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

356

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dot sqp
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

357

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
dot sqp
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

358

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

359

response_functions = 3
no_gradients
no_hessians

6.2.15

dot

Keywords Area
method
dot
Access to methods in the DOT package

Topics
This keyword is related to the topics:
package dot

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
frcg

Required(Choose
One)

Group 1
mmfd
bfgs

slp
sqp
Optional

max iterations

Dakota Keyword
Description
A conjugate
gradient
optimization
method
Method of feasible
directions
A conjugate
gradient
optimization
method
Sequential Linear
Programming
Sequential
Quadratic Program
Stopping criterion
based on number
of iterations

360

CHAPTER 6. KEYWORDS AREA

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities

6.2. METHOD

361
Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
The DOT library [85] contains nonlinear programming optimizers, specifically the Broyden-Fletcher-Goldfarb-Shanno (Dakotas dot bfgs method) and Fletcher-Reeves conjugate gradient (Dakotas dot frcg method)
methods for unconstrained optimization, and the modified method of feasible directions (Dakotas dot mmfd
method), sequential linear programming (Dakotas dot slp method), and sequential quadratic programming
(Dakotas dot sqp method) methods for constrained optimization.
Specialized handling of linear constraints is supported with DOT; linear constraint coefficients, bounds, and
targets can be provided to DOT at start-up and tracked internally.
One of the five available methods in Group 1 must be specified.
All these methods take the same Optional Keywords , dealing with linear equality and inequality constraints.
Method Independent Controls - Stopping Critiera
Stopping critiera are set by:
max iterations
max function evaluations
convergence tolerance
constraint tolerance
Note: The convergence tolerance criterion must be satisfied for two consecutive iterations before DOT
will terminate.
Method Independent Controls - Output
The output verbosity specification controls the amount of information generated by DOT: the silent and
quiet settings result in header information, final results, and objective function, constraint, and parameter information on each iteration; whereas the verbose and debug settings add additional information on gradients,
search direction, one-dimensional search results, and parameter scaling factors.
Concurrency
DOT contains no parallel algorithms which can directly take advantage of concurrent evaluations. However,
if numerical gradients with method source dakota is specified, then the finite difference function
evaluations can be performed concurrently (using any of the parallel modes described in the Users Manual[4]).

362

CHAPTER 6. KEYWORDS AREA

In addition, if speculative is specified, then gradients (dakota numerical or analytic gradients) will
be computed on each line search evaluation in order to balance the load and lower the total run time in parallel
optimization studies.
frcg
Keywords Area
method
dot
frcg
A conjugate gradient optimization method

Topics
This keyword is related to the topics:
package dot

Specification
Alias: none
Argument(s): none

Description
We here provide a caution regarding dot frcg. In DOT Version 4.20, we have noticed inconsistent behavior of
this algorithm across different versions of Linux. Our best assessment is that it is due to different treatments of
uninitialized variables. As we do not know the intention of the code authors and maintaining DOT source code
is outside of the Dakota project scope, we have not made nor are we recommending any code changes to address
this. However, all users who use dot frcg in DOT Version 4.20 should be aware that results may not be reliable.
See package dot for information related to all DOT methods.

See Also
These keywords may also be of interest:
bfgs
mmfd
slp
sqp

6.2. METHOD
mmfd
Keywords Area
method
dot
mmfd
Method of feasible directions

Topics
This keyword is related to the topics:
package dot

Specification
Alias: none
Argument(s): none

Description
See package dot for information related to all DOT methods.

See Also
These keywords may also be of interest:
bfgs
frcg
slp
sqp
bfgs
Keywords Area
method
dot
bfgs
A conjugate gradient optimization method

Topics
This keyword is related to the topics:
package dot

363

364

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
See package dot for information related to all DOT methods.

See Also
These keywords may also be of interest:
frcg
mmfd
slp
sqp
slp
Keywords Area
method
dot
slp
Sequential Linear Programming

Topics
This keyword is related to the topics:
package dot

Specification
Alias: none
Argument(s): none

Description
See package dot for information related to all DOT methods.

6.2. METHOD

See Also
These keywords may also be of interest:
bfgs
frcg
mmfd
sqp
sqp
Keywords Area
method
dot
sqp
Sequential Quadratic Program

Topics
This keyword is related to the topics:
package dot

Specification
Alias: none
Argument(s): none

Description
See package dot for information related to all DOT methods.

See Also
These keywords may also be of interest:
bfgs
frcg
mmfd
slp

365

366

CHAPTER 6. KEYWORDS AREA

max iterations
Keywords Area
method
dot
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
dot
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

367

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
dot
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

368

CHAPTER 6. KEYWORDS AREA

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
dot
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

6.2. METHOD

369

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
dot
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

370

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
dot
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

371

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

372

CHAPTER 6. KEYWORDS AREA

linear inequality constraint matrix

Keywords Area
method
dot
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dot
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

373

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dot
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

374

CHAPTER 6. KEYWORDS AREA

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
dot
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

6.2. METHOD

375

auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
dot
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

376

CHAPTER 6. KEYWORDS AREA

value - required
auto - optional

If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
dot
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

6.2. METHOD

377

linear equality targets

Keywords Area
method
dot
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dot
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

378

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dot
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

379

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
dot
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

380

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

381

response_functions = 3
no_gradients
no_hessians

6.2.16

conmin frcg

Keywords Area
method
conmin frcg
A conjugate gradient optimization method

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

382

CHAPTER 6. KEYWORDS AREA

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicated keyword. Please use conmin instead.

See Also
These keywords may also be of interest:

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

6.2. METHOD

383

frcg
max iterations
Keywords Area
method
conmin frcg
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
conmin frcg
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

384

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
conmin frcg
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

6.2. METHOD

385

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
conmin frcg
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

386

CHAPTER 6. KEYWORDS AREA

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
conmin frcg
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

6.2. METHOD

387

scaling
Keywords Area
method
conmin frcg
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

388

CHAPTER 6. KEYWORDS AREA

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

6.2. METHOD

389

linear inequality constraint matrix

Keywords Area
method
conmin frcg
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
conmin frcg
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

390

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
conmin frcg
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

6.2. METHOD

391

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
conmin frcg
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

392

CHAPTER 6. KEYWORDS AREA

auto - automatic scaling If a single string is specified it will apply to all constraints.

Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
conmin frcg
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

6.2. METHOD

393

value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
conmin frcg
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

394

CHAPTER 6. KEYWORDS AREA

linear equality targets

Keywords Area
method
conmin frcg
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
conmin frcg
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

395

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
conmin frcg
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

396

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
conmin frcg
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

397

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

398

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.17

conmin mfd

Keywords Area
method
conmin mfd
Method of feasible directions

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

399
Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicated keyword. Please use conmin instead.

See Also
These keywords may also be of interest:

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

400

CHAPTER 6. KEYWORDS AREA

mfd

max iterations
Keywords Area
method
conmin mfd
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
conmin mfd
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

401

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
conmin mfd
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

402

CHAPTER 6. KEYWORDS AREA

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
conmin mfd
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

6.2. METHOD

403

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
conmin mfd
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

404

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
conmin mfd
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

405

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

406

CHAPTER 6. KEYWORDS AREA

linear inequality constraint matrix

Keywords Area
method
conmin mfd
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
conmin mfd
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

407

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
conmin mfd
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

408

CHAPTER 6. KEYWORDS AREA

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
conmin mfd
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

6.2. METHOD

409

auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
conmin mfd
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

410

CHAPTER 6. KEYWORDS AREA

value - required
auto - optional

If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
conmin mfd
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

6.2. METHOD

411

linear equality targets

Keywords Area
method
conmin mfd
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
conmin mfd
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

412

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
conmin mfd
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

413

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
conmin mfd
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

414

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

415

response_functions = 3
no_gradients
no_hessians

6.2.18

conmin

Keywords Area
method
conmin
Access to methods in the CONMIN library

Topics
This keyword is related to the topics:
package conmin

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
frcg

mfd
Optional

max iterations

Optional

convergence tolerance

Dakota Keyword
Description
A conjugate
gradient
optimization
method
Method of feasible
directions
Stopping criterion
based on number
of iterations
Stopping criterion
based on
convergence of the
objective function
or statistics

416

CHAPTER 6. KEYWORDS AREA

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints

6.2. METHOD

417
Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Specify how each

linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
The CONMIN library[83] is a public domain library of nonlinear programming optimizers, specifically the
Fletcher-Reeves conjugate gradient (Dakotas conmin frcg method) method for unconstrained optimization,
and the method of feasible directions (Dakotas conmin mfd method) for constrained optimization. As CONMIN was a predecessor to the DOT commercial library, the algorithm controls are very similar.
One of the two available methods in Group 1 must be specified.
All these methods take the same Optional Keywords , dealing with linear equality and inequality constraints.

See Also
These keywords may also be of interest:
dot
frcg
Keywords Area
method
conmin
frcg
A conjugate gradient optimization method

Topics
This keyword is related to the topics:
package conmin

Specification
Alias: none
Argument(s): none

418

CHAPTER 6. KEYWORDS AREA

Description
The interpretations of the method independent controls for CONMIN are essentially identical to those for DOT.
See package dot for information related to CONMIN methods.

See Also
These keywords may also be of interest:
mfd
frcg
mfd
Keywords Area
method
conmin
mfd
Method of feasible directions

Topics
This keyword is related to the topics:
package conmin

Specification
Alias: none
Argument(s): none

Description
The interpretations of the method independent controls for CONMIN are essentially identical to those for DOT.
See package dot for information related to CONMIN methods.

See Also
These keywords may also be of interest:
frcg
mmfd

6.2. METHOD

419

max iterations
Keywords Area
method
conmin
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
conmin
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

420

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
constraint tolerance
Keywords Area
method
conmin
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

6.2. METHOD

421

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
conmin
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

422

CHAPTER 6. KEYWORDS AREA

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
conmin
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

6.2. METHOD

423

scaling
Keywords Area
method
conmin
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

424

CHAPTER 6. KEYWORDS AREA

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

6.2. METHOD

425

linear inequality constraint matrix

Keywords Area
method
conmin
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
conmin
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

426

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
conmin
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

6.2. METHOD

427

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
conmin
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

428

CHAPTER 6. KEYWORDS AREA

auto - automatic scaling If a single string is specified it will apply to all constraints.

Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
conmin
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

6.2. METHOD

429

value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
conmin
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

430

CHAPTER 6. KEYWORDS AREA

linear equality targets

Keywords Area
method
conmin
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
conmin
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

431

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
conmin
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

432

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
conmin
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

433

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

434

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.19

dl solver

Keywords Area
method
dl solver
(Experimental) Dynamically-loaded solver

Topics
This keyword is related to the topics:
optimization and calibration

Specification
Alias: none
Argument(s): STRING
Required/Optional
Optional

Description of
Group

Dakota Keyword
linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Dakota Keyword
Description
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities

6.2. METHOD

435
Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
This keyword specifies a dynamically-loaded optimization solver library, an experimental Dakota feature that is
not enabled by default.
linear inequality constraint matrix
Keywords Area
method
dl solver
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

436

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
dl solver
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0

6.2. METHOD

437

result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
dl solver
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).

438

CHAPTER 6. KEYWORDS AREA

linear inequality scale types

Keywords Area
method
dl solver
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

6.2. METHOD

439

linear inequality scales

Keywords Area
method
dl solver
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

440

CHAPTER 6. KEYWORDS AREA

linear equality constraint matrix

Keywords Area
method
dl solver
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
dl solver
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

6.2. METHOD

441

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
dl solver
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU

442

CHAPTER 6. KEYWORDS AREA

aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U

and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
dl solver
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

6.2. METHOD
max function evaluations
Keywords Area
method
dl solver
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
dl solver
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

443

444

CHAPTER 6. KEYWORDS AREA

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.

6.2. METHOD

445

none, auto, log - optional

value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
dl solver
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

446

CHAPTER 6. KEYWORDS AREA

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.20

npsol sqp

Keywords Area

6.2. METHOD

447

method
npsol sqp
Sequential Quadratic Program

Topics
This keyword is related to the topics:
package npsol
sequential quadratic programming
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
verify level

Optional

function precision

Optional

linesearch tolerance

Optional

convergence tolerance

Dakota Keyword
Description
Verify the quality
of analytic
gradients
Specify the
maximum
precision of the
analysis code
responses
Choose how
accurately the
algorithm will
compute the
minimum in a line
search
Stopping criterion
based on
convergence of the
objective function
or statistics

448

CHAPTER 6. KEYWORDS AREA

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities

6.2. METHOD

449
Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
NPSOL provides an implementation of sequential quadratic programming that can be accessed with npsol sqp.
Stopping Criteria
The method independent controls for max iterations and max function evaluations limit the
number of major SQP iterations and the number of function evaluations that can be performed during an NPSOL
optimization. The convergence tolerance control defines NPSOLs internal optimality tolerance which is
used in evaluating if an iterate satisfies the first-order Kuhn-Tucker conditions for a minimum. The magnitude
of convergence tolerance approximately specifies the number of significant digits of accuracy desired in
the final objective function (e.g., convergence tolerance = 1.e-6 will result in approximately six digits
of accuracy in the final objective function). The constraint tolerance control defines how tightly the
constraint functions are satisfied at convergence. The default value is dependent upon the machine precision
of the platform in use, but is typically on the order of 1.e-8 for double precision computations. Extremely
small values for constraint tolerance may not be attainable. The output verbosity setting controls the
amount of information generated at each major SQP iteration: the silent and quiet settings result in only one
line of diagnostic output for each major iteration and print the final optimization solution, whereas the verbose
and debug settings add additional information on the objective function, constraints, and variables at each major
iteration.
Concurrency
NPSOL is not a parallel algorithm and cannot directly take advantage of concurrent evaluations. However,
if numerical gradients with method source dakota is specified, then the finite difference function
evaluations can be performed concurrently (using any of the parallel modes described in the Users Manual [4]).
An important related observation is the fact that NPSOL uses two different line searches depending on how
gradients are computed. For either analytic gradients or numerical gradients with method source dakota, NPSOL is placed in user-supplied gradient mode (NPSOLs Derivative Level is set to 3) and
it uses a gradient-based line search (the assumption is that user-supplied gradients are inexpensive). On the other
hand, if numerical gradients are selected with method source vendor, then NPSOL is computing
finite differences internally and it will use a value-based line search (the assumption is that finite differencing on
each line search evaluation is too expensive). The ramifications of this are: (1) performance will vary between
method source dakota and method source vendor for numerical gradients, and (2) gradient
speculation is unnecessary when performing optimization in parallel since the gradient-based line search in usersupplied gradient mode is already load balanced for parallel execution. Therefore, a speculative specification
will be ignored by NPSOL, and optimization with numerical gradients should select method source dakota
for load balanced parallel operation and method source vendor for efficient serial operation.

450

CHAPTER 6. KEYWORDS AREA

Linear constraints
Lastly, NPSOL supports specialized handling of linear inequality and equality constraints. By specifying the
coefficients and bounds of the linear inequality constraints and the coefficients and targets of the linear equality
constraints, this information can be provided to NPSOL at initialization and tracked internally, removing the need
for the user to provide the values of the linear constraints on every function evaluation.
verify level
Keywords Area
method
npsol sqp
verify level
Verify the quality of analytic gradients

Specification
Alias: none
Argument(s): INTEGER
Default: -1 (no gradient verification)

Description
verify level instructs the NPSOL and NLSSOL algorithms to perform their own finite difference verification
of the gradients provided by Dakota. Typically these are used to verify analytic gradients produced by a
simulation code, though the option can be used with other Dakota-supplied gradient types including numerical or
mixed.
Level 1 will verify the objective gradients, level 2, the nonlinear constraint gradients, and level 3, both. See
the Optional Input Parameters section of the NPSOL manual[33] for additional information, including options to
verify at the user-supplied initial point vs. first feasible point.
function precision
Keywords Area
method
npsol sqp
function precision
Specify the maximum precision of the analysis code responses

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-10

6.2. METHOD

451

Description
The function precision control provides the algorithm with an estimate of the accuracy to which the
problem functions can be computed. This is used to prevent the algorithm from trying to distinguish between
function values that differ by less than the inherent error in the calculation.
linesearch tolerance
Keywords Area
method
npsol sqp
linesearch tolerance
Choose how accurately the algorithm will compute the minimum in a line search

Specification
Alias: none
Argument(s): REAL
Default: 0.9 (inaccurate line search)

Description
The linesearch tolerance setting controls the accuracy of the line search. The smaller the value (between
0 and 1), the more accurately the algorithm will attempt to compute a precise minimum along the search direction.
convergence tolerance
Keywords Area
method
npsol sqp
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

452

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
npsol sqp
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

6.2. METHOD

453

Description
The maximum number of iterations (default: 100). See also max function evaluations.
constraint tolerance
Keywords Area
method
npsol sqp
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
npsol sqp
speculative
Compute speculative gradients

454

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
npsol sqp
max function evaluations

6.2. METHOD

455

Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
npsol sqp
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.

456

CHAPTER 6. KEYWORDS AREA

Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

6.2. METHOD

457

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
npsol sqp
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.

458

CHAPTER 6. KEYWORDS AREA

linear inequality lower bounds

Keywords Area
method
npsol sqp
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
npsol sqp
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

6.2. METHOD

459

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
npsol sqp
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

460

CHAPTER 6. KEYWORDS AREA

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
npsol sqp
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

6.2. METHOD

461

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
npsol sqp
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

462

CHAPTER 6. KEYWORDS AREA

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
npsol sqp
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
npsol sqp
linear equality scale types
Specify how each linear equality constraint is scaled

6.2. METHOD

463

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
npsol sqp
linear equality scales
Define the characteristic values to scale linear equalities

464

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
npsol sqp
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

6.2. METHOD

465

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

466

CHAPTER 6. KEYWORDS AREA

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.21

nlssol sqp

Keywords Area
method
nlssol sqp
Sequential Quadratic Program for nonlinear least squares

Topics
This keyword is related to the topics:
sequential quadratic programming
nonlinear least squares

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
verify level

Optional

function precision

Optional

linesearch tolerance

Dakota Keyword
Description
Verify the quality
of analytic
gradients
Specify the
maximum
precision of the
analysis code
responses
Choose how
accurately the
algorithm will
compute the
minimum in a line
search

6.2. METHOD

467
Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities

468

CHAPTER 6. KEYWORDS AREA

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
NLSSOL is available as nlssol sqp and supports unconstrained, bound-constrained, and generally-constrained
problems. It exploits the structure of a least squares objective function through the periodic use of Gauss-Newton
Hessian approximations to accelerate the SQP algorithm.
Stopping Criteria
The method independent controls for max iterations and max function evaluations limit the
number of major SQP iterations and the number of function evaluations that can be performed during an NPSOL
optimization. The convergence tolerance control defines NPSOLs internal optimality tolerance which is
used in evaluating if an iterate satisfies the first-order Kuhn-Tucker conditions for a minimum. The magnitude
of convergence tolerance approximately specifies the number of significant digits of accuracy desired in
the final objective function (e.g., convergence tolerance = 1.e-6 will result in approximately six digits
of accuracy in the final objective function). The constraint tolerance control defines how tightly the
constraint functions are satisfied at convergence. The default value is dependent upon the machine precision of
the platform in use, but is typically on the order of 1.e-8 for double precision computations. Extremely small
values for constraint tolerance may not be attainable.

See Also
These keywords may also be of interest:
npsol sqp
nl2sol
optpp g newton
field calibration terms
verify level
Keywords Area

6.2. METHOD

469

method
nlssol sqp
verify level
Verify the quality of analytic gradients

Specification
Alias: none
Argument(s): INTEGER
Default: -1 (no gradient verification)

Description
verify level instructs the NPSOL and NLSSOL algorithms to perform their own finite difference verification
of the gradients provided by Dakota. Typically these are used to verify analytic gradients produced by a
simulation code, though the option can be used with other Dakota-supplied gradient types including numerical or
mixed.
Level 1 will verify the objective gradients, level 2, the nonlinear constraint gradients, and level 3, both. See
the Optional Input Parameters section of the NPSOL manual[33] for additional information, including options to
verify at the user-supplied initial point vs. first feasible point.
function precision
Keywords Area
method
nlssol sqp
function precision
Specify the maximum precision of the analysis code responses

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-10

Description
The function precision control provides the algorithm with an estimate of the accuracy to which the
problem functions can be computed. This is used to prevent the algorithm from trying to distinguish between
function values that differ by less than the inherent error in the calculation.

470

CHAPTER 6. KEYWORDS AREA

linesearch tolerance
Keywords Area
method
nlssol sqp
linesearch tolerance
Choose how accurately the algorithm will compute the minimum in a line search

Specification
Alias: none
Argument(s): REAL
Default: 0.9 (inaccurate line search)

Description
The linesearch tolerance setting controls the accuracy of the line search. The smaller the value (between
0 and 1), the more accurately the algorithm will attempt to compute a precise minimum along the search direction.
convergence tolerance
Keywords Area
method
nlssol sqp
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

471

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
nlssol sqp
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

472

CHAPTER 6. KEYWORDS AREA

Description
The maximum number of iterations (default: 100). See also max function evaluations.
constraint tolerance
Keywords Area
method
nlssol sqp
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
nlssol sqp
speculative
Compute speculative gradients

6.2. METHOD

473

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
nlssol sqp
max function evaluations

474

CHAPTER 6. KEYWORDS AREA

Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
nlssol sqp
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.

6.2. METHOD

475

Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

476

CHAPTER 6. KEYWORDS AREA

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
nlssol sqp
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.

6.2. METHOD

477

linear inequality lower bounds

Keywords Area
method
nlssol sqp
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
nlssol sqp
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

478

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
nlssol sqp
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

6.2. METHOD

479

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
nlssol sqp
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

480

CHAPTER 6. KEYWORDS AREA

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
nlssol sqp
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

6.2. METHOD

481

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
nlssol sqp
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
nlssol sqp
linear equality scale types
Specify how each linear equality constraint is scaled

482

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
nlssol sqp
linear equality scales
Define the characteristic values to scale linear equalities

6.2. METHOD

483

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
nlssol sqp
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

484

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

485

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.22

stanford

Keywords Area
method
stanford
Select methods from the Stanford package

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
npsol

nlssol

Optional

verify level

Optional

function precision

Optional

linesearch tolerance

Dakota Keyword
Description
Duplicate of
method-npsolsqp
Duplicate of
method-nlssolsqp
Verify the quality
of analytic
gradients
Specify the
maximum
precision of the
analysis code
responses
Choose how
accurately the
algorithm will
compute the
minimum in a line
search

486

CHAPTER 6. KEYWORDS AREA

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

constraint tolerance

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

The maximum
allowable value of
constraint violation
still considered to
be feasible
Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities

6.2. METHOD

487
Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Description
This is a duplicate. See the method pages here:
nlssol sqp
npsol sqp
npsol
Keywords Area
method
stanford
npsol
Duplicate of method-npsol sqp

Specification
Alias: none
Argument(s): none

Description
See the page for npsol sqp

Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

488

CHAPTER 6. KEYWORDS AREA

nlssol
Keywords Area
method
stanford
nlssol
Duplicate of method-nlssol sqp

Specification
Alias: none
Argument(s): none

Description
See the page for nlssol sqp
verify level
Keywords Area
method
stanford
verify level
Verify the quality of analytic gradients

Specification
Alias: none
Argument(s): INTEGER
Default: -1 (no gradient verification)

Description
verify level instructs the NPSOL and NLSSOL algorithms to perform their own finite difference verification
of the gradients provided by Dakota. Typically these are used to verify analytic gradients produced by a
simulation code, though the option can be used with other Dakota-supplied gradient types including numerical or
mixed.
Level 1 will verify the objective gradients, level 2, the nonlinear constraint gradients, and level 3, both. See
the Optional Input Parameters section of the NPSOL manual[33] for additional information, including options to
verify at the user-supplied initial point vs. first feasible point.

6.2. METHOD

489

function precision
Keywords Area
method
stanford
function precision
Specify the maximum precision of the analysis code responses

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-10

Description
The function precision control provides the algorithm with an estimate of the accuracy to which the
problem functions can be computed. This is used to prevent the algorithm from trying to distinguish between
function values that differ by less than the inherent error in the calculation.
linesearch tolerance
Keywords Area
method
stanford
linesearch tolerance
Choose how accurately the algorithm will compute the minimum in a line search

Specification
Alias: none
Argument(s): REAL
Default: 0.9 (inaccurate line search)

Description
The linesearch tolerance setting controls the accuracy of the line search. The smaller the value (between
0 and 1), the more accurately the algorithm will attempt to compute a precise minimum along the search direction.

490

CHAPTER 6. KEYWORDS AREA

convergence tolerance
Keywords Area
method
stanford
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

6.2. METHOD

491

max iterations
Keywords Area
method
stanford
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
constraint tolerance
Keywords Area
method
stanford
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

492

CHAPTER 6. KEYWORDS AREA

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
speculative
Keywords Area
method
stanford
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function

6.2. METHOD

493

values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
stanford
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

494

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
stanford
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

495

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

496

CHAPTER 6. KEYWORDS AREA

linear inequality constraint matrix

Keywords Area
method
stanford
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
stanford
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

497

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
stanford
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

498

CHAPTER 6. KEYWORDS AREA

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
stanford
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

6.2. METHOD

499

auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
stanford
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

500

CHAPTER 6. KEYWORDS AREA

value - required
auto - optional

If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
stanford
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

6.2. METHOD

501

linear equality targets

Keywords Area
method
stanford
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
stanford
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

502

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
stanford
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

503

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
stanford
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

504

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

505

response_functions = 3
no_gradients
no_hessians

6.2.23

nlpql sqp

Keywords Area
method
nlpql sqp
Sequential Quadratic Program

Topics
This keyword is related to the topics:
package nlpql
sequential quadratic programming
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max iterations

Dakota Keyword
Description
Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

linear inequality constraint matrix

Define coefficients
of the linear
inequality
constraints

506

CHAPTER 6. KEYWORDS AREA

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
NLPQL provides an implementation of sequential quadratic programming through nlpqp sqp. The particular
SQP implementation in nlpql sqp uses a variant with distributed and non-monotone line search. Thus, this
variant is designed to be more robust in the presence of inaccurate or noisy gradients common in many engineering
applications.
The method independent controls for maximum iterations and output verbosity are mapped to NLPQL controls
MAXIT and IPRINT, respectively. The maximum number of function evaluations is enforced within the NLPQ-

6.2. METHOD

507

LPOptimizer class.
max iterations
Keywords Area
method
nlpql sqp
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
nlpql sqp
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

508

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
linear inequality constraint matrix
Keywords Area
method
nlpql sqp
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

6.2. METHOD

509

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
nlpql sqp
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).

510

CHAPTER 6. KEYWORDS AREA

linear inequality upper bounds

Keywords Area
method
nlpql sqp
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
nlpql sqp
linear inequality scale types
Specify how each linear inequality constraint is scaled

6.2. METHOD

511

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
nlpql sqp
linear inequality scales
Define the characteristic values to scale linear inequalities

512

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
nlpql sqp
linear equality constraint matrix
Define coefficients of the linear equalities

6.2. METHOD

513

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
nlpql sqp
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0

514

CHAPTER 6. KEYWORDS AREA

linear equality scale types

Keywords Area
method
nlpql sqp
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

6.2. METHOD

515

linear equality scales

Keywords Area
method
nlpql sqp
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

516

CHAPTER 6. KEYWORDS AREA

max function evaluations

Keywords Area
method
nlpql sqp
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
nlpql sqp
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

6.2. METHOD

517

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.

518

CHAPTER 6. KEYWORDS AREA

none, auto, log - optional
value - required.

A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
nlpql sqp
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

6.2. METHOD

519

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.24

optpp cg

Keywords Area

520

CHAPTER 6. KEYWORDS AREA

method
optpp cg
A conjugate gradient optimization method

Topics
This keyword is related to the topics:
package optpp
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max step

Dakota Keyword
Description
Max change in
design point
Stopping critiera
based on L2 norm
of gradient
Stopping criterion
based on number
of iterations

Optional

gradient tolerance

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

speculative

Optional

max function evaluations

Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

521
Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
The conjugate gradient method is an implementation of the Polak-Ribiere approach and handles only unconstrained problems.
See package optpp for info related to all optpp methods.

522

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
optpp g newton
optpp pds
optpp fd newton
optpp newton
optpp g newton
max step
Keywords Area
method
optpp cg
max step
Max change in design point

Specification
Alias: none
Argument(s): REAL
Default: 1000.

Description
The max step control specifies the maximum step that can be taken when computing a change in the current
design point (e.g., limiting the Newton step computed from current gradient and Hessian information). It is equivalent to a move limit or a maximum trust region size. The gradient tolerance control defines the threshold
value on the L2 norm of the objective function gradient that indicates convergence to an unconstrained minimum
(no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
gradient tolerance
Keywords Area
method
optpp cg
gradient tolerance
Stopping critiera based on L2 norm of gradient

6.2. METHOD

523

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The gradient tolerance control defines the threshold value on the L2 norm of the objective function
gradient that indicates convergence to an unconstrained minimum (no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
max iterations
Keywords Area
method
optpp cg
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
optpp cg
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

524

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
speculative
Keywords Area
method
optpp cg
speculative
Compute speculative gradients

6.2. METHOD

525

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
optpp cg
max function evaluations

526

CHAPTER 6. KEYWORDS AREA

Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
optpp cg
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.

6.2. METHOD

527

Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

528

CHAPTER 6. KEYWORDS AREA

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
optpp cg
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.

6.2. METHOD

529

linear inequality lower bounds

Keywords Area
method
optpp cg
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
optpp cg
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

530

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
optpp cg
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

6.2. METHOD

531

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
optpp cg
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

532

CHAPTER 6. KEYWORDS AREA

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
optpp cg
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

6.2. METHOD

533

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
optpp cg
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
optpp cg
linear equality scale types
Specify how each linear equality constraint is scaled

534

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
optpp cg
linear equality scales
Define the characteristic values to scale linear equalities

6.2. METHOD

535

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
optpp cg
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

536

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

537

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.25

optpp q newton

Keywords Area
method
optpp q newton
Quasi-Newton optimization method

Topics
This keyword is related to the topics:
package optpp
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
search method

Optional

merit function

Optional

steplength to boundary

Dakota Keyword
Description
Select a search
method for
Newton-based
optimizers
Balance goals of
reducing objective
function and
satisfying
constraints
Controls how close
to the boundary of
the feasible region
the algorithm is
allowed to move

538

CHAPTER 6. KEYWORDS AREA

Optional

centering parameter

Optional

max step

Optional

gradient tolerance

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint

Controls how
closely the
algorithm should
follow the central
path
Max change in
design point
Stopping critiera
based on L2 norm
of gradient
Stopping criterion
based on number
of iterations

6.2. METHOD

539
Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Specify how each

linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
This is a Newton method that expects a gradient and computes a low-rank approximation to the Hessian. Each of
the Newton-based methods are automatically bound to the appropriate OPT++ algorithm based on the user constraint specification (unconstrained, bound-constrained, or generally-constrained). In the generally-constrained
case, the Newton methods use a nonlinear interior-point approach to manage the constraints.
See package optpp for info related to all optpp methods.
search method
Keywords Area
method
optpp q newton
search method
Select a search method for Newton-based optimizers

Specification
Alias: none
Argument(s): none

540

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
value based line search
gradient based line search
trust region

tr pds

Dakota Keyword
Description
Use only function
values for line
search
Set the search
method to use the
gradient
Use trust region as
the globalization
strategy.
Use direct search
as the local search
in a trust region
method

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

value based line search

Keywords Area
method
optpp q newton
search method
value based line search
Use only function values for line search

Specification
Alias: none
Argument(s): none
Default: trust region (unconstrained), value based line search (bound/general constraints)

6.2. METHOD

541

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

gradient based line search

Keywords Area
method
optpp q newton
search method
gradient based line search
Set the search method to use the gradient

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

trust region
Keywords Area
method

542

CHAPTER 6. KEYWORDS AREA

optpp q newton
search method
trust region
Use trust region as the globalization strategy.

Specification
Alias: none
Argument(s): none

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
tr pds
Keywords Area
method
optpp q newton
search method
tr pds
Use direct search as the local search in a trust region method

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function

6.2. METHOD

543

and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

merit function
Keywords Area
method
optpp q newton
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none
Default: argaez tapia
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
el bakry

Group 1
argaez tapia

van shanno

Dakota Keyword
Description
El-Bakry merit
function
The merit function
by Tapia and
Argaez
The merit function
by Vanderbei and
Shanno

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.
el bakry
Keywords Area
method
optpp q newton
merit function
el bakry
El-Bakry merit function

544

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
The el bakry merit function is the L2-norm of the first order optimality conditions for the nonlinear programming problem. The cost per linesearch iteration is n+1 function evaluations. For more information, see[20].

argaez tapia
Keywords Area
method
optpp q newton
merit function
argaez tapia
The merit function by Tapia and Argaez

Specification
Alias: none
Argument(s): none

Description
The argaez tapia merit function can be classified as a modified augmented Lagrangian function. The augmented
Lagrangian is modified by adding to its penalty term a potential reduction function to handle the perturbed complementarity condition. The cost per linesearch iteration is one function evaluation. For more information, see
[80].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
van shanno
Keywords Area
method
optpp q newton
merit function
van shanno
The merit function by Vanderbei and Shanno

6.2. METHOD

545

Specification
Alias: none
Argument(s): none

Description
The van shanno merit function can be classified as a penalty function for the logarithmic barrier formulation
of the nonlinear programming problem. The cost per linesearch iteration is one function evaluation. For more
information see[82].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
steplength to boundary
Keywords Area
method
optpp q newton
steplength to boundary
Controls how close to the boundary of the feasible region the algorithm is allowed to move

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.8 (el bakry), 0.99995 (argaez tapia), 0.95 (van shanno)

Description
The steplength to boundary specification is a parameter (between 0 and 1) that controls how close to the
boundary of the feasible region the algorithm is allowed to move. A value of 1 means that the algorithm is allowed
to take steps that may reach the boundary of the feasible region. If the user wishes to maintain strict feasibility of
the design parameters this value should be less than 1. Default values are .8, .99995, and .95 for the el bakry,
argaez tapia, and van shanno merit functions, respectively.
centering parameter
Keywords Area
method
optpp q newton
centering parameter
Controls how closely the algorithm should follow the central path

546

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.2 (el bakry), 0.2 (argaez tapia), 0.1 (van shanno)

Description
The centering parameter specification is a parameter (between 0 and 1) that controls how closely the
algorithm should follow the central path. See[88] for the definition of central path. The larger the value, the
more closely the algorithm follows the central path, which results in small steps. A value of 0 indicates that the
algorithm will take a pure Newton step. Default values are .2, .2, and .1 for the el bakry, argaez tapia,
and van shanno merit functions, respectively.
max step
Keywords Area
method
optpp q newton
max step
Max change in design point

Specification
Alias: none
Argument(s): REAL
Default: 1000.

Description
The max step control specifies the maximum step that can be taken when computing a change in the current
design point (e.g., limiting the Newton step computed from current gradient and Hessian information). It is equivalent to a move limit or a maximum trust region size. The gradient tolerance control defines the threshold
value on the L2 norm of the objective function gradient that indicates convergence to an unconstrained minimum
(no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
gradient tolerance
Keywords Area
method
optpp q newton
gradient tolerance
Stopping critiera based on L2 norm of gradient

6.2. METHOD

547

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The gradient tolerance control defines the threshold value on the L2 norm of the objective function
gradient that indicates convergence to an unconstrained minimum (no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
max iterations
Keywords Area
method
optpp q newton
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
optpp q newton
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

548

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
speculative
Keywords Area
method
optpp q newton
speculative
Compute speculative gradients

6.2. METHOD

549

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
optpp q newton
max function evaluations

550

CHAPTER 6. KEYWORDS AREA

Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
optpp q newton
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.

6.2. METHOD

551

Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

552

CHAPTER 6. KEYWORDS AREA

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
optpp q newton
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.

6.2. METHOD

553

linear inequality lower bounds

Keywords Area
method
optpp q newton
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
optpp q newton
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

554

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
optpp q newton
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

6.2. METHOD

555

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
optpp q newton
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

556

CHAPTER 6. KEYWORDS AREA

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
optpp q newton
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

6.2. METHOD

557

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
optpp q newton
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
optpp q newton
linear equality scale types
Specify how each linear equality constraint is scaled

558

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
optpp q newton
linear equality scales
Define the characteristic values to scale linear equalities

6.2. METHOD

559

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
optpp q newton
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

560

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

561

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.26

optpp fd newton

Keywords Area
method
optpp fd newton
Finite Difference Newton optimization method

Topics
This keyword is related to the topics:
package optpp
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
search method

Optional

merit function

Optional

steplength to boundary

Dakota Keyword
Description
Select a search
method for
Newton-based
optimizers
Balance goals of
reducing objective
function and
satisfying
constraints
Controls how close
to the boundary of
the feasible region
the algorithm is
allowed to move

562

CHAPTER 6. KEYWORDS AREA

Optional

centering parameter

Optional

max step

Optional

gradient tolerance

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint

Controls how
closely the
algorithm should
follow the central
path
Max change in
design point
Stopping critiera
based on L2 norm
of gradient
Stopping criterion
based on number
of iterations

6.2. METHOD

563
Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Specify how each

linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
This is a Newton method that expects a gradient and computes a finite-difference approximation to the Hessian. Each of the Newton-based methods are automatically bound to the appropriate OPT++ algorithm based on
the user constraint specification (unconstrained, bound-constrained, or generally-constrained). In the generallyconstrained case, the Newton methods use a nonlinear interior-point approach to manage the constraints.
See package optpp for info related to all optpp methods.

See Also
These keywords may also be of interest:
optpp cg
optpp g newton
optpp pds
optpp newton
optpp g newton
search method
Keywords Area

564

CHAPTER 6. KEYWORDS AREA

method
optpp fd newton
search method
Select a search method for Newton-based optimizers

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
value based line search
gradient based line search
trust region

tr pds

Dakota Keyword
Description
Use only function
values for line
search
Set the search
method to use the
gradient
Use trust region as
the globalization
strategy.
Use direct search
as the local search
in a trust region
method

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

value based line search

Keywords Area
method
optpp fd newton
search method

6.2. METHOD

565

value based line search

Use only function values for line search

Specification
Alias: none
Argument(s): none
Default: trust region (unconstrained), value based line search (bound/general constraints)

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

gradient based line search

Keywords Area
method
optpp fd newton
search method
gradient based line search
Set the search method to use the gradient

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods

566

CHAPTER 6. KEYWORDS AREA

additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

trust region
Keywords Area
method
optpp fd newton
search method
trust region
Use trust region as the globalization strategy.

Specification
Alias: none
Argument(s): none

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
tr pds
Keywords Area
method
optpp fd newton
search method
tr pds
Use direct search as the local search in a trust region method

6.2. METHOD

567

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

merit function
Keywords Area
method
optpp fd newton
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none
Default: argaez tapia
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
el bakry

Group 1
argaez tapia

van shanno

Dakota Keyword
Description
El-Bakry merit
function
The merit function
by Tapia and
Argaez
The merit function
by Vanderbei and
Shanno

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.

568

CHAPTER 6. KEYWORDS AREA

el bakry
Keywords Area
method
optpp fd newton
merit function
el bakry
El-Bakry merit function

Specification
Alias: none
Argument(s): none

Description
The el bakry merit function is the L2-norm of the first order optimality conditions for the nonlinear programming problem. The cost per linesearch iteration is n+1 function evaluations. For more information, see[20].

argaez tapia
Keywords Area
method
optpp fd newton
merit function
argaez tapia
The merit function by Tapia and Argaez

Specification
Alias: none
Argument(s): none

Description
The argaez tapia merit function can be classified as a modified augmented Lagrangian function. The augmented
Lagrangian is modified by adding to its penalty term a potential reduction function to handle the perturbed complementarity condition. The cost per linesearch iteration is one function evaluation. For more information, see
[80].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.

6.2. METHOD

569

van shanno
Keywords Area
method
optpp fd newton
merit function
van shanno
The merit function by Vanderbei and Shanno

Specification
Alias: none
Argument(s): none

Description
The van shanno merit function can be classified as a penalty function for the logarithmic barrier formulation
of the nonlinear programming problem. The cost per linesearch iteration is one function evaluation. For more
information see[82].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
steplength to boundary
Keywords Area
method
optpp fd newton
steplength to boundary
Controls how close to the boundary of the feasible region the algorithm is allowed to move

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.8 (el bakry), 0.99995 (argaez tapia), 0.95 (van shanno)

Description
The steplength to boundary specification is a parameter (between 0 and 1) that controls how close to the
boundary of the feasible region the algorithm is allowed to move. A value of 1 means that the algorithm is allowed
to take steps that may reach the boundary of the feasible region. If the user wishes to maintain strict feasibility of
the design parameters this value should be less than 1. Default values are .8, .99995, and .95 for the el bakry,
argaez tapia, and van shanno merit functions, respectively.

570

CHAPTER 6. KEYWORDS AREA

centering parameter
Keywords Area
method
optpp fd newton
centering parameter
Controls how closely the algorithm should follow the central path

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.2 (el bakry), 0.2 (argaez tapia), 0.1 (van shanno)

Description
The centering parameter specification is a parameter (between 0 and 1) that controls how closely the
algorithm should follow the central path. See[88] for the definition of central path. The larger the value, the
more closely the algorithm follows the central path, which results in small steps. A value of 0 indicates that the
algorithm will take a pure Newton step. Default values are .2, .2, and .1 for the el bakry, argaez tapia,
and van shanno merit functions, respectively.
max step
Keywords Area
method
optpp fd newton
max step
Max change in design point

Specification
Alias: none
Argument(s): REAL
Default: 1000.

Description
The max step control specifies the maximum step that can be taken when computing a change in the current
design point (e.g., limiting the Newton step computed from current gradient and Hessian information). It is equivalent to a move limit or a maximum trust region size. The gradient tolerance control defines the threshold
value on the L2 norm of the objective function gradient that indicates convergence to an unconstrained minimum
(no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.

6.2. METHOD

571

gradient tolerance
Keywords Area
method
optpp fd newton
gradient tolerance
Stopping critiera based on L2 norm of gradient

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The gradient tolerance control defines the threshold value on the L2 norm of the objective function
gradient that indicates convergence to an unconstrained minimum (no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
max iterations
Keywords Area
method
optpp fd newton
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

572

CHAPTER 6. KEYWORDS AREA

convergence tolerance
Keywords Area
method
optpp fd newton
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

6.2. METHOD

573

speculative
Keywords Area
method
optpp fd newton
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable

574

CHAPTER 6. KEYWORDS AREA

only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
optpp fd newton
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
optpp fd newton
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

6.2. METHOD

575

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.

576

CHAPTER 6. KEYWORDS AREA

none, auto, log - optional
value - required.

A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
optpp fd newton
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.

6.2. METHOD

577

linear inequality lower bounds

Keywords Area
method
optpp fd newton
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
optpp fd newton
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

578

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
optpp fd newton
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

6.2. METHOD

579

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
optpp fd newton
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

580

CHAPTER 6. KEYWORDS AREA

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
optpp fd newton
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

6.2. METHOD

581

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
optpp fd newton
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
optpp fd newton
linear equality scale types
Specify how each linear equality constraint is scaled

582

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
optpp fd newton
linear equality scales
Define the characteristic values to scale linear equalities

6.2. METHOD

583

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
model pointer
Keywords Area
method
optpp fd newton
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

584

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

585

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.27

optpp g newton

Keywords Area
method
optpp g newton
Newton method based least-squares calbration

Topics
This keyword is related to the topics:
package optpp
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
search method

Optional

merit function

Optional

steplength to boundary

Dakota Keyword
Description
Select a search
method for
Newton-based
optimizers
Balance goals of
reducing objective
function and
satisfying
constraints
Controls how close
to the boundary of
the feasible region
the algorithm is
allowed to move

586

CHAPTER 6. KEYWORDS AREA

Optional

centering parameter

Optional

max step

Optional

gradient tolerance

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint

Controls how
closely the
algorithm should
follow the central
path
Max change in
design point
Stopping critiera
based on L2 norm
of gradient
Stopping criterion
based on number
of iterations

6.2. METHOD

587
Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Specify how each

linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
The Gauss-Newton algorithm is available as optpp g newton and supports unconstrained, bound-constrained,
and generally-constrained problems. When interfaced with the unconstrained, bound-constrained, and nonlinear
interior point full-Newton optimizers from the OPT++ library, it provides a Gauss-Newton least squares capability
which on zero-residual test problems can exhibit quadratic convergence rates near the solution. (Real problems
almost never have zero residuals, i.e., perfect fits.)
See package optpp for info related to all optpp methods.

See Also
These keywords may also be of interest:
optpp cg
optpp pds
optpp fd newton
optpp newton
optpp g newton
field calibration terms

588

CHAPTER 6. KEYWORDS AREA

search method
Keywords Area
method
optpp g newton
search method
Select a search method for Newton-based optimizers

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
value based line search
gradient based line search
trust region

tr pds

Dakota Keyword
Description
Use only function
values for line
search
Set the search
method to use the
gradient
Use trust region as
the globalization
strategy.
Use direct search
as the local search
in a trust region
method

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

value based line search

Keywords Area
method

6.2. METHOD

589

optpp g newton
search method
value based line search
Use only function values for line search

Specification
Alias: none
Argument(s): none
Default: trust region (unconstrained), value based line search (bound/general constraints)

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

gradient based line search

Keywords Area
method
optpp g newton
search method
gradient based line search
Set the search method to use the gradient

Specification
Alias: none
Argument(s): none

590

CHAPTER 6. KEYWORDS AREA

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

trust region
Keywords Area
method
optpp g newton
search method
trust region
Use trust region as the globalization strategy.

Specification
Alias: none
Argument(s): none

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.
tr pds
Keywords Area
method

6.2. METHOD

591

optpp g newton
search method
tr pds
Use direct search as the local search in a trust region method

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

merit function
Keywords Area
method
optpp g newton
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none
Default: argaez tapia
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
el bakry

Group 1

Dakota Keyword
Description
El-Bakry merit
function

592

CHAPTER 6. KEYWORDS AREA

argaez tapia

van shanno

The merit function

by Tapia and
Argaez
The merit function
by Vanderbei and
Shanno

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.
el bakry
Keywords Area
method
optpp g newton
merit function
el bakry
El-Bakry merit function

Specification
Alias: none
Argument(s): none

Description
The el bakry merit function is the L2-norm of the first order optimality conditions for the nonlinear programming problem. The cost per linesearch iteration is n+1 function evaluations. For more information, see[20].

argaez tapia
Keywords Area
method
optpp g newton
merit function
argaez tapia
The merit function by Tapia and Argaez

Specification
Alias: none
Argument(s): none

6.2. METHOD

593

Description
The argaez tapia merit function can be classified as a modified augmented Lagrangian function. The augmented
Lagrangian is modified by adding to its penalty term a potential reduction function to handle the perturbed complementarity condition. The cost per linesearch iteration is one function evaluation. For more information, see
[80].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
van shanno
Keywords Area
method
optpp g newton
merit function
van shanno
The merit function by Vanderbei and Shanno

Specification
Alias: none
Argument(s): none

Description
The van shanno merit function can be classified as a penalty function for the logarithmic barrier formulation
of the nonlinear programming problem. The cost per linesearch iteration is one function evaluation. For more
information see[82].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
steplength to boundary
Keywords Area
method
optpp g newton
steplength to boundary
Controls how close to the boundary of the feasible region the algorithm is allowed to move

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.8 (el bakry), 0.99995 (argaez tapia), 0.95 (van shanno)

594

CHAPTER 6. KEYWORDS AREA

Description
The steplength to boundary specification is a parameter (between 0 and 1) that controls how close to the
boundary of the feasible region the algorithm is allowed to move. A value of 1 means that the algorithm is allowed
to take steps that may reach the boundary of the feasible region. If the user wishes to maintain strict feasibility of
the design parameters this value should be less than 1. Default values are .8, .99995, and .95 for the el bakry,
argaez tapia, and van shanno merit functions, respectively.
centering parameter
Keywords Area
method
optpp g newton
centering parameter
Controls how closely the algorithm should follow the central path

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.2 (el bakry), 0.2 (argaez tapia), 0.1 (van shanno)

Description
The centering parameter specification is a parameter (between 0 and 1) that controls how closely the
algorithm should follow the central path. See[88] for the definition of central path. The larger the value, the
more closely the algorithm follows the central path, which results in small steps. A value of 0 indicates that the
algorithm will take a pure Newton step. Default values are .2, .2, and .1 for the el bakry, argaez tapia,
and van shanno merit functions, respectively.
max step
Keywords Area
method
optpp g newton
max step
Max change in design point

Specification
Alias: none
Argument(s): REAL
Default: 1000.

6.2. METHOD

595

Description
The max step control specifies the maximum step that can be taken when computing a change in the current
design point (e.g., limiting the Newton step computed from current gradient and Hessian information). It is equivalent to a move limit or a maximum trust region size. The gradient tolerance control defines the threshold
value on the L2 norm of the objective function gradient that indicates convergence to an unconstrained minimum
(no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
gradient tolerance
Keywords Area
method
optpp g newton
gradient tolerance
Stopping critiera based on L2 norm of gradient

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The gradient tolerance control defines the threshold value on the L2 norm of the objective function
gradient that indicates convergence to an unconstrained minimum (no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
max iterations
Keywords Area
method
optpp g newton
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

596

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
optpp g newton
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

6.2. METHOD

597

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
speculative
Keywords Area
method
optpp g newton
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.

598

CHAPTER 6. KEYWORDS AREA

In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
optpp g newton
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
optpp g newton
scaling
Turn on scaling for variables, responses, and constraints

6.2. METHOD

599

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].

600

CHAPTER 6. KEYWORDS AREA

4. log - logarithmic scaling

First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
optpp g newton
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

601

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
optpp g newton
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0

602

CHAPTER 6. KEYWORDS AREA

result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
optpp g newton
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).

6.2. METHOD

603

linear inequality scale types

Keywords Area
method
optpp g newton
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

604

CHAPTER 6. KEYWORDS AREA

linear inequality scales

Keywords Area
method
optpp g newton
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

6.2. METHOD

605

linear equality constraint matrix

Keywords Area
method
optpp g newton
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
optpp g newton
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

606

CHAPTER 6. KEYWORDS AREA

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
optpp g newton
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU

6.2. METHOD

607
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U

and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
optpp g newton
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

608

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
optpp g newton
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD

609

surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.28

optpp newton

Keywords Area
method
optpp newton
Newton method based optimization

Topics
This keyword is related to the topics:
package optpp
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

610

CHAPTER 6. KEYWORDS AREA

Optional

search method

Optional

merit function

Optional

steplength to boundary

Optional

centering parameter

Optional

max step

Optional

gradient tolerance

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

speculative

Optional

max function evaluations

Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations

Select a search
method for
Newton-based
optimizers
Balance goals of
reducing objective
function and
satisfying
constraints
Controls how close
to the boundary of
the feasible region
the algorithm is
allowed to move
Controls how
closely the
algorithm should
follow the central
path
Max change in
design point
Stopping critiera
based on L2 norm
of gradient
Stopping criterion
based on number
of iterations

6.2. METHOD

611
Optional

scaling

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

model pointer

Turn on scaling for

variables,
responses, and
constraints
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Identifier for
model block to be
used by a method

Description
This is a full Newton method that expects a gradient and a Hessian. Each of the Newton-based methods are automatically bound to the appropriate OPT++ algorithm based on the user constraint specification (unconstrained,
bound-constrained, or generally-constrained). In the generally-constrained case, the Newton methods use a nonlinear interior-point approach to manage the constraints.
See package optpp for info related to all optpp methods.

612

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
optpp cg
optpp g newton
optpp pds
optpp fd newton
optpp g newton
search method
Keywords Area
method
optpp newton
search method
Select a search method for Newton-based optimizers

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
value based line search
gradient based line search
trust region

tr pds

Dakota Keyword
Description
Use only function
values for line
search
Set the search
method to use the
gradient
Use trust region as
the globalization
strategy.
Use direct search
as the local search
in a trust region
method

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function

6.2. METHOD

613

and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

value based line search

Keywords Area
method
optpp newton
search method
value based line search
Use only function values for line search

Specification
Alias: none
Argument(s): none
Default: trust region (unconstrained), value based line search (bound/general constraints)

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

gradient based line search

Keywords Area
method
optpp newton
search method
gradient based line search
Set the search method to use the gradient

614

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

trust region
Keywords Area
method
optpp newton
search method
trust region
Use trust region as the globalization strategy.

Specification
Alias: none
Argument(s): none

Description
The trust region optional group specification can be used to specify the initial size of the trust region (using
initial size) relative to the total variable bounds, the minimum size of the trust region (using minimum size), the contraction factor for the trust region size (using contraction factor) used when the surrogate
model is performing poorly, and the expansion factor for the trust region size (using expansion factor) used
when the the surrogate model is performing well. Two additional commands are the trust region size contraction threshold (using contract threshold) and the trust region size expansion threshold (using expandthreshold). These two commands are related to what is called the trust region ratio, which is the actual decrease in the truth model divided by the predicted decrease in the truth model in the current trust region. The command contract threshold sets the minimum acceptable value for the trust region ratio, i.e., values below
this threshold cause the trust region to shrink for the next SBL iteration. The command expand threshold
determines the trust region value above which the trust region will expand for the next SBL iteration.

6.2. METHOD

615

tr pds
Keywords Area
method
optpp newton
search method
tr pds
Use direct search as the local search in a trust region method

Specification
Alias: none
Argument(s): none

Description
The search method control is defined for all Newton-based optimizers and is used to select between trust region, gradient based line search, and value based line search methods. The gradientbased line search option uses the line search method proposed by[61]. This option satisfies sufficient
decrease and curvature conditions; whereas, value base line search only satisfies the sufficient decrease
condition. At each line search iteration, the gradient based line search method computes the function
and gradient at the trial point. Consequently, given expensive function evaluations, the value based line search method is preferred to the gradient based line search method. Each of these Newton methods
additionally supports the tr pds selection for unconstrained problems. This option performs a robust trust region
search using pattern search techniques. Use of a line search is the default for bound-constrained and generallyconstrained problems, and use of a trust region search method is the default for unconstrained problems.

merit function
Keywords Area
method
optpp newton
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none
Default: argaez tapia

616

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
el bakry
argaez tapia

van shanno

Dakota Keyword
Description
El-Bakry merit
function
The merit function
by Tapia and
Argaez
The merit function
by Vanderbei and
Shanno

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.
el bakry
Keywords Area
method
optpp newton
merit function
el bakry
El-Bakry merit function

Specification
Alias: none
Argument(s): none

Description
The el bakry merit function is the L2-norm of the first order optimality conditions for the nonlinear programming problem. The cost per linesearch iteration is n+1 function evaluations. For more information, see[20].

argaez tapia
Keywords Area
method
optpp newton
merit function
argaez tapia
The merit function by Tapia and Argaez

6.2. METHOD

617

Specification
Alias: none
Argument(s): none

Description
The argaez tapia merit function can be classified as a modified augmented Lagrangian function. The augmented
Lagrangian is modified by adding to its penalty term a potential reduction function to handle the perturbed complementarity condition. The cost per linesearch iteration is one function evaluation. For more information, see
[80].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
van shanno
Keywords Area
method
optpp newton
merit function
van shanno
The merit function by Vanderbei and Shanno

Specification
Alias: none
Argument(s): none

Description
The van shanno merit function can be classified as a penalty function for the logarithmic barrier formulation
of the nonlinear programming problem. The cost per linesearch iteration is one function evaluation. For more
information see[82].
If the function evaluation is expensive or noisy, set the merit function to argaez tapia or van shanno.
steplength to boundary
Keywords Area
method
optpp newton
steplength to boundary
Controls how close to the boundary of the feasible region the algorithm is allowed to move

618

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.8 (el bakry), 0.99995 (argaez tapia), 0.95 (van shanno)

Description
The steplength to boundary specification is a parameter (between 0 and 1) that controls how close to the
boundary of the feasible region the algorithm is allowed to move. A value of 1 means that the algorithm is allowed
to take steps that may reach the boundary of the feasible region. If the user wishes to maintain strict feasibility of
the design parameters this value should be less than 1. Default values are .8, .99995, and .95 for the el bakry,
argaez tapia, and van shanno merit functions, respectively.
centering parameter
Keywords Area
method
optpp newton
centering parameter
Controls how closely the algorithm should follow the central path

Specification
Alias: none
Argument(s): REAL
Default: Merit function dependent: 0.2 (el bakry), 0.2 (argaez tapia), 0.1 (van shanno)

Description
The centering parameter specification is a parameter (between 0 and 1) that controls how closely the
algorithm should follow the central path. See[88] for the definition of central path. The larger the value, the
more closely the algorithm follows the central path, which results in small steps. A value of 0 indicates that the
algorithm will take a pure Newton step. Default values are .2, .2, and .1 for the el bakry, argaez tapia,
and van shanno merit functions, respectively.
max step
Keywords Area
method
optpp newton
max step
Max change in design point

6.2. METHOD

619

Specification
Alias: none
Argument(s): REAL
Default: 1000.

Description
The max step control specifies the maximum step that can be taken when computing a change in the current
design point (e.g., limiting the Newton step computed from current gradient and Hessian information). It is equivalent to a move limit or a maximum trust region size. The gradient tolerance control defines the threshold
value on the L2 norm of the objective function gradient that indicates convergence to an unconstrained minimum
(no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
gradient tolerance
Keywords Area
method
optpp newton
gradient tolerance
Stopping critiera based on L2 norm of gradient

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The gradient tolerance control defines the threshold value on the L2 norm of the objective function
gradient that indicates convergence to an unconstrained minimum (no active constraints). The gradient tolerance control is defined for all gradient-based optimizers.
max iterations
Keywords Area
method
optpp newton
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

620

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
optpp newton
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

6.2. METHOD

621

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
speculative
Keywords Area
method
optpp newton
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.

622

CHAPTER 6. KEYWORDS AREA

In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.
The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
optpp newton
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
optpp newton
scaling
Turn on scaling for variables, responses, and constraints

6.2. METHOD

623

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].

624

CHAPTER 6. KEYWORDS AREA

4. log - logarithmic scaling

First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

linear inequality constraint matrix

Keywords Area
method
optpp newton
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

625

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
optpp newton
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0

626

CHAPTER 6. KEYWORDS AREA

result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
optpp newton
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).

6.2. METHOD

627

linear inequality scale types

Keywords Area
method
optpp newton
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

628

CHAPTER 6. KEYWORDS AREA

linear inequality scales

Keywords Area
method
optpp newton
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

6.2. METHOD

629

linear equality constraint matrix

Keywords Area
method
optpp newton
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
optpp newton
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

630

CHAPTER 6. KEYWORDS AREA

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
optpp newton
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU

6.2. METHOD

631
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U

and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
optpp newton
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

632

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
optpp newton
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD

633

surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.29

optpp pds

Keywords Area
method
optpp pds
Simplex-based derivative free optimization method

Topics
This keyword is related to the topics:
package optpp

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

634

CHAPTER 6. KEYWORDS AREA

Optional

search scheme size

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Number of points
to be used in the
direct search
template
Stopping criterion
based on number
of iterations

Description
The direct search algorithm, PDS (parallel direct search method), supports bound constraints.
The PDS method can directly exploit asynchronous evaluations; however, this capability has not yet been
implemented in Dakota.
See package optpp for info related to all optpp methods.

See Also
These keywords may also be of interest:
optpp cg
optpp g newton
optpp fd newton
optpp newton
optpp g newton
search scheme size
Keywords Area

6.2. METHOD

635

method
optpp pds
search scheme size
Number of points to be used in the direct search template

Specification
Alias: none
Argument(s): INTEGER
Default: 32

Description
The search scheme size is defined for the PDS method to specify the number of points to be used in the
direct search template.
max iterations
Keywords Area
method
optpp pds
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

636

CHAPTER 6. KEYWORDS AREA

convergence tolerance
Keywords Area
method
optpp pds
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

6.2. METHOD
max function evaluations
Keywords Area
method
optpp pds
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
optpp pds
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

637

638

CHAPTER 6. KEYWORDS AREA

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.

6.2. METHOD

639

none, auto, log - optional

value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
optpp pds
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

640

CHAPTER 6. KEYWORDS AREA

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.30

asynch pattern search

Keywords Area

6.2. METHOD

641

method
asynch pattern search
Pattern search, derivative free optimization method

Topics
This keyword is related to the topics:
package hopspack
global optimization methods

Specification
Alias: coliny apps
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
initial delta

Optional

contraction factor

Optional

threshold delta

Optional

solution target

Optional

synchronization

Optional

merit function

Dakota Keyword
Description
Initial step size for
non-gradient based
optimizers
Amount by which
step length is
rescaled
Stopping criteria
based on step
length or pattern
size
Stopping criteria
based on objective
function value
Select how Dakota
schedules function
evaluations in a
pattern search
Balance goals of
reducing objective
function and
satisfying
constraints

642

CHAPTER 6. KEYWORDS AREA

Optional

constraint penalty

Optional

smoothing factor

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

constraint tolerance

Multiplier for the

penalty function
Smoothing value
for smoothed
penalty functions
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
The maximum
allowable value of
constraint violation
still considered to
be feasible

6.2. METHOD

643
Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
The asynchronous parallel pattern search (APPS) algorithm [37] is a fully asynchronous pattern search technique
in that the search along each offset direction continues without waiting for searches along other directions to
finish.
Currently, APPS only supports coordinate bases with a total of 2n function evaluations in the pattern, and
these patterns may only contract.
Concurrency
APPS exploits parallelism through the use of Dakotas concurrent function evaluations. The variant of the
algorithm that is currently exposed, however, limits the amount of concurrency that can be exploited. In particular,
APPS can leverage an evaluation concurrency level of at most twice the number of variables. More options that
allow for greater evaluation concurrency may be exposed in future releases.
Algorithm Behavior
initial delta: the initial step length, must be positive
threshold delta: step length used to determine convergence, must be greater than or equal to 4.4e-16
contraction factor: amount by which step length is rescaled after unsuccesful iterates, must be
strictly between 0 and 1
Merit Functions
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit functionbase subproblems. There are several exact and smoothed exact penalty functions that can be specified with the
merit function control. The options are as follows:
merit max: based on ` norm
merit max smooth: based on smoothed ` norm
merit1: based on `1 norm
merit1 smooth: based on smoothed `1 norm
merit2: based on `2 norm
merit2 smooth: based on smoothed `2 norm
merit2 squared: based on `22 norm
The user can also specify the following to affect the merit functions:

644

CHAPTER 6. KEYWORDS AREA

constraint penalty
smoothing parameter

Method Independent Controls

The only method independent controls that are currently mapped to APPS are:
max function evaluations
constraint tolerance
output
Note that while APPS treats the constraint tolerance separately for linear and nonlinear constraints, we apply the
same value to both if the user specifies constraint tolerance.
The APPS internal display level is mapped to the Dakota output settings as follows:
debug: display final solution, all input parameters, variable and constraint info, trial points, search directions, and execution details
verbose: display final solution, all input parameters, variable and constraint info, and trial points
normal: display final solution, all input parameters, variable and constraint summaries, and new best
points
quiet: display final solution and all input parameters
silent: display final solution
initial delta
Keywords Area
method
asynch pattern search
initial delta
Initial step size for non-gradient based optimizers

Specification
Alias: none
Argument(s): REAL
Default: 1.0

Description
If initial delta is supplied by the user, it will be applied in an absolute sense in all coordinate directions.
APPS documentation advocates choosing initial delta to be the approximate distance from the initial point
to the solution. If this is unknown, it is advisable to err on the side of choosing an initial delta that is too
large or to not specify it. In the latter case, APPS will take a full step to the boundary in each direction. Relative
application of initial delta is not available unless the user scales the problem accordingly.

6.2. METHOD

645

contraction factor
Keywords Area
method
asynch pattern search
contraction factor
Amount by which step length is rescaled

Specification
Alias: none
Argument(s): REAL
Default: 0.5

Description
For pattern search methods, contraction factor specifies the amount by which step length is rescaled after
unsuccesful iterates, must be strictly between 0 and 1.
For methods that can expand the step length, the expansion is 1/ contraction factor
threshold delta
Keywords Area
method
asynch pattern search
threshold delta
Stopping criteria based on step length or pattern size

Specification
Alias: none
Argument(s): REAL
Default: 0.01

Description
threshold delta is the step length or pattern size used to determine convergence.
solution target
Keywords Area
method
asynch pattern search
solution target
Stopping criteria based on objective function value

646

CHAPTER 6. KEYWORDS AREA

Specification
Alias: solution accuracy
Argument(s): REAL
Default: no target

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
synchronization
Keywords Area
method
asynch pattern search
synchronization
Select how Dakota schedules function evaluations in a pattern search

Specification
Alias: none
Argument(s): none
Default: nonblocking
Required/Optional
Required(Choose
One)

Description of
Group
synchronization
(Group 1)

Dakota Keyword
blocking
nonblocking

Dakota Keyword
Description
Evaluate all points
in a pattern
Evaluate points in
the pattern until an
improving point is
found

Description
The synchronization specification can be used to specify the use of either blocking or nonblocking
schedulers.
blocking
Keywords Area
method
asynch pattern search
synchronization
blocking
Evaluate all points in a pattern

6.2. METHOD

647

Specification
Alias: none
Argument(s): none

Description
In the blocking case, all points in the pattern are evaluated (in parallel), and if the best of these trial points is
an improving point, then it becomes the next iterate. These runs are reproducible, assuming use of the same seed
in the stochastic case.
nonblocking
Keywords Area
method
asynch pattern search
synchronization
nonblocking
Evaluate points in the pattern until an improving point is found

Specification
Alias: none
Argument(s): none

Description
In the nonblocking case, all points in the pattern may not be evaluated. The first improving point found
becomes the next iterate. Since the algorithm steps will be subject to parallel timing variabilities, these runs will
not generally be repeatable.
merit function
Keywords Area
method
asynch pattern search
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none
Default: merit2 squared

648

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Dakota Keyword
merit max

Required(Choose
One)

merit function
(Group 1)

merit max smooth

merit1
merit1 smooth
merit2
merit2 smooth
merit2 squared

Dakota Keyword
Description
Nonsmoothed
merit function
Smoothed merit
function
Nonsmoothed
merit function
Smoothed merit
function
Nonsmoothed
merit function
Smoothed merit
function
Nonsmoothed
merit function

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.
merit max
Keywords Area
method
asynch pattern search
merit function
merit max
Nonsmoothed merit function

Specification
Alias: none
Argument(s): none

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit max: based on ` norm
merit max smooth
Keywords Area
method

6.2. METHOD

649

asynch pattern search

merit function
merit max smooth
Smoothed merit function

Specification
Alias: none
Argument(s): none

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit max smooth: based on smoothed ` norm
merit1
Keywords Area
method
asynch pattern search
merit function
merit1
Nonsmoothed merit function

Specification
Alias: none
Argument(s): none

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit1: based on `1 norm
merit1 smooth
Keywords Area
method
asynch pattern search
merit function
merit1 smooth
Smoothed merit function

650

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit1 smooth: based on smoothed `1 norm
merit2
Keywords Area
method
asynch pattern search
merit function
merit2
Nonsmoothed merit function

Specification
Alias: none
Argument(s): none

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit2: based on `2 norm
merit2 smooth
Keywords Area
method
asynch pattern search
merit function
merit2 smooth
Smoothed merit function

Specification
Alias: none
Argument(s): none

6.2. METHOD

651

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit2 smooth: based on smoothed `2 norm
merit2 squared
Keywords Area
method
asynch pattern search
merit function
merit2 squared
Nonsmoothed merit function

Specification
Alias: none
Argument(s): none

Description
APPS solves nonlinearly constrained problems by solving a sequence of linearly constrained merit function-base
subproblems. There are several exact and smoothed exact penalty functions.
merit2 squared: based on `22 norm
constraint penalty
Keywords Area
method
asynch pattern search
constraint penalty
Multiplier for the penalty function

Specification
Alias: none
Argument(s): REAL
Default: 1.0

Description
Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty
times the sum of squares of the constraint violations to the objective function. The default value of constraintpenalty is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default
value is 1.0.

652

CHAPTER 6. KEYWORDS AREA

smoothing factor
Keywords Area
method
asynch pattern search
smoothing factor
Smoothing value for smoothed penalty functions

Specification
Alias: none
Argument(s): REAL
Default: 0.0

Description
smoothing parameter: initial smoothing value for smoothed penalty functions, must be between 0
and 1 (inclusive)
linear inequality constraint matrix
Keywords Area
method
asynch pattern search
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

6.2. METHOD

653

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
asynch pattern search
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).

654

CHAPTER 6. KEYWORDS AREA

linear inequality upper bounds

Keywords Area
method
asynch pattern search
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
asynch pattern search
linear inequality scale types
Specify how each linear inequality constraint is scaled

6.2. METHOD

655

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
asynch pattern search
linear inequality scales
Define the characteristic values to scale linear inequalities

656

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
asynch pattern search
linear equality constraint matrix
Define coefficients of the linear equalities

6.2. METHOD

657

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
asynch pattern search
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0

658

CHAPTER 6. KEYWORDS AREA

linear equality scale types

Keywords Area
method
asynch pattern search
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

6.2. METHOD

659

linear equality scales

Keywords Area
method
asynch pattern search
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].

660

CHAPTER 6. KEYWORDS AREA

constraint tolerance
Keywords Area
method
asynch pattern search
constraint tolerance
The maximum allowable value of constraint violation still considered to be feasible

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: Library default

Description
The constraint tolerance specification determines the maximum allowable value of infeasibility that any
constraint in an optimization problem may possess and still be considered to be satisfied.
If a constraint function is greater than this value then it is considered to be violated by the optimization
algorithm. This specification gives some control over how tightly the constraints will be satisfied at convergence
of the algorithm. However, if the value is set too small the algorithm may terminate with one or more constraints
being violated.
This specification is currently meaningful for the NPSOL, NLSSOL, DOT and CONMIN constrained optimizers.
Defaults
Defaults can vary depending on the method.
DOT constrained optimizers: 0.003
NPSOL: dependent upon the machine precision, typically on the order of 1.e-8 for double precision
computations
max function evaluations
Keywords Area
method
asynch pattern search
max function evaluations
Stopping criteria based on number of function evaluations

6.2. METHOD

661

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
asynch pattern search
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.

662

CHAPTER 6. KEYWORDS AREA

a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values

The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

6.2. METHOD

663

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
asynch pattern search
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

664

CHAPTER 6. KEYWORDS AREA

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.31

mesh adaptive search

Keywords Area
method
mesh adaptive search
Finds optimal variable values using adaptive mesh-based search

6.2. METHOD

665

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
function precision

Dakota Keyword
Description
Specify the
maximum
precision of the
analysis code
responses
Seed of the random
number generator

Optional

seed

Optional

history file

Name of file where

mesh adaptive
search records all
evaluation points.

Optional

display format

Information to be
reported from
mesh adaptive
searchs internal
records.

Optional

variable neighborhood search

Percentage of
evaluations to do to
escape local
minima.

Optional

neighbor order

Number of
dimensions in
which to perturb
categorical
variables.

Optional

display all evaluations

Shows mesh
adaptive searchs
internally held list
of all evaluations

666

CHAPTER 6. KEYWORDS AREA

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
The mesh adaptive direct search algorithm[9] is a derivative-free generalized pattern search in which the set of
points evaluated becomes increasingly dense, leading to good convergence properties. It can handle unconstrained
problems as well as those with bound constraints and general nonlinear constraints. Furthermore, it can handle
continuous, discrete, and categorical variables.
Default Behavior
By default, mesh adaptive search operates on design variables. The types of variables can be expanded
through the use of the active keyword in the variables block in the Dakota input file. Categorical variables,
however, must be limited to design variables.
Expected Outputs
The best objective function value achieved and associated parameter and constraint values can be found at the
end of the Dakota output. The methods internally summarized iteration history will appear in the screen output.
It also generates a history file containing a list of all function evaluations done.
Additional Discussion
The mesh adaptive direct search method is made available in Dakota through the NOMAD software[2], available to the public under the GNU LGPL from http://www.gerad.ca/nomad.

Examples
The following is an example of a Dakota input file that makes use of mesh adaptive search to optimize the
textbook function.
method,
mesh_adaptive_search
seed = 1234
variables,
continuous_design = 3
initial_point
-1.0
1.5
2.0
upper_bounds
10.0
10.0 10.0
lower_bounds
-10.0 -10.0 -10.0
descriptors
x1 x2 x3
interface,
direct

6.2. METHOD
analysis_driver = text_book
responses,
objective_functions = 1
no_gradients
no_hessians

The best function value and associated parameters are found at the end of the Dakota output.
<<<<< Function evaluation summary: 674 total (674 new, 0 duplicate)
<<<<< Best parameters
=
1.0000000000e+00 x1
1.0000000000e+00 x2
1.0000000000e+00 x3
<<<<< Best objective function =
1.0735377280e-52
<<<<< Best data captured at function evaluation 658

A NOMAD-generated iteration summary is also printed to the screen.

MADS run {
BBE OBJ
1
2
13
24
41
43
54
83
105
112
114
135
142
153
159
171
193
200
207
223
229
250
266
282
288
314
320
321
327
354
361
372
373
389
400
417
444
459

17.0625000000
1.0625000000
0.0625000000
0.0002441406
0.0000314713
0.0000028610
0.0000000037
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

667

668

CHAPTER 6. KEYWORDS AREA

461
488
492
494
501
518
530
537
564
566
583
590
592
604
606
629
636
658
674

0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

} end of run (mesh size reached NOMAD precision)

blackbox evaluations
best feasible solution

: 674
: ( 1 1 1 ) h=0 f=1.073537728e-52

function precision
Keywords Area
method
mesh adaptive search
function precision
Specify the maximum precision of the analysis code responses

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-10

Description
The function precision control provides the algorithm with an estimate of the accuracy to which the
problem functions can be computed. This is used to prevent the algorithm from trying to distinguish between
function values that differ by less than the inherent error in the calculation.
seed
Keywords Area
method
mesh adaptive search

6.2. METHOD

669

seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

history file
Keywords Area
method
mesh adaptive search
history file
Name of file where mesh adaptive search records all evaluation points.

Specification
Alias: none
Argument(s): STRING
Default: mads history

670

CHAPTER 6. KEYWORDS AREA

Description
The history file is used to specify the name of a file to which mesh adaptive direct search will write its own
list of evaluated points.
Default Behavior
By default, mesh adaptive direct search will write the list of evaluation points in a file named mads history.xxxx, where xxxx corresponds to a randomly generated number.

Examples
The example below shows the syntax for specifying the name of the history file.
method
mesh_adaptive_search
history_file = output.log
seed = 1234

display format
Keywords Area
method
mesh adaptive search
display format
Information to be reported from mesh adaptive searchs internal records.

Specification
Alias: none
Argument(s): STRING

Description
The display format keyword is used to specify the set of information to be reported by the mesh adaptive
direct search method. This is information mostly internal to the method and not reported via Dakota output.
Default Behavior
By default, only the number of function evaluations (bbe) and the objective function value (obj) are reported.
The full list of options is as follows. Note that case does not matter.
BBE: Blackbox evaluations.
BBO: Blackbox outputs.
EVAL: Evaluations (includes cache hits).
MESH INDEX: Mesh index.
MESH SIZE: Mesh size parameter.
OBJ: Objective function value.
POLL SIZE: Poll size parameter.

6.2. METHOD

671

SOL: Solution, with format iSOLj where i and j are two (optional) strings: i will be displayed before each
coordinate, and j after each coordinate (except the last).
STAT AVG: The AVG statistic.
STAT SUM: The SUM statistic defined by argument.
TIME: Wall-clock time.
VARi: Value of variable i. The index 0 corresponds to the first variable.
Expected Outputs
A list of the requested information will be printed to the screen.
Usage Tips
This will most likely only be useful for power users who want to understand and/or report more detailed
information on method behavior.

Examples
The following example shows the syntax for specifying display format. Note that all desired information
options should be listed within a single string.
method
mesh_adaptive_search
display_format bbe obj poll_size
seed = 1234

Below is the output reported for the above example.

MADS run {
BBE OBJ POLL_SIZE
1
2
13
24
41
43
54
83
105
112
114
135
142
153
159
171
193
200
207
223
229
250
266
282
288
314

17.0625000000
1.0625000000
0.0625000000
0.0002441406
0.0000314713
0.0000028610
0.0000000037
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

2.0000000000
2.0000000000
1.0000000000
0.5000000000
0.1250000000
0.2500000000
0.1250000000
0.0078125000
0.0009765625
0.0009765625
0.0019531250
0.0004882812
0.0004882812
0.0004882812
0.0009765625
0.0004882812
0.0000610352
0.0000610352
0.0000610352
0.0000305176
0.0000610352
0.0000152588
0.0000076294
0.0000038147
0.0000076294
0.0000009537

2.0000000000
2.0000000000
1.0000000000
0.5000000000
0.1250000000
0.2500000000
0.1250000000
0.0078125000
0.0009765625
0.0009765625
0.0019531250
0.0004882812
0.0004882812
0.0004882812
0.0009765625
0.0004882812
0.0000610352
0.0000610352
0.0000610352
0.0000305176
0.0000610352
0.0000152588
0.0000076294
0.0000038147
0.0000076294
0.0000009537

2.0000000000
2.0000000000
1.0000000000
0.5000000000
0.1250000000
0.2500000000
0.1250000000
0.0078125000
0.0009765625
0.0009765625
0.0019531250
0.0004882812
0.0004882812
0.0004882812
0.0009765625
0.0004882812
0.0000610352
0.0000610352
0.0000610352
0.0000305176
0.0000610352
0.0000152588
0.0000076294
0.0000038147
0.0000076294
0.0000009537

672

CHAPTER 6. KEYWORDS AREA

320
321
327
354
361
372
373
389
400
417
444
459
461
488
492
494
501
518
530
537
564
566
583
590
592
604
606
629
636
658
674

0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

0.0000019073
0.0000038147
0.0000076294
0.0000004768
0.0000004768
0.0000004768
0.0000009537
0.0000004768
0.0000004768
0.0000001192
0.0000000075
0.0000000037
0.0000000075
0.0000000005
0.0000000009
0.0000000019
0.0000000019
0.0000000005
0.0000000002
0.0000000002
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

0.0000019073
0.0000038147
0.0000076294
0.0000004768
0.0000004768
0.0000004768
0.0000009537
0.0000004768
0.0000004768
0.0000001192
0.0000000075
0.0000000037
0.0000000075
0.0000000005
0.0000000009
0.0000000019
0.0000000019
0.0000000005
0.0000000002
0.0000000002
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

0.0000019073
0.0000038147
0.0000076294
0.0000004768
0.0000004768
0.0000004768
0.0000009537
0.0000004768
0.0000004768
0.0000001192
0.0000000075
0.0000000037
0.0000000075
0.0000000005
0.0000000009
0.0000000019
0.0000000019
0.0000000005
0.0000000002
0.0000000002
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000
0.0000000000

} end of run (mesh size reached NOMAD precision)

blackbox evaluations
best feasible solution

: 674
: ( 1 1 1 ) h=0 f=1.073537728e-52

See Also
These keywords may also be of interest:
display all evaluations
variable neighborhood search
Keywords Area
method
mesh adaptive search
variable neighborhood search
Percentage of evaluations to do to escape local minima.

Specification
Alias: none
Argument(s): REAL
Default: 0.0

6.2. METHOD

673

Description
The variable neighborhood search keyword is used to set the percentage (in decimal form) of function
evaluations used to escape local minima. The mesh adaptive direct search method will try to perform a maximum
of that percentage of the function evaluations within this more extensive search.
Default Behavior
By default, variable neighborhood search is not used.
Usage Tips
Using variable neighborhood search results in an increased number of function evaluations. If the
desired result is a local minimum, the added cost is of little or no value, so the recommendation is not to use it. If
the desired result is the best local minimum possible within a computational budget, then there is value in setting
this parameter. Note that the higher the value, the greater the computational cost.

Examples
The following example shows the syntax used to set variable neighborhood search.
method
mesh_adaptive_search
seed = 1234
variable_neighborhood_search = 0.1

neighbor order
Keywords Area
method
mesh adaptive search
neighbor order
Number of dimensions in which to perturb categorical variables.

Specification
Alias: none
Argument(s): INTEGER

Description
The neighbor order keyword allows the user to specify the number of categorical dimensions to perturb
when determining neighboring points that will be used by the mesh adaptive direct search method to augment its
search. When greater than 1, the neighbors are defined from the tensor product of the admissible 1-dimensional
perturbations.
Default Behavior
By default, the categorical neighbors will be defined by perturbing only one categorical variable at a time
(according to the corresponding adjacency matrix; see adjacency matrix) while leaving the others fixed at their
current values.
Usage Tips
The maximum meaningful value neighbor order can take on is the number of categorical variables.

674

CHAPTER 6. KEYWORDS AREA

Examples
In this example, suppose we have the following categorical variables and associated adjacency matrices.
variables
discrete_design_set
real = 2
categorical yes yes
num_set_values = 3 5
set_values = 1.2 2.3
1.2 3.3
adjacency_matrix = 1
1
0
1
0
1
0
1

3.4
4.4
1 0
1 1
1 1
0 1
1 0
0 1
1 0
0 1

5.5 7.7

0
1
0
1
0

1
0
1
0
1

Also suppose that we have the following method specification.

method
mesh_adaptive_search
seed = 1234

If the mesh adaptive direct search is at the point (1.2, 1.2), then the neighbors will be defined by the default
1-dimensional perturbations and would be the following:
(2.3, 1.2)
(1.2, 4.4)
(1.2, 7.7)

If, instead, the method specification is the following:

method
mesh_adaptive_search
seed = 1234
neighbor_order = 2

The neighbors will be defined by 2-dimensional perturbations defined from the tensor product of the 1dimensional perturbation and would be the following:
(2.3,
(2.3,
(2.3,
(1.2,
(1.2,

1.2)
4.4)
7.7)
4.4)
7.7)

See Also
These keywords may also be of interest:
adjacency matrix

6.2. METHOD

675

display all evaluations

Keywords Area
method
mesh adaptive search
display all evaluations
Shows mesh adaptive searchs internally held list of all evaluations

Specification
Alias: none
Argument(s): none
Default: false

Description
If set, display all evaluations will instruct the mesh adaptive direct search method to print out its own
record of all evaluations. The information reported may be controlled using display format.
Default Behavior
By default, mesh adaptive direct search does not report information on all evaluations, only on those for which
an improvement in the objective function is found.
Expected Outputs
The information specified by display format will be reported to the screen for every function evaluation.
Usage Tips
This will most likely only be useful for power users who want to understand and/or report more detailed
information on method behavior.

Examples
The following example shows the syntax for specifying display all evaluations.
method
mesh_adaptive_search
display_all_evaluations
max_function evaluations=20
seed = 1234

Note that the output below reports information (default for display format) for all function evaluations.
MADS run {
BBE OBJ
1
2
3
4
5
6
7
8
9

17.0625000000
1.0625000000
1297.0625000000
257.0625000000
81.0625000000
151.0625000000
1051.0625000000
40.0625000000
17.0625000000

676

CHAPTER 6. KEYWORDS AREA

10
11
12
13
14
15
16
17
18
19
20

40.0625000000
1.0625000000
102.0625000000
0.0625000000
231.0625000000
16.0625000000
5.0625000000
16.0625000000
71.0625000000
0.0625000000
1.0625000000

} end of run (max number of blackbox evaluations)

blackbox evaluations
best feasible solution

: 20
: ( 1 0.5 1 ) h=0 f=0.0625

That is in contrast with what would be reported by default.

MADS run {
BBE OBJ
1
2
13
20

17.0625000000
1.0625000000
0.0625000000
0.0625000000

} end of run (max number of blackbox evaluations)

blackbox evaluations
best feasible solution

: 20
: ( 1 0.5 1 ) h=0 f=0.0625

See Also
These keywords may also be of interest:
display format
max iterations
Keywords Area
method
mesh adaptive search
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

677

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
max function evaluations
Keywords Area
method
mesh adaptive search
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
mesh adaptive search
scaling
Turn on scaling for variables, responses, and constraints

678

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].

6.2. METHOD

679

4. log - logarithmic scaling

First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
mesh adaptive search
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

680

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

681

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.32

moga

Keywords Area
method
moga
Multi-objective Genetic Algorithm (a.k.a Evolutionary Algorithm)

Topics
This keyword is related to the topics:
package jega

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
fitness type

Optional

replacement type

Optional

niching type

Optional

convergence type

Optional

postprocessor type

Dakota Keyword
Description
Select the fitness
type for JEGA
methods
Select a
replacement type
for JEGA methods
Specify the type of
niching pressure
Select the
convergence type
for JEGA methods
Post process the
final solution from
moga

682

CHAPTER 6. KEYWORDS AREA

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

max function evaluations

Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

683
Optional

scaling

Optional

population size

Optional

log file

Optional

print each pop

Optional

initialization type

Optional

crossover type

Optional

mutation type

Optional

seed

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

model pointer

Identifier for
model block to be
used by a method

Turn on scaling for

variables,
responses, and
constraints
Set the initial
population size in
JEGA methods
Specify the name
of a log file
Print every
population to a
population file
Specify how to
initialize the
population
Select a crossover
type for JEGA
methods
Select a mutation
type for JEGA
methods
Seed of the random
number generator

Description
moga stands for Multi-objective Genetic Algorithm, which is a global optimization method that does Pareto
optimization for multiple objectives. It supports general constraints and a mixture of real and discrete variables.
Constraints
moga can utilize linear constraints using the keywords: - linear inequality constraint matrix - linear inequality lower bounds - linear inequality upper bounds - linear inequality scale types - linear inequalityscales - linear equality constraint matrix - linear equality targets - linear equality scale types - linear equality scales
Configuration
The genetic algorithm configurations are:
1. fitness
2. replacement

684

CHAPTER 6. KEYWORDS AREA

3. niching
4. convergence
5. postprocessor
6. initialization
7. crossover
8. mutation
9. population size
The steps followed by the algorithm are listed below. The configurations will effect how the algorithm completes each step.
Stopping Criteria
The moga method respects the max iterations and max function evaluations method independent controls to provide integer limits for the maximum number of generations and function evaluations, respectively.
The algorithm also stops when convergence is reached. This involves repeated assessment of the algorithms
progress in solving the problem, until some criterion is met.
The specification for convergence in a moga can either be metric tracker or can be omitted all together.
If omitted, no convergence algorithm will be used and the algorithm will rely on stopping criteria only.
Outputs
The moga method respects the output method independent control to vary the amount of information presented to the user during execution.
The final results are written to the Dakota tabular output. Additional information is also available - see the
log file and print each pop keywords.
Note that moga and SOGA create additional output files during execution. finaldata.dat is a file that holds
the final set of Pareto optimal solutions after any post-processing is complete. discards.dat holds solutions that
were discarded from the population during the course of evolution.
It can often be useful to plot objective function values from these files to visually see the Pareto front and
ensure that finaldata.dat solutions dominate discards.dat solutions. The solutions are written to these output files
in the format Input1...InputN..Output1...OutputM.
Important Notes
The pool of potential members is the current population and the current set of offspring.
Choice of fitness assessors is strongly related to the type of replacement algorithm being used and can have a
profound effect on the solutions selected for the next generation.
If using the fitness types layer rank or domination count, it is strongly recommended that you use
the replacement type below limit (although the roulette wheel selectors can also be used).
The functionality of the domination count selector of JEGA v1.0 can now be achieved using the dominationcount fitness type and below limit replacement type.

Theory
The basic steps of the moga algorithm are as follows:
1. Initialize the population
2. Evaluate the population (calculate the values of the objective function and constraints for each population
member)

6.2. METHOD

685

3. Loop until converged, or stopping criteria reached

(a) Perform crossover
(b) Perform mutation
(c) Evaluate the new population
(d) Assess the fitness of each member in the population
(e) Replace the population with members selected to continue in the next generation
(f) Apply niche pressure to the population
(g) Test for convergence
4. Perform post processing
If moga is used in a hybrid optimization method (which requires one optimal solution from each individual
optimization method to be passed to the subsequent optimization method as its starting point), the solution in the
Pareto set closest to the utopia point is given as the best solution. This solution is also reported in the Dakota
output.
This best solution in the Pareto set has minimum distance from the utopia point. The utopia point is defined
as the point of extreme (best) values for each objective function. For example, if the Pareto front is bounded by
(1,100) and (90,2), then (1,2) is the utopia point. There will be a point in the Pareto set that has minimum L2-norm
distance to this point, for example (10,10) may be such a point.
If moga is used in a method which may require passing multiple solutions to the next level (such as the
surrogate based global method or hybrid methods), the orthogonal distance postprocessor type
may be used to specify the distances between each solution value to winnow down the solutions in the full Pareto
front to a subset which will be passed to the next iteration.

See Also
These keywords may also be of interest:
soga
fitness type
Keywords Area
method
moga
fitness type
Select the fitness type for JEGA methods

Specification
Alias: none
Argument(s): none
Default: domination count

686

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
layer rank

domination count

Dakota Keyword
Description
Assign each
member to a layer,
based on
domination the
rank based on
layers
Rank each member
by the number of
members that
dominate it

Description
The two JEGA methods use different fitness types, which are described on their respective pages.
layer rank
Keywords Area
method
moga
fitness type
layer rank
Assign each member to a layer, based on domination the rank based on layers

Specification
Alias: none
Argument(s): none

Description
The fitness type: layer rank has been specifically designed to avoid problems with aggregating and
scaling objective function values and transforming them into a single objective.
The layer rank fitness assessor works by assigning all non-dominated designs a layer of 0, then from what
remains, assigning all the non-dominated a layer of 1, and so on until all designs have been assigned a layer. The
values are negated to follow the higher-is-better fitness convention.
Use of the below limit selector with the layer rank fitness assessor has the effect of keeping all those
designs whose layer is below a certain threshold again subject to the shrinkage limit.
domination count
Keywords Area
method
moga

6.2. METHOD

687

fitness type
domination count
Rank each member by the number of members that dominate it

Specification
Alias: none
Argument(s): none

Description
The fitness type: domination count has been specifically designed to avoid problems with aggregating
and scaling objective function values and transforming them into a single objective.
Instead, the domination count fitness assessor works by ordering population members by the negative
of the number of designs that dominate them. The values are negated in keeping with the convention that higher
fitness is better.
The layer rank fitness assessor works by assigning all non-dominated designs a layer of 0, then from what
remains, assigning all the non-dominated a layer of 1, and so on until all designs have been assigned a layer.
Again, the values are negated for the higher-is-better fitness convention.
Use of the below limit selector with the domination count fitness assessor has the effect of keeping
all designs that are dominated by fewer then a limiting number of other designs subject to the shrinkage limit.
Using it with the layer rank fitness assessor has the effect of keeping all those designs whose layer is
below a certain threshold again subject to the shrinkage limit.
replacement type
Keywords Area
method
moga
replacement type
Select a replacement type for JEGA methods

Specification
Alias: none
Argument(s): none
Default: below limit
Required/Optional

Description of
Group

Dakota Keyword
elitist

Required(Choose
One)

Group 1

Dakota Keyword
Description
Use the best
designs to form a
new population

688

CHAPTER 6. KEYWORDS AREA

roulette wheel
unique roulette wheel
below limit

Replace population
Replace population
Limit number of
designs dominating
those kept

Description
Replace the population with members selected to continue in the next generation. The pool of potential members
is the current population and the current set of offspring. The replacement type of roulette wheel or
unique roulette wheel may be used either with MOGA or SOGA problems however they are not recommended for use with MOGA. Given that the only two fitness assessors for MOGA are the layer rank and
domination count, the recommended selector is the below limit selector. The below limit replacement will only keep designs that are dominated by fewer than a limiting number of other designs.
In roulette wheel replacement, each design is conceptually allotted a portion of a wheel proportional to
its fitness relative to the fitnesses of the other Designs. Then, portions of the wheel are chosen at random and the
design occupying those portions are duplicated into the next population. Those Designs allotted larger portions
of the wheel are more likely to be selected (potentially many times). unique roulette wheel replacement
is the same as roulette wheel replacement, with the exception that a design may only be selected once. The
below limit selector attempts to keep all designs for which the negated fitness is below a certain limit. The
values are negated to keep with the convention that higher fitness is better. The inputs to the below limit
selector are the limit as a real value, and a shrinkage percentage as a real value. The shrinkage percentage defines the minimum amount of selections that will take place if enough designs are available. It
is interpreted as a percentage of the population size that must go on to the subsequent generation. To enforce this,
below limit makes all the selections it would make anyway and if that is not enough, it takes the remaining
that it needs from the best of what is left (effectively raising its limit as far as it must to get the minimum number
of selections). It continues until it has made enough selections. The shrinkage percentage is designed to
prevent extreme decreases in the population size at any given generation, and thus prevent a big loss of genetic
diversity in a very short time. Without a shrinkage limit, a small group of super designs may appear and quickly
cull the population down to a size on the order of the limiting value. In this case, all the diversity of the population
is lost and it is expensive to re-diversify and spread the population. The
The replacement type for a SOGA may be roulette wheel, unique roulette wheel, elitist,
or favor feasible. The elitist selector simply chooses the required number of designs taking the most
fit. For example, if 100 selections are requested, then the top 100 designs as ranked by fitness will be selected
and the remaining will be discarded. The favor feasible replacement type first considers feasibility as a
selection criteria. If that does not produce a winner then it moves on to considering fitness value. Because of
this, any fitness assessor used with the favor feasible selector must only account objectives in the creation
of fitness. Therefore, there is such a fitness assessor and its use is enforced when the favor feasible selector
is chosen. In that case, and if the output level is set high enough, a message will be presented indicating that the
weighted sum only fitness assessor will be used.
elitist
Keywords Area
method
moga
replacement type

6.2. METHOD

689

elitist
Use the best designs to form a new population

Specification
Alias: none
Argument(s): none

Description
The elitist (default) setting creates a new population using (a) the replacement size best individuals
from the current population, (b) and population size - replacement size individuals randomly selected
from the newly generated individuals. It is possible in this case to lose a good solution from the newly generated
individuals if it is not randomly selected for replacement; however, the default new solutions generated
value is set such that the entire set of newly generated individuals will be selected for replacement.
roulette wheel
Keywords Area
method
moga
replacement type
roulette wheel
Replace population

Specification
Alias: none
Argument(s): none

Description
Replace the population with members selected to continue in the next generation. The pool of potential members
is the current population and the current set of offspring. The replacement type of roulette wheel
or unique roulette wheel may be used either with MOGA or SOGA problems however they are not recommended for use with MOGA. Given that the only two fitness assessors for MOGA are the layer rank
and domination count, the recommended selector is the below limit selector. The below limit replacement will only keep designs that are dominated by fewer than a limiting number of other designs. The
replacement type of favor feasible is specific to a SOGA. This replacement operator will always prefer a more feasible design to a less feasible one. Beyond that, it favors solutions based on an assigned fitness value
which must have been installed by the weighted sum only fitness assessor (see the discussion below).

690

CHAPTER 6. KEYWORDS AREA

unique roulette wheel

Keywords Area
method
moga
replacement type
unique roulette wheel
Replace population

Specification
Alias: none
Argument(s): none

Description
Replace the population with members selected to continue in the next generation. The pool of potential members
is the current population and the current set of offspring. The replacement type of roulette wheel
or unique roulette wheel may be used either with MOGA or SOGA problems however they are not recommended for use with MOGA. Given that the only two fitness assessors for MOGA are the layer rank
and domination count, the recommended selector is the below limit selector. The below limit replacement will only keep designs that are dominated by fewer than a limiting number of other designs. The
replacement type of favor feasible is specific to a SOGA. This replacement operator will always prefer a more feasible design to a less feasible one. Beyond that, it favors solutions based on an assigned fitness value
which must have been installed by the weighted sum only fitness assessor (see the discussion below).
below limit
Keywords Area
method
moga
replacement type
below limit
Limit number of designs dominating those kept

Specification
Alias: none
Argument(s): REAL
Default: 6

6.2. METHOD

691
Required/Optional
Optional

Description of
Group

Dakota Keyword
shrinkage fraction

Dakota Keyword
Description
Decrease the
population size by
a percentage

Description
The below limit replacement will only keep designs that are dominated by fewer than a limiting number of
other designs.
shrinkage fraction
Keywords Area
method
moga
replacement type
below limit
shrinkage fraction
Decrease the population size by a percentage

Specification
Alias: shrinkage percentage
Argument(s): REAL
Default: 0.9

Description
As of JEGA v2.0, all replacement types are common to both MOGA and SOGA. They include the roulette wheel, unique roulette wheel, elitist, and below limit selectors. In roulette wheel replacement,
each design is conceptually allotted a portion of a wheel proportional to its fitness relative to the fitnesses of the
other Designs. Then, portions of the wheel are chosen at random and the design occupying those portions are
duplicated into the next population. Those Designs allotted larger portions of the wheel are more likely to be
selected (potentially many times). unique roulette wheel replacement is the same as roulette wheel
replacement, with the exception that a design may only be selected once. The below limit selector attempts
to keep all designs for which the negated fitness is below a certain limit. The values are negated to keep with the
convention that higher fitness is better. The inputs to the below limit selector are the limit as a real value, and
a shrinkage percentage as a real value. The shrinkage percentage defines the minimum amount
of selections that will take place if enough designs are available. It is interpreted as a percentage of the population
size that must go on to the subsequent generation. To enforce this, below limit makes all the selections it
would make anyway and if that is not enough, it takes the remaining that it needs from the best of what is left
(effectively raising its limit as far as it must to get the minimum number of selections). It continues until it
has made enough selections. The shrinkage percentage is designed to prevent extreme decreases in the
population size at any given generation, and thus prevent a big loss of genetic diversity in a very short time.
Without a shrinkage limit, a small group of super designs may appear and quickly cull the population down to

692

CHAPTER 6. KEYWORDS AREA

a size on the order of the limiting value. In this case, all the diversity of the population is lost and it is expensive
to re-diversify and spread the population. The elitist selector simply chooses the required number of designs
taking the most fit. For example, if 100 selections are requested, then the top 100 designs as ranked by fitness will
be selected and the remaining will be discarded.
niching type
Keywords Area
method
moga
niching type
Specify the type of niching pressure

Specification
Alias: none
Argument(s): none
Default: No niche pressure
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
radial

Group 1

distance

max designs

Dakota Keyword
Description
Set niching
distance to
percentage of
non-dominated
range
Enforce minimum
Euclidean distance
between designs
Limit number of
solutions to remain
in the population

Description
The purpose of niching is to encourage differentiation along the Pareto frontier and thus a more even and uniform
sampling.
This is typically accomplished by discouraging clustering of design points in the performance space. In JEGA, the application of niche pressure occurs as a secondary selection operation. The nicher is given a chance to
perform a pre-selection operation prior to the operation of the selection (replacement) operator, and is then called
to perform niching on the set of designs that were selected by the selection operator.
The radial nicher takes information input from the user to compute a minimum allowable distance between
designs in the performance space and acts as a secondary selection operator whereby it enforces this minimum
distance. The distance nicher requires that solutions must be separated from other solutions by a minimum
distance in each dimension (vs. Euclidean distance for the radial niching). After niching is complete, all designs
in the population will be at least the minimum distance from one another in all directions.
The radial niche pressure applicator works by enforcing a minimum Euclidean distance between designs
in the performance space at each generation. The algorithm proceeds by starting at the (or one of the) extreme

6.2. METHOD

693

designs along objective dimension 0 and marching through the population removing all designs that are too close
to the current design. One exception to the rule is that the algorithm will never remove an extreme design which
is defined as a design that is maximal or minimal in all but 1 objective dimension (for a classical 2 objective
problem, the extreme designs are those at the tips of the non-dominated frontier). The distance nicher enforces
a minimimum distance in each dimension.
The designs that are removed by the nicher are not discarded. They are buffered and re-inserted into the
population during the next pre-selection operation. This way, the selector is still the only operator that discards
designs and the algorithm will not waste time re-filling gaps created by the nicher.
The radial nicher requires as input a vector of fractions with length equal to the number of objectives.
The elements of the vector are interpreted as percentages of the non-dominated range for each objective defining
a minimum distance to all other designs. All values should be in the range (0, 1). The minimum allowable
distance between any two designs in the performance space is the Euclidian (simple square-root-sum-of-squares
calculation) distance defined by these percentages. The distance nicher has a similar input vector requirement,
only the distance is the minimum distance in each dimension.
The max designs niche pressure applicator is designed to choose a limited number of solutions to remain
in the population. That number is specified by num designs. It does so in order to balance the tendency for
populations to grow very large and thus consuming too many computer resources. It operates by ranking designs
according to their fitness standing and a computed count of how many other designs are too close to them. Too
close is a function of the supplied niche vector, which specifies the minimum distance between any two points
in the performance space along each dimension individually. Once the designs are all ranked, the top c\ num designs designs are kept in the population and the remaining ones are bufferred or discarded. Note that like other
niching operators, this one will not discard an extreme design.
radial
Keywords Area
method
moga
niching type
radial
Set niching distance to percentage of non-dominated range

Specification
Alias: none
Argument(s): REALLIST
Default: 0.01 for all objectives

Description
The radial nicher requires as input a vector of fractions with length equal to the number of objectives. The
elements of the vector are interpreted as percentages of the non-dominated range for each objective defining
a minimum distance to all other designs. All values should be in the range (0, 1). The minimum allowable
distance between any two designs in the performance space is the Euclidian (simple square-root-sum-of-squares
calculation) distance defined by these percentages. The distance nicher has a similar input vector requirement,
only the distance is the minimum distance in each dimension.

694

CHAPTER 6. KEYWORDS AREA

distance
Keywords Area
method
moga
niching type
distance
Enforce minimum Euclidean distance between designs

Specification
Alias: none
Argument(s): REALLIST

Description
Currently, the only niche pressure operators available are the radial nicher, the distance nicher, and the
max designs nicher. The radial niche pressure applicator works by enforcing a minimum Euclidean distance
between designs in the performance space at each generation. The algorithm proceeds by starting at the (or one of
the) extreme designs along objective dimension 0 and marching through the population removing all designs that
are too close to the current design. One exception to the rule is that the algorithm will never remove an extreme
design which is defined as a design that is maximal or minimal in all but 1 objective dimension (for a classical
2 objective problem, the extreme designs are those at the tips of the non-dominated frontier). The distance
nicher enforces a minimimum distance in each dimension.
The designs that are removed by the nicher are not discarded. They are buffered and re-inserted into the
population during the next pre-selection operation. This way, the selector is still the only operator that discards
designs and the algorithm will not waste time re-filling gaps created by the nicher.
max designs
Keywords Area
method
moga
niching type
max designs
Limit number of solutions to remain in the population

Specification
Alias: none
Argument(s): REALLIST

6.2. METHOD

695
Required/Optional
Optional

Description of
Group

Dakota Keyword
num designs

Dakota Keyword
Description
Limit the number
of solutions

Description
The max designs niche pressure applicator is designed to choose a limited number of solutions to remain in
the population. That number is specified by num designs. It does so in order to balance the tendency for
populations to grow very large and thus consuming too many computer resources. It operates by ranking designs
according to their fitness standing and a computed count of how many other designs are too close to them. Too
close is a function of the supplied niche vector, which specifies the minimum distance between any two points
in the performance space along each dimension individually. Once the designs are all ranked, the top c\ num designs designs are kept in the population and the remaining ones are bufferred or discarded. Note that like other
niching operators, this one will not discard an extreme design.
num designs
Keywords Area
method
moga
niching type
max designs
num designs
Limit the number of solutions

Specification
Alias: none
Argument(s): INTEGER
Default: 100

Description
The max designs niche pressure applicator is designed to choose a limited number of solutions to remain in
the population. That number is specified by num designs. It does so in order to balance the tendency for
populations to grow very large and thus consuming too many computer resources. It operates by ranking designs
according to their fitness standing and a computed count of how many other designs are too close to them. Too
close is a function of the supplied niche vector, which specifies the minimum distance between any two points
in the performance space along each dimension individually. Once the designs are all ranked, the top c\ num designs designs are kept in the population and the remaining ones are bufferred or discarded. Note that like other
niching operators, this one will not discard an extreme design.

696

CHAPTER 6. KEYWORDS AREA

convergence type
Keywords Area
method
moga
convergence type
Select the convergence type for JEGA methods

Specification
Alias: none
Argument(s): none
Default: average fitness tracker
Required/Optional
Required

Description of
Group

Dakota Keyword
metric tracker

Optional

percent change

Optional

num generations

Dakota Keyword
Description
Track changes in
the non-dominated
frontier
Define the
convergence
criterion for JEGA
methods
Define the
convergence
criterion for JEGA
methods

Description
The two JEGA methods use different convergence types, which are described on their respective pages.
All the convergence types are modified by the optional keywords percent change and num generations.

metric tracker
Keywords Area
method
moga
convergence type
metric tracker
Track changes in the non-dominated frontier

6.2. METHOD

697

Specification
Alias: none
Argument(s): none
Default: metric tracker

Description
The moga converger (metric tracker) operates by tracking various changes in the non-dominated frontier
from generation to generation. When the changes occurring over a user specified number of generations fall below
a user specified threshold, the algorithm stops.
If metric tracker is specified, then a percent change and num generations must be supplied as
well. These are listed as optional keywords in the input spec.

Theory
The metric tracker converger tracks 3 metrics specific to the non-dominated frontier from generation to
generation. All 3 of these metrics are computed as percent changes between the generations. In order to compute
these metrics, the converger stores a duplicate of the non-dominated frontier at each generation for comparison to
the non-dominated frontier of the next generation.
The first metric is one that indicates how the expanse of the frontier is changing. The expanse along a given
objective is defined by the range of values existing within the non-dominated set. The expansion metric is computed by tracking the extremes of the non-dominated frontier from one generation to the next. Any movement of
the extreme values is noticed and the maximum percentage movement is computed as:
Em = max over j of abs((range(j, i) - range(j, i-1)) /
range(j, i-1)) j=1,nof

where Em is the max expansion metric, j is the objective function index, i is the current generation number, and
nof is the total number of objectives. The range is the difference between the largest value along an objective and
the smallest when considering only non-dominated designs.
The second metric monitors changes in the density of the non-dominated set. The density metric is computed
as the number of non-dominated points divided by the hypervolume of the non-dominated region of space. Therefore, changes in the density can be caused by changes in the number of non-dominated points or by changes in
size of the non-dominated space or both. The size of the non-dominated space is computed as:
Vps(i) = product over j of range(j, i)

j=1,nof

where Vps(i) is the hypervolume of the non-dominated space at generation i and all other terms have the same
meanings as above.
The density of the a given non-dominated space is then:
Dps(i) = Pct(i) / Vps(i)

where Pct(i) is the number of points on the non-dominated frontier at generation i.

The percentage increase in density of the frontier is then calculated as
Cd = abs((Dps(i) - Dps(i-1)) / Dps(i-1))

where Cd is the change in density metric.

The final metric is one that monitors the goodness of the non-dominated frontier. This metric is computed
by considering each design in the previous population and determining if it is dominated by any designs in the
current population. All that are determined to be dominated are counted. The metric is the ratio of the number
that are dominated to the total number that exist in the previous population.
As mentioned above, each of these metrics is a percentage. The tracker records the largest of these three at
each generation. Once the recorded percentage is below the supplied percent change for the supplied number of
generations consecutively, the algorithm is converged.

698

CHAPTER 6. KEYWORDS AREA

percent change
Keywords Area
method
moga
convergence type
percent change
Define the convergence criterion for JEGA methods

Specification
Alias: none
Argument(s): REAL
Default: 0.1

Description
The percent change is the threshold beneath which convergence is attained whereby it is compared to the
metric value computed.
num generations
Keywords Area
method
moga
convergence type
num generations
Define the convergence criterion for JEGA methods

Specification
Alias: none
Argument(s): INTEGER
Default: 10

Description
The num generations is the number of generations over which the metric value should be tracked. Convergence will be attained if the recorded metric is below percent change for num generations consecutive
generations.

6.2. METHOD

699

postprocessor type
Keywords Area
method
moga
postprocessor type
Post process the final solution from moga

Specification
Alias: none
Argument(s): none
Default: No post-processing of solutions
Required/Description of
Optional
Group
Required

Dakota Keyword
orthogonal distance

Dakota Keyword
Description
Get subset of
Pareto front based
on distance

Description
The purpose of this operation is to perform any needed data manipulations on the final solution deemed necessary.
Currently the orthogonal distance is the only one. It reduces the final solution set size such that a minimum
distance in each direction exists between any two designs.
orthogonal distance
Keywords Area
method
moga
postprocessor type
orthogonal distance
Get subset of Pareto front based on distance

Specification
Alias: none
Argument(s): REALLIST
Default: 0.01 for all objectives

700

CHAPTER 6. KEYWORDS AREA

Description
Note that MOGA and SOGA create additional output files during execution. finaldata.dat is a file that holds
the final set of Pareto optimal solutions after any post-processing is complete. discards.dat holds solutions that
were discarded from the population during the course of evolution. It can often be useful to plot objective function
values from these files to visually see the Pareto front and ensure that finaldata.dat solutions dominate discards.dat
solutions. The solutions are written to these output files in the format Input1...InputN..Output1...OutputM. If
MOGA is used in a hybrid optimization meta-iteration (which requires one optimal solution from each individual
optimization method to be passed to the subsequent optimization method as its starting point), the solution in the
Pareto set closest to the utopia point is given as the best solution. This solution is also reported in the Dakota
output. This best solution in the Pareto set has minimum distance from the utopia point. The utopia point
is defined as the point of extreme (best) values for each objective function. For example, if the Pareto front is
bounded by (1,100) and (90,2), then (1,2) is the utopia point. There will be a point in the Pareto set that has
minimum L2-norm distance to this point, for example (10,10) may be such a point. In SOGA, the solution that
minimizes the single objective function is returned as the best solution. If moga is used in meta-iteration which
may require passing multiple solutions to the next level (such as the surrogate based global or hybrid
methods), the orthogonal distance postprocessor type may be used to specify the distances between each
solution value to winnow down the solutions in the full Pareto front to a subset which will be passed to the next
iteration.
max iterations
Keywords Area
method
moga
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

6.2. METHOD

701

linear inequality constraint matrix

Keywords Area
method
moga
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.
linear inequality lower bounds
Keywords Area
method
moga
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

702

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
moga
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

6.2. METHOD

703

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
moga
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified

704

CHAPTER 6. KEYWORDS AREA

auto - automatic scaling If a single string is specified it will apply to all constraints.

Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
moga
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored

6.2. METHOD

705

value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
moga
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

706

CHAPTER 6. KEYWORDS AREA

linear equality targets

Keywords Area
method
moga
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
moga
linear equality scale types
Specify how each linear equality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

6.2. METHOD

707

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
moga
linear equality scales
Define the characteristic values to scale linear equalities

Topics
This keyword is related to the topics:
linear constraints

708

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
max function evaluations
Keywords Area
method
moga
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

6.2. METHOD

709

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
moga
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored

710

CHAPTER 6. KEYWORDS AREA

2. value - multiplicative scaling

3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

6.2. METHOD

711

population size
Keywords Area
method
moga
population size
Set the initial population size in JEGA methods

Specification
Alias: none
Argument(s): INTEGER
Default: 50

Description
The number of designs in the initial population is specified by the population size. Note that the populationsize only sets the size of the initial population. The population size may vary in the JEGA methods according
to the type of operators chosen for a particular optimization run.
log file
Keywords Area
method
moga
log file
Specify the name of a log file

Specification
Alias: none
Argument(s): STRING
Default: JEGAGlobal.log

Description
New as of JEGA v2.0 is the introduction of the log file specification. JEGA now uses a logging library to
output messages and status to the user. JEGA can be configured at build time to log to both the console window
and a text file, one or the other, or neither. The log file input is a string name of a file into which to log. If
the build was configured without file logging in JEGA, this input is ignored. If file logging is enabled and no
log file is specified, the default file name of JEGAGlobal.log is used.

712

CHAPTER 6. KEYWORDS AREA

print each pop

Keywords Area
method
moga
print each pop
Print every population to a population file

Specification
Alias: none
Argument(s): none
Default: No printing

Description
New to JEGA v2.0 is the introduction of the print each pop specification. It serves as a flag and if supplied,
the population at each generation will be printed to a file named population<GEN#>.dat where <GEN#> is
the number of the current generation.
initialization type
Keywords Area
method
moga
initialization type
Specify how to initialize the population

Specification
Alias: none
Argument(s): none
Default: unique random
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
simple random

Group 1
unique random

Dakota Keyword
Description
Create random
initial solutions
Create random
initial solutions,
but enforce
uniqueness
(default)

6.2. METHOD

713
flat file

Read initial
solutions from file

Description
The initialization type defines how the initial population is created for the GA. There are three types:
1. simple random
2. unique random (default)
3. flat file
Setting the size for the flat file initializer has the effect of requiring a minimum number of designs to
create. If this minimum number has not been created once the files are all read, the rest are created using the
unique random initializer and then the simple random initializer if necessary.
simple random
Keywords Area
method
moga
initialization type
simple random
Create random initial solutions

Specification
Alias: none
Argument(s): none

Description
simple random creates initial solutions with random variable values according to a uniform random number
distribution. It gives no consideration to any previously generated designs.
unique random
Keywords Area
method
moga
initialization type
unique random
Create random initial solutions, but enforce uniqueness (default)

714

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
unique random is the same as simple random, except that when a new solution is generated, it is checked
against the rest of the solutions. If it duplicates any of them, it is rejected.
flat file
Keywords Area
method
moga
initialization type
flat file
Read initial solutions from file

Specification
Alias: none
Argument(s): STRING

Description
flat file allows the initial population to be read from a flat file. If flat file is specified, a file name must
be given.
Variables can be delimited in the flat file in any way you see fit with a few exceptions. The delimiter must be
the same on any given line of input with the exception of leading and trailing whitespace. So a line could look
like: 1.1, 2.2 ,3.3 for example but could not look like: 1.1, 2.2 3.3. The delimiter can vary from line to line within
the file which can be useful if data from multiple sources is pasted into the same input file. The delimiter can be
any string that does not contain any of the characters .+-dDeE or any of the digits 0-9. The input will be read until
the end of the file. The algorithm will discard any configurations for which it was unable to retrieve at least the
number of design variables. The objective and constraint entries are not required but if ALL are present, they will
be recorded and the design will be tagged as evaluated so that evaluators may choose not to re-evaluate them.
Setting the size for this initializer has the effect of requiring a minimum number of designs to create. If this
minimum number has not been created once the files are all read, the rest are created using the unique random
initializer and then the simple random initializer if necessary.
crossover type
Keywords Area
method
moga
crossover type
Select a crossover type for JEGA methods

6.2. METHOD

715

Specification
Alias: none
Argument(s): none
Default: shuffle random
Required/Optional

Description of
Group

Dakota Keyword
multi point binary

Required(Choose
One)

Group 1
multi point parameterized binary
multi point real

shuffle random

Optional

crossover rate

Dakota Keyword
Description
Use bit switching
for crossover
events
Use bit switching
to crossover each
design variable
Perform crossover
in real valued
genome
Perform crossover
by choosing design
variable(s)
Specify the
probability of a
crossover event

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.
The final crossover type is shuffle random. This crossover type performs crossover by choosing design
variables at random from a specified number of parents enough times that the requested number of children are
produced. For example, consider the case of 3 parents producing 2 children. This operator would go through and
for each design variable, select one of the parents as the donor for the child. So it creates a random shuffle of the
parent design variable values. The relative numbers of children and parents are controllable to allow for as much
mixing as desired. The more parents involved, the less likely that the children will wind up exact duplicates of the
parents.
All crossover types take a crossover rate. The crossover rate is used to calculate the number of crossover
operations that take place. The number of crossovers is equal to the rate population size.
multi point binary
Keywords Area

716

CHAPTER 6. KEYWORDS AREA

method
moga
crossover type
multi point binary
Use bit switching for crossover events

Specification
Alias: none
Argument(s): INTEGER

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.
multi point parameterized binary
Keywords Area
method
moga
crossover type
multi point parameterized binary
Use bit switching to crossover each design variable

Specification
Alias: none
Argument(s): INTEGER

6.2. METHOD

717

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.
multi point real
Keywords Area
method
moga
crossover type
multi point real
Perform crossover in real valued genome

Specification
Alias: none
Argument(s): INTEGER

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.

718

CHAPTER 6. KEYWORDS AREA

shuffle random
Keywords Area
method
moga
crossover type
shuffle random
Perform crossover by choosing design variable(s)

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
num parents

num offspring

Dakota Keyword
Description
Number of parents
in random shuffle
crossover
Number of
offspring in
random shuffle
crossover

Description
The final crossover type is shuffle random. This crossover type performs crossover by choosing design
variables at random from a specified number of parents enough times that the requested number of children are
produced. For example, consider the case of 3 parents producing 2 children. This operator would go through and
for each design variable, select one of the parents as the donor for the child. So it creates a random shuffle of the
parent design variable values. The relative numbers of children and parents are controllable to allow for as much
mixing as desired. The more parents involved, the less likely that the children will wind up exact duplicates of the
parents.
num parents
Keywords Area
method
moga
crossover type
shuffle random
num parents
Number of parents in random shuffle crossover

6.2. METHOD

Specification
Alias: none
Argument(s): INTEGER
Default: 2

Description
Number of parents in random shuffle crossover
num offspring
Keywords Area
method
moga
crossover type
shuffle random
num offspring
Number of offspring in random shuffle crossover

Specification
Alias: none
Argument(s): INTEGER
Default: 2

Description
Number of offspring in random shuffle crossover
crossover rate
Keywords Area
method
moga
crossover type
crossover rate
Specify the probability of a crossover event

Specification
Alias: none
Argument(s): REAL
Default: 0.8

719

720

CHAPTER 6. KEYWORDS AREA

Description
The crossover type controls what approach is employed for combining parent genetic information to create offspring, and the crossover rate specifies the probability of a crossover operation being performed to
generate a new offspring. The SCOLIB EA method supports three forms of crossover, two point, blend, and
uniform, which generate a new individual through combinations of two parent individuals. Two-point crossover
divides each parent into three regions, where offspring are created from the combination of the middle region from
one parent and the end regions from the other parent. Since the SCOLIB EA does not utilize bit representations
of variable values, the crossover points only occur on coordinate boundaries, never within the bits of a particular
coordinate. Uniform crossover creates offspring through random combination of coordinates from the two parents. Blend crossover generates a new individual randomly along the multidimensional vector connecting the two
parents.
mutation type
Keywords Area
method
moga
mutation type
Select a mutation type for JEGA methods

Specification
Alias: none
Argument(s): none
Default: replace uniform
Required/Optional

Description of
Group

Dakota Keyword
bit random

Required(Choose
One)

Group 1

replace uniform

offset normal

offset cauchy

offset uniform

Dakota Keyword
Description
Mutate by flipping
a random bit
Use uniformly
distributed value
over range of
parameter
Set mutation offset
to use a normal
distribution
Use a Cauchy
distribution for the
mutation offset
Set mutation offset
to use a uniform
distribution

6.2. METHOD

721
Optional

mutation rate

Set probability of a
mutation

Description
Five mutation types are available for selection by keyword: replace uniform, bit random, offset cauchy, offset normal, and offset uniform. They are described in greater detail on their respective
keyword pages.
The offset mutators all act by adding a random offset to a variable value. The random amount has a
mean of zero in all cases. The size of the offset is controlled using the mutation scale keyword, which is
interpreted differently for each offset type.
The rate of mutations for all types is controlled suing the mutation rate. The rate is applied differently
in each mutation type.
bit random
Keywords Area
method
moga
mutation type
bit random
Mutate by flipping a random bit

Specification
Alias: none
Argument(s): none

Description
The bit random mutator introduces random variation by first converting a randomly chosen variable of a randomly chosen design into a binary string. It then flips a randomly chosen bit in the string from a 1 to a 0 or visa
versa. In this mutation scheme, the resulting value has more probability of being similar to the original value.
replace uniform
Keywords Area
method
moga
mutation type
replace uniform
Use uniformly distributed value over range of parameter

722

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
replace uniform introduces random variation by first randomly choosing a design variable of a randomly
selected design and reassigning it to a random valid value for that variable. No consideration of the current value
is given when determining the new value.
offset normal
Keywords Area
method
moga
mutation type
offset normal
Set mutation offset to use a normal distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mutation scale

Dakota Keyword
Description
Scales mutation
across range of
parameter

Description
The offset normal mutator introduces random variation by adding a Gaussian random amount to a variable
value. The random amount has a standard deviation dependent on the mutation scale.
mutation scale
Keywords Area
method
moga
mutation type
offset normal
mutation scale
Scales mutation across range of parameter

6.2. METHOD

723

Specification
Alias: none
Argument(s): REAL
Default: 0.15

Description
The mutation scale is a fraction in the range [0, 1] and is meant to help control the amount of variation that takes
place when a variable is mutated. Its behavior depends on the selected mutation type. For offset normal
and offset cauchy, mutation scale is multipled by the range of the variable being mutated to obtain the
standard deviation of the offset. For offset uniform, the range of possible deviation amounts is +/- 1/2
(mutation scale variable range).
offset cauchy
Keywords Area
method
moga
mutation type
offset cauchy
Use a Cauchy distribution for the mutation offset

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mutation scale

Dakota Keyword
Description
Scales mutation
across range of
parameter

Description
The offset cauchy mutator introduces random variation by adding a Cauchy random amount to a variable
value. The random amount has a standard deviation dependent on the mutation scale.
mutation scale
Keywords Area
method
moga
mutation type
offset cauchy

724

CHAPTER 6. KEYWORDS AREA

mutation scale
Scales mutation across range of parameter

Specification
Alias: none
Argument(s): REAL
Default: 0.15

Description
The mutation scale is a fraction in the range [0, 1] and is meant to help control the amount of variation that takes
place when a variable is mutated. Its behavior depends on the selected mutation type. For offset normal
and offset cauchy, mutation scale is multipled by the range of the variable being mutated to obtain the
standard deviation of the offset. For offset uniform, the range of possible deviation amounts is +/- 1/2
(mutation scale variable range).
offset uniform
Keywords Area
method
moga
mutation type
offset uniform
Set mutation offset to use a uniform distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mutation scale

Dakota Keyword
Description
Scales mutation
across range of
parameter

Description
The offset uniform mutator introduces random variation by adding a uniform random amount to a variable
value. The random amount depends on the mutation scale.

6.2. METHOD

725

mutation scale
Keywords Area
method
moga
mutation type
offset uniform
mutation scale
Scales mutation across range of parameter

Specification
Alias: none
Argument(s): REAL
Default: 0.15

Description
The mutation scale is a fraction in the range [0, 1] and is meant to help control the amount of variation that takes
place when a variable is mutated. Its behavior depends on the selected mutation type. For offset normal
and offset cauchy, mutation scale is multipled by the range of the variable being mutated to obtain the
standard deviation of the offset. For offset uniform, the range of possible deviation amounts is +/- 1/2
(mutation scale variable range).
mutation rate
Keywords Area
method
moga
mutation type
mutation rate
Set probability of a mutation

Specification
Alias: none
Argument(s): REAL
Default: 0.08

Description
All mutation types have a mutation rate, which controls the number of mutations performed. For replaceuniform and all the offset types, the number of mutations performed is the product of mutation rate and population size. For bit random, its the product of the mutation rate, number of design
variables, and population size

726

CHAPTER 6. KEYWORDS AREA

seed
Keywords Area
method
moga
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

convergence tolerance
Keywords Area
method
moga
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

6.2. METHOD

727

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
model pointer
Keywords Area
method
moga
model pointer
Identifier for model block to be used by a method

728

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single

6.2. METHOD

729

interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.33

soga

Keywords Area
method
soga
Single-objective Genetic Algorithm (a.k.a Evolutionary Algorithm)

Topics
This keyword is related to the topics:
package jega
global optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
fitness type

replacement type

Dakota Keyword
Description
Select the fitness
type for JEGA
methods
Select a
replacement type
for JEGA methods

730

CHAPTER 6. KEYWORDS AREA

Optional

convergence type

Optional

max iterations

Optional

linear inequality constraint matrix

Optional

linear inequality lower bounds

Optional

linear inequality upper bounds

Optional

linear inequality scale types

Optional

linear inequality scales

Optional

linear equality constraint matrix

Optional

linear equality targets

Optional

linear equality scale types

Optional

linear equality scales

Optional

max function evaluations

Select the
convergence type
for JEGA methods
Stopping criterion
based on number
of iterations
Define coefficients
of the linear
inequality
constraints
Define lower
bounds for the
linear inequality
constraint
Define upper
bounds for the
linear inequality
constraint
Specify how each
linear inequality
constraint is scaled
Define the
characteristic
values to scale
linear inequalities
Define coefficients
of the linear
equalities
Define target
values for the
linear equality
constraints
Specify how each
linear equality
constraint is scaled
Define the
characteristic
values to scale
linear equalities
Stopping criteria
based on number
of function
evaluations

6.2. METHOD

731
Optional

scaling

Optional

population size

Optional

log file

Optional

print each pop

Optional

initialization type

Optional

crossover type

Optional

mutation type

Optional

seed

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

model pointer

Identifier for
model block to be
used by a method

Turn on scaling for

variables,
responses, and
constraints
Set the initial
population size in
JEGA methods
Specify the name
of a log file
Print every
population to a
population file
Specify how to
initialize the
population
Select a crossover
type for JEGA
methods
Select a mutation
type for JEGA
methods
Seed of the random
number generator

Description
soga stands for Single-objective Genetic Algorithm, which is a global optimization method that supports general
constraints and a mixture of real and discrete variables. soga is part of the JEGA library.
Constraints soga can utilize linear constraints.
Configuration
The genetic algorithm configurations are:
1. fitness
2. replacement
3. convergence
4. initialization
5. crossover

732

CHAPTER 6. KEYWORDS AREA

6. mutation
7. population size
The pool of potential members is the current population and the current set of offspring. Choice of fitness
assessors is strongly related to the type of replacement algorithm being used and can have a profound effect on
the solutions selected for the next generation.
Stopping Criteria
The soga method respects the max iterations and max function evaluations method independent controls to provide integer limits for the maximum number of generations and function evaluations, respectively.
The algorithm also stops when convergence is reached. This involves repeated assessment of the algorithms
progress in solving the problem, until some criterion is met.
Outputs The soga method respects the output method independent control to vary the amount of information presented to the user during execution.
The final results are written to the Dakota tabular output. Additional information is also available - see the
log file and print each pop keywords.

Theory
The basic steps of the soga algorithm are as follows:
1. Initialize the population
2. Evaluate the population (calculate the values of the objective function and constraints for each population
member)
3. Loop until converged, or stopping criteria reached
(a) Perform crossover
(b) Perform mutation
(c) Evaluate the new population
(d) Assess the fitness of each member in the population
(e) Replace the population with members selected to continue in the next generation
(f) Test for convergence

See Also
These keywords may also be of interest:
moga
fitness type
Keywords Area
method
soga
fitness type
Select the fitness type for JEGA methods

6.2. METHOD

733

Specification
Alias: none
Argument(s): none
Default: merit function
Required/Optional
Required

Optional

Description of
Group

Dakota Keyword
merit function

constraint penalty

Dakota Keyword
Description
Balance goals of
reducing objective
function and
satisfying
constraints
Multiplier for the
penalty function

Description
The two JEGA methods use different fitness types, which are described on their respective pages.
merit function
Keywords Area
method
soga
fitness type
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.
constraint penalty
Keywords Area
method
soga
fitness type
constraint penalty
Multiplier for the penalty function

734

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: 1.0

Description
The merit function fitness assessor uses an exterior penalty function formulation to penalize infeasible designs. The specification allows the input of a constraint penalty which is the multiplier to use on the
constraint violations.
replacement type
Keywords Area
method
soga
replacement type
Select a replacement type for JEGA methods

Specification
Alias: none
Argument(s): none
Default: elitist
Required/Optional

Description of
Group

Dakota Keyword
elitist

Required(Choose
One)

Group 1
favor feasible
roulette wheel
unique roulette wheel

Dakota Keyword
Description
Use the best
designs to form a
new population
Prioritize feasible
designs
Replace population
Replace population

Description
Replace the population with members selected to continue in the next generation. The pool of potential members
is the current population and the current set of offspring. The replacement type of roulette wheel or
unique roulette wheel may be used either with MOGA or SOGA problems however they are not recommended for use with MOGA. Given that the only two fitness assessors for MOGA are the layer rank and
domination count, the recommended selector is the below limit selector. The below limit replacement will only keep designs that are dominated by fewer than a limiting number of other designs.
In roulette wheel replacement, each design is conceptually allotted a portion of a wheel proportional to
its fitness relative to the fitnesses of the other Designs. Then, portions of the wheel are chosen at random and the
design occupying those portions are duplicated into the next population. Those Designs allotted larger portions
of the wheel are more likely to be selected (potentially many times). unique roulette wheel replacement

6.2. METHOD

735

is the same as roulette wheel replacement, with the exception that a design may only be selected once. The
below limit selector attempts to keep all designs for which the negated fitness is below a certain limit. The
values are negated to keep with the convention that higher fitness is better. The inputs to the below limit
selector are the limit as a real value, and a shrinkage percentage as a real value. The shrinkage percentage defines the minimum amount of selections that will take place if enough designs are available. It
is interpreted as a percentage of the population size that must go on to the subsequent generation. To enforce this,
below limit makes all the selections it would make anyway and if that is not enough, it takes the remaining
that it needs from the best of what is left (effectively raising its limit as far as it must to get the minimum number
of selections). It continues until it has made enough selections. The shrinkage percentage is designed to
prevent extreme decreases in the population size at any given generation, and thus prevent a big loss of genetic
diversity in a very short time. Without a shrinkage limit, a small group of super designs may appear and quickly
cull the population down to a size on the order of the limiting value. In this case, all the diversity of the population
is lost and it is expensive to re-diversify and spread the population. The
The replacement type for a SOGA may be roulette wheel, unique roulette wheel, elitist,
or favor feasible. The elitist selector simply chooses the required number of designs taking the most
fit. For example, if 100 selections are requested, then the top 100 designs as ranked by fitness will be selected
and the remaining will be discarded. The favor feasible replacement type first considers feasibility as a
selection criteria. If that does not produce a winner then it moves on to considering fitness value. Because of
this, any fitness assessor used with the favor feasible selector must only account objectives in the creation
of fitness. Therefore, there is such a fitness assessor and its use is enforced when the favor feasible selector
is chosen. In that case, and if the output level is set high enough, a message will be presented indicating that the
weighted sum only fitness assessor will be used.
elitist
Keywords Area
method
soga
replacement type
elitist
Use the best designs to form a new population

Specification
Alias: none
Argument(s): none

Description
The elitist (default) setting creates a new population using (a) the replacement size best individuals
from the current population, (b) and population size - replacement size individuals randomly selected
from the newly generated individuals. It is possible in this case to lose a good solution from the newly generated
individuals if it is not randomly selected for replacement; however, the default new solutions generated
value is set such that the entire set of newly generated individuals will be selected for replacement.

736

CHAPTER 6. KEYWORDS AREA

favor feasible
Keywords Area
method
soga
replacement type
favor feasible
Prioritize feasible designs

Specification
Alias: none
Argument(s): none

Description
This replacement operator will always prefer a more feasible design to a less feasible one. Beyond that, it favors
solutions based on an assigned fitness value which must have been installed by the weighted sum only fitness
assessor.
The favor feasible replacement type first considers feasibility as a selection criteria. If that does not
produce a winner then it moves on to considering fitness value. Because of this, any fitness assessor used with
the favor feasible selector must only account objectives in the creation of fitness. Therefore, there is such
a fitness assessor and its use is enforced when the favor feasible selector is chosen. In that case, and if the
output level is set high enough, a message will be presented indicating that the weighted sum only fitness
assessor will be used.
roulette wheel
Keywords Area
method
soga
replacement type
roulette wheel
Replace population

Specification
Alias: none
Argument(s): none

6.2. METHOD

737

Description
Replace the population with members selected to continue in the next generation. The pool of potential members
is the current population and the current set of offspring. The replacement type of roulette wheel
or unique roulette wheel may be used either with MOGA or SOGA problems however they are not recommended for use with MOGA. Given that the only two fitness assessors for MOGA are the layer rank
and domination count, the recommended selector is the below limit selector. The below limit replacement will only keep designs that are dominated by fewer than a limiting number of other designs. The
replacement type of favor feasible is specific to a SOGA. This replacement operator will always prefer a more feasible design to a less feasible one. Beyond that, it favors solutions based on an assigned fitness value
which must have been installed by the weighted sum only fitness assessor (see the discussion below).
unique roulette wheel
Keywords Area
method
soga
replacement type
unique roulette wheel
Replace population

Specification
Alias: none
Argument(s): none

Description
Replace the population with members selected to continue in the next generation. The pool of potential members
is the current population and the current set of offspring. The replacement type of roulette wheel
or unique roulette wheel may be used either with MOGA or SOGA problems however they are not recommended for use with MOGA. Given that the only two fitness assessors for MOGA are the layer rank
and domination count, the recommended selector is the below limit selector. The below limit replacement will only keep designs that are dominated by fewer than a limiting number of other designs. The
replacement type of favor feasible is specific to a SOGA. This replacement operator will always prefer a more feasible design to a less feasible one. Beyond that, it favors solutions based on an assigned fitness value
which must have been installed by the weighted sum only fitness assessor (see the discussion below).
convergence type
Keywords Area
method
soga
convergence type
Select the convergence type for JEGA methods

738

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: average fitness tracker
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
best fitness tracker

average fitness tracker

Dakota Keyword
Description
Tracks the best
fitness of the
population
Tracks the average
fitness of the
population

Description
The two JEGA methods use different convergence types, which are described on their respective pages.
All the convergence types are modified by the optional keywords percent change and num generations.

best fitness tracker

Keywords Area
method
soga
convergence type
best fitness tracker
Tracks the best fitness of the population

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
percent change

num generations

Dakota Keyword
Description
Define the
convergence
criterion for JEGA
methods
Define the
convergence
criterion for JEGA
methods

Description
The best fitness tracker tracks the best fitness in the population. Convergence occurs after num generations has passed and there has been less than percent change in the best fitness value. The percent
change can be as low as 0% in which case there must be no change at all over the number of generations.

6.2. METHOD

739

See Also
These keywords may also be of interest:
average fitness tracker
percent change
Keywords Area
method
soga
convergence type
best fitness tracker
percent change
Define the convergence criterion for JEGA methods

Specification
Alias: none
Argument(s): REAL
Default: 0.1

Description
The percent change is the threshold beneath which convergence is attained whereby it is compared to the
metric value computed.
num generations
Keywords Area
method
soga
convergence type
best fitness tracker
num generations
Define the convergence criterion for JEGA methods

Specification
Alias: none
Argument(s): INTEGER
Default: 10

740

CHAPTER 6. KEYWORDS AREA

Description
The num generations is the number of generations over which the metric value should be tracked. Convergence will be attained if the recorded metric is below percent change for num generations consecutive
generations.
average fitness tracker
Keywords Area
method
soga
convergence type
average fitness tracker
Tracks the average fitness of the population

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
percent change

num generations

Dakota Keyword
Description
Define the
convergence
criterion for JEGA
methods
Define the
convergence
criterion for JEGA
methods

Description
The convergence type called average fitness tracker keeps track of the average fitness in a population. If this average fitness does not change more than percent change over some number of generations,
num generations, then the solution is reported as converged and the algorithm terminates.

See Also
These keywords may also be of interest:
best fitness tracker
percent change
Keywords Area
method
soga

6.2. METHOD

741

convergence type
average fitness tracker
percent change
Define the convergence criterion for JEGA methods

Specification
Alias: none
Argument(s): REAL
Default: 0.1

Description
The percent change is the threshold beneath which convergence is attained whereby it is compared to the
metric value computed.
num generations
Keywords Area
method
soga
convergence type
average fitness tracker
num generations
Define the convergence criterion for JEGA methods

Specification
Alias: none
Argument(s): INTEGER
Default: 10

Description
The num generations is the number of generations over which the metric value should be tracked. Convergence will be attained if the recorded metric is below percent change for num generations consecutive
generations.
max iterations
Keywords Area
method
soga
max iterations
Stopping criterion based on number of iterations

742

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
linear inequality constraint matrix
Keywords Area
method
soga
linear inequality constraint matrix
Define coefficients of the linear inequality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear inequality constraints

Description
In the inequality case, the constraint matrix A provides coefficients for the variables in the two-sided formulation:
al Ax au
Where the bounds are optionally specified by linear inequality lower bounds, and linear inequality upper bounds. The bounds, if not specified, will default to -infinity, and 0, respectively, resulting in one-sided inequalities of the form
Ax 0.0
.

6.2. METHOD

743

linear inequality lower bounds

Keywords Area
method
soga
linear inequality lower bounds
Define lower bounds for the linear inequality constraint

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = -infinity

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality upper bounds
Keywords Area
method
soga
linear inequality upper bounds
Define upper bounds for the linear inequality constraint

744

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the inequality case, the lower al and upper au bounds provide constraint limits for the two-sided formulation:
al Ax au
Where A is the constrain matrix of variable coefficients.
As with nonlinear inequality constraints (see objective functions), the default linear inequality constraint
bounds are selected so that one-sided inequalities of the form
Ax 0.0
result when there are no user bounds specifications (this provides backwards compatibility with previous Dakota
versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize are
treated as -infinity.
This feature is commonly used to drop one of the bounds in order to specify a 1-sided constraint (just as the
default lower bounds drop out since -DBL MAX < -bigRealBoundSize).
linear inequality scale types
Keywords Area
method
soga
linear inequality scale types
Specify how each linear inequality constraint is scaled

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

6.2. METHOD

745

Description
linear inequality scale types provide strings specifying the scaling type for each linear inequality
constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear inequality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear inequality scales
Keywords Area
method
soga
linear inequality scales
Define the characteristic values to scale linear inequalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

746

CHAPTER 6. KEYWORDS AREA

Description
Each entry in linear inequality scales may be a user-specified, nonzero characteristic value to be used
in scaling each constraint.
Behavior depends on the choice of linear inequality scale type :
scale type - behavior of linear inequality scales
none - ignored
value - required
auto - optional
If a single real value is specified it will apply to all components of the constraint.
Scaling for linear constraints is applied after any continuous variable scaling. For example, for variable scaling
on continuous design variables x:
xj xjO
x
j =
xjM
we have the following system for linear inequality constraints
aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO

a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality constraint matrix
Keywords Area
method
soga
linear equality constraint matrix
Define coefficients of the linear equalities

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: no linear equality constraints

6.2. METHOD

747

Description
In the equality case, the constraint matrix A provides coefficients for the variables on the left hand side of:
Ax = at

linear equality targets

Keywords Area
method
soga
linear equality targets
Define target values for the linear equality constraints

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 0 .

Description
In the equality case, the targets at provide the equality constraint right hand sides:
Ax = at
.
If this is not specified, the defaults for the equality constraint targets enforce a value of 0. for each constraint:
Ax = 0.0
linear equality scale types
Keywords Area
method
soga
linear equality scale types
Specify how each linear equality constraint is scaled

748

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = none

Description
linear equality scale types provide strings specifying the scaling type for each linear equality constraint, in methods that support scaling.
An entry may be selected for each constraint. The options are:
none - no scaling
value - characteristic value if this is chosen, then linear equality scales must be specified
auto - automatic scaling If a single string is specified it will apply to all constraints.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear equality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
linear equality scales
Keywords Area
method
soga
linear equality scales
Define the characteristic values to scale linear equalities

6.2. METHOD

749

Topics
This keyword is related to the topics:
linear constraints

Specification
Alias: none
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
Each entry in linear equality scales may be a user-specified, nonzero characteristic value to be used in
scaling each constraint.
See the scaling keyword in the method section for details on how to use this keyword.
Scaling for linear constraints is applied after any continuous variable scaling.
For example, for variable scaling on continuous design variables x:
x
j =

xj xjO
xjM

we have the following system for linear inequality constraints

aL Ai x aU
aL Ai (diag(xM )
x + xO ) aU
aL Ai xO Ai diag(xM )
x aU Ai xO
a
L Ai x
a
U
and user-specified or automatically computed scaling multipliers are appplied to this final transformed system,
which accounts for continuous design variable scaling. When automatic scaling is in use for linear constraints
they are linearly scaled by a computed characteristic value, but not affinely to [0,1].
max function evaluations
Keywords Area
method
soga
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

750

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
soga
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values

6.2. METHOD

751

The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

752

CHAPTER 6. KEYWORDS AREA

population size
Keywords Area
method
soga
population size
Set the initial population size in JEGA methods

Specification
Alias: none
Argument(s): INTEGER
Default: 50

Description
The number of designs in the initial population is specified by the population size. Note that the populationsize only sets the size of the initial population. The population size may vary in the JEGA methods according
to the type of operators chosen for a particular optimization run.
log file
Keywords Area
method
soga
log file
Specify the name of a log file

Specification
Alias: none
Argument(s): STRING
Default: JEGAGlobal.log

Description
New as of JEGA v2.0 is the introduction of the log file specification. JEGA now uses a logging library to
output messages and status to the user. JEGA can be configured at build time to log to both the console window
and a text file, one or the other, or neither. The log file input is a string name of a file into which to log. If
the build was configured without file logging in JEGA, this input is ignored. If file logging is enabled and no
log file is specified, the default file name of JEGAGlobal.log is used.

6.2. METHOD

753

print each pop

Keywords Area
method
soga
print each pop
Print every population to a population file

Specification
Alias: none
Argument(s): none
Default: No printing

Description
New to JEGA v2.0 is the introduction of the print each pop specification. It serves as a flag and if supplied,
the population at each generation will be printed to a file named population<GEN#>.dat where <GEN#> is
the number of the current generation.
initialization type
Keywords Area
method
soga
initialization type
Specify how to initialize the population

Specification
Alias: none
Argument(s): none
Default: unique random
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
simple random

Group 1
unique random

Dakota Keyword
Description
Create random
initial solutions
Create random
initial solutions,
but enforce
uniqueness
(default)

754

CHAPTER 6. KEYWORDS AREA

flat file

Read initial
solutions from file

Description
The initialization type defines how the initial population is created for the GA. There are three types:
1. simple random
2. unique random (default)
3. flat file
Setting the size for the flat file initializer has the effect of requiring a minimum number of designs to
create. If this minimum number has not been created once the files are all read, the rest are created using the
unique random initializer and then the simple random initializer if necessary.
simple random
Keywords Area
method
soga
initialization type
simple random
Create random initial solutions

Specification
Alias: none
Argument(s): none

Description
simple random creates initial solutions with random variable values according to a uniform random number
distribution. It gives no consideration to any previously generated designs.
unique random
Keywords Area
method
soga
initialization type
unique random
Create random initial solutions, but enforce uniqueness (default)

6.2. METHOD

755

Specification
Alias: none
Argument(s): none

Description
unique random is the same as simple random, except that when a new solution is generated, it is checked
against the rest of the solutions. If it duplicates any of them, it is rejected.
flat file
Keywords Area
method
soga
initialization type
flat file
Read initial solutions from file

Specification
Alias: none
Argument(s): STRING

Description
flat file allows the initial population to be read from a flat file. If flat file is specified, a file name must
be given.
Variables can be delimited in the flat file in any way you see fit with a few exceptions. The delimiter must be
the same on any given line of input with the exception of leading and trailing whitespace. So a line could look
like: 1.1, 2.2 ,3.3 for example but could not look like: 1.1, 2.2 3.3. The delimiter can vary from line to line within
the file which can be useful if data from multiple sources is pasted into the same input file. The delimiter can be
any string that does not contain any of the characters .+-dDeE or any of the digits 0-9. The input will be read until
the end of the file. The algorithm will discard any configurations for which it was unable to retrieve at least the
number of design variables. The objective and constraint entries are not required but if ALL are present, they will
be recorded and the design will be tagged as evaluated so that evaluators may choose not to re-evaluate them.
Setting the size for this initializer has the effect of requiring a minimum number of designs to create. If this
minimum number has not been created once the files are all read, the rest are created using the unique random
initializer and then the simple random initializer if necessary.
crossover type
Keywords Area
method
soga
crossover type
Select a crossover type for JEGA methods

756

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: shuffle random
Required/Optional

Description of
Group

Dakota Keyword
multi point binary

Required(Choose
One)

Group 1
multi point parameterized binary
multi point real

shuffle random

Optional

crossover rate

Dakota Keyword
Description
Use bit switching
for crossover
events
Use bit switching
to crossover each
design variable
Perform crossover
in real valued
genome
Perform crossover
by choosing design
variable(s)
Specify the
probability of a
crossover event

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.
The final crossover type is shuffle random. This crossover type performs crossover by choosing design
variables at random from a specified number of parents enough times that the requested number of children are
produced. For example, consider the case of 3 parents producing 2 children. This operator would go through and
for each design variable, select one of the parents as the donor for the child. So it creates a random shuffle of the
parent design variable values. The relative numbers of children and parents are controllable to allow for as much
mixing as desired. The more parents involved, the less likely that the children will wind up exact duplicates of the
parents.
All crossover types take a crossover rate. The crossover rate is used to calculate the number of crossover
operations that take place. The number of crossovers is equal to the rate population size.
multi point binary
Keywords Area

6.2. METHOD

757

method
soga
crossover type
multi point binary
Use bit switching for crossover events

Specification
Alias: none
Argument(s): INTEGER

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.
multi point parameterized binary
Keywords Area
method
soga
crossover type
multi point parameterized binary
Use bit switching to crossover each design variable

Specification
Alias: none
Argument(s): INTEGER

758

CHAPTER 6. KEYWORDS AREA

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.
multi point real
Keywords Area
method
soga
crossover type
multi point real
Perform crossover in real valued genome

Specification
Alias: none
Argument(s): INTEGER

Description
There are many crossover types available. multi point binary crossover requires an integer number, N, of
crossover points. This crossover type performs a bit switching crossover at N crossover points in the binary encoded genome of two designs. Thus, crossover may occur at any point along a solution chromosome (in the middle
of a gene representing a design variable, for example). multi point parameterized binary crossover
is similar in that it performs a bit switching crossover routine at N crossover points. However, this crossover
type performs crossover on each design variable individually. So the individual chromosomes are crossed at N
locations. multi point real crossover performs a variable switching crossover routing at N crossover points
in the real real valued genome of two designs. In this scheme, crossover only occurs between design variables
(chromosomes). Note that the standard solution chromosome representation in the JEGA algorithm is real encoded and can handle integer or real design variables. For any crossover types that use a binary representation,
real variables are converted to long integers by multiplying the real number by 10 6 and then truncating. Note
that this assumes a precision of only six decimal places. Discrete variables are represented as integers (indices
within a list of possible values) within the algorithm and thus require no special treatment by the binary operators.

6.2. METHOD

759

shuffle random
Keywords Area
method
soga
crossover type
shuffle random
Perform crossover by choosing design variable(s)

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
num parents

num offspring

Dakota Keyword
Description
Number of parents
in random shuffle
crossover
Number of
offspring in
random shuffle
crossover

Description
The final crossover type is shuffle random. This crossover type performs crossover by choosing design
variables at random from a specified number of parents enough times that the requested number of children are
produced. For example, consider the case of 3 parents producing 2 children. This operator would go through and
for each design variable, select one of the parents as the donor for the child. So it creates a random shuffle of the
parent design variable values. The relative numbers of children and parents are controllable to allow for as much
mixing as desired. The more parents involved, the less likely that the children will wind up exact duplicates of the
parents.
num parents
Keywords Area
method
soga
crossover type
shuffle random
num parents
Number of parents in random shuffle crossover

760

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 2

Description
Number of parents in random shuffle crossover
num offspring
Keywords Area
method
soga
crossover type
shuffle random
num offspring
Number of offspring in random shuffle crossover

Specification
Alias: none
Argument(s): INTEGER
Default: 2

Description
Number of offspring in random shuffle crossover
crossover rate
Keywords Area
method
soga
crossover type
crossover rate
Specify the probability of a crossover event

Specification
Alias: none
Argument(s): REAL
Default: 0.8

6.2. METHOD

761

Description
The crossover type controls what approach is employed for combining parent genetic information to create offspring, and the crossover rate specifies the probability of a crossover operation being performed to
generate a new offspring. The SCOLIB EA method supports three forms of crossover, two point, blend, and
uniform, which generate a new individual through combinations of two parent individuals. Two-point crossover
divides each parent into three regions, where offspring are created from the combination of the middle region from
one parent and the end regions from the other parent. Since the SCOLIB EA does not utilize bit representations
of variable values, the crossover points only occur on coordinate boundaries, never within the bits of a particular
coordinate. Uniform crossover creates offspring through random combination of coordinates from the two parents. Blend crossover generates a new individual randomly along the multidimensional vector connecting the two
parents.
mutation type
Keywords Area
method
soga
mutation type
Select a mutation type for JEGA methods

Specification
Alias: none
Argument(s): none
Default: replace uniform
Required/Optional

Description of
Group

Dakota Keyword
bit random

Required(Choose
One)

Group 1

replace uniform

offset normal

offset cauchy

offset uniform

Dakota Keyword
Description
Mutate by flipping
a random bit
Use uniformly
distributed value
over range of
parameter
Set mutation offset
to use a normal
distribution
Use a Cauchy
distribution for the
mutation offset
Set mutation offset
to use a uniform
distribution

762

CHAPTER 6. KEYWORDS AREA

Optional

mutation rate

Set probability of a
mutation

Description
Five mutation types are available for selection by keyword: replace uniform, bit random, offset cauchy, offset normal, and offset uniform. They are described in greater detail on their respective
keyword pages.
The offset mutators all act by adding a random offset to a variable value. The random amount has a
mean of zero in all cases. The size of the offset is controlled using the mutation scale keyword, which is
interpreted differently for each offset type.
The rate of mutations for all types is controlled suing the mutation rate. The rate is applied differently
in each mutation type.
bit random
Keywords Area
method
soga
mutation type
bit random
Mutate by flipping a random bit

Specification
Alias: none
Argument(s): none

Description
The bit random mutator introduces random variation by first converting a randomly chosen variable of a randomly chosen design into a binary string. It then flips a randomly chosen bit in the string from a 1 to a 0 or visa
versa. In this mutation scheme, the resulting value has more probability of being similar to the original value.
replace uniform
Keywords Area
method
soga
mutation type
replace uniform
Use uniformly distributed value over range of parameter

6.2. METHOD

763

Specification
Alias: none
Argument(s): none

Description
replace uniform introduces random variation by first randomly choosing a design variable of a randomly
selected design and reassigning it to a random valid value for that variable. No consideration of the current value
is given when determining the new value.
offset normal
Keywords Area
method
soga
mutation type
offset normal
Set mutation offset to use a normal distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mutation scale

Dakota Keyword
Description
Scales mutation
across range of
parameter

Description
The offset normal mutator introduces random variation by adding a Gaussian random amount to a variable
value. The random amount has a standard deviation dependent on the mutation scale.
mutation scale
Keywords Area
method
soga
mutation type
offset normal
mutation scale
Scales mutation across range of parameter

764

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: 0.15

Description
The mutation scale is a fraction in the range [0, 1] and is meant to help control the amount of variation that takes
place when a variable is mutated. Its behavior depends on the selected mutation type. For offset normal
and offset cauchy, mutation scale is multipled by the range of the variable being mutated to obtain the
standard deviation of the offset. For offset uniform, the range of possible deviation amounts is +/- 1/2
(mutation scale variable range).
offset cauchy
Keywords Area
method
soga
mutation type
offset cauchy
Use a Cauchy distribution for the mutation offset

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mutation scale

Dakota Keyword
Description
Scales mutation
across range of
parameter

Description
The offset cauchy mutator introduces random variation by adding a Cauchy random amount to a variable
value. The random amount has a standard deviation dependent on the mutation scale.
mutation scale
Keywords Area
method
soga
mutation type
offset cauchy

6.2. METHOD

765

mutation scale
Scales mutation across range of parameter

Specification
Alias: none
Argument(s): REAL
Default: 0.15

Description
The mutation scale is a fraction in the range [0, 1] and is meant to help control the amount of variation that takes
place when a variable is mutated. Its behavior depends on the selected mutation type. For offset normal
and offset cauchy, mutation scale is multipled by the range of the variable being mutated to obtain the
standard deviation of the offset. For offset uniform, the range of possible deviation amounts is +/- 1/2
(mutation scale variable range).
offset uniform
Keywords Area
method
soga
mutation type
offset uniform
Set mutation offset to use a uniform distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mutation scale

Dakota Keyword
Description
Scales mutation
across range of
parameter

Description
The offset uniform mutator introduces random variation by adding a uniform random amount to a variable
value. The random amount depends on the mutation scale.

766

CHAPTER 6. KEYWORDS AREA

mutation scale
Keywords Area
method
soga
mutation type
offset uniform
mutation scale
Scales mutation across range of parameter

Specification
Alias: none
Argument(s): REAL
Default: 0.15

Description
The mutation scale is a fraction in the range [0, 1] and is meant to help control the amount of variation that takes
place when a variable is mutated. Its behavior depends on the selected mutation type. For offset normal
and offset cauchy, mutation scale is multipled by the range of the variable being mutated to obtain the
standard deviation of the offset. For offset uniform, the range of possible deviation amounts is +/- 1/2
(mutation scale variable range).
mutation rate
Keywords Area
method
soga
mutation type
mutation rate
Set probability of a mutation

Specification
Alias: none
Argument(s): REAL
Default: 0.08

Description
All mutation types have a mutation rate, which controls the number of mutations performed. For replaceuniform and all the offset types, the number of mutations performed is the product of mutation rate and population size. For bit random, its the product of the mutation rate, number of design
variables, and population size

6.2. METHOD

767

seed
Keywords Area
method
soga
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

convergence tolerance
Keywords Area
method
soga
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

768

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
model pointer
Keywords Area
method
soga
model pointer
Identifier for model block to be used by a method

6.2. METHOD

769

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single

770

CHAPTER 6. KEYWORDS AREA

interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.34

coliny pattern search

Keywords Area
method
coliny pattern search
Pattern search, derivative free optimization method

Topics
This keyword is related to the topics:
package scolib
package coliny
global optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
constant penalty

Dakota Keyword
Description
Use a simple
weighted penalty
to manage
feasibility

6.2. METHOD

771
Optional

no expansion

Optional

expand after success

Optional

pattern basis

Optional

stochastic

Optional

total pattern size

Optional

exploratory moves

Optional

synchronization

Optional

contraction factor

Optional

constraint penalty

Optional

initial delta

Optional

threshold delta

Optional

solution target

Optional

seed

Optional

show misc options

Dont allow
expansion of the
search pattern
Set the factor by
which a search
pattern can be
expanded
Pattern basis
selection
Generate trial
points in random
order
Total number of
points in search
pattern
Exploratory moves
selection
Select how Dakota
schedules function
evaluations in a
pattern search
Amount by which
step length is
rescaled
Multiplier for the
penalty function
Initial step size for
non-gradient based
optimizers
Stopping criteria
based on step
length or pattern
size
Stopping criteria
based on objective
function value
Seed of the random
number generator
Show algorithm
parameters not
exposed in Dakota
input

772

CHAPTER 6. KEYWORDS AREA

Optional

misc options

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Set method options

not available
through Dakota
spec
Stopping criterion
based on number
of iterations

Description
Pattern search techniques are nongradient-based optimization methods which use a set of offsets from the current
iterate to locate improved points in the design space.
See the page package scolib for important information regarding all SCOLIB methods
coliny pattern search supports concurrency up to the size of the search pattern
Traditional pattern search methods search with a fixed pattern of search directions to try to find improvements to the current iterate. The SCOLIB pattern search methods generalize this simple algorithmic strategy
to enable control of how the search pattern is adapted, as well as how each search pattern is evaluated. The
stochastic and synchronization specifications denote how the the trial points are evaluated. The
stochastic specification indicates that the trial points are considered in a random order. For parallel pattern search, synchronization dictates whether the evaluations are scheduled using a blocking scheduler
or a nonblocking scheduler. In the blocking case, all points in the pattern are evaluated (in parallel), and if
the best of these trial points is an improving point, then it becomes the next iterate. These runs are reproducible,
assuming use of the same seed in the stochastic case. In the nonblocking case, all points in the pattern
may not be evaluated, since the first improving point found becomes the next iterate. Since the algorithm steps will
be subject to parallel timing variabilities, these runs will not generally be repeatable. The synchronization
specification has similar connotations for sequential pattern search. If blocking is specified, then each sequential iteration terminates after all trial points have been considered, and if nonblocking is specified, then each
sequential iteration terminates after the first improving trial point is evaluated. In this release, both blocking
and nonblocking specifications result in blocking behavior (except in the case where exporatory moves
below is set to adaptive pattern). Nonblocking behavior will be re-enabled after some underlying technical
issues have been resolved.

6.2. METHOD

773

The particular form of the search pattern is controlled by the pattern basis specification. If patternbasis is coordinate basis, then the pattern search uses a plus and minus offset in each coordinate direction,
for a total of 2n function evaluations in the pattern. This case is depicted in Figure 5.3 for three coordinate
dimensions.

Figure 6.1: Depiction of coordinate pattern search algorithm

If pattern basis is simplex, then pattern search uses a minimal positive basis simplex for the parameter
space, for a total of n+1 function evaluations in the pattern. Note that the simplex pattern basis can be used
for unbounded problems only. The total pattern size specification can be used to augment the basic
coordinate and simplex patterns with additional function evaluations, and is particularly useful for parallel
load balancing. For example, if some function evaluations in the pattern are dropped due to duplication or bound
constraint interaction, then the total pattern size specification instructs the algorithm to generate new
offsets to bring the total number of evaluations up to this consistent total.
The exploratory moves specification controls how the search pattern is adapted. (The search pattern can
be adapted after an improving trial point is found, or after all trial points in a search pattern have been found to be
unimproving points.) The following exploratory moves selections are supported by SCOLIB:
The basic pattern case is the simple pattern search approach, which uses the same pattern in each
iteration.
The multi step case examines each trial step in the pattern in turn. If a successful step is found, the
pattern search continues examining trial steps about this new point. In this manner, the effects of multiple

774

CHAPTER 6. KEYWORDS AREA

successful steps are cumulative within a single iteration. This option does not support any parallelism and
will result in a serial pattern search.
The adaptive pattern case invokes a pattern search technique that adaptively rescales the different
search directions to maximize the number of redundant function evaluations. See[45] for details of this
method. In preliminary experiments, this method had more robust performance than the standard basicpattern case in serial tests. This option supports a limited degree of parallelism. After successful
iterations (where the step length is not contracted), a parallel search will be performed. After unsuccessful
iterations (where the step length is contracted), only a single evaluation is performed.

The initial delta and threshold delta specifications provide the initial offset size and the threshold
size at which to terminate the algorithm. For any dimension that has both upper and lower bounds, this step length
will be internally rescaled to provide search steps of length initial delta range 0.1. This rescaling does
not occur for other dimensions, so search steps in those directions have length initial delta. Note that the
factor of 0.1 in the rescaling could result in an undesirably small initial step. This can be offset by providing a
large initial delta.
In general, pattern search methods can expand and contract their step lengths. SCOLIB pattern search methods
contract the step length by the value contraction factor, and they expand the step length by the value
(1/contraction factor). The expand after success control specifies how many successful objective function
improvements must occur with a specific step length prior to expansion of the step length, whereas the no expansion flag instructs the algorithm to forgo pattern expansion altogether.
Finally, constraint infeasibility can be managed in a somewhat more sophisticated manner than the simple
weighted penalty function. If the constant penalty specification is used, then the simple weighted penalty
scheme described above is used. Otherwise, the constraint penalty is adapted to the value constraint penalty/L, where L is the the smallest step length used so far.

See Also
These keywords may also be of interest:
coliny beta
coliny direct
coliny cobyla
coliny ea
coliny solis wets
constant penalty
Keywords Area
method
coliny pattern search
constant penalty
Use a simple weighted penalty to manage feasibility

6.2. METHOD

775

Specification
Alias: none
Argument(s): none
Default: algorithm dynamically adapts the constraint penalty

Description
Finally, constraint infeasibility can be managed in a somewhat more sophisticated manner than the simple weighted
penalty function. If the constant penalty specification is used, then the simple weighted penalty scheme
described above is used. Otherwise, the constraint penalty is adapted to the value constraint penalty/L,
where L is the the smallest step length used so far.
no expansion
Keywords Area
method
coliny pattern search
no expansion
Dont allow expansion of the search pattern

Specification
Alias: none
Argument(s): none
Default: algorithm may expand pattern size

Description
In general, pattern search methods can expand and contract their step lengths. SCOLIB pattern search methods
contract the step length by the value contraction factor, and they expand the step length by the value
(1/contraction factor). The expand after success control specifies how many successful objective function
improvements must occur with a specific step length prior to expansion of the step length, whereas the no expansion flag instructs the algorithm to forgo pattern expansion altogether.
expand after success
Keywords Area
method
coliny pattern search
expand after success
Set the factor by which a search pattern can be expanded

776

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 5

Description
In general, pattern search methods can expand and contract their step lengths. SCOLIB pattern search methods
contract the step length by the value contraction factor, and they expand the step length by the value
(1/contraction factor). The expand after success control specifies how many successful objective function
improvements must occur with a specific step length prior to expansion of the step length, whereas the no expansion flag instructs the algorithm to forgo pattern expansion altogether.
pattern basis
Keywords Area
method
coliny pattern search
pattern basis
Pattern basis selection

Specification
Alias: none
Argument(s): none
Default: coordinate
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
coordinate

simplex

Dakota Keyword
Description
Use coordinate
directions as
search pattern
Use a minimal
simplex for the
search pattern

Description
The particular form of the search pattern is controlled by the pattern basis specification. If pattern basis is coordinate basis, then the pattern search uses a plus and minus offset in each coordinate direction,
for a total of 2n function evaluations in the pattern. This case is depicted in Figure 5.3 for three coordinate
dimensions.
coordinate
Keywords Area
method

6.2. METHOD

777

coliny pattern search

pattern basis
coordinate
Use coordinate directions as search pattern

Specification
Alias: none
Argument(s): none

Description
The particular form of the search pattern is controlled by the pattern basis specification. If pattern basis is coordinate basis, then the pattern search uses a plus and minus offset in each coordinate direction,
for a total of 2n function evaluations in the pattern. This case is depicted in Figure 5.3 for three coordinate
dimensions.
simplex
Keywords Area
method
coliny pattern search
pattern basis
simplex
Use a minimal simplex for the search pattern

Specification
Alias: none
Argument(s): none

Description
If pattern basis is simplex, then pattern search uses a minimal positive basis simplex for the parameter
space, for a total of n+1 function evaluations in the pattern. Note that the simplex pattern basis can be used
for unbounded problems only. The total pattern size specification can be used to augment the basic
coordinate and simplex patterns with additional function evaluations, and is particularly useful for parallel
load balancing. For example, if some function evaluations in the pattern are dropped due to duplication or bound
constraint interaction, then the total pattern size specification instructs the algorithm to generate new
offsets to bring the total number of evaluations up to this consistent total.

778

CHAPTER 6. KEYWORDS AREA

stochastic
Keywords Area
method
coliny pattern search
stochastic
Generate trial points in random order

Specification
Alias: none
Argument(s): none

Description
Traditional pattern search methods search with a fixed pattern of search directions to try to find improvements to
the current iterate. The SCOLIB pattern search methods generalize this simple algorithmic strategy to enable control of how the search pattern is adapted, as well as how each search pattern is evaluated. The stochastic and
synchronization specifications denote how the the trial points are evaluated. The stochastic specification indicates that the trial points are considered in a random order. For parallel pattern search, synchronization
dictates whether the evaluations are scheduled using a blocking scheduler or a nonblocking scheduler (i.e.,
total pattern size
Keywords Area
method
coliny pattern search
total pattern size
Total number of points in search pattern

Specification
Alias: none
Argument(s): INTEGER
Default: no augmentation of basic pattern

Description
If pattern basis is simplex, then pattern search uses a minimal positive basis simplex for the parameter
space, for a total of n+1 function evaluations in the pattern. Note that the simplex pattern basis can be used
for unbounded problems only. The total pattern size specification can be used to augment the basic
coordinate and simplex patterns with additional function evaluations, and is particularly useful for parallel
load balancing. For example, if some function evaluations in the pattern are dropped due to duplication or bound
constraint interaction, then the total pattern size specification instructs the algorithm to generate new
offsets to bring the total number of evaluations up to this consistent total.

6.2. METHOD

779

exploratory moves
Keywords Area
method
coliny pattern search
exploratory moves
Exploratory moves selection

Specification
Alias: none
Argument(s): none
Default: basic pattern
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
multi step

Group 1
adaptive pattern
basic pattern

Dakota Keyword
Description
Examine trial step
around successful
new point
Adaptively rescale
search directions
Use the same
search pattern
every iteration

Description
The exploratory moves specification controls how the search pattern is adapted. (The search pattern can be
adapted after an improving trial point is found, or after all trial points in a search pattern have been found to be
unimproving points.) The following exploratory moves selections are supported by SCOLIB:
multi step
Keywords Area
method
coliny pattern search
exploratory moves
multi step
Examine trial step around successful new point

Specification
Alias: none
Argument(s): none

780

CHAPTER 6. KEYWORDS AREA

Description
The multi step case examines each trial step in the pattern in turn. If a successful step is found, the pattern
search continues examining trial steps about this new point. In this manner, the effects of multiple successful steps
are cumulative within a single iteration. This option does not support any parallelism and will result in a serial
pattern
adaptive pattern
Keywords Area
method
coliny pattern search
exploratory moves
adaptive pattern
Adaptively rescale search directions

Specification
Alias: none
Argument(s): none

Description
The adaptive pattern case invokes a pattern search technique that adaptively rescales the different search
directions to maximize the number of redundant function evaluations. See[45] for details of this method. In
preliminary experiments, this method had more robust performance than the standard basic pattern case in
serial tests. This option supports a limited degree of parallelism. After successful iterations (where the step length
is not contracted), a parallel search will be performed. After unsuccessful iterations (where the step length is
contracted), only a single evaluation is performed.
basic pattern
Keywords Area
method
coliny pattern search
exploratory moves
basic pattern
Use the same search pattern every iteration

Specification
Alias: none
Argument(s): none

6.2. METHOD

781

Description
The basic pattern case is the simple pattern search approach, which uses the same pattern in each iteration.
synchronization
Keywords Area
method
coliny pattern search
synchronization
Select how Dakota schedules function evaluations in a pattern search

Specification
Alias: none
Argument(s): none
Default: nonblocking
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
blocking
nonblocking

Dakota Keyword
Description
Evaluate all points
in a pattern
Evaluate points in
the pattern until an
improving point is
found

Description
The synchronization specification can be used to specify the use of either blocking or nonblocking
schedulers.
blocking
Keywords Area
method
coliny pattern search
synchronization
blocking
Evaluate all points in a pattern

Specification
Alias: none
Argument(s): none

782

CHAPTER 6. KEYWORDS AREA

Description
In the blocking case, all points in the pattern are evaluated (in parallel), and if the best of these trial points is
an improving point, then it becomes the next iterate. These runs are reproducible, assuming use of the same seed
in the stochastic case.
nonblocking
Keywords Area
method
coliny pattern search
synchronization
nonblocking
Evaluate points in the pattern until an improving point is found

Specification
Alias: none
Argument(s): none

Description
In the nonblocking case, all points in the pattern may not be evaluated. The first improving point found
becomes the next iterate. Since the algorithm steps will be subject to parallel timing variabilities, these runs will
not generally be repeatable.
contraction factor
Keywords Area
method
coliny pattern search
contraction factor
Amount by which step length is rescaled

Specification
Alias: none
Argument(s): REAL
Default: 0.5

Description
For pattern search methods, contraction factor specifies the amount by which step length is rescaled after
unsuccesful iterates, must be strictly between 0 and 1.
For methods that can expand the step length, the expansion is 1/ contraction factor

6.2. METHOD

783

constraint penalty
Keywords Area
method
coliny pattern search
constraint penalty
Multiplier for the penalty function

Specification
Alias: none
Argument(s): REAL
Default: 1.0

Description
Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty
times the sum of squares of the constraint violations to the objective function. The default value of constraintpenalty is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default
value is 1.0.
initial delta
Keywords Area
method
coliny pattern search
initial delta
Initial step size for non-gradient based optimizers

Specification
Alias: none
Argument(s): REAL
Default: 1.0 (COBYLA), 0.1range (PS, SW)

Description
If initial delta is supplied by the user, it will be applied in an absolute sense in all coordinate directions.
APPS documentation advocates choosing initial delta to be the approximate distance from the initial point
to the solution. If this is unknown, it is advisable to err on the side of choosing an initial delta that is too
large or to not specify it. In the latter case, APPS will take a full step to the boundary in each direction. Relative
application of initial delta is not available unless the user scales the problem accordingly.

784

CHAPTER 6. KEYWORDS AREA

threshold delta
Keywords Area
method
coliny pattern search
threshold delta
Stopping criteria based on step length or pattern size

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-4 (COBYLA), 1.0e-5 (PS), 1.0e-6 (SW)

Description
threshold delta is the step length or pattern size used to determine convergence.
solution target
Keywords Area
method
coliny pattern search
solution target
Stopping criteria based on objective function value

Specification
Alias: solution accuracy
Argument(s): REAL
Default: -DBL MAX

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
seed
Keywords Area
method
coliny pattern search
seed
Seed of the random number generator

6.2. METHOD

785

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

show misc options

Keywords Area
method
coliny pattern search
show misc options
Show algorithm parameters not exposed in Dakota input

Specification
Alias: none
Argument(s): none
Default: no dump of specification options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using

786

CHAPTER 6. KEYWORDS AREA

this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
misc options
Keywords Area
method
coliny pattern search
misc options
Set method options not available through Dakota spec

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
max iterations
Keywords Area
method
coliny pattern search
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

787

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
coliny pattern search
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

788

CHAPTER 6. KEYWORDS AREA

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

max function evaluations

Keywords Area
method
coliny pattern search
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
coliny pattern search
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

789

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.

790

CHAPTER 6. KEYWORDS AREA

Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
coliny pattern search
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

791

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

792

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.35

coliny solis wets

Keywords Area
method
coliny solis wets
Simple greedy local search method

Topics
This keyword is related to the topics:
package scolib
package coliny

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
contract after failure

Optional

no expansion

Optional

expand after success

Optional

constant penalty

Optional

contraction factor

Dakota Keyword
Description
The number of
unsuccessful
cycles prior to
contraction.
Dont allow
expansion of the
search pattern
Set the factor by
which a search
pattern can be
expanded
Use a simple
weighted penalty
to manage
feasibility
Amount by which
step length is
rescaled

6.2. METHOD

793
Optional

constraint penalty

Optional

initial delta

Optional

threshold delta

Optional

solution target

Optional

seed

Optional

show misc options

Optional

misc options

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

scaling

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints

Multiplier for the

penalty function
Initial step size for
non-gradient based
optimizers
Stopping criteria
based on step
length or pattern
size
Stopping criteria
based on objective
function value
Seed of the random
number generator
Show algorithm
parameters not
exposed in Dakota
input
Set method options
not available
through Dakota
spec
Stopping criterion
based on number
of iterations

794

CHAPTER 6. KEYWORDS AREA

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The Solis-Wets method is a simple greedy local search heuristic for continuous parameter spaces. Solis-Wets
generates trial points using a multivariate normal distribution, and unsuccessful trial points are reflected about the
current point to find a descent direction.
See the page package scolib for important information regarding all SCOLIB methods
coliny solis wets is inherently serial, no concurrency is used.
These specifications have the same meaning as corresponding specifications for coliny pattern search. Please
see that page for specification details.
In particular, coliny solis wets supports dynamic rescaling of the step length, and dynamic rescaling of
the constraint penalty. The only new specification is contract after failure, which specifies the number
of unsuccessful cycles which must occur with a specific delta prior to contraction of the delta.

See Also
These keywords may also be of interest:
coliny beta
coliny direct
coliny pattern search
coliny cobyla
coliny ea
contract after failure
Keywords Area
method
coliny solis wets
contract after failure
The number of unsuccessful cycles prior to contraction.

Specification
Alias: none
Argument(s): INTEGER
Default: 4number of variables

Description
In particular, coliny solis wets supports dynamic rescaling of the step length, and dynamic rescaling of the
constraint penalty. The only new specification is contract after failure, which specifies the number of
unsuccessful cycles which must occur with a specific delta prior to contraction of the delta.

6.2. METHOD

795

no expansion
Keywords Area
method
coliny solis wets
no expansion
Dont allow expansion of the search pattern

Specification
Alias: none
Argument(s): none
Default: algorithm may expand pattern size

Description
In general, pattern search methods can expand and contract their step lengths. SCOLIB pattern search methods
contract the step length by the value contraction factor, and they expand the step length by the value
(1/contraction factor). The expand after success control specifies how many successful objective function
improvements must occur with a specific step length prior to expansion of the step length, whereas the no expansion flag instructs the algorithm to forgo pattern expansion altogether.
expand after success
Keywords Area
method
coliny solis wets
expand after success
Set the factor by which a search pattern can be expanded

Specification
Alias: none
Argument(s): INTEGER
Default: 5

Description
In general, pattern search methods can expand and contract their step lengths. SCOLIB pattern search methods
contract the step length by the value contraction factor, and they expand the step length by the value
(1/contraction factor). The expand after success control specifies how many successful objective function
improvements must occur with a specific step length prior to expansion of the step length, whereas the no expansion flag instructs the algorithm to forgo pattern expansion altogether.

796

CHAPTER 6. KEYWORDS AREA

constant penalty
Keywords Area
method
coliny solis wets
constant penalty
Use a simple weighted penalty to manage feasibility

Specification
Alias: none
Argument(s): none
Default: algorithm dynamically adapts the constraint penalty

Description
Finally, constraint infeasibility can be managed in a somewhat more sophisticated manner than the simple weighted
penalty function. If the constant penalty specification is used, then the simple weighted penalty scheme
described above is used. Otherwise, the constraint penalty is adapted to the value constraint penalty/L,
where L is the the smallest step length used so far.
contraction factor
Keywords Area
method
coliny solis wets
contraction factor
Amount by which step length is rescaled

Specification
Alias: none
Argument(s): REAL
Default: 0.5

Description
For pattern search methods, contraction factor specifies the amount by which step length is rescaled after
unsuccesful iterates, must be strictly between 0 and 1.
For methods that can expand the step length, the expansion is 1/ contraction factor

6.2. METHOD

797

constraint penalty
Keywords Area
method
coliny solis wets
constraint penalty
Multiplier for the penalty function

Specification
Alias: none
Argument(s): REAL
Default: 1.0

Description
Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty
times the sum of squares of the constraint violations to the objective function. The default value of constraintpenalty is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default
value is 1.0.
initial delta
Keywords Area
method
coliny solis wets
initial delta
Initial step size for non-gradient based optimizers

Specification
Alias: none
Argument(s): REAL
Default: 1.0 (COBYLA), 0.1range (PS, SW)

Description
If initial delta is supplied by the user, it will be applied in an absolute sense in all coordinate directions.
APPS documentation advocates choosing initial delta to be the approximate distance from the initial point
to the solution. If this is unknown, it is advisable to err on the side of choosing an initial delta that is too
large or to not specify it. In the latter case, APPS will take a full step to the boundary in each direction. Relative
application of initial delta is not available unless the user scales the problem accordingly.

798

CHAPTER 6. KEYWORDS AREA

threshold delta
Keywords Area
method
coliny solis wets
threshold delta
Stopping criteria based on step length or pattern size

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-4 (COBYLA), 1.0e-5 (PS), 1.0e-6 (SW)

Description
threshold delta is the step length or pattern size used to determine convergence.
solution target
Keywords Area
method
coliny solis wets
solution target
Stopping criteria based on objective function value

Specification
Alias: solution accuracy
Argument(s): REAL
Default: -DBL MAX

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
seed
Keywords Area
method
coliny solis wets
seed
Seed of the random number generator

6.2. METHOD

799

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

show misc options

Keywords Area
method
coliny solis wets
show misc options
Show algorithm parameters not exposed in Dakota input

Specification
Alias: none
Argument(s): none
Default: no dump of specification options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using

800

CHAPTER 6. KEYWORDS AREA

this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
misc options
Keywords Area
method
coliny solis wets
misc options
Set method options not available through Dakota spec

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
max iterations
Keywords Area
method
coliny solis wets
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

801

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
coliny solis wets
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

802

CHAPTER 6. KEYWORDS AREA

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

max function evaluations

Keywords Area
method
coliny solis wets
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
coliny solis wets
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

803

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.

804

CHAPTER 6. KEYWORDS AREA

Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
coliny solis wets
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

805

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

806

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.36

coliny cobyla

Keywords Area
method
coliny cobyla
Constrained Optimization BY Linear Approximations (COBYLA)

Topics
This keyword is related to the topics:
package scolib
package coliny
local optimization methods
constrained

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
initial delta

Dakota Keyword
Description
Reasonable initial
changes to
optimization
variables

Optional

threshold delta

Required or
expected accuracy
in optimization
variables.

Optional

solution target

Optional

seed

Stopping criteria
based on objective
function value
Seed of the random
number generator

6.2. METHOD

807
Optional

show misc options

Optional

misc options

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Show algorithm
parameters not
exposed in Dakota
input
Set method options
not available
through Dakota
spec
Stopping criterion
based on number
of iterations

Description
The Constrained Optimization BY Linear Approximations (COBYLA) algorithm is an extension to the Nelder-Mead simplex algorithm for handling general linear/nonlinear constraints and is invoked using the colinycobyla group specification. The COBYLA algorithm employs linear approximations to the objective and
constraint functions, the approximations being formed by linear interpolation at N+1 points in the space of the
variables. We regard these interpolation points as vertices of a simplex. The step length parameter controls the size
of the simplex and it is reduced automatically from initial delta to threshold delta. One advantage
that COBYLA has over many of its competitors is that it treats each constraint individually when calculating a
change to the variables, instead of lumping the constraints together into a single penalty function.
See the page package scolib for important information regarding all SCOLIB methods
coliny cobyla is inherently serial.
Stopping Critieria
COBYLA currently only supports termination based on
max function evaluations
solution target
Other method-independent stopping criteria (max iterations and convergence tolerance) will be ignored if set.

808

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
coliny beta
coliny direct
coliny pattern search
coliny ea
coliny solis wets
initial delta
Keywords Area
method
coliny cobyla
initial delta
Reasonable initial changes to optimization variables

Specification
Alias: none
Argument(s): REAL
Default: 1.0 (COBYLA), 0.1range (PS, SW)

Description
initial delta for COBYLA should be set to be a value that is reasonable for initial changes to the optimization variables. It represents a distance from the initial simplex within which linear approximation subproblems
can be trusted to be sufficiently representative of the true problem. It is analagous to the initial trust-region size
used in trust-region methods.
Default Behavior
The default value is 1.0.
threshold delta
Keywords Area
method
coliny cobyla
threshold delta
Required or expected accuracy in optimization variables.

6.2. METHOD

809

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-4 (COBYLA), 1.0e-5 (PS), 1.0e-6 (SW)

Description
Unlike its use as a stopping criteria in other methods, threshold delta is used to communicate the accuracy
of the optimization variables to COBYLA. It represents the mimimum distance from the simplex within which linear approximation subproblems can be trusted to be sufficiently representative of the true problem. It is analagous
to the minimum trust-region size used in trust-region methods. Note that, per COBYLA documentation, the level
of accuracy is not guaranteed.
Default Behavior
The default value is 0.0001.
Additional Discussion
While threshold delta is not a stopping criteria for COBYLA, we note that it may have a side effect
regarding convergence. In particular, if lower accuracy is required of the optimization variables, it may stop
sooner than if higher accuracy is required.
solution target
Keywords Area
method
coliny cobyla
solution target
Stopping criteria based on objective function value

Specification
Alias: solution accuracy
Argument(s): REAL
Default: -DBL MAX

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
seed
Keywords Area
method
coliny cobyla
seed
Seed of the random number generator

810

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

show misc options

Keywords Area
method
coliny cobyla
show misc options
Show algorithm parameters not exposed in Dakota input

Specification
Alias: none
Argument(s): none
Default: no dump of specification options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using

6.2. METHOD

811

this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
misc options
Keywords Area
method
coliny cobyla
misc options
Set method options not available through Dakota spec

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
max iterations
Keywords Area
method
coliny cobyla
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

812

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
coliny cobyla
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

6.2. METHOD

813

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max function evaluations
Keywords Area
method
coliny cobyla
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
coliny cobyla
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

814

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.

6.2. METHOD

815

Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
coliny cobyla
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

816

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

817

response_functions = 3
no_gradients
no_hessians

6.2.37

coliny direct

Keywords Area
method
coliny direct
DIviding RECTangles method

Topics
This keyword is related to the topics:
package scolib
package coliny
global optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
division

Optional

global balance parameter

Optional

local balance parameter

Optional

max boxsize limit

Dakota Keyword
Description
Determine how
rectangles are
subdivided
Tolerance for
whether a
subregion is worth
dividing
Tolerance for
whether a
subregion is worth
dividing
Stopping Criterion
based on longest
edge of
hyperrectangle

818

CHAPTER 6. KEYWORDS AREA

Optional

min boxsize limit

Optional

constraint penalty

Optional

solution target

Optional

seed

Optional

show misc options

Optional

misc options

Optional

max iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Stopping Criterion
based on shortest
edge of
hyperrectangle
Multiplier for the
penalty function
Stopping criteria
based on objective
function value
Seed of the random
number generator
Show algorithm
parameters not
exposed in Dakota
input
Set method options
not available
through Dakota
spec
Stopping criterion
based on number
of iterations

Description
The DIviding RECTangles (DIRECT) optimization algorithm is a derivative free global optimization method that
balances local search in promising regions of the design space with global search in unexplored regions. As shown
in Figure 5.1, DIRECT adaptively subdivides the space of feasible design points so as to guarantee that iterates
are generated in the neighborhood of a global minimum in finitely many iterations.
DIRECT \image latex direct1.eps Design space partitioning with DIRECT width=10cm

6.2. METHOD

819

In practice, DIRECT has proven an effective heuristic for engineering design applications, for which it is able
to quickly identify candidate solutions that can be further refined with fast local optimizers.
See the page package scolib for important information regarding all SCOLIB methods
The DIRECT algorithm supports concurrency up to twice the number of variables being optimized.
DIRECT uses the solution target, constraint penalty and show misc options specifications that are described in package scolib. Note, however, that DIRECT uses a fixed penalty value for constraint
violations (i.e. it is not dynamically adapted as is done in coliny pattern search).
Search Parameters
The global balance parameter controls how much global search is performed by only allowing a
subregion to be subdivided if the size of the subregion divided by the size of the largest subregion is at least
global balance parameter. Intuitively, this forces large subregions to be subdivided before the smallest
subregions are refined. The local balance parameter provides a tolerance for estimating whether the
smallest subregion can provide a sufficient decrease to be worth subdividing; the default value is a small value
that is suitable for most applications.
Stopping Critieria
DIRECT can be terminated with:
max function evaluations
max iterations
convergence tolerance
solution target
max boxsize limit
min boxsize limit - most effective in practice

See Also
These keywords may also be of interest:
coliny beta
coliny pattern search
coliny cobyla
coliny ea
coliny solis wets
ncsu direct
division
Keywords Area
method
coliny direct
division
Determine how rectangles are subdivided

820

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: major dimension
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
major dimension

all dimensions

Dakota Keyword
Description
(default) Longest
edge of subregion
is subdivided
All dimensions are
simultaneously
subdivided

Description
The division specification determines how DIRECT subdivides each subregion of the search space.
If division is set to major dimension, then the dimension representing the longest edge of the subregion is subdivided (this is the default). If division is set to all dimensions, then all dimensions are
simultaneously subdivided.
major dimension
Keywords Area
method
coliny direct
division
major dimension
(default) Longest edge of subregion is subdivided

Specification
Alias: none
Argument(s): none

Description
Longest edge of subregion is subdivided
all dimensions
Keywords Area
method
coliny direct
division
all dimensions
All dimensions are simultaneously subdivided

6.2. METHOD

821

Specification
Alias: none
Argument(s): none

Description
All dimensions are simultaneously subdivided
global balance parameter
Keywords Area
method
coliny direct
global balance parameter
Tolerance for whether a subregion is worth dividing

Specification
Alias: none
Argument(s): REAL
Default: 0.0

Description
The global balance parameter controls how much global search is performed by only allowing a subregion to be subdivided if the size of the subregion divided by the size of the largest subregion is at least global balance parameter. Intuitively, this forces large subregions to be subdivided before the smallest subregions
are refined.
local balance parameter
Keywords Area
method
coliny direct
local balance parameter
Tolerance for whether a subregion is worth dividing

Specification
Alias: none
Argument(s): REAL
Default: 1.e-8

822

CHAPTER 6. KEYWORDS AREA

Description
See parent page. The local balance parameter provides a tolerance for estimating whether the smallest
subregion can provide a sufficient decrease to be worth subdividing; the default value is a small value that is
suitable for most applications.
max boxsize limit
Keywords Area
method
coliny direct
max boxsize limit
Stopping Criterion based on longest edge of hyperrectangle

Specification
Alias: none
Argument(s): REAL
Default: 0.0

Description
Each subregion considered by DIRECT has a size, which corresponds to the longest diagonal of the subregion.
max boxsize limit specification terminates DIRECT if the size of the largest subregion falls below this
threshold.
min boxsize limit
Keywords Area
method
coliny direct
min boxsize limit
Stopping Criterion based on shortest edge of hyperrectangle

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-4

6.2. METHOD

823

Description
min boxsize limit is a setting that terminates the optimization when the measure of a hyperrectangle S with
f(c(S)) = fmin is less than min boxsize limit.
Each subregion considered by DIRECT has a size, which corresponds to the longest diagonal of the subregion.
min boxsize limit specification terminates DIRECT if the size of the smallest subregion falls below this
threshold.
In practice, this specification is likely to be more effective at limiting DIRECTs search.
constraint penalty
Keywords Area
method
coliny direct
constraint penalty
Multiplier for the penalty function

Specification
Alias: none
Argument(s): REAL
Default: 1000.0

Description
Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty
times the sum of squares of the constraint violations to the objective function. The default value of constraintpenalty is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default
value is 1.0.
solution target
Keywords Area
method
coliny direct
solution target
Stopping criteria based on objective function value

Specification
Alias: solution accuracy
Argument(s): REAL
Default: -DBL MAX

824

CHAPTER 6. KEYWORDS AREA

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
seed
Keywords Area
method
coliny direct
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

show misc options

Keywords Area
method
coliny direct
show misc options
Show algorithm parameters not exposed in Dakota input

6.2. METHOD

825

Specification
Alias: none
Argument(s): none
Default: no dump of specification options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
misc options
Keywords Area
method
coliny direct
misc options
Set method options not available through Dakota spec

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
max iterations
Keywords Area
method
coliny direct

826

CHAPTER 6. KEYWORDS AREA

max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
coliny direct
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

827

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max function evaluations
Keywords Area
method
coliny direct
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

828

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
coliny direct
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

829

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

830

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
coliny direct
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.38

coliny ea

Keywords Area
method
coliny ea
Evolutionary Algorithm

Topics
This keyword is related to the topics:
package scolib
package coliny
global optimization methods

Specification
Alias: none
Argument(s): none

831

832

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
population size

Optional

initialization type

Optional
Optional

fitness type
replacement type

Optional

crossover rate

Optional

crossover type

Optional

mutation rate

Optional

mutation type

Optional

constraint penalty

Optional

solution target

Optional

seed

Optional

show misc options

Optional

misc options

Dakota Keyword
Description
Set the population
size
Specify how to
initialize the
population
Select fitness type
Select a
replacement type
for SCOLIB
evolutionary
algorithm
(coliny ea)
Specify the
probability of a
crossover event
Select a crossover
type
Set probability of a
mutation
Select a mutation
type
Multiplier for the
penalty function
Stopping criteria
based on objective
function value
Seed of the random
number generator
Show algorithm
parameters not
exposed in Dakota
input
Set method options
not available
through Dakota
spec

6.2. METHOD

833
Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
Evolutionary Algorithm
See the page package scolib for important information regarding all SCOLIB methods
coliny pattern search supports concurrency up to the size of the population
The random seed control provides a mechanism for making a stochastic optimization repeatable. That is, the
use of the same random seed in identical studies will generate identical results. The population size control
specifies how many individuals will comprise the EAs population.
The initialization type defines the type of initialization for the population of the EA. There are three
types: simple random, unique random, and flat file. simple random creates initial solutions with
random variable values according to a uniform random number distribution. It gives no consideration to any
previously generated designs. The number of designs is specified by the population size. unique random is the same as simple random, except that when a new solution is generated, it is checked against
the rest of the solutions. If it duplicates any of them, it is rejected. flat file allows the initial population to be
read from a flat file. If flat file is specified, a file name must be given.
The fitness type controls how strongly differences in fitness (i.e., the objective function) are weighted
in the process of selecting parents for crossover:
the linear rank setting uses a linear scaling of probability of selection based on the rank order of each
individuals objective function within the population
the merit function setting uses a proportional scaling of probability of selection based on the relative
value of each individuals objective function within the population
The replacement type controls how current populations and newly generated individuals are combined to
create a new population. Each of the replacement type selections accepts an integer value, which is referred
to below as the replacement size.

834

CHAPTER 6. KEYWORDS AREA

The random setting creates a new population using (a) replacement size randomly selected individuals from the current population, and (b) population size - replacement size individuals randomly selected from among the newly generated individuals (the number of which is optionally specified
using new solutions generated) that are created for each generation (using the selection, crossover,
and mutation procedures).
The chc setting creates a new population using (a) the replacement size best individuals from the
combination of the current population and the newly generated individuals, and (b) population size replacement size individuals randomly selected from among the remaining individuals in this combined pool. The chc setting is the preferred selection for many engineering problems.
The elitist (default) setting creates a new population using (a) the replacement size best individuals from the current population, (b) and population size - replacement size individuals
randomly selected from the newly generated individuals. It is possible in this case to lose a good solution
from the newly generated individuals if it is not randomly selected for replacement; however, the default
new solutions generated value is set such that the entire set of newly generated individuals will be
selected for replacement.

Note that new solutions generated is not recognized by Dakota as a valid keyword unless replacementtype has been specified.

Theory
The basic steps of an evolutionary algorithm are depicted in Figure 5.2.

Figure 6.2: Depiction of evolutionary algorithm

They can be enumerated as follows:

1. Select an initial population randomly and perform function evaluations on these individuals
2. Perform selection for parents based on relative fitness

6.2. METHOD

835

3. Apply crossover and mutation to generate new solutions generated new individuals from the selected parents
Apply crossover with a fixed probability from two selected parents
If crossover is applied, apply mutation to the newly generated individual with a fixed probability
If crossover is not applied, apply mutation with a fixed probability to a single selected parent
4. Perform function evaluations on the new individuals
5. Perform replacement to determine the new population
6. Return to step 2 and continue the algorithm until convergence criteria are satisfied or iteration limits are
exceeded

See Also
These keywords may also be of interest:
coliny beta
coliny direct
coliny pattern search
coliny cobyla
coliny solis wets
population size
Keywords Area
method
coliny ea
population size
Set the population size

Specification
Alias: none
Argument(s): INTEGER
Default: 50

Description
The number of designs in the population is specified by the population size.

836

CHAPTER 6. KEYWORDS AREA

initialization type
Keywords Area
method
coliny ea
initialization type
Specify how to initialize the population

Specification
Alias: none
Argument(s): none
Default: unique random
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
simple random

Group 1
unique random

flat file

Dakota Keyword
Description
Create random
initial solutions
Create random
initial solutions,
but enforce
uniqueness
(default)
Read initial
solutions from file

Description
The initialization type defines how the initial population is created for the GA. There are three types:
1. simple random
2. unique random (default)
3. flat file
Setting the size for the flat file initializer has the effect of requiring a minimum number of designs to
create. If this minimum number has not been created once the files are all read, the rest are created using the
unique random initializer and then the simple random initializer if necessary.
simple random
Keywords Area
method
coliny ea
initialization type
simple random
Create random initial solutions

6.2. METHOD

837

Specification
Alias: none
Argument(s): none

Description
simple random creates initial solutions with random variable values according to a uniform random number
distribution. It gives no consideration to any previously generated designs.
unique random
Keywords Area
method
coliny ea
initialization type
unique random
Create random initial solutions, but enforce uniqueness (default)

Specification
Alias: none
Argument(s): none

Description
unique random is the same as simple random, except that when a new solution is generated, it is checked
against the rest of the solutions. If it duplicates any of them, it is rejected.
flat file
Keywords Area
method
coliny ea
initialization type
flat file
Read initial solutions from file

Specification
Alias: none
Argument(s): STRING

838

CHAPTER 6. KEYWORDS AREA

Description
flat file allows the initial population to be read from a flat file. If flat file is specified, a file name must
be given.
fitness type
Keywords Area
method
coliny ea
fitness type
Select fitness type

Specification
Alias: none
Argument(s): none
Default: linear rank
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
linear rank
merit function

Dakota Keyword
Description
Set selection
scaling
Balance goals of
reducing objective
function and
satisfying
constraints

Description
The fitness type controls how strongly differences in fitness (i.e., the objective function) are weighted in
the process of selecting parents for crossover. It has two options, linear rank and merit function.
linear rank
Keywords Area
method
coliny ea
fitness type
linear rank
Set selection scaling

Specification
Alias: none
Argument(s): none

6.2. METHOD

839

Description
The linear rank setting uses a linear scaling of probability of selection based on the rank order of each
individuals objective function within the population
merit function
Keywords Area
method
coliny ea
fitness type
merit function
Balance goals of reducing objective function and satisfying constraints

Specification
Alias: none
Argument(s): none

Description
A merit function is a function in constrained optimization that attempts to provide joint progress toward
reducing the objective function and satisfying the constraints.
replacement type
Keywords Area
method
coliny ea
replacement type
Select a replacement type for SCOLIB evolutionary algorithm (coliny ea)

Specification
Alias: none
Argument(s): none
Default: elitist=1
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
random

Dakota Keyword
Description
Create new
population
randomly

840

CHAPTER 6. KEYWORDS AREA

chc

elitist

Optional

new solutions generated

Create new
population using
replacement
Use the best
designs to form a
new population
Replace population
with individuals
chosen from
population

Description
The replacement type controls how current populations and newly generated individuals are combined to create
a new population. Each of the replacement type selections accepts an associated integer value, which is specified
by the replacement size:
The random setting creates a new population using (a) replacement size randomly selected individuals from the current population, and (b) population size - replacement size individuals randomly
selected from among the newly generated individuals (the number of which is optionally specified using newsolutions generated) that are created for each generation (using the selection, crossover, and mutation
procedures).
The chc setting creates a new population using (a) the replacement size best individuals from the
combination of the current population and the newly generated individuals, and (b) population size replacement size individuals randomly selected from among the remaining individuals in this combined
pool. The chc setting is the preferred selection for many engineering problems.
The elitist (default) setting creates a new population using (a) the replacement size best individuals
from the current population, (b) and population size - replacement size individuals randomly selected
from the newly generated individuals. It is possible in this case to lose a good solution from the newly generated
individuals if it is not randomly selected for replacement; however, the default new solutions generated
value is set such that the entire set of newly generated individuals will be selected for replacement.
Note that new solutions generated is not recognized by Dakota as a valid keyword unless replacementtype has been specified.
random
Keywords Area
method
coliny ea
replacement type
random
Create new population randomly

Specification
Alias: none
Argument(s): INTEGER

6.2. METHOD

841

Description
The replacement type controls how current populations and newly generated individuals are combined to
create a new population. Each of the replacement type selections accepts an integer value, which is referred
as the replacement size:
The random setting creates a new population using:
replacement size randomly selected individuals from the current population, and
population size - replacement size individuals randomly selected from among the newly generated individuals (the number of which is optionally specified using new solutions generated) that
are created for each generation (using the selection, crossover, and mutation procedures).
chc
Keywords Area
method
coliny ea
replacement type
chc
Create new population using replacement

Specification
Alias: none
Argument(s): INTEGER

Description
The replacement type controls how current populations and newly generated individuals are combined to
create a new population. Each of the replacement type selections accepts an integer value, which is referred
as the replacement size:
The chc setting creates a new population using (a) the replacement size best individuals from the
combination of the current population and the newly generated individuals, and (b) population size replacement size individuals randomly selected from among the remaining individuals in this combined
pool. The chc setting is the preferred selection for many engineering problems.
elitist
Keywords Area
method
coliny ea
replacement type
elitist
Use the best designs to form a new population

842

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER

Description
The elitist (default) setting creates a new population using (a) the replacement size best individuals
from the current population, (b) and population size - replacement size individuals randomly selected
from the newly generated individuals. It is possible in this case to lose a good solution from the newly generated
individuals if it is not randomly selected for replacement; however, the default new solutions generated
value is set such that the entire set of newly generated individuals will be selected for replacement.
new solutions generated
Keywords Area
method
coliny ea
replacement type
new solutions generated
Replace population with individuals chosen from population

Specification
Alias: none
Argument(s): INTEGER
Default: population size - replacement size

Description
The random setting creates a new population using (a) replacement size randomly selected individuals from the current population, and (b) population size - replacement size individuals randomly selected from among the newly generated individuals (the number of which is optionally specified
using new solutions generated) that are created for each generation (using the selection, crossover,
and mutation procedures).
crossover rate
Keywords Area
method
coliny ea
crossover rate
Specify the probability of a crossover event

6.2. METHOD

843

Specification
Alias: none
Argument(s): REAL
Default: 0.8

Description
The crossover type controls what approach is employed for combining parent genetic information to create offspring, and the crossover rate specifies the probability of a crossover operation being performed to
generate a new offspring. The SCOLIB EA method supports three forms of crossover, two point, blend, and
uniform, which generate a new individual through combinations of two parent individuals. Two-point crossover
divides each parent into three regions, where offspring are created from the combination of the middle region from
one parent and the end regions from the other parent. Since the SCOLIB EA does not utilize bit representations
of variable values, the crossover points only occur on coordinate boundaries, never within the bits of a particular
coordinate. Uniform crossover creates offspring through random combination of coordinates from the two parents. Blend crossover generates a new individual randomly along the multidimensional vector connecting the two
parents.
crossover type
Keywords Area
method
coliny ea
crossover type
Select a crossover type

Specification
Alias: none
Argument(s): none
Default: two point
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
two point

blend
uniform

Dakota Keyword
Description
Combine middle of
one parent with
end of another
Random blend of
parents
Randomly
combine
coordinates from
parents

Description
The crossover type controls what approach is employed for combining parent genetic information to create
offspring. The SCOLIB EA method supports three forms of crossover, two point, blend, and uniform,
which generate a new individual through combinations of two parent individuals.

844

CHAPTER 6. KEYWORDS AREA

two point
Keywords Area
method
coliny ea
crossover type
two point
Combine middle of one parent with end of another

Specification
Alias: none
Argument(s): none

Description
Two-point crossover divides each parent into three regions, where offspring are created from the combination
of the middle region from one parent and the end regions from the other parent. Since the SCOLIB EA does
not utilize bit representations of variable values, the crossover points only occur on coordinate boundaries, never
within the bits of a particular coordinate.
blend
Keywords Area
method
coliny ea
crossover type
blend
Random blend of parents

Specification
Alias: none
Argument(s): none

Description
blend crossover generates a new individual randomly along the multidimensional vector connecting the two
parents.

6.2. METHOD

845

uniform
Keywords Area
method
coliny ea
crossover type
uniform
Randomly combine coordinates from parents

Specification
Alias: none
Argument(s): none

Description
Uniform crossover creates offspring through random combination of coordinates from the two parents.
mutation rate
Keywords Area
method
coliny ea
mutation rate
Set probability of a mutation

Specification
Alias: none
Argument(s): REAL
Default: 1.0

Description
The mutation rate controls the probability of mutation being performed on an individual, both for new
individuals generated by crossover (if crossover occurs) and for individuals from the existing population. It is the
fraction of trial points that are mutated in a given iteration and therefore must be specified to be between 0 and 1.
mutation type
Keywords Area
method
coliny ea
mutation type
Select a mutation type

846

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: offset normal
Required/Optional

Description of
Group

Dakota Keyword
replace uniform

Required(Choose
One)

Group 1
offset normal

offset cauchy

offset uniform

Optional

non adaptive

Dakota Keyword
Description
Replace coordinate
with randomly
generated value
Set mutation offset
to use a normal
distribution
Use a Cauchy
distribution for the
mutation offset
Set mutation offset
to use a uniform
distribution
Disable
self-adaptive
mutation

Description
The mutation type controls what approach is employed in randomly modifying continuous design variables
within the EA population. Each of the mutation methods generates coordinate-wise changes to individuals, usually
by adding a random variable to a given coordinate value (an offset mutation), but also by replacing a given
coordinate value with a random variable (a replace mutation).
Discrete design variables are always mutated using the offset uniform method.
replace uniform
Keywords Area
method
coliny ea
mutation type
replace uniform
Replace coordinate with randomly generated value

Specification
Alias: none
Argument(s): none

6.2. METHOD

847

Description
The replace uniform mutation type generates a replacement value for a coordinate using a uniformly distributed value over the total range for that coordinate.
offset normal
Keywords Area
method
coliny ea
mutation type
offset normal
Set mutation offset to use a normal distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
mutation scale

mutation range

Dakota Keyword
Description
Scales mutation
across range of
parameter
Set uniform offset
control for discrete
parameters

Description
The offset normal type is an offset mutation that adds a 0-mean random variable with a normal uniform
distribution to the existing coordinate value. The offset is limited in magnitude by mutation scale.
mutation scale
Keywords Area
method
coliny ea
mutation type
offset normal
mutation scale
Scales mutation across range of parameter

848

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: 0.1

Description
The mutation scale specifies a scale factor which scales continuous mutation offsets; this is a fraction of the
total range of each dimension, so mutation scale is a relative value between 0 and 1.
mutation range
Keywords Area
method
coliny ea
mutation type
offset normal
mutation range
Set uniform offset control for discrete parameters

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
The mutation range is used to control offset uniform mutation used for discrete parameters. The replacement discrete value is the original value plus or minus an integer value up to mutation range.
offset cauchy
Keywords Area
method
coliny ea
mutation type
offset cauchy
Use a Cauchy distribution for the mutation offset

Specification
Alias: none
Argument(s): none

6.2. METHOD

849
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
mutation scale

mutation range

Dakota Keyword
Description
Scales mutation
across range of
parameter
Set uniform offset
control for discrete
parameters

Description
The offset cauchy type is an offset mutation that adds a 0-mean random variable with a cauchy distribution
to the existing coordinate value. The offset is limited in magnitude by mutation scale.
mutation scale
Keywords Area
method
coliny ea
mutation type
offset cauchy
mutation scale
Scales mutation across range of parameter

Specification
Alias: none
Argument(s): REAL
Default: 0.1

Description
The mutation scale specifies a scale factor which scales continuous mutation offsets; this is a fraction of the
total range of each dimension, so mutation scale is a relative value between 0 and 1.
mutation range
Keywords Area
method
coliny ea
mutation type
offset cauchy
mutation range
Set uniform offset control for discrete parameters

850

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
The mutation range is used to control offset uniform mutation used for discrete parameters. The replacement discrete value is the original value plus or minus an integer value up to mutation range.
offset uniform
Keywords Area
method
coliny ea
mutation type
offset uniform
Set mutation offset to use a uniform distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
mutation scale

mutation range

Dakota Keyword
Description
Scales mutation
across range of
parameter
Set uniform offset
control for discrete
parameters

Description
The offset uniform type is an offset mutation that adds a 0-mean random variable with a uniform distribution to the existing coordinate value. The offset is limited in magnitude by mutation scale
For discrete design variables, offset uniform is always used, and mutation range controls the magnitude of the mutation.
mutation scale
Keywords Area
method
coliny ea
mutation type

6.2. METHOD

851

offset uniform
mutation scale
Scales mutation across range of parameter

Specification
Alias: none
Argument(s): REAL
Default: 0.1

Description
The mutation scale specifies a scale factor which scales continuous mutation offsets; this is a fraction of the
total range of each dimension, so mutation scale is a relative value between 0 and 1.
mutation range
Keywords Area
method
coliny ea
mutation type
offset uniform
mutation range
Set uniform offset control for discrete parameters

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
The mutation range is used to control offset uniform mutation used for discrete parameters. The replacement discrete value is the original value plus or minus an integer value up to mutation range.
non adaptive
Keywords Area
method
coliny ea
mutation type
non adaptive
Disable self-adaptive mutation

852

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: Adaptive mutation

Description
The SCOLIB EA method uses self-adaptive mutation, which modifies the mutation scale dynamically. This
mechanism is borrowed from EAs like evolution strategies. The non adaptive flag can be used to deactivate
the self-adaptation, which may facilitate a more global search.
Note that non adaptive is not recognized by Dakota as a valid keyword unless mutation type has
been specified.
constraint penalty
Keywords Area
method
coliny ea
constraint penalty
Multiplier for the penalty function

Specification
Alias: none
Argument(s): REAL

Description
Most SCOLIB optimizers treat constraints with a simple penalty scheme that adds constraint penalty
times the sum of squares of the constraint violations to the objective function. The default value of constraintpenalty is 1000.0, except for methods that dynamically adapt their constraint penalty, for which the default
value is 1.0.
solution target
Keywords Area
method
coliny ea
solution target
Stopping criteria based on objective function value

6.2. METHOD

853

Specification
Alias: solution accuracy
Argument(s): REAL
Default: -DBL MAX

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
seed
Keywords Area
method
coliny ea
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

854

CHAPTER 6. KEYWORDS AREA

show misc options

Keywords Area
method
coliny ea
show misc options
Show algorithm parameters not exposed in Dakota input

Specification
Alias: none
Argument(s): none
Default: no dump of specification options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
misc options
Keywords Area
method
coliny ea
misc options
Set method options not available through Dakota spec

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

6.2. METHOD

855

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
max iterations
Keywords Area
method
coliny ea
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
coliny ea
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

856

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max function evaluations
Keywords Area
method
coliny ea
max function evaluations
Stopping criteria based on number of function evaluations

6.2. METHOD

857

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
coliny ea
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.

858

CHAPTER 6. KEYWORDS AREA

a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values

The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

6.2. METHOD

859

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
coliny ea
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

860

CHAPTER 6. KEYWORDS AREA

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.39

coliny beta

Keywords Area
method
coliny beta
(Experimental) Coliny beta solver

6.2. METHOD

861

Topics
This keyword is related to the topics:
package scolib
package coliny

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
beta solver name

Optional

solution target

Optional

seed

Optional

show misc options

Optional

misc options

Optional

max iterations

Optional

convergence tolerance

Dakota Keyword
Description
Use an
in-development
SCOLIB solver
Stopping criteria
based on objective
function value
Seed of the random
number generator
Show algorithm
parameters not
exposed in Dakota
input
Set method options
not available
through Dakota
spec
Stopping criterion
based on number
of iterations
Stopping criterion
based on
convergence of the
objective function
or statistics

862

CHAPTER 6. KEYWORDS AREA

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
This method keyword allows testing of experimental (beta) Coliny (Scolib) optimization solvers during software
development. It is intended primarily for developer use. Additional information on Coliny solvers is available at
package scolib.

See Also
These keywords may also be of interest:
coliny direct
coliny pattern search
coliny cobyla
coliny ea
coliny solis wets
beta solver name
Keywords Area
method
coliny beta
beta solver name
Use an in-development SCOLIB solver

Specification
Alias: none
Argument(s): STRING

Description
This is a means of accessing new methods in SCOLIB before they are exposed through the Dakota interface. Seek
help from a Dakota or SCOLIB developer or a Dakota developer.

6.2. METHOD

863

solution target
Keywords Area
method
coliny beta
solution target
Stopping criteria based on objective function value

Specification
Alias: solution accuracy
Argument(s): REAL
Default: -DBL MAX

Description
solution target is a termination criterion. The algorithm will terminate when the function value falls below
solution target.
seed
Keywords Area
method
coliny beta
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

864

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

show misc options

Keywords Area
method
coliny beta
show misc options
Show algorithm parameters not exposed in Dakota input

Specification
Alias: none
Argument(s): none
Default: no dump of specification options

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
misc options
Keywords Area
method
coliny beta
misc options
Set method options not available through Dakota spec

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

6.2. METHOD

865

Description
All SCOLIB methods support the show misc options optional specification which results in a dump of all the
allowable method inputs. Note that the information provided by this command refers to optimizer parameters that
are internal to SCOLIB, and which may differ from corresponding parameters used by the Dakota interface. The
misc options optional specification provides a means for inputing additional settings supported by the SCOLIB methods but which are not currently mapped through the Dakota input specification. Care must be taken in using
this specification; they should only be employed by users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that exist between those specifications and the
ones available through Dakota.
max iterations
Keywords Area
method
coliny beta
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
coliny beta
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

866

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max function evaluations
Keywords Area
method
coliny beta
max function evaluations
Stopping criteria based on number of function evaluations

6.2. METHOD

867

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
coliny beta
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.

868

CHAPTER 6. KEYWORDS AREA

a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values

The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

6.2. METHOD

869

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
coliny beta
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

870

CHAPTER 6. KEYWORDS AREA

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.40

nl2sol

Keywords Area
method
nl2sol
Trust-region method for nonlinear least squares

6.2. METHOD

871

Topics
This keyword is related to the topics:
nonlinear least squares

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
function precision

Optional

absolute conv tol

Optional

x conv tol

Optional

singular conv tol

Optional
Optional

singular radius
false conv tol

Optional

initial trust radius

Optional

covariance

Optional

regression diagnostics
convergence tolerance

Optional

Dakota Keyword
Description
Specify the
maximum
precision of the
analysis code
responses
Absolute
convergence
tolerance
X-convergence
tolerance
Singular
convergence
tolerance
Singular radius
False convergence
tolerance
Initial trust region
radius
Determine how the
final covariance
matrix is computed
Turn on regression
diagnostics
Stopping criterion
based on
convergence of the
objective function
or statistics

872

CHAPTER 6. KEYWORDS AREA

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

speculative

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Compute
speculative
gradients
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
NL2SOL is available as nl2sol and addresses unconstrained and bound-constrained least squares problems. It
uses a trust-region method (and thus can be viewed as a generalization of the Levenberg-Marquardt algorithm)
and adaptively chooses between two Hessian approximations, the Gauss-Newton approximation alone and the
Gauss-Newton approximation plus a quasi-Newton approximation to the rest of the Hessian. Even on smallresidual problems, the latter Hessian approximation can be useful when the starting guess is far from the solution.
On problems that are not over-parameterized (i.e., that do not involve more optimization variables than the data
support), NL2SOL usually exhibits fast convergence.
Several internal NL2SOL convergence tolerances are adjusted in response to function precision, which
gives the relative precision to which responses are computed.
These tolerances may also be specified explicitly using:
convergence tolerance (NL2SOLs rfctol)
x conv tol (NL2SOLs xctol)
absolute conv tol (NL2SOLs afctol)
singular conv tol (NL2SOLs sctol)
false conv tol (NL2SOLs xftol)
initial trust radius (NL2SOLs lmax0)
The internal NL2SOL defaults can be obtained for many of these controls by specifying the value -1. The internal
defaults are often functions of machine epsilon (as limited by function precision).

Examples
An example of nl2sol is given below, and is discussed in the Users Manual.
Note that in this usage of calibration terms, the driver script rosenbrock, is returning residuals, which the
nl2sol method is attempting to minimze. Another use case is to provide a data file, which Dakota will attempt

6.2. METHOD

873

to match the model responses to. See calibration data file. Finally, as of Dakota 6.2, the field data capability may
be used with nl2sol. That is, the user can specify field simulation data and field experiment data, and Dakota
will interpolate and provide the proper residuals for the calibration.
# Dakota Input File: rosen_opt_nls.in
environment
tabular_data
tabular_data_file = rosen_opt_nls.dat
method
max_iterations = 100
convergence_tolerance = 1e-4
nl2sol
model
single
variables
continuous_design = 2
initial_point
-1.2
lower_bounds
-2.0
upper_bounds
2.0
descriptors
x1

1.0
-2.0
2.0
"x2"

interface
analysis_driver = rosenbrock
direct
responses
calibration_terms = 2
analytic_gradients
no_hessians

Theory
NL2SOL has a variety of internal controls as described in AT&T Bell Labs CS TR 153 (http://cm.bell-labs.com/cm/cs/cstr/153.ps.gz). A number of existing Dakota controls (method independent controls and
responses controls) are mapped into these NL2SOL internal controls. In particular, Dakotas convergencetolerance, max iterations, max function evaluations, and fd gradient step size are
mapped directly into NL2SOLs rfctol, mxiter, mxfcal, and dltfdj controls, respectively. In addition, Dakotas fd hessian step size is mapped into both delta0 and dltfdc, and Dakotas output
verbosity is mapped into NL2SOLs auxprt and outlev (for normal/verbose/debug output, NL2SOL prints initial guess, final solution, solution statistics, nondefault values, and changes to the active bound
constraint set on every iteration; for quiet output, NL2SOL prints only the initial guess and final solution;
and for silent output, NL2SOL output is suppressed).

See Also
These keywords may also be of interest:
nlssol sqp
optpp g newton
field calibration terms

874

CHAPTER 6. KEYWORDS AREA

function precision
Keywords Area
method
nl2sol
function precision
Specify the maximum precision of the analysis code responses

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-10

Description
The function precision control provides the algorithm with an estimate of the accuracy to which the
problem functions can be computed. This is used to prevent the algorithm from trying to distinguish between
function values that differ by less than the inherent error in the calculation.
absolute conv tol
Keywords Area
method
nl2sol
absolute conv tol
Absolute convergence tolerance

Specification
Alias: none
Argument(s): REAL
Default: -1. (use NL2SOL internal default)

Description
absolute conv tol (NL2SOLs afctol) is the absolute function convergence tolerance (stop when half the
sum of squares is less than absolute conv tol, which is mainly of interest on zero-residual test problems).
The internal default is a function of machine epsilon (as limited by function precision). The default is
selected with a value of -1.

6.2. METHOD

875

x conv tol
Keywords Area
method
nl2sol
x conv tol
X-convergence tolerance

Specification
Alias: none
Argument(s): REAL
Default: -1. (use NL2SOL internal default)

Description
x conv tol maps to the internal NL2SOL control xctol. It is the X-convergence tolerance (scaled relative
accuracy of the solution variables).
The internal default is a function of machine epsilon (as limited by function precision). The default is
selected with a value of -1.
singular conv tol
Keywords Area
method
nl2sol
singular conv tol
Singular convergence tolerance

Specification
Alias: none
Argument(s): REAL
Default: -1. (use NL2SOL internal default)

Description
singular conv tol (NL2SOLs sctol) is the singular convergence tolerance, which works in conjunction with singular radius to test for underdetermined least-squares problems (stop when the relative reduction
yet possible in the sum of squares appears less then singular conv tol for steps of scaled length at most
singular radius).
The internal default is a function of machine epsilon (as limited by function precision). The default is
selected with a value of -1.

876

CHAPTER 6. KEYWORDS AREA

singular radius
Keywords Area
method
nl2sol
singular radius
Singular radius

Specification
Alias: none
Argument(s): REAL
Default: -1. (use NL2SOL internal default of 1)

Description
singular radius works in conjunction with singular conv tol to test for underdetermined least-squares problems (stop when the relative reduction yet possible in the sum of squares appears less than singular conv tol
for steps of scaled length at most singular radius).
The internal default results in the internal use of steps of length 1. The default is selected with a value of -1.
false conv tol
Keywords Area
method
nl2sol
false conv tol
False convergence tolerance

Specification
Alias: none
Argument(s): REAL
Default: -1. (use NL2SOL internal default)

Description
false conv tol (NL2SOLs xftol) is the false-convergence tolerance (stop with a suspicion of discontinuity
when a more favorable stopping test is not satisfied and a step of scaled length at most false conv tol is not
accepted)
The internal default is a function of machine epsilon (as limited by function precision). The default is
selected with a value of -1.

6.2. METHOD

877

initial trust radius

Keywords Area
method
nl2sol
initial trust radius
Initial trust region radius

Specification
Alias: none
Argument(s): REAL
Default: -1. (use NL2SOL internal default of 1)

Description
initial trust radius specification (NL2SOLs lmax0) specifies the initial trust region radius for the algorithm.
The internal default results in the internal use of steps of length 1. The default is selected with a value of -1.
covariance
Keywords Area
method
nl2sol
covariance
Determine how the final covariance matrix is computed

Specification
Alias: none
Argument(s): INTEGER
Default: 0 (no covariance)

Description
covariance (NL2SOLs covreq) specifies whether and how NL2SOL computes a final covariance matrix.
The desired covariance approximation:
0 = default = none
1 or -1 ==> 2 H 1 J T JH 1
2 or -2 ==> 2 H 1
3 or -3 ==> 2 (J T J)1

878

CHAPTER 6. KEYWORDS AREA

Negative values ==> estimate the final Hessian H by finite differences of function values only (using fd hessian step size)
Positive values ==> differences of gradients (using fd hessian step size)

regression diagnostics
Keywords Area
method
nl2sol
regression diagnostics
Turn on regression diagnostics

Specification
Alias: none
Argument(s): none
Default: no regression diagnostics

Description
When regression diagnostics (NL2SOLs rdreq) is specified and a positive-definite final Hessian approximation H is computed, NL2SOL computes and prints a regression diagnostic vector RD such that if omitting
the i-th observation would cause alpha times the change in the solution that omitting the j-th observation would
cause, then RD[i] = |alpha| RD[j]. The finite-difference step-size tolerance affecting H is fd step size (NL2SOLs
delta0 and dltfdc).
convergence tolerance
Keywords Area
method
nl2sol
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

6.2. METHOD

879

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
nl2sol
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

880

CHAPTER 6. KEYWORDS AREA

Description
The maximum number of iterations (default: 100). See also max function evaluations.
speculative
Keywords Area
method
nl2sol
speculative
Compute speculative gradients

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no speculation

Description
When performing gradient-based optimization in parallel, speculative gradients can be selected to address
the load imbalance that can occur between gradient evaluation and line search phases. In a typical gradient-based
optimization, the line search phase consists primarily of evaluating the objective function and any constraints at a
trial point, and then testing the trial point for a sufficient decrease in the objective function value and/or constraint
violation. If a sufficient decrease is not observed, then one or more additional trial points may be attempted
sequentially. However, if the trial point is accepted then the line search phase is complete and the gradient
evaluation phase begins. By speculating that the gradient information associated with a given line search trial point
will be used later, additional coarse grained parallelism can be introduced by computing the gradient information
(either by finite difference or analytically) in parallel, at the same time as the line search phase trial-point function
values. This balances the total amount of computation to be performed at each design point and allows for
efficient utilization of multiple processors. While the total amount of work performed will generally increase
(since some speculative gradients will not be used when a trial point is rejected in the line search phase), the run
time will usually decrease (since gradient evaluations needed at the start of each new optimization cycle were
already performed in parallel during the line search phase). Refer to [14] for additional details. The speculative
specification is implemented for the gradient-based optimizers in the DOT, CONMIN, and OPT++ libraries,
and it can be used with dakota numerical or analytic gradient selections in the responses specification (refer
to responses gradient section for information on these specifications). It should not be selected with vendor
numerical gradients since vendor internal finite difference algorithms have not been modified for this purpose.
In full-Newton approaches, the Hessian is also computed speculatively. NPSOL and NLSSOL do not support
speculative gradients, as their gradient-based line search in user-supplied gradient mode (dakota numerical or
analytic gradients) is a superior approach for load-balanced parallel execution.

6.2. METHOD

881

The speculative specification enables speculative computation of gradient and/or Hessian information,
where applicable, for parallel optimization studies. By speculating that the derivative information at the current
point will be used later, the complete data set (all available gradient/Hessian information) can be computed on
every function evaluation. While some of these computations will be wasted, the positive effects are a consistent parallel load balance and usually shorter wall clock time. The speculative specification is applicable
only when parallelism in the gradient calculations can be exploited by Dakota (it will be ignored for vendor
numerical gradients).
max function evaluations
Keywords Area
method
nl2sol
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
nl2sol
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

882

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.

6.2. METHOD

883

Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
nl2sol
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

884

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

885

response_functions = 3
no_gradients
no_hessians

6.2.41

nonlinear cg

Keywords Area
method
nonlinear cg
(Experimental) nonlinear conjugate gradient optimization

Topics
This keyword is related to the topics:
local optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
misc options

Dakota Keyword
Description
Options for
nonlinear CG
optimizer

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

scaling

Turn on scaling for

variables,
responses, and
constraints

886

CHAPTER 6. KEYWORDS AREA

Optional

model pointer

Identifier for
model block to be
used by a method

Description
This method is an incomplete experimental implementation of nonlinear conjugate gradient optimization, a local,
gradient-based solver.
misc options
Keywords Area
method
nonlinear cg
misc options
Options for nonlinear CG optimizer

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

Description
List of miscellaneous string options to pass to the experimental nonlinear CG solver (see NonlinearCGOptimizer.cpp in the Dakota source code for available controls). Includes controls for step sizes, linesearch control, convergence, etc.
convergence tolerance
Keywords Area
method
nonlinear cg
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

887

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
nonlinear cg
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

888

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
scaling
Keywords Area
method
nonlinear cg
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values

6.2. METHOD

889

The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

890

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
nonlinear cg
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD

891

surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.42

ncsu direct

Keywords Area
method
ncsu direct
DIviding RECTangles method

Topics
This keyword is related to the topics:
global optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

892

CHAPTER 6. KEYWORDS AREA

Optional

solution target

Optional

min boxsize limit

Optional

volume boxsize limit

Optional

convergence tolerance

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Specifies a
globally optimal
value toward which
the optimizer
should track
Stopping Criterion
based on shortest
edge of
hyperrectangle
Stopping criterion
based on volume
of search space
Stopping criterion
based on
convergence of the
objective function
or statistics

Description
North Carolina State University (NCSU) has an implementation of the DIRECT algorithm (DIviding RECTangles
algorithm that is outlined in the SCOLIB method section above). This version is documented in [28] We have
found that the NCSU DIRECT implementation works better and is more robust for some problems than colinydirect. Currently, we maintain both versions of DIRECT in Dakota; in the future, we may deprecate one.
The NCSU DIRECT method is selected with ncsu direct. We have tried to maintain consistency between
the keywords in SCOLIB and NCSU implementation of DIRECT, but the algorithms have different parameters,
so the keywords sometimes have slightly different meaning.
Stopping Criteria
The algorithm stops based on:
1. max iterations - number of iterations
2. max function evaluations - number of function evaluations

6.2. METHOD

893

3. solution target and convergence tolerance

4. min boxsize limit
5. volume boxsize limit
This method will always strictly respect the number of iterations, but may slightly exceed the number of
function evaluations, as it will always explore all sub-rectangles at the current level.

See Also
These keywords may also be of interest:
coliny direct
solution target
Keywords Area
method
ncsu direct
solution target
Specifies a globally optimal value toward which the optimizer should track

Specification
Alias: solution accuracy
Argument(s): REAL
Default: 0

Description
The solution target specifies a goal toward which the optimizer should track.
This is used for test problems, when the true global minimum is known (call it solution target := fglobal). Then, the optimization terminates when 100(f min-fglobal)/max(1,abs(fglobal) < convergence tolerance. The default for fglobal is -1.0e100 and the default for convergence tolerance is described at convergencetolerance.
min boxsize limit
Keywords Area
method
ncsu direct
min boxsize limit
Stopping Criterion based on shortest edge of hyperrectangle

894

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-4

Description
min boxsize limit is a setting that terminates the optimization when the measure of a hyperrectangle S with
f(c(S)) = fmin is less than min boxsize limit.
Each subregion considered by DIRECT has a size, which corresponds to the longest diagonal of the subregion.
min boxsize limit specification terminates DIRECT if the size of the smallest subregion falls below this
threshold.
In practice, this specification is likely to be more effective at limiting DIRECTs search.
volume boxsize limit
Keywords Area
method
ncsu direct
volume boxsize limit
Stopping criterion based on volume of search space

Specification
Alias: none
Argument(s): REAL
Default: 1.0e-6

Description
volume boxsize limit is a setting that terminates the optimization when the volume of a hyperrectangle S
with f(c(S)) = fmin is less than volume boxsize limit percent of the original hyperrectangle. Basically, volumeboxsize limit stops the optimization when the volume of the particular rectangle which has fmin is less than a
certain percentage of the whole volume.
convergence tolerance
Keywords Area
method
ncsu direct
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

6.2. METHOD

895

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
ncsu direct
max iterations
Stopping criterion based on number of iterations

896

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
max function evaluations
Keywords Area
method
ncsu direct
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
ncsu direct
scaling
Turn on scaling for variables, responses, and constraints

6.2. METHOD

897

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].

898

CHAPTER 6. KEYWORDS AREA

4. log - logarithmic scaling

First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
ncsu direct
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

6.2. METHOD

899

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

900

CHAPTER 6. KEYWORDS AREA

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.43

genie opt darts

Keywords Area
method
genie opt darts
Voronoi-based high-dimensional global Lipschitzian optimization

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
seed

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Dakota Keyword
Description
Seed of the random
number generator
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
OPT-Darts method is a fast alternative to DIRECT for global Lipschitzian optimization purposes. Instead of
hyperrectangular, OPT-Darts decomposes a high-dimensional domain into Voronoi cells, and places samples via
stochastic blue noise instead of deterministic cell division.
To refine a cell, OPT-Darts first adds a new sample within it via spoke-dart sampling, then set the conflict
radius to the cells inscribed hypersphere radius, to avoid adding a sample point that is too close to a prior sample,
then divide that cell (and update its neighboring cells) via the approximate Delaunay graph, and use the computed
witnesses to decide the next refinement candidate. These two steps replace the corresponding deterministic centersample and rectangular cell division in DIRECT, respectively.

6.2. METHOD

901

OPT-Darts is the first exact stochastic Lipschitzian optimization technique that combines the benefits of guaranteed convergence in [Jones et al. 1993] and high dimensional efficiency in [Spall 2005]. Computing blue
noise and Voronoi regions has been intractable in high dimensions, and are being done within OPT-Darts using
Spoke-Darts.
seed
Keywords Area
method
genie opt darts
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

max function evaluations

Keywords Area
method
genie opt darts
max function evaluations
Stopping criteria based on number of function evaluations

902

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.
scaling
Keywords Area
method
genie opt darts
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.

6.2. METHOD

903

a scales keyword, which gives characteristic values

a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling
3. auto - automatic scaling
First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

904

CHAPTER 6. KEYWORDS AREA

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

model pointer
Keywords Area
method
genie opt darts
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

6.2. METHOD

905

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.44

genie direct

Keywords Area
method
genie direct
Classical high-dimensional global Lipschitzian optimization Classical high-dimensional global Lipschitzian
optimization

906

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
seed

Optional

max function evaluations

Optional

scaling

Optional

model pointer

Dakota Keyword
Description
Seed of the random
number generator
Stopping criteria
based on number
of function
evaluations
Turn on scaling for
variables,
responses, and
constraints
Identifier for
model block to be
used by a method

Description
DIRECT (DIviding RECTangles) partitions the domain into hyperrectangles and uses an iterative Lipschitzian
optimization approach to search for a global optimal point.
DIRECT begins by scaling the domain into the unit hypercube by adopting a center-sampling strategy. The
objective function is evaluated at the midpoint of the domain, where a lower bound is constructed. In onedimension, the domain is tri-sected and two new center points are sampled. At each iteration (dividing and
sampling), DIRECT identifies intervals that contain the best minimal value of the objective function found up
to that point. This strategy of selecting and dividing gives DIRECT its performance and convergence properties
compared to other deterministic methods.
The classical DIRECT method [Shubert 1972] has two limitations: poor scaling to high dimensions; and
relying on a global K; whose exact value is often unknown. The enhanced DIRECT algorithm [Jones et al. 1993]
generalizes [Shubert 1972] to higher dimensions and does not require knowledge of the Lipschitz constant.
seed
Keywords Area
method
genie direct
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

6.2. METHOD

907

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

max function evaluations

Keywords Area
method
genie direct
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

908

CHAPTER 6. KEYWORDS AREA

scaling
Keywords Area
method
genie direct
scaling
Turn on scaling for variables, responses, and constraints

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): none
Default: no scaling

Description
Some of the optimization and calibration methods support scaling of continuous design variables, objective functions, calibration terms, and constraints. This is activated by by providing the scaling keyword. Discrete
variable scaling is not supported.
When scaling is enabled, variables, functions, gradients, Hessians, etc., are transformed such that the method
iterates in scaled variable space, whereas evaluations of the computational model as specified in the interface are
performed on the original problem scale. Therefore using scaling does not require rewriting the interface to the
simulation code.
Scaling also requires the specification of additional keywords which are found in the method, variables, and
responses blocks. When the scaling keyword is omitted, all scale types and scales specifications
are ignored in the method, variables, and responses sections.
This page describes the usage of all scaling related keywords. The additional keywords come in pairs, one
pair for each set of quantities to be scaled. These quantities can be constraint equations, variables, or responses.
a scales keyword, which gives characteristic values
a scale type keyword, which determines how to use the characteristic values
The pair of keywords both take argument(s), and the length of the arguments can either be zero, one, or equal to
the number of quantities to be scaled. If one argument is given, it will apply to all quantities in the set. See the
examples below.
Scale Types
There are four scale types:
1. none (default) - no scaling, value of scales keyword is ignored
2. value - multiplicative scaling

6.2. METHOD

909

3. auto - automatic scaling

First the quantity is scaled by the characteristic value, then automatic scaling will be attempted according
to the following scheme:
two-sided bounds scaled into the interval [0,1];
one-sided bound or targets are scaled by the characteristic value, moving the bound or target to 1 and
changing the sense of inequalities where necessary;
no bounds or targets: no automatic scaling possible, therefore no scaling for this component
Automatic scaling is not available for objective functions nor calibration terms since they lack bound constraints. Futher, when automatically scaled, linear constraints are scaled by characteristic values only, not
affinely scaled into [0,1].
4. log - logarithmic scaling
First, any characteristic values from the optional scales specification are applied. Then logarithm base
10 scaling is applied.
Logarithmic scaling is not available for linear constraints.
When continuous design variables are log scaled, linear constraints are not allowed.
Scales
The scales keywords are used to specify the characteristic values. These must be non-zero real numbers.
The numbers are used according to the corresponding scale type, as described above.
Depending on the scale type, the characteristic values may be required or optional.
none, auto, log - optional
value - required.
A warning is issued if scaling would result in division by a value smaller in magnitude than 1.0e10DBL MIN. User-provided values violating this lower bound are accepted unaltered, whereas for automatically calculated
scaling, the lower bound is enforced.

Examples
The two examples below are equivalent:
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value"
primary_scales = 1 1 100
responses
objective_functions 3
sense "maximize"
primary_scale_types = "value" "value" "value"
primary_scales = 1 1 100

910

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
genie direct
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD

911

surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.45

efficient global

Keywords Area
method
efficient global
Global Surrogate Based Optimization, a.k.a. EGO

Topics
This keyword is related to the topics:
global optimization methods
surrogate based optimization methods

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

912

CHAPTER 6. KEYWORDS AREA

Optional

gaussian process

Gaussian Process
surrogate model

Optional

use derivatives

Use derivative data

to construct
surrogate models

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Optional

seed

Seed of the random

number generator

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The Efficient Global Optimization (EGO) method was first developed by Jones, Schonlau, and Welch[54]. In
EGO, a stochastic response surface approximation for the objective function is developed based on some sample
points from the true simulation.
Note that several major differences exist between our implementation and that of[54]. First, rather than using
a branch and bound method to find the point which maximizes the EIF, we use the DIRECT global optimization
method.
Second, we support both global optimization and global nonlinear least squares as well as general nonlinear
constraints through abstraction and subproblem recasting.
The efficient global method is in prototype form. Currently, we do not expose any specification controls for
the underlying Gaussian process model used or for the optimization of the expected improvement function (which
is currently performed by the NCSU DIRECT algorithm using its internal defaults).
By default, EGO uses the Surfpack GP (Kriging) model, but the Dakota implementation may be selected
instead. If use derivatives is specified the GP model will be built using available derivative data (Surfpack
GP only).

Theory
The particular response surface used is a Gaussian process (GP). The GP allows one to calculate the prediction at a
new input location as well as the uncertainty associated with that prediction. The key idea in EGO is to maximize
the Expected Improvement Function (EIF). The EIF is used to select the location at which a new training point

6.2. METHOD

913

should be added to the Gaussian process model by maximizing the amount of improvement in the objective
function that can be expected by adding that point. A point could be expected to produce an improvement in the
objective function if its predicted value is better than the current best solution, or if the uncertainty in its prediction
is such that the probability of it producing a better solution is high. Because the uncertainty is higher in regions of
the design space with few observations, this provides a balance between exploiting areas of the design space that
predict good solutions, and exploring areas where more information is needed. EGO trades off this exploitation
vs. exploration. The general procedure for these EGO-type methods is:
Build an initial Gaussian process model of the objective function
Find the point that maximizes the EIF. If the EIF value at this point is sufficiently small, stop.
Evaluate the objective function at the point where the EIF is maximized. Update the Gaussian process
model using this new point.
Return to the previous step.

See Also
These keywords may also be of interest:
surrogate based local
surrogate based global
gaussian process
Keywords Area
method
efficient global
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates

914

CHAPTER 6. KEYWORDS AREA

dakota

Select the built in

Gaussian Process
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
efficient global
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.

6.2. METHOD

915

4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
efficient global
gaussian process
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

916

CHAPTER 6. KEYWORDS AREA

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
use derivatives
Keywords Area
method
efficient global
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
import build points file
Keywords Area
method
efficient global

6.2. METHOD

917

import build points file

File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

918

CHAPTER 6. KEYWORDS AREA

annotated
Keywords Area
method
efficient global
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

919

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
efficient global
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

920

CHAPTER 6. KEYWORDS AREA

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

header
Keywords Area
method
efficient global

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
efficient global
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
efficient global
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

921

922

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
efficient global
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

6.2. METHOD

923

In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

active only
Keywords Area
method
efficient global
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.

924

CHAPTER 6. KEYWORDS AREA

export approx points file

Keywords Area
method
efficient global
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.
Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
efficient global
export approx points file

6.2. METHOD

925

annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

926

CHAPTER 6. KEYWORDS AREA

custom annotated
Keywords Area
method
efficient global
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips

6.2. METHOD

927

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
efficient global
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

928

CHAPTER 6. KEYWORDS AREA

eval id
Keywords Area
method
efficient global
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
efficient global
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated

6.2. METHOD

929

freeform
Keywords Area
method
efficient global
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

930

CHAPTER 6. KEYWORDS AREA

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

seed
Keywords Area
method
efficient global
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

6.2. METHOD

931

max iterations
Keywords Area
method
efficient global
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
model pointer
Keywords Area
method
efficient global
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

932

CHAPTER 6. KEYWORDS AREA

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

6.2. METHOD

933

response_functions = 3
no_gradients
no_hessians

6.2.46

polynomial chaos

Keywords Area
method
polynomial chaos
Uncertainty quantification using polynomial chaos expansions

Specification
Alias: nond polynomial chaos
Argument(s): none
Required/Optional
Optional

Optional(Choose
One)

Description of
Group

Dakota Keyword
p refinement

Basis polynomial
family (Group 1)

askey

wiener

Dakota Keyword
Description
Automatic
polynomial order
refinement
Select the
standardized
random variables
(and associated
basis polynomials)
from the Askey
family that best
match the
user-specified
random variables.
Use standard
normal random
variables (along
with Hermite
orthogonal basis
polynomials) when
transforming to a
standardized
probability space.

934

CHAPTER 6. KEYWORDS AREA

quadrature order
Required(Choose
One)

Coefficient
estimation
approach (Group
2)

sparse grid level

cubature integrand

expansion order

orthogonal least interpolation

import expansion file

Optional

variance based decomp

Cubature using
tensor-products of
Gaussian
quadrature rules
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation
Cubature using
Stroud rules and
their extensions
The (initial) order
of a polynomial
expansion
Build a polynomial
chaos expansion
from simulation
samples using
orthogonal least
interpolation.
Build a Polynomial
Chaos Expansion
(PCE) by import
coefficients and a
multi-index from a
file
Activates global
sensitivity analysis
based on
decomposition of
response variance
into main,
interaction, and
total effects

6.2. METHOD

935
Optional(Choose
One)

Covariance type
(Group 3)

diagonal covariance

full covariance

Display only the

diagonal terms of
the covariance
matrix
Display the full
covariance matrix
The normalized
specification
requests output of
PCE coefficients
that correspond to
normalized
orthogonal basis
polynomials
Selection of
sampling strategy

Optional

normalized

Optional

sample type

Optional

probability refinement

Optional

import approx points file

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Optional

export expansion file

Export the
coefficients and
multi-index of a
Polynomial Chaos
Expansion (PCE)
to a file

Allow refinement
of probability and
generalized
reliability results
using importance
sampling
Filename for
points at which to
evaluate the
PCE/SC surrogate

936

CHAPTER 6. KEYWORDS AREA

Optional

fixed seed

Reuses the same

seed value for
multiple random
sampling sets

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

reliability levels

Optional

response levels

Specify reliability
levels at which the
response values
will be estimated
Values at which to
estimate desired
statistics for each
response

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value

6.2. METHOD

937
Optional

rng

Selection of a
random number
generator

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The polynomial chaos expansion (PCE) is a general framework for the approximate representation of random
response functions in terms of finite-dimensional series expansions in standardized random variables
R=

P
X

i i ()

i=0

where i is a deterministic coefficient, i is a multidimensional orthogonal polynomial and is a vector of

standardized random variables. An important distinguishing feature of the methodology is that the functional
relationship between random inputs and outputs is captured, not merely the output statistics as in the case of many
nondeterministic methodologies.
Basis polynomial family (Group 1)
Group 1 keywords are used to select the type of basis, i , of the expansion. Three approaches may be
employed:
Wiener: employs standard normal random variables in a transformed probability space, corresponding to
Hermite orthogonal basis polynomials (see wiener).
Askey: employs standard normal, standard uniform, standard exponential, standard beta, and standard
gamma random variables in a transformed probability space, corresponding to Hermite, Legendre, Laguerre, Jacobi, and generalized Laguerre orthogonal basis polynomials, respectively (see askey).
Extended (default if no option is selected): The Extended option avoids the use of any nonlinear variable
transformations by augmenting the Askey approach with numerically-generated orthogonal polynomials for
non-Askey probability density functions. Extended polynomial selections replace each of the sub-optimal
Askey basis selections for bounded normal, lognormal, bounded lognormal, loguniform, triangular, gumbel,
frechet, weibull, and bin-based histogram.
For supporting correlated random variables, certain fallbacks must be implemented.
The Extended option is the default and supports only Gaussian correlations.
If needed to support prescribed correlations (not under user control), the Extended and Askey options will
fall back to the Wiener option on a per variable basis. If the prescribed correlations are also unsupported
by Wiener expansions, then Dakota will exit with an error.

938

CHAPTER 6. KEYWORDS AREA

Refer to variable support for additional information on supported variable types, with and without correlation.
Coefficient estimation approach (Group 2)
To obtain the coefficients i of the expansion, seven options are provided:

1. multidimensional integration by a tensor-product of Gaussian quadrature rules (specified with quadratureorder, and, optionally, dimension preference).
2. multidimensional integration by the Smolyak sparse grid method (specified with sparse grid level
and, optionally, dimension preference)
3. multidimensional integration by Stroud cubature rules and extensions as specified with cubature integrand.
4. multidimensional integration by Latin hypercube sampling (specified with expansion order and expansionsamples).
5. linear regression (specified with expansion order and either collocation points or collocationratio), using either over-determined (least squares) or under-determined (compressed sensing) approaches.
6. orthogonal least interpolation (specified with orthogonal least interpolation and collocationpoints)
7. coefficient import from a file (specified with import expansion file). The expansion can be comprised of a general set of expansion terms, as indicated by the multi-index annotation within the file.
It is important to note that, while quadrature order, sparse grid level, and expansion order
are array inputs, only one scalar from these arrays is active at a time for a particular expansion estimation. These
scalars can be augmented with a dimension preference to support anisotropy across the random dimension
set. The array inputs are present to support advanced use cases such as multifidelity UQ, where multiple grid
resolutions can be employed.
Active Variables
The default behavior is to form expansions over aleatory uncertain continuous variables. To form expansions
over a broader set of variables, one needs to specify active followed by state, epistemic, design, or
all in the variables specification block.
For continuous design, continuous state, and continuous epistemic uncertain variables included in the expansion, Legendre chaos bases are used to model the bounded intervals for these variables. However, these variables
are not assumed to have any particular probability distribution, only that they are independent variables. Moreover, when probability integrals are evaluated, only the aleatory random variable domain is integrated, leaving
behind a polynomial relationship between the statistics and the remaining design/state/epistemic variables.
Covariance type (Group 3)
These two keywords are used to specify how this method computes, stores, and outputs the covariance of the
responses. In particular, the diagonal covariance option is provided for reducing post-processing overhead and
output volume in high dimensional applications.
Optional Keywords regarding method outputs
Each of these sampling specifications refer to sampling on the PCE approximation for the purposes of generating approximate statistics.
sample type
samples
seed
fixed seed

6.2. METHOD

939

rng
probability refinement
distribution
reliability levels
response levels
probability levels
gen reliability levels
which should be distinguished from simulation sampling for generating the PCE coefficients as described in
options 4, 5, and 6 above (although these options will share the sample type, seed, and rng settings, if
provided).
When using the probability refinement control, the number of refinement samples is not under the
users control (these evaluations are approximation-based, so management of this expense is less critical). This
option allows for refinement of probability and generalized reliability results using importance sampling.
Multi-fidelity UQ
The advanced use case of multifidelity UQ automatically becomes active if the model selected for iteration by
the method specification is a multifidelity surrogate model (see hierarchical). In this case, an expansion will first
be formed for the model discrepancy (the difference between response results if additive correction or the
ratio of results if multiplicative correction), using the first quadrature order, sparse grid level, or expansion order value along with any specified refinement strategy. Second, an expansion will
be formed for the low fidelity surrogate model, using the second quadrature order, sparse grid level,
or expansion order value (if present; the first is reused if not present) along with any specified refinement
strategy. Then the two expansions are combined (added or multiplied) into an expansion that approximates the
high fidelity model, from which the final set of statistics are generated. For polynomial chaos expansions, this high
fidelity expansion can differ significantly in form from the low fidelity and discrepancy expansions, particularly
in the multiplicative case where it is expanded to include all of the basis products.
Usage Tips
If n is small (e.g., two or three), then tensor-product Gaussian quadrature is quite effective and can be the
preferred choice. For moderate to large n (e.g., five or more), tensor-product quadrature quickly becomes too
expensive and the sparse grid and regression approaches are preferred. Random sampling for coefficient estimation is generally not recommended due to its slow convergence rate. For incremental studies, approaches 4 and 5
support reuse of previous samples through the incremental lhs and reuse points specifications, respectively.
In the quadrature and sparse grid cases, growth rates for nested and non-nested rules can be synchronized
for consistency. For a non-nested Gauss rule used within a sparse grid, linear one-dimensional growth rules of
m = 2l + 1 are used to enforce odd quadrature orders, where l is the grid level and m is the number of points
in the rule. The precision of this Gauss rule is then i = 2m 1 = 4l + 1. For nested rules, order growth
with level is typically exponential; however, the default behavior is to restrict the number of points to be the
lowest order rule that is available that meets the one-dimensional precision requirement implied by either a level
l for a sparse grid ( i = 4l + 1) or an order m for a tensor grid ( i = 2m 1). This behavior is known as
restricted growth or delayed sequences. To override this default behavior in the case of sparse grids, the
unrestricted keyword can be used; it cannot be overridden for tensor grids using nested rules since it also
provides a mapping to the available nested rule quadrature orders. An exception to the default usage of restricted
growth is the dimension adaptive p refinement generalized sparse grid case described previously,
since the ability to evolve the index sets of a sparse grid in an unstructured manner eliminates the motivation for
restricting the exponential growth of nested rules.
Additional Resources

940

CHAPTER 6. KEYWORDS AREA

Dakota provides access to PCE methods through the NonDPolynomialChaos class. Refer to the Uncertainty
Quantification Capabilities chapter of the Users Manual[4] and the Stochastic Expansion Methods chapter of the
Theory Manual[6] for additional information on the PCE algorithm.

Examples
method,
polynomial_chaos
sparse_grid_level = 2
samples = 10000 seed = 12347 rng rnum2
response_levels = .1 1. 50. 100. 500. 1000.
variance_based_decomp

See Also
These keywords may also be of interest:
adaptive sampling
gpais
local reliability
global reliability
sampling
importance sampling
stoch collocation
p refinement
Keywords Area
method
polynomial chaos
p refinement
Automatic polynomial order refinement

Specification
Alias: none
Argument(s): none
Default: no refinement
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

941
Required(Choose
One)

p-refinement type
(Group 1)

uniform

dimension adaptive

Refine an
expansion
uniformly in all
dimensions.
Perform
anisotropic
expansion
refinement by
preferentially
adapting in
dimensions that are
detected to have
higher
importance.

Description
The p refinement keyword specifies the usage of automated polynomial order refinement, which can be either
uniform or dimension adaptive.
The dimension adaptive option is supported for the tensor-product quadrature and Smolyak sparse grid
options and uniform is supported for tensor and sparse grids as well as regression approaches (collocationpoints or collocation ratio).
Each of these refinement cases makes use of the max iterations and convergence tolerance
method independent controls. The former control limits the number of refinement iterations, and the latter control
terminates refinement when the two-norm of the change in the response covariance matrix (or, in goal-oriented
approaches, the two-norm of change in the statistical quantities of interest (QOI)) falls below the tolerance.
The dimension adaptive case can be further specified to utilize sobol, decay, or generalized
refinement controls. The former two cases employ anisotropic tensor/sparse grids in which the anisotropic dimension preference (leading to anisotropic integrations/expansions with differing refinement levels for different
random dimensions) is determined using either total Sobol indices from variance-based decomposition (sobol
case: high indices result in high dimension preference) or using spectral coefficient decay rates from a rate
estimation technique similar to Richardson extrapolation (decay case: low decay rates result in high dimension preference). In these two cases as well as the uniform refinement case, the quadrature order or
sparse grid level are ramped by one on each refinement iteration until either of the two convergence controls is satisfied. For the uniform refinement case with regression approaches, the expansion order is
ramped by one on each iteration while the oversampling ratio (either defined by collocation ratio or inferred from collocation points based on the initial expansion) is held fixed. Finally, the generalized
dimension adaptive case is the default adaptive approach; it refers to the generalized sparse grid algorithm,
a greedy approach in which candidate index sets are evaluated for their impact on the statistical QOI, the most
influential sets are selected and used to generate additional candidates, and the index set frontier of a sparse grid
is evolved in an unstructured and goal-oriented manner (refer to Users Manual PCE descriptions for additional
specifics).
For the case of p refinement or the case of an explicit nested override, Gauss-Hermite rules are replaced
with Genz-Keister nested rules and Gauss-Legendre rules are replaced with Gauss-Patterson nested rules, both of
which exchange lower integrand precision for greater point reuse.
uniform
Keywords Area

942

CHAPTER 6. KEYWORDS AREA

method
polynomial chaos
p refinement
uniform
Refine an expansion uniformly in all dimensions.

Specification
Alias: none
Argument(s): none

Description
The quadrature order or sparse grid level are ramped by one on each refinement iteration until either of the two
convergence controls is satisfied. For the uniform refinement case with regression approaches, the expansionorder is ramped by one on each iteration while the oversampling ratio (either defined by collocation ratio or
inferred from collocation points based on the initial expansion) is held fixed.

dimension adaptive
Keywords Area
method
polynomial chaos
p refinement
dimension adaptive
Perform anisotropic expansion refinement by preferentially adapting in dimensions that are detected to have
higher importance.

Specification
Alias: none
Argument(s): none

6.2. METHOD

943
Required/Optional
Required(Choose
One)

Description of
Group
dimension
adaptivity
estimation
approach (Group
1)

Dakota Keyword
sobol

Dakota Keyword
Description
Estimate
dimension
preference for
automated
refinement of
stochastic
expansion using
total Sobol
sensitivity indices.

decay

Estimate spectral
coefficient decay
rates to guide
dimensionadaptive
refinement.

generalized

Use the
generalized sparse
grid dimension
adaptive algorithm
to refine a sparse
grid approximation
of stochastic
expansion.

Description
Perform anisotropic expansion refinement by preferentially adapting in dimensions that are detected to hold higher
importance in resolving statistical quantities of interest.
Dimension importance must be estimated as part of the refinement process. Techniques include either sobol or
generalized for stochastic collocation and either sobol, decay, or generalized for polynomial chaos. Each of these
automated refinement approaches makes use of the max iterations and convergence tolerance iteration controls.
sobol
Keywords Area
method
polynomial chaos
p refinement
dimension adaptive
sobol
Estimate dimension preference for automated refinement of stochastic expansion using total Sobol sensitivity
indices.

944

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: generalized

Description
Determine dimension preference for refinement of a stochastic expansion from the total Sobol sensitivity indices
obtained from global sensitivity analysis. High indices indicate high importance for resolving statistical quantities
of interest and therefore result in high dimension preference.

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement sobol
max_iterations = 20
convergence_tol = 1.e-4

decay
Keywords Area
method
polynomial chaos
p refinement
dimension adaptive
decay
Estimate spectral coefficient decay rates to guide dimension-adaptive refinement.

Specification
Alias: none
Argument(s): none

Description
Estimate spectral coefficient decay rates from a rate estimation technique similar to Richardson extrapolation.
These decay rates are used to guide dimension-adaptive refinement, where slower decay rates result in higher
dimension preference.

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement decay
max_iterations = 20
convergence_tol = 1.e-4

6.2. METHOD

945

generalized
Keywords Area
method
polynomial chaos
p refinement
dimension adaptive
generalized
Use the generalized sparse grid dimension adaptive algorithm to refine a sparse grid approximation of stochastic expansion.

Specification
Alias: none
Argument(s): none

Description
The generalized sparse grid algorithm is a greedy approach in which candidate index sets are evaluated for their
impact on the statistical QOI, the most influential sets are selected and used to generate additional candidates,
and the index set frontier of a sparse grid is evolved in an unstructured and goal-oriented manner (refer to Users
Manual PCE descriptions for additional specifics).

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement generalized
max_iterations = 20
convergence_tol = 1.e-4

askey
Keywords Area
method
polynomial chaos
askey
Select the standardized random variables (and associated basis polynomials) from the Askey family that best
match the user-specified random variables.

Specification
Alias: none
Argument(s): none
Default: extended (Askey + numerically-generated)

946

CHAPTER 6. KEYWORDS AREA

Description
The Askey option employs standard normal, standard uniform, standard exponential, standard beta, and standard
gamma random variables in a transformed probability space. These selections correspond to Hermite, Legendre,
Laguerre, Jacobi, and generalized Laguerre orthogonal polynomials, respectively.
Specific mappings for the basis polynomials are based on a closest match criterion, and include Hermite
for normal (optimal) as well as bounded normal, lognormal, bounded lognormal, gumbel, frechet, and weibull
(sub-optimal); Legendre for uniform (optimal) as well as loguniform, triangular, and bin-based histogram (suboptimal); Laguerre for exponential (optimal); Jacobi for beta (optimal); and generalized Laguerre for gamma
(optimal).

See Also
These keywords may also be of interest:
polynomial chaos
wiener
wiener
Keywords Area
method
polynomial chaos
wiener
Use standard normal random variables (along with Hermite orthogonal basis polynomials) when transforming
to a standardized probability space.

Specification
Alias: none
Argument(s): none
Default: extended (Askey + numerically-generated)

Description
The Wiener option employs standard normal random variables in a transformed probability space, corresponding
to a Hermite orthogonal polynomial basis. This is the same nonlinear variable transformation used by local and
global reliability methods (and therefore has the same variable support).

See Also
These keywords may also be of interest:
polynomial chaos
askey

6.2. METHOD

947

quadrature order
Keywords Area
method
polynomial chaos
quadrature order
Cubature using tensor-products of Gaussian quadrature rules

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Optional

Optional(Choose
One)

Description of
Group

Dakota Keyword
dimension preference

Nesting of
quadrature rules
(Group 1)

nested

non nested

Dakota Keyword
Description
A set of weights
specifying the
realtive importance
of each uncertain
variable
(dimension)
Enforce use of
nested quadrature
rules if available
Enforce use of
non-nested
quadrature rules

Description
Multidimensional integration by a tensor-product of Gaussian quadrature rules (specified with quadratureorder, and, optionally, dimension preference). The default rule selection is to employ non nested
Gauss rules including Gauss-Hermite (for normals or transformed normals), Gauss-Legendre (for uniforms or
transformed uniforms), Gauss-Jacobi (for betas), Gauss-Laguerre (for exponentials), generalized Gauss-Laguerre
(for gammas), and numerically-generated Gauss rules (for other distributions when using an Extended basis).
For the case of p refinement or the case of an explicit nested override, Gauss-Hermite rules are replaced
with Genz-Keister nested rules and Gauss-Legendre rules are replaced with Gauss-Patterson nested rules, both of
which exchange lower integrand precision for greater point reuse. By specifying a dimension preference,
where higher preference leads to higher order polynomial resolution, the tensor grid may be rendered anisotropic.
The dimension specified to have highest preference will be set to the specified quadrature order and all
other dimensions will be reduced in proportion to their reduced preference; any non-integral portion is truncated.
To synchronize with tensor-product integration, a tensor-product expansion is used, where the order pi of the
expansion in each dimension is selected to be half of the integrand precision available from the rule in use,
rounded down. In the case of non-nested Gauss rules with integrand precision 2mi 1, pi is one less than the
quadrature order mi in each dimension (a one-dimensional expansion contains the same number of terms, p + 1,
as the number of Gauss points). The total number of terms, N, in a tensor-product expansion involving n uncertain
input variables is
n
Y
N = 1+P =
(pi + 1)
i=1

948

CHAPTER 6. KEYWORDS AREA

In some advanced use cases (e.g., multifidelity UQ), multiple grid resolutions can be employed; for this reason,
the quadrature order specification supports an array input.
dimension preference
Keywords Area
method
polynomial chaos
quadrature order
dimension preference
A set of weights specifying the realtive importance of each uncertain variable (dimension)

Specification
Alias: none
Argument(s): REALLIST
Default: isotropic grids

Description
A set of weights specifying the realtive importance of each uncertain variable (dimension). Using this specification
leada to anisotropic integrations with differing refinement levels for different random dimensions.

See Also
These keywords may also be of interest:
sobol
decay
nested
Keywords Area
method
polynomial chaos
quadrature order
nested
Enforce use of nested quadrature rules if available

Specification
Alias: none
Argument(s): none
Default: quadrature: non nested unless automated refinement; sparse grids: nested

6.2. METHOD

949

Description
Enforce use of nested quadrature rules if available. For instance if the aleatory variables are Gaussian use the
Nested Genz-Keister rule instead of the default non-nested Gauss-Hermite rule variables are
non nested
Keywords Area
method
polynomial chaos
quadrature order
non nested
Enforce use of non-nested quadrature rules

Specification
Alias: none
Argument(s): none

Description
Enforce use of non-nested quadrature rules if available. For instance if the aleatory variables are Gaussian use the
non-nested Gauss-Hermite rule
sparse grid level
Keywords Area
method
polynomial chaos
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

950

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
restricted

unrestricted

Optional

Optional(Choose
One)

dimension preference

Nesting of
quadrature rules
(Group 2)

nested

non nested

Dakota Keyword
Description
Restrict the growth
rates for nested and
non-nested rules
can be
synchronized for
consistency.
Overide the default
restriction of
growth rates for
nested and
non-nested rules
that are by defualt
synchronized for
consistency.
A set of weights
specifying the
realtive importance
of each uncertain
variable
(dimension)
Enforce use of
nested quadrature
rules if available
Enforce use of
non-nested
quadrature rules

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

6.2. METHOD

951

restricted
Keywords Area
method
polynomial chaos
sparse grid level
restricted
Restrict the growth rates for nested and non-nested rules can be synchronized for consistency.

Specification
Alias: none
Argument(s): none
Default: restricted (except for generalized sparse grids)

Description
In the quadrature and sparse grid cases, growth rates for nested and non-nested rules can be synchronized for
consistency. For a non-nested Gauss rule used within a sparse grid, linear one-dimensional growth rules of m =
2l + 1 are used to enforce odd quadrature orders, where l is the grid level and m is the number of points in the
rule. The precision of this Gauss rule is then i = 2m 1 = 4l + 1. For nested rules, order growth with level is
typically exponential; however, the default behavior is to restrict the number of points to be the lowest order rule
that is available that meets the one-dimensional precision requirement implied by either a level l for a sparse grid
( i = 4l + 1) or an order m for a tensor grid ( i = 2m 1). This behavior is known as restricted growth or
delayed sequences. To override this default behavior in the case of sparse grids, the unrestricted keyword can be
used; it cannot be overridden for tensor grids using nested rules since it also provides a mapping to the available
nested rule quadrature orders. An exception to the default usage of restricted growth is the dimension adaptive prefinement generalized sparse grid case described previously, since the ability to evolve the index sets of a sparse
grid in an unstructured manner eliminates the motivation for restricting the exponential growth of nested rules.
unrestricted
Keywords Area
method
polynomial chaos
sparse grid level
unrestricted
Overide the default restriction of growth rates for nested and non-nested rules that are by defualt synchronized
for consistency.

Specification
Alias: none
Argument(s): none

952

CHAPTER 6. KEYWORDS AREA

Description
In the quadrature and sparse grid cases, growth rates for nested and non-nested rules can be synchronized for
consistency. For a non-nested Gauss rule used within a sparse grid, linear one-dimensional growth rules of m =
2l + 1 are used to enforce odd quadrature orders, where l is the grid level and m is the number of points in the
rule. The precision of this Gauss rule is then i = 2m 1 = 4l + 1. For nested rules, order growth with level is
typically exponential; however, the default behavior is to restrict the number of points to be the lowest order rule
that is available that meets the one-dimensional precision requirement implied by either a level l for a sparse grid
( i = 4l + 1) or an order m for a tensor grid ( i = 2m 1). This behavior is known as restricted growth or
delayed sequences. To override this default behavior in the case of sparse grids, the unrestricted keyword can be
used; it cannot be overridden for tensor grids using nested rules since it also provides a mapping to the available
nested rule quadrature orders. An exception to the default usage of restricted growth is the dimension adaptive prefinement generalized sparse grid case described previously, since the ability to evolve the index sets of a sparse
grid in an unstructured manner eliminates the motivation for restricting the exponential growth of nested rules.
dimension preference
Keywords Area
method
polynomial chaos
sparse grid level
dimension preference
A set of weights specifying the realtive importance of each uncertain variable (dimension)

Specification
Alias: none
Argument(s): REALLIST
Default: isotropic grids

Description
A set of weights specifying the realtive importance of each uncertain variable (dimension). Using this specification
leada to anisotropic integrations with differing refinement levels for different random dimensions.

See Also
These keywords may also be of interest:
sobol
decay

6.2. METHOD

953

nested
Keywords Area
method
polynomial chaos
sparse grid level
nested
Enforce use of nested quadrature rules if available

Specification
Alias: none
Argument(s): none
Default: quadrature: non nested unless automated refinement; sparse grids: nested

Description
Enforce use of nested quadrature rules if available. For instance if the aleatory variables are Gaussian use the
Nested Genz-Keister rule instead of the default non-nested Gauss-Hermite rule variables are
non nested
Keywords Area
method
polynomial chaos
sparse grid level
non nested
Enforce use of non-nested quadrature rules

Specification
Alias: none
Argument(s): none

Description
Enforce use of non-nested quadrature rules if available. For instance if the aleatory variables are Gaussian use the
non-nested Gauss-Hermite rule

954

CHAPTER 6. KEYWORDS AREA

cubature integrand
Keywords Area
method
polynomial chaos
cubature integrand
Cubature using Stroud rules and their extensions

Specification
Alias: none
Argument(s): INTEGER

Description
Multi-dimensional integration by Stroud cubature rules [77] and extensions [90], as specified with cubature integrand. A total-order expansion is used, where the isotropic order p of the expansion is half of the integrand
order, rounded down. The total number of terms N for an isotropic total-order expansion of order p over n variables
is given by
p
s1
X
1 Y
(n + p)!
N = 1+P = 1+
(n + r) =
s!
n!p!
s=1
r=0
Since the maximum integrand order is currently five for normal and uniform and two for all other types, at most
second- and first-order expansions, respectively, will be used. As a result, cubature is primarily useful for global
sensitivity analysis, where the Sobol indices will provide main effects and, at most, two-way interactions. In
addition, the random variable set must be independent and identically distributed (iid), so the use of askey or
wiener transformations may be required to create iid variable sets in the transformed space (as well as to allow
usage of the higher order cubature rules for normal and uniform). Note that global sensitivity analysis often
assumes uniform bounded regions, rather than precise probability distributions, so the iid restriction would not be
problematic in that case.
expansion order
Keywords Area
method
polynomial chaos
expansion order
The (initial) order of a polynomial expansion

Specification
Alias: none
Argument(s): INTEGERLIST

6.2. METHOD

955
Required/Optional
Optional

Description of
Group

dimension preference

Optional

Required(Choose
One)

Dakota Keyword

basis type

collocation points
Group 1

collocation ratio

expansion samples

Optional

import build points file

Dakota Keyword
Description
A set of weights
specifying the
realtive importance
of each uncertain
variable
(dimension)
Specify the type of
truncation to be
used with a
Polynomial Chaos
Expansion.
Specify the
number of
collocation points
used to estimate
PCE coefficients
using regression or
orthogonal-leastinterpolation.
Set the number of
points used to
build a PCE via
regression to be
proportional to the
number of terms in
the expansion.
The Number
simulation samples
to estimate the
PCE coefficients
File containing
points you wish to
use to build a
surrogate

Description
When the expansion order for a a polynomial chaos expansion is specified, the coefficients may be computed
by integration based on random samples or by regression using either random or sub-sampled tensor product
quadrature points.
Multidimensional integration by Latin hypercube sampling (specified with expansion samples). In this
case, the expansion order p cannot be inferred from the numerical integration specification and it is necessary to
provide an expansion order to specify p for a total-order expansion.
Linear regression (specified with either collocation points or collocation ratio). A total-order
expansion is used and must be specified using expansion order as described in the previous option. To
avoid requiring the user to calculate N from n and p), the collocation ratio allows for specification of a

956

CHAPTER 6. KEYWORDS AREA

constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this
case, the number of samples becomes cN o where c is the collocation ratio and o is the ratio order.
The use derivatives flag informs the regression approach to include derivative matching equations (limited
to gradients at present) in the least squares solutions, enabling the use of fewer collocation points for a given
cN o
expansion order and dimension (number of points required becomes n+1
). When admissible, a constrained least
squares approach is employed in which response values are first reproduced exactly and error in reproducing
response derivatives is minimized. Two collocation grid options are supported: the default is Latin hypercube
sampling (point collocation), and an alternate approach of probabilistic collocation is also available through
inclusion of the tensor grid keyword. In this alternate case, the collocation grid is defined using a subset of
tensor-product quadrature points: the order of the tensor-product grid is selected as one more than the expansion
order in each dimension (to avoid sampling at roots of the basis polynomials) and then the tensor multi-index is
uniformly sampled to generate a non-repeated subset of tensor quadrature points.
If collocation points or collocation ratio is specified, the PCE coefficients will be determined
by regression. If no regression specification is provided, appropriate defaults are defined. Specifically SVD-based
least-squares will be used for solving over-determined systems and under-determined systems will be solved
using LASSO. For the situation when the number of function values is smaller than the number of terms in a
PCE, but the total number of samples including gradient values is greater than the number of terms, the resulting
over-determined system will be solved using equality constrained least squares. Technical information on the
various methods listed below can be found in the Linear regression section of the Theory Manual. Some of the
regression methods (OMP, LASSO, and LARS) are able to produce a set of possible PCE coefficient vectors
(see the Linear regression section in the Theory Manual). If cross validation is inactive, then only one solution,
consistent with the noise tolerance, will be returned. If cross validation is active, Dakota will choose
between possible coefficient vectors found internally by the regression method across the set of expansion orders
(1,...,expansion order) and the set of specified noise tolerances and return the one with the lowest cross
validation error indicator.
dimension preference
Keywords Area
method
polynomial chaos
expansion order
dimension preference
A set of weights specifying the realtive importance of each uncertain variable (dimension)

Specification
Alias: none
Argument(s): REALLIST
Default: isotropic grids

Description
A set of weights specifying the realtive importance of each uncertain variable (dimension). Using this specification
leada to anisotropic integrations with differing refinement levels for different random dimensions.

6.2. METHOD

957

See Also
These keywords may also be of interest:
sobol
decay
basis type
Keywords Area
method
polynomial chaos
expansion order
basis type
Specify the type of truncation to be used with a Polynomial Chaos Expansion.

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
tensor product

total order

adapted

Description
Specify the type of truncation to be used with a Polynomial Chaos Expansion.

Dakota Keyword
Description
Use a
tensor-product
index set to
construct a
polynomial chaos
expansion.
Use a total-order
index set to
construct a
polynomial chaos
expansion.
Use adaptive basis
selection to choose
the basis terms in a
polynomial chaos
expansion.

958

CHAPTER 6. KEYWORDS AREA

tensor product
Keywords Area
method
polynomial chaos
expansion order
basis type
tensor product
Use a tensor-product index set to construct a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none

Description
Use a tensor-product index set to construct a polynomial chaos expansion. That is for a given order p keep all
terms with d-dimensional multi index i = (i1 , . . . , id ) that satisfies
max (i1 , . . . , id ) p

total order
Keywords Area
method
polynomial chaos
expansion order
basis type
total order
Use a total-order index set to construct a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none

6.2. METHOD

959

Description
Use the traditional total-order index set to construct a polynomial chaos expansion. That is for a given order p
keep all terms with a d-dimensional multi index i = (i1 , . . . , id ) that satisfies
d
X

ik p

k=1

adapted
Keywords Area
method
polynomial chaos
expansion order
basis type
adapted
Use adaptive basis selection to choose the basis terms in a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
advancements

soft convergence limit

Dakota Keyword
Description
The maximum
number of steps
used to expand a
basis step.
The maximum
number of times no
improvement in
cross validation
error is allowed
before the
algorithm is
terminated.

Description
Use adaptive basis selection to choose the basis terms in a polynomial chaos expansion. Basis selection uses
compressed sensing to identify a initial set of non zero PCE coefficients. Then these non-zero terms are expanded
a set number of times (we suggest 3) and compressed sensing is then applied to these three new index sets. Cross
valiation is used to choose the best candidate basis. The best basis is then restricted again to the non-zero terms
and expanded until no improvement can be gained by adding additional terms.

960

CHAPTER 6. KEYWORDS AREA

advancements
Keywords Area
method
polynomial chaos
expansion order
basis type
adapted
advancements
The maximum number of steps used to expand a basis step.

Specification
Alias: none
Argument(s): INTEGER

Description
Use adaptive basis selection to choose the basis terms in a polynomial chaos expansion. Basis selection uses
compressed sensing to identify a initial set of non zero PCE coefficients. Then these non-zero terms are expanded
a set number of times (we suggest 3) and compressed sensing is then applied to these three new index sets. Cross
valiation is used to choose the best candidate basis. The best basis is then restricted again to the non-zero terms
and expanded until no improvement can be gained by adding additional terms.

See Also
These keywords may also be of interest:
adapted
soft convergence limit
Keywords Area
method
polynomial chaos
expansion order
basis type
adapted
soft convergence limit
The maximum number of times no improvement in cross validation error is allowed before the algorithm is
terminated.

6.2. METHOD

961

Specification
Alias: none
Argument(s): INTEGER

Description
Use adaptive basis selection to choose the basis terms in a polynomial chaos expansion. Basis selection uses
compressed sensing to identify a initial set of non zero PCE coefficients. Then these non-zero terms are expanded
a set number of times (we suggest 3) and compressed sensing is then applied to these three new index sets. Cross
valiation is used to choose the best candidate basis. The best basis is then restricted again to the non-zero terms
and expanded until no improvement can be gained by adding additional terms.

See Also
These keywords may also be of interest:
adapted

collocation points
Keywords Area
method
polynomial chaos
expansion order
collocation points
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonalleast-interpolation.

Specification
Alias: none
Argument(s): INTEGERLIST

962

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
ratio order

least squares
Optional(Choose
One)

Group 1
orthogonal matching pursuit

basis pursuit

Dakota Keyword
Description
Specify a
non-linear the
relationship
between the
expansion order of
a polynomial chaos
expansion and the
number of samples
that will be used to
compute the PCE
coefficients.
Compute the
coefficients of a
polynomial
expansion using
least squares
Compute the
coefficients of a
polynomial
expansion using
orthogonal
matching pursuit
(OMP)
Compute the
coefficients of a
polynomial
expansion by
solving the Basis
Pursuit
`1 -minimization
problem using
linear
programming.

6.2. METHOD

963
basis pursuit denoising

least angle regression

least absolute shrinkage

Optional

cross validation

Optional

use derivatives

Optional

tensor grid

Compute the
coefficients of a
polynomial
expansion by
solving the Basis
Pursuit Denoising
`1 -minimization
problem using
second order cone
optimization.
Compute the
coefficients of a
polynomial
expansion by using
the greedy least
angle regression
(LAR) method.
Compute the
coefficients of a
polynomial
expansion by using
the LASSO
problem.
Use cross
validation to
choose the best
polynomial order
of a polynomial
chaos expansion.
Use derivative data
to construct
surrogate models
Use sub-sampled
tensor-product
quadrature points
to build a
polynomial chaos
expansion.

964

CHAPTER 6. KEYWORDS AREA

Optional

reuse points

This describes the

behavior of reuse
of points in
constructing
polynomial chaos
expansion models.

Description
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonal-leastinterpolation.
ratio order
Keywords Area
method
polynomial chaos
expansion order
collocation points
ratio order
Specify a non-linear the relationship between the expansion order of a polynomial chaos expansion and the
number of samples that will be used to compute the PCE coefficients.

Specification
Alias: none
Argument(s): REAL
Default: 1.

Description
When using regression type methods (specified with either collocation points or collocation ratio), a total-order
expansion can be specified using expansion order. To avoid requiring the user to calculate N from n and p), the
collocation ratio allows for specification of a constant factor applied to N (e.g., collocation ratio = 2. produces
samples = 2N). In addition, the default linear relationship with N can be overridden using a real-valued exponent
specified using ratio order. In this case, the number of samples becomes $cN o$ where $c$ is the collocation ratio and $o$ is the ratio order.
least squares
Keywords Area
method
polynomial chaos
expansion order

6.2. METHOD

965

collocation points
least squares
Compute the coefficients of a polynomial expansion using least squares

Specification
Alias: none
Argument(s): none
Default: svd
Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
svd

equality constrained

Dakota Keyword
Description
Calculate the
coefficients of a
polynomial chaos
expansion using
the singular value
decomposition.
Calculate the
coefficients of a
polynomial chaos
expansion using
equality
constrained least
squares.

Description
Compute the coefficients of a polynomial expansion using least squares. Specifically SVD-based least-squares
will be used for solving over-determined systems. For the situation when the number of function values is smaller
than the number of terms in a PCE, but the total number of samples including gradient values is greater than the
number of terms, the resulting over-determined system will be solved using equality constrained least squares
svd
Keywords Area
method
polynomial chaos
expansion order
collocation points
least squares
svd
Calculate the coefficients of a polynomial chaos expansion using the singular value decomposition.

966

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
Calculate the coefficients of a polynomial chaos expansion using the singular value decomposition. When the
number of model runs exceeds the number of terms in the PCE, the solution returned will be the least-squares
solution, otherwise the solution will be the minimum norm solution computed using the pseudo-inverse.
equality constrained
Keywords Area
method
polynomial chaos
expansion order
collocation points
least squares
equality constrained
Calculate the coefficients of a polynomial chaos expansion using equality constrained least squares.

Specification
Alias: none
Argument(s): none

Description
Calculate the coefficients of a polynomial chaos expansion using equality constrained least squares.
orthogonal matching pursuit
Keywords Area
method
polynomial chaos
expansion order
collocation points
orthogonal matching pursuit
Compute the coefficients of a polynomial expansion using orthogonal matching pursuit (OMP)

Specification
Alias: omp
Argument(s): none

6.2. METHOD

967
Required/Optional
Optional

Description of
Group

Dakota Keyword
noise tolerance

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.

Description
Compute the coefficients of a polynomial expansion using orthogonal matching pursuit (OMP). Orthogonal
matching pursuit (OMP) is a greedy algorithm that is usefult when solving underdetermined linear systems.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation points
orthogonal matching pursuit
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
basis pursuit
Keywords Area
method
polynomial chaos
expansion order
collocation points

968

CHAPTER 6. KEYWORDS AREA

basis pursuit

Compute the coefficients of a polynomial expansion by solving the Basis Pursuit `1 -minimization problem
using linear programming.

Specification
Alias: bp
Argument(s): none

Description
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit `1 -minimization problem using
linear programming.
basis pursuit denoising
Keywords Area
method
polynomial chaos
expansion order
collocation points
basis pursuit denoising
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit Denoising `1 -minimization
problem using second order cone optimization.

Specification
Alias: bpdn
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
noise tolerance

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.

Description
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit Denoising `1 -minimization
problem using second order cone optimization.

6.2. METHOD

969

noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation points
basis pursuit denoising
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
least angle regression
Keywords Area
method
polynomial chaos
expansion order
collocation points
least angle regression
Compute the coefficients of a polynomial expansion by using the greedy least angle regression (LAR) method.

Specification
Alias: lars
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

970

CHAPTER 6. KEYWORDS AREA

Optional

noise tolerance

The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.

Description
Compute the coefficients of a polynomial expansion by using the greedy least angle regression (LAR) method.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation points
least angle regression
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
least absolute shrinkage
Keywords Area
method
polynomial chaos
expansion order
collocation points
least absolute shrinkage
Compute the coefficients of a polynomial expansion by using the LASSO problem.

6.2. METHOD

971

Specification
Alias: lasso
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
noise tolerance

l2 penalty

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.
The l2 pentalty
used when
performing
compressed
sensing with
elastic net.

Description
Compute the coefficients of a polynomial expansion by using the LASSO problem.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation points
least absolute shrinkage
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

972

CHAPTER 6. KEYWORDS AREA

l2 penalty
Keywords Area
method
polynomial chaos
expansion order
collocation points
least absolute shrinkage
l2 penalty
The l2 pentalty used when performing compressed sensing with elastic net.

Specification
Alias: none
Argument(s): REAL
Default: 0. (reverts to standard LASSO formulation)

Description
The l2 pentalty used when performing compressed sensing with elastic net.
cross validation
Keywords Area
method
polynomial chaos
expansion order
collocation points
cross validation
Use cross validation to choose the best polynomial order of a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none

Description
Use cross validation to choose the best polynomial degree of a polynomial chaos expansion. 10 fold cross
validation is used to estimate the cross validation error of a total-order polynomial expansion for orders 1 through
to order. The order chosen is the one that produces the lowest cross validation error. If there are not enough points
to perform 10 fold cross validation then one-at-a-time cross validation will be performed.

6.2. METHOD

973

use derivatives
Keywords Area
method
polynomial chaos
expansion order
collocation points
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
tensor grid
Keywords Area
method
polynomial chaos
expansion order
collocation points
tensor grid
Use sub-sampled tensor-product quadrature points to build a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none
Default: regression with LHS sample set (point collocation)

974

CHAPTER 6. KEYWORDS AREA

Description
Tthe collocation grid is defined using a subset of tensor-product quadrature points: the order of the tensor-product
grid is selected as one more than the expansion order in each dimension (to avoid sampling at roots of the basis
polynomials) and then the tensor multi-index is uniformly sampled to generate a non-repeated subset of tensor
quadrature points.
reuse points
Keywords Area
method
polynomial chaos
expansion order
collocation points
reuse points
This describes the behavior of reuse of points in constructing polynomial chaos expansion models.

Specification
Alias: reuse samples
Argument(s): none
Default: no sample reuse in coefficient estimation

Description
The reuse points option controls the reuse behavior of points for various types of polynomial chaos expansions, including: collocation points, collocation ratio, expansion samples, or orthogonalleast interpolation. If any of these approaches are specified to create a set of points for the polynomial
chaos expansion, one can specify reuse points so that any points that have been previously generated (for
example, from the import points file) can be reused.
collocation ratio
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion.

Specification
Alias: none
Argument(s): REAL

6.2. METHOD

975
Required/Optional
Optional

Description of
Group

Dakota Keyword
ratio order

least squares
Optional(Choose
One)

Group 1
orthogonal matching pursuit

basis pursuit

Dakota Keyword
Description
Specify a
non-linear the
relationship
between the
expansion order of
a polynomial chaos
expansion and the
number of samples
that will be used to
compute the PCE
coefficients.
Compute the
coefficients of a
polynomial
expansion using
least squares
Compute the
coefficients of a
polynomial
expansion using
orthogonal
matching pursuit
(OMP)
Compute the
coefficients of a
polynomial
expansion by
solving the Basis
Pursuit
`1 -minimization
problem using
linear
programming.

976

CHAPTER 6. KEYWORDS AREA

basis pursuit denoising

least angle regression

least absolute shrinkage

Optional

cross validation

Optional

use derivatives

Optional

tensor grid

Compute the
coefficients of a
polynomial
expansion by
solving the Basis
Pursuit Denoising
`1 -minimization
problem using
second order cone
optimization.
Compute the
coefficients of a
polynomial
expansion by using
the greedy least
angle regression
(LAR) method.
Compute the
coefficients of a
polynomial
expansion by using
the LASSO
problem.
Use cross
validation to
choose the best
polynomial order
of a polynomial
chaos expansion.
Use derivative data
to construct
surrogate models
Use sub-sampled
tensor-product
quadrature points
to build a
polynomial chaos
expansion.

6.2. METHOD

977
Optional

reuse points

This describes the

behavior of reuse
of points in
constructing
polynomial chaos
expansion models.

Description
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion. To avoid requiring the user to calculate N from n and p, the collocation ratio allows for specification
of a constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this case,
the number of samples becomes cN o where c is the collocation ratio and o is the ratio order. The use derivatives
flag informs the regression approach to include derivative matching equations (limited to gradients at present) in
the least squares solutions, enabling the use of fewer collocation points for a given expansion order and dimension
cN o
(number of points required becomes n+1
).
ratio order
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
ratio order
Specify a non-linear the relationship between the expansion order of a polynomial chaos expansion and the
number of samples that will be used to compute the PCE coefficients.

Specification
Alias: none
Argument(s): REAL
Default: 1.

Description
When using regression type methods (specified with either collocation points or collocation ratio), a total-order
expansion can be specified using expansion order. To avoid requiring the user to calculate N from n and p), the
collocation ratio allows for specification of a constant factor applied to N (e.g., collocation ratio = 2. produces
samples = 2N). In addition, the default linear relationship with N can be overridden using a real-valued exponent
specified using ratio order. In this case, the number of samples becomes $cN o$ where $c$ is the collocation ratio and $o$ is the ratio order.

978

CHAPTER 6. KEYWORDS AREA

least squares
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
least squares
Compute the coefficients of a polynomial expansion using least squares

Specification
Alias: none
Argument(s): none
Default: svd
Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
svd

equality constrained

Dakota Keyword
Description
Calculate the
coefficients of a
polynomial chaos
expansion using
the singular value
decomposition.
Calculate the
coefficients of a
polynomial chaos
expansion using
equality
constrained least
squares.

Description
Compute the coefficients of a polynomial expansion using least squares. Specifically SVD-based least-squares
will be used for solving over-determined systems. For the situation when the number of function values is smaller
than the number of terms in a PCE, but the total number of samples including gradient values is greater than the
number of terms, the resulting over-determined system will be solved using equality constrained least squares
svd
Keywords Area
method
polynomial chaos
expansion order

6.2. METHOD

979

collocation ratio
least squares
svd
Calculate the coefficients of a polynomial chaos expansion using the singular value decomposition.

Specification
Alias: none
Argument(s): none

Description
Calculate the coefficients of a polynomial chaos expansion using the singular value decomposition. When the
number of model runs exceeds the number of terms in the PCE, the solution returned will be the least-squares
solution, otherwise the solution will be the minimum norm solution computed using the pseudo-inverse.
equality constrained
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
least squares
equality constrained
Calculate the coefficients of a polynomial chaos expansion using equality constrained least squares.

Specification
Alias: none
Argument(s): none

Description
Calculate the coefficients of a polynomial chaos expansion using equality constrained least squares.

980

CHAPTER 6. KEYWORDS AREA

orthogonal matching pursuit
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
orthogonal matching pursuit
Compute the coefficients of a polynomial expansion using orthogonal matching pursuit (OMP)

Specification
Alias: omp
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
noise tolerance

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.

Description
Compute the coefficients of a polynomial expansion using orthogonal matching pursuit (OMP). Orthogonal
matching pursuit (OMP) is a greedy algorithm that is usefult when solving underdetermined linear systems.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
orthogonal matching pursuit
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

6.2. METHOD

981

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
basis pursuit
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
basis pursuit
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit `1 -minimization problem
using linear programming.

Specification
Alias: bp
Argument(s): none

Description
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit `1 -minimization problem using
linear programming.
basis pursuit denoising
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
basis pursuit denoising
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit Denoising `1 -minimization
problem using second order cone optimization.

Specification
Alias: bpdn
Argument(s): none

982

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
noise tolerance

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.

Description
Compute the coefficients of a polynomial expansion by solving the Basis Pursuit Denoising `1 -minimization
problem using second order cone optimization.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
basis pursuit denoising
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
least angle regression
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
least angle regression
Compute the coefficients of a polynomial expansion by using the greedy least angle regression (LAR) method.

6.2. METHOD

983

Specification
Alias: lars
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
noise tolerance

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.

Description
Compute the coefficients of a polynomial expansion by using the greedy least angle regression (LAR) method.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
least angle regression
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
least absolute shrinkage
Keywords Area
method
polynomial chaos

984

CHAPTER 6. KEYWORDS AREA

expansion order
collocation ratio
least absolute shrinkage
Compute the coefficients of a polynomial expansion by using the LASSO problem.

Specification
Alias: lasso
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
noise tolerance

l2 penalty

Dakota Keyword
Description
The noise
tolerance used
when performing
cross validation in
the presence of
noise or truncation
errors.
The l2 pentalty
used when
performing
compressed
sensing with
elastic net.

Description
Compute the coefficients of a polynomial expansion by using the LASSO problem.
noise tolerance
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
least absolute shrinkage
noise tolerance
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.

Specification
Alias: none
Argument(s): REALLIST
Default: 1e-3 for BPDN, 0. otherwise (algorithms run until termination)

6.2. METHOD

Description
The noise tolerance used when performing cross validation in the presence of noise or truncation errors.
l2 penalty
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
least absolute shrinkage
l2 penalty
The l2 pentalty used when performing compressed sensing with elastic net.

Specification
Alias: none
Argument(s): REAL
Default: 0. (reverts to standard LASSO formulation)

Description
The l2 pentalty used when performing compressed sensing with elastic net.
cross validation
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
cross validation
Use cross validation to choose the best polynomial order of a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none

985

986

CHAPTER 6. KEYWORDS AREA

Description
Use cross validation to choose the best polynomial degree of a polynomial chaos expansion. 10 fold cross
validation is used to estimate the cross validation error of a total-order polynomial expansion for orders 1 through
to order. The order chosen is the one that produces the lowest cross validation error. If there are not enough points
to perform 10 fold cross validation then one-at-a-time cross validation will be performed.
use derivatives
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
tensor grid
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
tensor grid
Use sub-sampled tensor-product quadrature points to build a polynomial chaos expansion.

6.2. METHOD

987

Specification
Alias: none
Argument(s): none
Default: regression with LHS sample set (point collocation)

Description
Tthe collocation grid is defined using a subset of tensor-product quadrature points: the order of the tensor-product
grid is selected as one more than the expansion order in each dimension (to avoid sampling at roots of the basis
polynomials) and then the tensor multi-index is uniformly sampled to generate a non-repeated subset of tensor
quadrature points.
reuse points
Keywords Area
method
polynomial chaos
expansion order
collocation ratio
reuse points
This describes the behavior of reuse of points in constructing polynomial chaos expansion models.

Specification
Alias: reuse samples
Argument(s): none
Default: no sample reuse in coefficient estimation

Description
The reuse points option controls the reuse behavior of points for various types of polynomial chaos expansions, including: collocation points, collocation ratio, expansion samples, or orthogonalleast interpolation. If any of these approaches are specified to create a set of points for the polynomial
chaos expansion, one can specify reuse points so that any points that have been previously generated (for
example, from the import points file) can be reused.
expansion samples
Keywords Area
method
polynomial chaos
expansion order
expansion samples
The Number simulation samples to estimate the PCE coefficients

988

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
reuse points

incremental lhs

Dakota Keyword
Description
This describes the
behavior of reuse
of points in
constructing
polynomial chaos
expansion models.
Augments an
existing Latin
Hypercube
Sampling (LHS)
study

Description
The Number simulation samples to estimate the PCE coefficients In this case, the expansion order p cannot be
inferred from the numerical integration specification and it is necessary to provide an expansion order to specify
p for a total-order expansion.
reuse points
Keywords Area
method
polynomial chaos
expansion order
expansion samples
reuse points
This describes the behavior of reuse of points in constructing polynomial chaos expansion models.

Specification
Alias: reuse samples
Argument(s): none
Default: no sample reuse in coefficient estimation

Description
The reuse points option controls the reuse behavior of points for various types of polynomial chaos expansions, including: collocation points, collocation ratio, expansion samples, or orthogonalleast interpolation. If any of these approaches are specified to create a set of points for the polynomial
chaos expansion, one can specify reuse points so that any points that have been previously generated (for
example, from the import points file) can be reused.

6.2. METHOD

989

incremental lhs
Keywords Area
method
polynomial chaos
expansion order
expansion samples
incremental lhs
Augments an existing Latin Hypercube Sampling (LHS) study

Specification
Alias: none
Argument(s): none
Default: no sample reuse in coefficient estimation

Description
incremental lhs will augment an existing LHS sampling study with more samples to get better estimates
of mean, variance, and percentiles. The number of samples in the second set MUST currently be 2 times the
number of previous samples, although incremental sampling based on any power of two may be supported in
future releases.
Default Behavior
Incremental Latin Hypercube Sampling is not used by default. To change this behavior, the incrementallhs keyword must be specified in conjuction with the sample type keyword. Additionally, a previous LHS
(or incremental LHS) sampling study with sample size N must have already been performed, and the dakota
restart file must be available from this previous study. The variables and responses specifications must be
the same in both studies. Incremental LHS sampling support both continuous uncertain variables and discrete
uncertain variables such as discrete distributions (e.g. binomial, Poisson, etc.) as well as histogram variables and
uncertain set types.
Usage Tips
The incremental approach is useful if it is uncertain how many simulations can be completed within available
time.
See the examples below and the Usage and Restarting Dakota Studies pages.

Examples
For example, say a user performs an initial study using lhs as the sample type, and generates 10 samples.
One way to ensure the restart file is saved is to specify a non-default name, via a command line option:
dakota -i LHS_10.in -w LHS_10.rst

which uses the input file:

# LHS_10.in
environment
tabular_data
tabular_data_file = lhs10.dat

990

CHAPTER 6. KEYWORDS AREA

method
sampling
sample_type lhs
samples = 10
model
single
variables
uniform_uncertain = 2
descriptors =
input1
input2
lower_bounds = -2.0
-2.0
upper_bounds =
2.0
2.0
interface
analysis_drivers text_book
fork
responses
response_functions = 1
no_gradients
no_hessians

and the restart file is written to LHS 10.rst.

Then an incremental LHS study can be run with:
dakota -i LHS_20.in -r LHS_10.rst -w LHS_20.rst

where LHS 20.in is shown below, and LHS 10.rst is the restart file containing the results of the previous LHS
study.
# LHS_20.in
environment
tabular_data
tabular_data_file = lhs_incremental_20.dat
method
sampling
sample_type incremental_lhs
samples = 20
previous_samples = 10
model
single
variables
uniform_uncertain = 2
descriptors =
input1
input2
lower_bounds = -2.0
-2.0
upper_bounds =
2.0
2.0
interface
analysis_drivers text_book
fork
responses
response_functions = 1
no_gradients
no_hessians

6.2. METHOD

991

The user will get 10 new LHS samples which maintain both the correlation and stratification of the original
LHS sample. The new samples will be combined with the original samples to generate a combined sample of size
20.
This is clearly seen by comparing the two tabular data files.
import build points file
Keywords Area
method
polynomial chaos
expansion order
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:

992

CHAPTER 6. KEYWORDS AREA

annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
polynomial chaos
expansion order
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id

6.2. METHOD

993

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
polynomial chaos
expansion order
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

994

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
header
Keywords Area
method
polynomial chaos
expansion order
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
polynomial chaos
expansion order
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

995

996

CHAPTER 6. KEYWORDS AREA

interface id
Keywords Area
method
polynomial chaos
expansion order
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
polynomial chaos
expansion order
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

6.2. METHOD

997

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
polynomial chaos
expansion order
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

998

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
orthogonal least interpolation
Keywords Area
method
polynomial chaos
orthogonal least interpolation
Build a polynomial chaos expansion from simulation samples using orthogonal least interpolation.

Specification
Alias: least interpolation oli
Argument(s): none
Required/Optional
Required

Optional

Description of
Group

Dakota Keyword
collocation points

cross validation

Dakota Keyword
Description
Specify the
number of
collocation points
used to estimate
PCE coefficients
using orthogonal
least interpolation
Use cross
validation to
choose the best
polynomial order
of a polynomial
chaos expansion.

6.2. METHOD

999
Optional

tensor grid

Optional

reuse points

Optional

import build points file

Use sub-sampled
tensor-product
quadrature points
to build a
polynomial chaos
expansion.
This describes the
behavior of reuse
of points in
constructing
polynomial chaos
expansion models.
File containing
points you wish to
use to build a
surrogate

Description
Build a polynomial chaos expansion from simulation samples using orthogonal least interpolation. Unlike the
other regression methods expansion order cannot be set. OLI will produce the lowest degree polynomial
that interpolates the data
collocation points
Keywords Area
method
polynomial chaos
orthogonal least interpolation
collocation points
Specify the number of collocation points used to estimate PCE coefficients using orthogonal least interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Specify the number of collocation points used to estimate PCE coefficients using orthogonal least interpolation
cross validation
Keywords Area
method

1000

CHAPTER 6. KEYWORDS AREA

polynomial chaos
orthogonal least interpolation
cross validation
Use cross validation to choose the best polynomial order of a polynomial chaos expansion.

Specification
Alias: none
Argument(s): none

Description
Use cross validation to choose the best polynomial degree of a polynomial chaos expansion. 10 fold cross
validation is used to estimate the cross validation error of a total-order polynomial expansion for orders 1 through
to order. The order chosen is the one that produces the lowest cross validation error. If there are not enough points
to perform 10 fold cross validation then one-at-a-time cross validation will be performed.
tensor grid
Keywords Area
method
polynomial chaos
orthogonal least interpolation
tensor grid
Use sub-sampled tensor-product quadrature points to build a polynomial chaos expansion.

Specification
Alias: none
Argument(s): INTEGERLIST
Default: regression with LHS sample set (point collocation)

Description
Tthe collocation grid is defined using a subset of tensor-product quadrature points: the order of the tensor-product
grid is selected as one more than the expansion order in each dimension (to avoid sampling at roots of the basis
polynomials) and then the tensor multi-index is uniformly sampled to generate a non-repeated subset of tensor
quadrature points.

6.2. METHOD

1001

reuse points
Keywords Area
method
polynomial chaos
orthogonal least interpolation
reuse points
This describes the behavior of reuse of points in constructing polynomial chaos expansion models.

Specification
Alias: reuse samples
Argument(s): none
Default: no sample reuse in coefficient estimation

Description
The reuse points option controls the reuse behavior of points for various types of polynomial chaos expansions, including: collocation points, collocation ratio, expansion samples, or orthogonalleast interpolation. If any of these approaches are specified to create a set of points for the polynomial
chaos expansion, one can specify reuse points so that any points that have been previously generated (for
example, from the import points file) can be reused.
import build points file
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

1002

CHAPTER 6. KEYWORDS AREA

Optional(Choose
One)

Optional

tabular format
(Group 1)

annotated

Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
annotated
Selects annotated tabular file format

6.2. METHOD

1003

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1004

CHAPTER 6. KEYWORDS AREA

custom annotated
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior

6.2. METHOD

1005

The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

1006
eval id
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1007

freeform
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1008

CHAPTER 6. KEYWORDS AREA

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

active only
Keywords Area
method
polynomial chaos
orthogonal least interpolation
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.

6.2. METHOD

1009

import expansion file

Keywords Area
method
polynomial chaos
import expansion file
Build a Polynomial Chaos Expansion (PCE) by import coefficients and a multi-index from a file

Specification
Alias: none
Argument(s): STRING

Description
The coefficients can be specified in an arbitrary order. The multi-index provided is used to generate a sparse
expansion that conists only of the indices corresponding to the non-zero coefficients provided in the file.
variance based decomp
Keywords Area
method
polynomial chaos
variance based decomp
Activates global sensitivity analysis based on decomposition of response variance into main, interaction, and
total effects

Specification
Alias: none
Argument(s): none
Default: no variance-based decomposition
Required/Description of
Optional
Group
Optional

Dakota Keyword
interaction order

Dakota Keyword
Description
Specify the
maximum number
of variables
allowed in an
interaction when
reporting
interaction metrics.

1010

CHAPTER 6. KEYWORDS AREA

Optional

drop tolerance

Suppresses output
of sensitivity
indices with values
lower than this
tolerance

Description
Dakota can calculate sensitivity indices through variance-based decomposition using the keyword variancebased decomp. This approach decomposes main, interaction, and total effects in order to identify the most
important variables and combinations of variables in contributing to the variance of output quantities of interest.
Default Behavior
Because of processing overhead and output volume, variance based decomp is inactive by default,
unless required for dimension-adaptive refinement using Sobol indices.
Expected Outputs
When variance based decomp is specified, sensitivity indices for main effects, total effects, and any
interaction effects will be reported. Each of these effects represents the percent contribution to the variance
in the model response, where main effects include the aggregated set of univariate terms for each individual
variable, interaction effects represent the set of mixed terms (the complement of the univariate set), and total effects
represent the complete set of terms (univariate and mixed) that contain each individual variable. The aggregated
set of main and interaction sensitivity indices will sum to one, whereas the sum of total effects sensitivity indices
will be greater than one due to redundant counting of mixed terms.
Usage Tips
An important consideration is that the number of possible interaction terms grows exponentially with dimension and expansion order. To mitigate this, both in terms of compute time and output volume, possible interaction
effects are suppressed whenever no contributions are present due to the particular form of an expansion. In addition, the interaction order and drop tolerance controls can further limit the computational and output
requirements.

Examples
method,
polynomial_chaos # or stoch_collocation
sparse_grid_level = 3
variance_based_decomp interaction_order = 2

Theory
In this context, we take sensitivity analysis to be global, not local as when calculating derivatives of output
variables with respect to input variables. Our definition is similar to that of[73] : The study of how uncertainty
in the output of a model can be apportioned to different sources of uncertainty in the model input.
Variance based decomposition is a way of using sets of samples to understand how the variance of the output
behaves, with respect to each input variable. A larger value of the sensitivity index, Si , means that the uncertainty
in the input variable i has a larger effect on the variance of the output. More details on the calculations and
interpretation of the sensitivity indices can be found in[87].
interaction order
Keywords Area

6.2. METHOD

1011

method
polynomial chaos
variance based decomp
interaction order
Specify the maximum number of variables allowed in an interaction when reporting interaction metrics.

Specification
Alias: none
Argument(s): INTEGER
Default: Unrestricted (VBD includes all interaction orders present in the expansion)

Description
The interaction order option has been added to allow suppression of higher-order interactions, since the output volume (and memory and compute consumption) of these results could be extensive for high dimensional
problems (note: the previous univariate effects specification is equivalent to interaction order = 1 in the current specification). Similar to suppression of interactions is the covariance control, which can be selected to be
diagonal covariance or full covariance, with the former supporting suppression of the off-diagonal covariance
terms (to again save compute and memory resources and reduce output volume)
drop tolerance
Keywords Area
method
polynomial chaos
variance based decomp
drop tolerance
Suppresses output of sensitivity indices with values lower than this tolerance

Specification
Alias: none
Argument(s): REAL
Default: All VBD indices displayed

Description
The drop tolerance keyword allows the user to specify a value below which sensitivity indices generated by
variance based decomp are not displayed.
Default Behavior
By default, all sensitivity indices generated by variance based decomp are displayed.
Usage Tips

1012

CHAPTER 6. KEYWORDS AREA

For polynomial chaos, which outputs main, interaction, and total effects by default, the univariateeffects may be a more appropriate option. It allows suppression of the interaction effects since the output
volume of these results can be prohibitive for high dimensional problems. Similar to suppression of these interactions is the covariance control, which can be selected to be diagonal covariance or full covariance, with the
former supporting suppression of the off-diagonal covariance terms (to save compute and memory resources and
reduce output volume).

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp
drop_tolerance = 0.001

diagonal covariance
Keywords Area
method
polynomial chaos
diagonal covariance
Display only the diagonal terms of the covariance matrix

Specification
Alias: none
Argument(s): none
Default: diagonal covariance for response vector > 10; else full covariance

Description
With a large number of responses, the covariance matrix can be very large. diagonal covariance is used to
suppress the off-diagonal covariance terms (to save compute and memory resources and reduce output volume).
full covariance
Keywords Area
method
polynomial chaos
full covariance
Display the full covariance matrix

Specification
Alias: none
Argument(s): none

6.2. METHOD

1013

Description
With a large number of responses, the covariance matrix can be very large. full covariance is used to force
Dakota to output the full covariance matrix.
normalized
Keywords Area
method
polynomial chaos
normalized
The normalized specification requests output of PCE coefficients that correspond to normalized orthogonal
basis polynomials

Specification
Alias: none
Argument(s): none
Default: PCE coefficients correspond to unnormalized basis polynomials

Description
The normalized specification requests output of PCE coefficients that correspond to normalized orthogonal basis
polynomials
sample type
Keywords Area
method
polynomial chaos
sample type
Selection of sampling strategy

Specification
Alias: none
Argument(s): none
Default: lhs
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

1014

CHAPTER 6. KEYWORDS AREA

Required(Choose
One)

Group 1

lhs

Uses Latin
Hypercube
Sampling (LHS) to
sample variables

random

Uses purely
random Monte
Carlo sampling to
sample variables

Description
The sample type keyword allows the user to select between multiple random sampling approaches. There are
two primary types of sampling: Monte Carlo (pure random) and Latin Hypercube Sampling. Additionally, these
methods have incremental variants that allow an existing study to be augmented with additional samples to get
better estimates of mean, variance, and percentiles.
Default Behavior
If the sample type keyword is present, it must be accompanied by lhs, random, incremental lhs,
or incremental random. Otherwise, lhs will be used by default.

Examples
method
sampling
sample_type lhs
samples = 20

lhs
Keywords Area
method
polynomial chaos
sample type
lhs
Uses Latin Hypercube Sampling (LHS) to sample variables

Specification
Alias: none
Argument(s): none

Description
The lhs keyword invokes Latin Hypercube Sampling as the means of drawing samples of uncertain variables
according to their probability distributions. This is a stratified, space-filling approach that selects variable values
from a set of equi-probable bins.
Default Behavior

6.2. METHOD

1015

By default, Latin Hypercube Sampling is used. To explicitly specify this in the Dakota input file, however, the
lhs keyword must appear in conjunction with the sample type keyword.
Usage Tips
Latin Hypercube Sampling is very robust and can be applied to any problem. It is fairly effective at estimating
the mean of model responses and linear correlations with a reasonably small number of samples relative to the
number of variables.

Examples
method
sampling
sample_type lhs
samples = 20

random
Keywords Area
method
polynomial chaos
sample type
random
Uses purely random Monte Carlo sampling to sample variables

Specification
Alias: none
Argument(s): none

Description
The random keyword invokes Monte Carlo sampling as the means of drawing samples of uncertain variables
according to their probability distributions.
Default Behavior
Monte Carlo sampling is not used by default. To change this behavior, the random keyword must be specified
in conjuction with the sample type keyword.
Usage Tips
Monte Carlo sampling is more computationally expensive than Latin Hypercube Sampling as it requires a
larger number of samples to accurately estimate statistics.

Examples
method
sampling
sample_type random
samples = 200

1016

CHAPTER 6. KEYWORDS AREA

probability refinement
Keywords Area
method
polynomial chaos
probability refinement
Allow refinement of probability and generalized reliability results using importance sampling

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: sample refinement
Argument(s): none
Default: no refinement
Required/Optional
Required(Choose
One)
Optional

Description of
Group
Group 1

Dakota Keyword
import
adapt import
mm adapt import
refinement samples

Dakota Keyword
Description
Sampling option
Importance
sampling option
Sampling option
Specify the
number of samples
used to improve a
probabilty
estimate.

Description
The probability refinement allows refinement of probability and generalized reliability results using
importance sampling. If one specifies probability refinement, there are some additional options. One
can specify which type of importance sampling to use (import, adapt import, or mm adapt import).
Additionally, one can specify the number of refinement samples to use with refinement samples and the
seed to use with seed.
The probability refinement density reweighting accounts originally was developed based on Gaussian distributions. It now accounts for additional non-Gaussian cases.
import
Keywords Area
method
polynomial chaos

6.2. METHOD

1017

probability refinement
import
Sampling option

Specification
Alias: none
Argument(s): none

Description
import centers a sampling density at one of the initial LHS samples identified in the failure region. It then
generates the importance samples, weights them by their probability of occurence given the original density, and
calculates the required probability (CDF or CCDF level).
adapt import
Keywords Area
method
polynomial chaos
probability refinement
adapt import
Importance sampling option

Specification
Alias: none
Argument(s): none

Description
adapt import centers a sampling density at one of the initial LHS samples identified in the failure region. It
then generates the importance samples, weights them by their probability of occurence given the original density,
and calculates the required probability (CDF or CCDF level). This continues iteratively until the failure probability
estimate converges.
mm adapt import
Keywords Area
method
polynomial chaos
probability refinement
mm adapt import
Sampling option

1018

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
mm adapt import starts with all of the samples located in the failure region to build a multimodal sampling
density. First, it uses a small number of samples around each of the initial samples in the failure region. Note
that these samples are allocated to the different points based on their relative probabilities of occurrence: more
probable points get more samples. This early part of the approach is done to search for representative points.
Once these are located, the multimodal sampling density is set and then mm adapt import proceeds similarly
to adapt import (sample until convergence).
refinement samples
Keywords Area
method
polynomial chaos
probability refinement
refinement samples
Specify the number of samples used to improve a probabilty estimate.

Specification
Alias: none
Argument(s): INTEGER

Description
Specify the number of samples used to improve a probabilty estimate. If using uni-modal sampling all samples
are assigned to the sampling center. If using multi-modal sampling the samples are split between mutiple samples
according to some internally computed weights.
import approx points file
Keywords Area
method
polynomial chaos
import approx points file
Filename for points at which to evaluate the PCE/SC surrogate

Specification
Alias: none
Argument(s): STRING
Default: no point import from a file

6.2. METHOD

1019
Required/Optional

Description of
Group

Optional(Choose
One)

tabular format
(Group 1)

Optional

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
Default Behavior No import of points at which to evaluate the surrogate.
Expected Output The PCE/SC surrogate model will be evaluated at the list of points (input variable values)
provided in the file and results tabulated and/or statistics computed at them, depending on the method context.

Examples
method
polynomial_chaos
expansion_order = 4
import_approx_points_file = import.mcmc_annot.dat
annotated

annotated
Keywords Area
method
polynomial chaos
import approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

1020

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
polynomial chaos
import approx points file
custom annotated
Selects custom-annotated tabular file format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1021

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:

1022

CHAPTER 6. KEYWORDS AREA

environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
polynomial chaos
import approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
polynomial chaos
import approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
polynomial chaos
import approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
polynomial chaos
import approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

1023

1024

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
polynomial chaos
import approx points file
active only
Import only active variables from tabular data file

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1025

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
polynomial chaos
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

1026

CHAPTER 6. KEYWORDS AREA

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.
Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
polynomial chaos
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips

6.2. METHOD

1027

To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
polynomial chaos
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1028

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
header
Keywords Area
method
polynomial chaos
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
polynomial chaos
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1029

1030
interface id
Keywords Area
method
polynomial chaos
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
polynomial chaos
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1031

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

export expansion file

Keywords Area
method
polynomial chaos
export expansion file
Export the coefficients and multi-index of a Polynomial Chaos Expansion (PCE) to a file

Specification
Alias: none
Argument(s): STRING

1032

CHAPTER 6. KEYWORDS AREA

Description
Export the coefficients and multi-index of a Polynomial Chaos Expansion (PCE) to a file. The multi-index written
will be sparse. Spcifically the expansion will conists only of the indices corresponding to the non-zero coefficients
of the PCE.
fixed seed
Keywords Area
method
polynomial chaos
fixed seed
Reuses the same seed value for multiple random sampling sets

Specification
Alias: none
Argument(s): none
Default: not fixed; pattern varies run-to-run

Description
The fixed seed flag is relevant if multiple sampling sets will be generated over the coarse of a Dakota analysis.
This occurs when using advance methods (e.g., surrogate-based optimization, optimization under uncertainty).
The same seed value is reused for each of these multiple sampling sets, which can be important for reducing
variability in the sampling results.
Default Behavior
The default behavior is to not use a fixed seed, as the repetition of the same sampling pattern can result in a
modeling weakness that an optimizer could potentially exploit (resulting in actual reliabilities that are lower than
the estimated reliabilities). For repeatable studies, the seed must also be specified.

Examples
method
sampling
sample_type lhs
samples = 10
fixed_seed

max iterations
Keywords Area
method
polynomial chaos
max iterations
Stopping criterion based on number of iterations

6.2. METHOD

1033

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
polynomial chaos
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.

1034

CHAPTER 6. KEYWORDS AREA

Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
reliability levels
Keywords Area
method
polynomial chaos
reliability levels
Specify reliability levels at which the response values will be estimated

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num reliability levels

Dakota Keyword
Description
Specify which
reliability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF reliabilities by projecting out the prescribed number of
sample standard deviations from the sample mean.

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.

6.2. METHOD

1035

An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num reliability levels
Keywords Area
method
polynomial chaos
reliability levels
num reliability levels
Specify which reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: reliability levels evenly distributed among response functions

Description
See parent page
response levels
Keywords Area
method
polynomial chaos
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute

1036

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1

6.2. METHOD

1037

complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06

1038
3.5000000000e+05
4.0000000000e+05

CHAPTER 6. KEYWORDS AREA

4.0000000000e+05
4.5000000000e+05

8.6000000000e-06
1.8000000000e-06

Level mappings for each response function:

Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
polynomial chaos
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

6.2. METHOD

1039

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
polynomial chaos
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
probabilities

Group 1

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

1040

CHAPTER 6. KEYWORDS AREA

Optional

reliabilities

Computes
reliabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
polynomial chaos
response levels

6.2. METHOD

1041

compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

reliabilities
Keywords Area
method
polynomial chaos
response levels
compute
reliabilities
Computes reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

1042

CHAPTER 6. KEYWORDS AREA

Description
The reliabilities keyword directs Dakota to compute reliabilities according to the specified distribution for
a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the reliabilities are not computed by default. To change this behavior,
the reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

gen reliabilities
Keywords Area
method
polynomial chaos
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

6.2. METHOD

1043

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
polynomial chaos
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.

1044
series
Keywords Area
method
polynomial chaos
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
polynomial chaos
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1045

distribution
Keywords Area
method
polynomial chaos
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

1046

CHAPTER 6. KEYWORDS AREA

cumulative
Keywords Area
method
polynomial chaos
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
polynomial chaos
distribution
complementary
Computes statistics according to complementary cumulative functions

6.2. METHOD

1047

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
polynomial chaos
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

1048

CHAPTER 6. KEYWORDS AREA

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

6.2. METHOD

1049

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels

1050

CHAPTER 6. KEYWORDS AREA

Keywords Area
method
polynomial chaos
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
polynomial chaos
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

6.2. METHOD

1051

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
polynomial chaos
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
polynomial chaos
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )

1052

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
polynomial chaos
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

6.2. METHOD

1053

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
polynomial chaos
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

1054

CHAPTER 6. KEYWORDS AREA

samples
Keywords Area
method
polynomial chaos
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
polynomial chaos
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

6.2. METHOD

1055

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
polynomial chaos
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

1056

CHAPTER 6. KEYWORDS AREA

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.47

stoch collocation

Keywords Area

6.2. METHOD

1057

method
stoch collocation
Uncertainty quantification with stochastic collocation

Specification
Alias: nond stoch collocation
Argument(s): none
Required/Optional
Optional(Choose
One)

Description of
Group
Automated
refinement type
(Group 1)

Dakota Keyword
p refinement

h refinement

Optional(Choose
One)

Basis polynomial
family (Group 2)

piecewise

askey

wiener

Dakota Keyword
Description
Automatic
polynomial order
refinement
Employ
h-refinement to
refine the grid
Use piecewise
local basis
functions
Select the
standardized
random variables
(and associated
basis polynomials)
from the Askey
family that best
match the
user-specified
random variables.
Use standard
normal random
variables (along
with Hermite
orthogonal basis
polynomials) when
transforming to a
standardized
probability space.

1058

CHAPTER 6. KEYWORDS AREA

Required(Choose
One)

Interpolation grid
type (Group 3)

quadrature order

sparse grid level

Optional

dimension preference

Optional

use derivatives

Optional(Choose
One)

Nesting of
quadrature rules
(Group 4)

nested

non nested

Optional

variance based decomp

Cubature using
tensor-products of
Gaussian
quadrature rules
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation
A set of weights
specifying the
realtive importance
of each uncertain
variable
(dimension)
Use derivative data
to construct
surrogate models
Enforce use of
nested quadrature
rules if available
Enforce use of
non-nested
quadrature rules
Activates global
sensitivity analysis
based on
decomposition of
response variance
into main,
interaction, and
total effects

6.2. METHOD

1059
Optional(Choose
One)

Covariance type
(Group 5)

diagonal covariance

full covariance

Display only the

diagonal terms of
the covariance
matrix
Display the full
covariance matrix
Selection of
sampling strategy

Optional

sample type

Optional

probability refinement

Optional

import approx points file

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Optional

fixed seed

Reuses the same

seed value for
multiple random
sampling sets

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Allow refinement
of probability and
generalized
reliability results
using importance
sampling
Filename for
points at which to
evaluate the
PCE/SC surrogate

1060

CHAPTER 6. KEYWORDS AREA

Optional

reliability levels

Optional

response levels

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify reliability
levels at which the
response values
will be estimated
Values at which to
estimate desired
statistics for each
response

Description
Stochastic collocation is a general framework for approximate representation of random response functions in
terms of finite-dimensional interpolation bases.
The stochastic collocation (SC) method is very similar to polynomial chaos, with the key difference that
the orthogonal polynomial basis functions are replaced with interpolation polynomial bases. The interpolation
polynomials may be either local or global and either value-based or gradient-enhanced. In the local case, valued-

6.2. METHOD

1061

based are piecewise linear splines and gradient-enhanced are piecewise cubic splines, and in the global case,
valued-based are Lagrange interpolants and gradient-enhanced are Hermite interpolants. A value-based expansion
takes the form
R=

Np
X

ri Li ()

i=1

where Np is the total number of collocation points, ri is a response value at the ith collocation point, Li is the
i multidimensional interpolation polynomial, and is a vector of standardized random variables.
Thus, in PCE, one forms coefficients for known orthogonal polynomial basis functions, whereas SC forms
multidimensional interpolation functions for known coefficients.
Basis polynomial family (Group 2)
In addition to the askey and wiener basis types also supported by polynomial chaos, SC supports the option of
piecewise local basis functions. These are piecewise linear splines, or in the case of gradient-enhanced interpolation via the use derivatives specification, piecewise cubic Hermite splines. Both of these basis options
provide local support only over the range from the interpolated point to its nearest 1D neighbors (within a tensor
grid or within each of the tensor grids underlying a sparse grid), which exchanges the fast convergence of global
bases for smooth functions for robustness in the representation of nonsmooth response functions (that can induce
Gibbs oscillations when using high-order global basis functions). When local basis functions are used, the usage
of nonequidistant collocation points (e.g., the Gauss point selections described above) is not well motivated, so
equidistant Newton-Cotes points are employed in this case, and all random variable types are transformed to standard uniform probability space. The global gradient-enhanced interpolants (Hermite interpolation polynomials)
are also restricted to uniform or transformed uniform random variables (due to the need to compute collocation
weights by integration of the basis polynomials) and share the variable support shown in variable support for
Piecewise SE. Due to numerical instability in these high-order basis polynomials, they are deactivated by default
but can be activated by developers using a compile-time switch.
Interpolation grid type (Group 3)
To form the multidimensional interpolants Li of the expansion, two options are provided.
th

1. interpolation on a tensor-product of Gaussian quadrature points (specified with quadrature order and,
optionally, dimension preference for anisotropic tensor grids). As for PCE, non-nested Gauss rules
are employed by default, although the presence of p refinement or h refinement will result in
default usage of nested rules for normal or uniform variables after any variable transformations have been
applied (both defaults can be overridden using explicit nested or non nested specifications).
2. interpolation on a Smolyak sparse grid (specified with sparse grid level and, optionally, dimensionpreference for anisotropic sparse grids) defined from Gaussian rules. As for sparse PCE, nested rules
are employed unless overridden with the non nested option, and the growth rules are restricted unless
overridden by the unrestricted keyword.
Another distinguishing characteristic of stochastic collocation relative to polynomial chaos is the ability to
reformulate the interpolation problem from a nodal interpolation approach into a hierarchical formulation
in which each new level of interpolation defines a set of incremental refinements (known as hierarchical surpluses)
layered on top of the interpolants from previous levels. This formulation lends itself naturally to uniform or adaptive refinement strategies, since the hierarchical surpluses can be interpreted as error estimates for the interpolant.
Either global or local/piecewise interpolants in either value-based or gradient-enhanced approaches can be formulated using hierarchical interpolation. The primary restriction for the hierarchical case is that it currently
requires a sparse grid approach using nested quadrature rules (Genz-Keister, Gauss-Patterson, or Newton-Cotes
for standard normals and standard uniforms in a transformed space: Askey, Wiener, or Piecewise settings may
be required), although this restriction can be relaxed in the future. A selection of hierarchical interpolation

1062

CHAPTER 6. KEYWORDS AREA

will provide greater precision in the increments to mean, standard deviation, covariance, and reliability-based
level mappings induced by a grid change within uniform or goal-oriented adaptive refinement approaches (see
following section).
It is important to note that, while quadrature order and sparse grid level are array inputs, only
one scalar from these arrays is active at a time for a particular expansion estimation. These scalars can be augmented with a dimension preference to support anisotropy across the random dimension set. The array
inputs are present to support advanced use cases such as multifidelity UQ, where multiple grid resolutions can be
employed.
Automated refinement type (Group 1)
Automated expansion refinement can be selected as either p refinement or h refinement, and either
refinement specification can be either uniform or dimension adaptive. The dimension adaptive
case can be further specified as either sobol or generalized (decay not supported). Each of these automated refinement approaches makes use of the max iterations and convergence tolerance iteration
controls. The h refinement specification involves use of the same piecewise interpolants (linear or cubic Hermite splines) described above for the piecewise specification option (it is not necessary to redundantly specify
piecewise in the case of h refinement). In future releases, the hierarchical interpolation approach
will enable local refinement in addition to the current uniform and dimension adaptive options.
Covariance type (Group 5)
These two keywords are used to specify how this method computes, stores, and outputs the covariance of the
responses. In particular, the diagonal covariance option is provided for reducing post-processing overhead and
output volume in high dimensional applications.
Active Variables
The default behavior is to form expansions over aleatory uncertain continuous variables. To form expansions
over a broader set of variables, one needs to specify active followed by state, epistemic, design, or
all in the variables specification block.
For continuous design, continuous state, and continuous epistemic uncertain variables included in the expansion, interpolation points for these dimensions are based on Gauss-Legendre rules if non-nested, Gauss-Patterson
rules if nested, and Newton-Cotes points in the case of piecewise bases. Again, when probability integrals are
evaluated, only the aleatory random variable domain is integrated, leaving behind a polynomial relationship between the statistics and the remaining design/state/epistemic variables.
Optional Keywords regarding method outputs
Each of these sampling specifications refer to sampling on the SC approximation for the purposes of generating
approximate statistics.
sample type
samples
seed
fixed seed
rng
probability refinement
distribution
reliability levels
response levels
probability levels

6.2. METHOD

1063

gen reliability levels

Since SC approximations are formed on structured grids, there should be no ambiguity with simulation sampling
for generating the SC expansion.
When using the probability refinement control, the number of refinement samples is not under the
users control (these evaluations are approximation-based, so management of this expense is less critical). This
option allows for refinement of probability and generalized reliability results using importance sampling.
Multi-fidelity UQ
When using multifidelity UQ, the high fidelity expansion generated from combining the low fidelity and discrepancy expansions retains the polynomial form of the low fidelity expansion (only the coefficients are updated).
Refer to polynomial chaos for information on the multifidelity interpretation of array inputs for quadratureorder and sparse grid level.
Usage Tips
If n is small, then tensor-product Gaussian quadrature is again the preferred choice. For larger n, tensorproduct quadrature quickly becomes too expensive and the sparse grid approach is preferred. For self-consistency
in growth rates, nested rules employ restricted exponential growth (with the exception of the dimension adaptive p refinement generalized case) for consistency with the linear growth used for non-nested
Gauss rules (integrand precision i = 4l + 1 for sparse grid level l and i = 2m 1 for tensor grid order m).
Additional Resources
Dakota provides access to SC methods through the NonDStochCollocation class. Refer to the Uncertainty
Quantification Capabilities chapter of the Users Manual[4] and the Stochastic Expansion Methods chapter of the
Theory Manual[6] for additional information on the SC algorithm.

Examples
method,
stoch_collocation
sparse_grid_level = 2
samples = 10000 seed = 12347 rng rnum2
response_levels = .1 1. 50. 100. 500. 1000.
variance_based_decomp

Theory
As mentioned above, a value-based expansion takes the form
R=

Np
X

ri Li ()

i=1

The ith interpolation polynomial assumes the value of 1 at the ith collocation point and 0 at all other collocation points, involving either a global Lagrange polynomial basis or local piecewise splines. It is easy to see that
the approximation reproduces the response values at the collocation points and interpolates between these values
at other points. A gradient-enhanced expansion (selected via the use derivatives keyword) involves both
type 1 and type 2 basis functions as follows:
R=

Np
X
i=1

(1)

[ri Hi () +

n
X
dri (2)
H ()]
dj ij
j=1

where the ith type 1 interpolant produces 1 for the value at the ith collocation point, 0 for values at all
other collocation points, and 0 for derivatives (when differentiated) at all collocation points, and the ij th type 2
interpolant produces 0 for values at all collocation points, 1 for the j th derivative component at the ith collocation

1064

CHAPTER 6. KEYWORDS AREA

point, and 0 for the j th derivative component at all other collocation points. Again, this expansion reproduces
the response values at each of the collocation points, and when differentiated, also reproduces each component of
the gradient at each of the collocation points. Since this technique includes the derivative interpolation explicitly,
it eliminates issues with matrix ill-conditioning that can occur in the gradient-enhanced PCE approach based on
regression. However, the calculation of high-order global polynomials with the desired interpolation properties
can be similarly numerically challenging such that the use of local cubic splines is recommended due to numerical
stability.

See Also
These keywords may also be of interest:
adaptive sampling
gpais
local reliability
global reliability
sampling
importance sampling
polynomial chaos
p refinement
Keywords Area
method
stoch collocation
p refinement
Automatic polynomial order refinement

Specification
Alias: none
Argument(s): none
Default: no refinement
Required/Optional
Required(Choose
One)

Description of
Group
p-refinement type
(Group 1)

Dakota Keyword
uniform

Dakota Keyword
Description
Refine an
expansion
uniformly in all
dimensions.

6.2. METHOD

1065
dimension adaptive

Perform
anisotropic
expansion
refinement by
preferentially
adapting in
dimensions that are
detected to have
higher
importance.

Description
The p refinement keyword specifies the usage of automated polynomial order refinement, which can be either
uniform or dimension adaptive.
The dimension adaptive option is supported for the tensor-product quadrature and Smolyak sparse grid
options and uniform is supported for tensor and sparse grids as well as regression approaches (collocationpoints or collocation ratio).
Each of these refinement cases makes use of the max iterations and convergence tolerance
method independent controls. The former control limits the number of refinement iterations, and the latter control
terminates refinement when the two-norm of the change in the response covariance matrix (or, in goal-oriented
approaches, the two-norm of change in the statistical quantities of interest (QOI)) falls below the tolerance.
The dimension adaptive case can be further specified to utilize sobol, decay, or generalized
refinement controls. The former two cases employ anisotropic tensor/sparse grids in which the anisotropic dimension preference (leading to anisotropic integrations/expansions with differing refinement levels for different
random dimensions) is determined using either total Sobol indices from variance-based decomposition (sobol
case: high indices result in high dimension preference) or using spectral coefficient decay rates from a rate
estimation technique similar to Richardson extrapolation (decay case: low decay rates result in high dimension preference). In these two cases as well as the uniform refinement case, the quadrature order or
sparse grid level are ramped by one on each refinement iteration until either of the two convergence controls is satisfied. For the uniform refinement case with regression approaches, the expansion order is
ramped by one on each iteration while the oversampling ratio (either defined by collocation ratio or inferred from collocation points based on the initial expansion) is held fixed. Finally, the generalized
dimension adaptive case is the default adaptive approach; it refers to the generalized sparse grid algorithm,
a greedy approach in which candidate index sets are evaluated for their impact on the statistical QOI, the most
influential sets are selected and used to generate additional candidates, and the index set frontier of a sparse grid
is evolved in an unstructured and goal-oriented manner (refer to Users Manual PCE descriptions for additional
specifics).
For the case of p refinement or the case of an explicit nested override, Gauss-Hermite rules are replaced
with Genz-Keister nested rules and Gauss-Legendre rules are replaced with Gauss-Patterson nested rules, both of
which exchange lower integrand precision for greater point reuse.
uniform
Keywords Area
method
stoch collocation

1066

CHAPTER 6. KEYWORDS AREA

p refinement
uniform
Refine an expansion uniformly in all dimensions.

Specification
Alias: none
Argument(s): none

Description
The quadrature order or sparse grid level are ramped by one on each refinement iteration until either of the two
convergence controls is satisfied. For the uniform refinement case with regression approaches, the expansionorder is ramped by one on each iteration while the oversampling ratio (either defined by collocation ratio or
inferred from collocation points based on the initial expansion) is held fixed.
dimension adaptive
Keywords Area
method
stoch collocation
p refinement
dimension adaptive
Perform anisotropic expansion refinement by preferentially adapting in dimensions that are detected to have
higher importance.

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
dimension
adaptivity
estimation
approach (Group
1)

Dakota Keyword
sobol

Dakota Keyword
Description
Estimate
dimension
preference for
automated
refinement of
stochastic
expansion using
total Sobol
sensitivity indices.

6.2. METHOD

1067
generalized

Use the
generalized sparse
grid dimension
adaptive algorithm
to refine a sparse
grid approximation
of stochastic
expansion.

Description
Perform anisotropic expansion refinement by preferentially adapting in dimensions that are detected to hold higher
importance in resolving statistical quantities of interest.
Dimension importance must be estimated as part of the refinement process. Techniques include either sobol or
generalized for stochastic collocation and either sobol, decay, or generalized for polynomial chaos. Each of these
automated refinement approaches makes use of the max iterations and convergence tolerance iteration controls.
sobol
Keywords Area
method
stoch collocation
p refinement
dimension adaptive
sobol
Estimate dimension preference for automated refinement of stochastic expansion using total Sobol sensitivity
indices.

Specification
Alias: none
Argument(s): none
Default: generalized

Description
Determine dimension preference for refinement of a stochastic expansion from the total Sobol sensitivity indices
obtained from global sensitivity analysis. High indices indicate high importance for resolving statistical quantities
of interest and therefore result in high dimension preference.

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement sobol
max_iterations = 20
convergence_tol = 1.e-4

1068

CHAPTER 6. KEYWORDS AREA

generalized
Keywords Area
method
stoch collocation
p refinement
dimension adaptive
generalized
Use the generalized sparse grid dimension adaptive algorithm to refine a sparse grid approximation of stochastic expansion.

Specification
Alias: none
Argument(s): none

Description
The generalized sparse grid algorithm is a greedy approach in which candidate index sets are evaluated for their
impact on the statistical QOI, the most influential sets are selected and used to generate additional candidates,
and the index set frontier of a sparse grid is evolved in an unstructured and goal-oriented manner (refer to Users
Manual PCE descriptions for additional specifics).

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement generalized
max_iterations = 20
convergence_tol = 1.e-4

h refinement
Keywords Area
method
stoch collocation
h refinement
Employ h-refinement to refine the grid

Specification
Alias: none
Argument(s): none
Default: no refinement

6.2. METHOD

1069
Required/Optional

Description of
Group

Required(Choose
One)

h-refinement type
(Group 1)

Dakota Keyword
uniform

dimension adaptive

local adaptive

Dakota Keyword
Description
Refine an
expansion
uniformly in all
dimensions.
Perform
anisotropic
expansion
refinement by
preferentially
adapting in
dimensions that are
detected to have
higher
importance.
Planned future
capability for local
pointwise
refinement within a
generalized sparse
grid.

Description
Automated expansion refinement can be selected as either p refinement or h refinement, and either refinement
specification can be either uniform or dimension adaptive. The dimension adaptive case can be further specified
as either sobol or generalized (decay not supported). Each of these automated refinement approaches makes use
of the max iterations and convergence tolerance iteration controls. The h refinement specification involves use of
the same piecewise interpolants (linear or cubic Hermite splines) described above for the piecewise specification
option (it is not necessary to redundantly specify piecewise in the case of h refinement). In future releases, the
hierarchical interpolation approach will enable local refinement in addition to the current uniform and dimensionadaptive options.
uniform
Keywords Area
method
stoch collocation
h refinement
uniform
Refine an expansion uniformly in all dimensions.

1070

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
The quadrature order or sparse grid level are ramped by one on each refinement iteration until either of the two
convergence controls is satisfied. For the uniform refinement case with regression approaches, the expansionorder is ramped by one on each iteration while the oversampling ratio (either defined by collocation ratio or
inferred from collocation points based on the initial expansion) is held fixed.
dimension adaptive
Keywords Area
method
stoch collocation
h refinement
dimension adaptive
Perform anisotropic expansion refinement by preferentially adapting in dimensions that are detected to have
higher importance.

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
dimension
adaptivity
estimation
approach (Group
1)

Dakota Keyword
sobol

Dakota Keyword
Description
Estimate
dimension
preference for
automated
refinement of
stochastic
expansion using
total Sobol
sensitivity indices.

6.2. METHOD

1071
generalized

Use the
generalized sparse
grid dimension
adaptive algorithm
to refine a sparse
grid approximation
of stochastic
expansion.

Description
Perform anisotropic expansion refinement by preferentially adapting in dimensions that are detected to hold higher
importance in resolving statistical quantities of interest.
Dimension importance must be estimated as part of the refinement process. Techniques include either sobol or
generalized for stochastic collocation and either sobol, decay, or generalized for polynomial chaos. Each of these
automated refinement approaches makes use of the max iterations and convergence tolerance iteration controls.
sobol
Keywords Area
method
stoch collocation
h refinement
dimension adaptive
sobol
Estimate dimension preference for automated refinement of stochastic expansion using total Sobol sensitivity
indices.

Specification
Alias: none
Argument(s): none
Default: generalized

Description
Determine dimension preference for refinement of a stochastic expansion from the total Sobol sensitivity indices
obtained from global sensitivity analysis. High indices indicate high importance for resolving statistical quantities
of interest and therefore result in high dimension preference.

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement sobol
max_iterations = 20
convergence_tol = 1.e-4

1072

CHAPTER 6. KEYWORDS AREA

generalized
Keywords Area
method
stoch collocation
h refinement
dimension adaptive
generalized
Use the generalized sparse grid dimension adaptive algorithm to refine a sparse grid approximation of stochastic expansion.

Specification
Alias: none
Argument(s): none

Description
The generalized sparse grid algorithm is a greedy approach in which candidate index sets are evaluated for their
impact on the statistical QOI, the most influential sets are selected and used to generate additional candidates,
and the index set frontier of a sparse grid is evolved in an unstructured and goal-oriented manner (refer to Users
Manual PCE descriptions for additional specifics).

Examples
method,
polynomial_chaos
sparse_grid_level = 3
dimension_adaptive p_refinement generalized
max_iterations = 20
convergence_tol = 1.e-4

local adaptive
Keywords Area
method
stoch collocation
h refinement
local adaptive
Planned future capability for local pointwise refinement within a generalized sparse grid.

Specification
Alias: none
Argument(s): none

6.2. METHOD

1073

Description
Sparse grid interpolation admits approaches for pointwise local refinement within the general framework of generalized sparse grids. This algorithmic capability is currently in a partial prototype stage.
piecewise
Keywords Area
method
stoch collocation
piecewise
Use piecewise local basis functions

Specification
Alias: none
Argument(s): none
Default: extended (Askey + numerically-generated)

Description
SC also supports the option of piecewise local basis functions. These are piecewise linear splines, or in the case
of gradient-enhanced interpolation via the use derivatives specification, piecewise cubic Hermite splines. Both
of these basis selections provide local support only over the range from the interpolated point to its nearest 1D
neighbors (within a tensor grid or within each of the tensor grids underlying a sparse grid), which exchanges the
fast convergence of global bases for smooth functions for robustness in the representation of nonsmooth response
functions (that can induce Gibbs oscillations when using high-order global basis functions). When local basis
functions are used, the usage of nonequidistant collocation points (e.g., the Gauss point selections described
above) is not well motivated, so equidistant Newton-Cotes points are employed in this case, and all random
variable types are transformed to standard uniform probability space.
askey
Keywords Area
method
stoch collocation
askey
Select the standardized random variables (and associated basis polynomials) from the Askey family that best
match the user-specified random variables.

Specification
Alias: none
Argument(s): none
Default: extended (Askey + numerically-generated)

1074

CHAPTER 6. KEYWORDS AREA

Description
The Askey option employs standard normal, standard uniform, standard exponential, standard beta, and standard
gamma random variables in a transformed probability space. These selections correspond to Hermite, Legendre,
Laguerre, Jacobi, and generalized Laguerre orthogonal polynomials, respectively.
Specific mappings for the basis polynomials are based on a closest match criterion, and include Hermite
for normal (optimal) as well as bounded normal, lognormal, bounded lognormal, gumbel, frechet, and weibull
(sub-optimal); Legendre for uniform (optimal) as well as loguniform, triangular, and bin-based histogram (suboptimal); Laguerre for exponential (optimal); Jacobi for beta (optimal); and generalized Laguerre for gamma
(optimal).

See Also
These keywords may also be of interest:
polynomial chaos
wiener
wiener
Keywords Area
method
stoch collocation
wiener
Use standard normal random variables (along with Hermite orthogonal basis polynomials) when transforming
to a standardized probability space.

Specification
Alias: none
Argument(s): none
Default: extended (Askey + numerically-generated)

Description
The Wiener option employs standard normal random variables in a transformed probability space, corresponding
to a Hermite orthogonal polynomial basis. This is the same nonlinear variable transformation used by local and
global reliability methods (and therefore has the same variable support).

See Also
These keywords may also be of interest:
polynomial chaos
askey

6.2. METHOD

1075

quadrature order
Keywords Area
method
stoch collocation
quadrature order
Cubature using tensor-products of Gaussian quadrature rules

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Multidimensional integration by a tensor-product of Gaussian quadrature rules (specified with quadratureorder, and, optionally, dimension preference). The default rule selection is to employ non nested
Gauss rules including Gauss-Hermite (for normals or transformed normals), Gauss-Legendre (for uniforms or
transformed uniforms), Gauss-Jacobi (for betas), Gauss-Laguerre (for exponentials), generalized Gauss-Laguerre
(for gammas), and numerically-generated Gauss rules (for other distributions when using an Extended basis).
For the case of p refinement or the case of an explicit nested override, Gauss-Hermite rules are replaced
with Genz-Keister nested rules and Gauss-Legendre rules are replaced with Gauss-Patterson nested rules, both of
which exchange lower integrand precision for greater point reuse. By specifying a dimension preference,
where higher preference leads to higher order polynomial resolution, the tensor grid may be rendered anisotropic.
The dimension specified to have highest preference will be set to the specified quadrature order and all
other dimensions will be reduced in proportion to their reduced preference; any non-integral portion is truncated.
To synchronize with tensor-product integration, a tensor-product expansion is used, where the order pi of the
expansion in each dimension is selected to be half of the integrand precision available from the rule in use,
rounded down. In the case of non-nested Gauss rules with integrand precision 2mi 1, pi is one less than the
quadrature order mi in each dimension (a one-dimensional expansion contains the same number of terms, p + 1,
as the number of Gauss points). The total number of terms, N, in a tensor-product expansion involving n uncertain
input variables is
n
Y
N = 1+P =
(pi + 1)
i=1

In some advanced use cases (e.g., multifidelity UQ), multiple grid resolutions can be employed; for this reason,
the quadrature order specification supports an array input.
sparse grid level
Keywords Area
method
stoch collocation
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

1076

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
restricted

unrestricted

Optional(Choose
One)

Group 2

nodal

hierarchical

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation
Overide the default
restriction of
growth rates for
nested and
non-nested rules
that are by defualt
synchronized for
consistency.
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in

6.2. METHOD

1077

proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.
restricted
Keywords Area
method
stoch collocation
sparse grid level
restricted
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): none
Default: restricted (except for generalized sparse grids)

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

1078

CHAPTER 6. KEYWORDS AREA

unrestricted
Keywords Area
method
stoch collocation
sparse grid level
unrestricted
Overide the default restriction of growth rates for nested and non-nested rules that are by defualt synchronized
for consistency.

Specification
Alias: none
Argument(s): none

Description
In the quadrature and sparse grid cases, growth rates for nested and non-nested rules can be synchronized for
consistency. For a non-nested Gauss rule used within a sparse grid, linear one-dimensional growth rules of m =
2l + 1 are used to enforce odd quadrature orders, where l is the grid level and m is the number of points in the
rule. The precision of this Gauss rule is then i = 2m 1 = 4l + 1. For nested rules, order growth with level is
typically exponential; however, the default behavior is to restrict the number of points to be the lowest order rule
that is available that meets the one-dimensional precision requirement implied by either a level l for a sparse grid
( i = 4l + 1) or an order m for a tensor grid ( i = 2m 1). This behavior is known as restricted growth or
delayed sequences. To override this default behavior in the case of sparse grids, the unrestricted keyword can be
used; it cannot be overridden for tensor grids using nested rules since it also provides a mapping to the available
nested rule quadrature orders. An exception to the default usage of restricted growth is the dimension adaptive prefinement generalized sparse grid case described previously, since the ability to evolve the index sets of a sparse
grid in an unstructured manner eliminates the motivation for restricting the exponential growth of nested rules.
nodal
Keywords Area
method
stoch collocation
sparse grid level
nodal
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): none
Default: nodal

6.2. METHOD

1079

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.
hierarchical
Keywords Area
method
stoch collocation
sparse grid level
hierarchical
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): none

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of

1080

CHAPTER 6. KEYWORDS AREA

tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.
dimension preference
Keywords Area
method
stoch collocation
dimension preference
A set of weights specifying the realtive importance of each uncertain variable (dimension)

Specification
Alias: none
Argument(s): REALLIST
Default: isotropic grids

Description
A set of weights specifying the realtive importance of each uncertain variable (dimension). Using this specification
leada to anisotropic integrations with differing refinement levels for different random dimensions.

See Also
These keywords may also be of interest:
sobol
decay
use derivatives
Keywords Area
method
stoch collocation
use derivatives
Use derivative data to construct surrogate models

6.2. METHOD

1081

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
nested
Keywords Area
method
stoch collocation
nested
Enforce use of nested quadrature rules if available

Specification
Alias: none
Argument(s): none
Default: quadrature: non nested unless automated refinement; sparse grids: nested

Description
Enforce use of nested quadrature rules if available. For instance if the aleatory variables are Gaussian use the
Nested Genz-Keister rule instead of the default non-nested Gauss-Hermite rule variables are
non nested
Keywords Area
method
stoch collocation
non nested
Enforce use of non-nested quadrature rules

Specification
Alias: none
Argument(s): none

1082

CHAPTER 6. KEYWORDS AREA

Description
Enforce use of non-nested quadrature rules if available. For instance if the aleatory variables are Gaussian use the
non-nested Gauss-Hermite rule
variance based decomp
Keywords Area
method
stoch collocation
variance based decomp
Activates global sensitivity analysis based on decomposition of response variance into main, interaction, and
total effects

Specification
Alias: none
Argument(s): none
Default: no variance-based decomposition
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
interaction order

drop tolerance

Dakota Keyword
Description
Specify the
maximum number
of variables
allowed in an
interaction when
reporting
interaction metrics.
Suppresses output
of sensitivity
indices with values
lower than this
tolerance

Description
Dakota can calculate sensitivity indices through variance-based decomposition using the keyword variancebased decomp. This approach decomposes main, interaction, and total effects in order to identify the most
important variables and combinations of variables in contributing to the variance of output quantities of interest.
Default Behavior
Because of processing overhead and output volume, variance based decomp is inactive by default,
unless required for dimension-adaptive refinement using Sobol indices.
Expected Outputs
When variance based decomp is specified, sensitivity indices for main effects, total effects, and any
interaction effects will be reported. Each of these effects represents the percent contribution to the variance
in the model response, where main effects include the aggregated set of univariate terms for each individual
variable, interaction effects represent the set of mixed terms (the complement of the univariate set), and total effects

6.2. METHOD

1083

represent the complete set of terms (univariate and mixed) that contain each individual variable. The aggregated
set of main and interaction sensitivity indices will sum to one, whereas the sum of total effects sensitivity indices
will be greater than one due to redundant counting of mixed terms.
Usage Tips
An important consideration is that the number of possible interaction terms grows exponentially with dimension and expansion order. To mitigate this, both in terms of compute time and output volume, possible interaction
effects are suppressed whenever no contributions are present due to the particular form of an expansion. In addition, the interaction order and drop tolerance controls can further limit the computational and output
requirements.

Examples
method,
polynomial_chaos # or stoch_collocation
sparse_grid_level = 3
variance_based_decomp interaction_order = 2

Theory
In this context, we take sensitivity analysis to be global, not local as when calculating derivatives of output
variables with respect to input variables. Our definition is similar to that of[73] : The study of how uncertainty
in the output of a model can be apportioned to different sources of uncertainty in the model input.
Variance based decomposition is a way of using sets of samples to understand how the variance of the output
behaves, with respect to each input variable. A larger value of the sensitivity index, Si , means that the uncertainty
in the input variable i has a larger effect on the variance of the output. More details on the calculations and
interpretation of the sensitivity indices can be found in[87].
interaction order
Keywords Area
method
stoch collocation
variance based decomp
interaction order
Specify the maximum number of variables allowed in an interaction when reporting interaction metrics.

Specification
Alias: none
Argument(s): INTEGER
Default: Unrestricted (VBD includes all interaction orders present in the expansion)

Description
The interaction order option has been added to allow suppression of higher-order interactions, since the output volume (and memory and compute consumption) of these results could be extensive for high dimensional
problems (note: the previous univariate effects specification is equivalent to interaction order = 1 in the current specification). Similar to suppression of interactions is the covariance control, which can be selected to be

1084

CHAPTER 6. KEYWORDS AREA

diagonal covariance or full covariance, with the former supporting suppression of the off-diagonal covariance
terms (to again save compute and memory resources and reduce output volume)
drop tolerance
Keywords Area
method
stoch collocation
variance based decomp
drop tolerance
Suppresses output of sensitivity indices with values lower than this tolerance

Specification
Alias: none
Argument(s): REAL
Default: All VBD indices displayed

Description
The drop tolerance keyword allows the user to specify a value below which sensitivity indices generated by
variance based decomp are not displayed.
Default Behavior
By default, all sensitivity indices generated by variance based decomp are displayed.
Usage Tips
For polynomial chaos, which outputs main, interaction, and total effects by default, the univariateeffects may be a more appropriate option. It allows suppression of the interaction effects since the output
volume of these results can be prohibitive for high dimensional problems. Similar to suppression of these interactions is the covariance control, which can be selected to be diagonal covariance or full covariance, with the
former supporting suppression of the off-diagonal covariance terms (to save compute and memory resources and
reduce output volume).

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp
drop_tolerance = 0.001

diagonal covariance
Keywords Area
method
stoch collocation
diagonal covariance
Display only the diagonal terms of the covariance matrix

6.2. METHOD

1085

Specification
Alias: none
Argument(s): none
Default: diagonal covariance for response vector > 10; else full covariance

Description
With a large number of responses, the covariance matrix can be very large. diagonal covariance is used to
suppress the off-diagonal covariance terms (to save compute and memory resources and reduce output volume).
full covariance
Keywords Area
method
stoch collocation
full covariance
Display the full covariance matrix

Specification
Alias: none
Argument(s): none

Description
With a large number of responses, the covariance matrix can be very large. full covariance is used to force
Dakota to output the full covariance matrix.
sample type
Keywords Area
method
stoch collocation
sample type
Selection of sampling strategy

Specification
Alias: none
Argument(s): none
Default: lhs

1086

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
lhs

random

Dakota Keyword
Description
Uses Latin
Hypercube
Sampling (LHS) to
sample variables
Uses purely
random Monte
Carlo sampling to
sample variables

Description
The sample type keyword allows the user to select between multiple random sampling approaches. There are
two primary types of sampling: Monte Carlo (pure random) and Latin Hypercube Sampling. Additionally, these
methods have incremental variants that allow an existing study to be augmented with additional samples to get
better estimates of mean, variance, and percentiles.
Default Behavior
If the sample type keyword is present, it must be accompanied by lhs, random, incremental lhs,
or incremental random. Otherwise, lhs will be used by default.

Examples
method
sampling
sample_type lhs
samples = 20

lhs
Keywords Area
method
stoch collocation
sample type
lhs
Uses Latin Hypercube Sampling (LHS) to sample variables

Specification
Alias: none
Argument(s): none

6.2. METHOD

1087

Description
The lhs keyword invokes Latin Hypercube Sampling as the means of drawing samples of uncertain variables
according to their probability distributions. This is a stratified, space-filling approach that selects variable values
from a set of equi-probable bins.
Default Behavior
By default, Latin Hypercube Sampling is used. To explicitly specify this in the Dakota input file, however, the
lhs keyword must appear in conjunction with the sample type keyword.
Usage Tips
Latin Hypercube Sampling is very robust and can be applied to any problem. It is fairly effective at estimating
the mean of model responses and linear correlations with a reasonably small number of samples relative to the
number of variables.

Examples
method
sampling
sample_type lhs
samples = 20

random
Keywords Area
method
stoch collocation
sample type
random
Uses purely random Monte Carlo sampling to sample variables

Specification
Alias: none
Argument(s): none

Description
The random keyword invokes Monte Carlo sampling as the means of drawing samples of uncertain variables
according to their probability distributions.
Default Behavior
Monte Carlo sampling is not used by default. To change this behavior, the random keyword must be specified
in conjuction with the sample type keyword.
Usage Tips
Monte Carlo sampling is more computationally expensive than Latin Hypercube Sampling as it requires a
larger number of samples to accurately estimate statistics.

1088

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type random
samples = 200

probability refinement
Keywords Area
method
stoch collocation
probability refinement
Allow refinement of probability and generalized reliability results using importance sampling

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: sample refinement
Argument(s): none
Required/Optional
Required(Choose
One)
Optional

Description of
Group
Group 1

Dakota Keyword
import
adapt import
mm adapt import
refinement samples

Dakota Keyword
Description
Sampling option
Importance
sampling option
Sampling option
Specify the
number of samples
used to improve a
probabilty
estimate.

Description
The probability refinement allows refinement of probability and generalized reliability results using
importance sampling. If one specifies probability refinement, there are some additional options. One
can specify which type of importance sampling to use (import, adapt import, or mm adapt import).
Additionally, one can specify the number of refinement samples to use with refinement samples and the
seed to use with seed.
The probability refinement density reweighting accounts originally was developed based on Gaussian distributions. It now accounts for additional non-Gaussian cases.

6.2. METHOD

1089

import
Keywords Area
method
stoch collocation
probability refinement
import
Sampling option

Specification
Alias: none
Argument(s): none

Description
import centers a sampling density at one of the initial LHS samples identified in the failure region. It then
generates the importance samples, weights them by their probability of occurence given the original density, and
calculates the required probability (CDF or CCDF level).
adapt import
Keywords Area
method
stoch collocation
probability refinement
adapt import
Importance sampling option

Specification
Alias: none
Argument(s): none

Description
adapt import centers a sampling density at one of the initial LHS samples identified in the failure region. It
then generates the importance samples, weights them by their probability of occurence given the original density,
and calculates the required probability (CDF or CCDF level). This continues iteratively until the failure probability
estimate converges.

1090

CHAPTER 6. KEYWORDS AREA

mm adapt import
Keywords Area
method
stoch collocation
probability refinement
mm adapt import
Sampling option

Specification
Alias: none
Argument(s): none

Description
mm adapt import starts with all of the samples located in the failure region to build a multimodal sampling
density. First, it uses a small number of samples around each of the initial samples in the failure region. Note
that these samples are allocated to the different points based on their relative probabilities of occurrence: more
probable points get more samples. This early part of the approach is done to search for representative points.
Once these are located, the multimodal sampling density is set and then mm adapt import proceeds similarly
to adapt import (sample until convergence).
refinement samples
Keywords Area
method
stoch collocation
probability refinement
refinement samples
Specify the number of samples used to improve a probabilty estimate.

Specification
Alias: none
Argument(s): INTEGER

Description
Specify the number of samples used to improve a probabilty estimate. If using uni-modal sampling all samples
are assigned to the sampling center. If using multi-modal sampling the samples are split between mutiple samples
according to some internally computed weights.

6.2. METHOD

1091

import approx points file

Keywords Area
method
stoch collocation
import approx points file
Filename for points at which to evaluate the PCE/SC surrogate

Specification
Alias: none
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Optional

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
Default Behavior No import of points at which to evaluate the surrogate.
Expected Output The PCE/SC surrogate model will be evaluated at the list of points (input variable values)
provided in the file and results tabulated and/or statistics computed at them, depending on the method context.

Examples
method
polynomial_chaos
expansion_order = 4
import_approx_points_file = import.mcmc_annot.dat
annotated

annotated
Keywords Area
method

1092

CHAPTER 6. KEYWORDS AREA

stoch collocation
import approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1093

custom annotated
Keywords Area
method
stoch collocation
import approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips

1094

CHAPTER 6. KEYWORDS AREA

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
stoch collocation
import approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

6.2. METHOD
eval id
Keywords Area
method
stoch collocation
import approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
stoch collocation
import approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated

1095

1096

CHAPTER 6. KEYWORDS AREA

freeform
Keywords Area
method
stoch collocation
import approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1097

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

active only
Keywords Area
method
stoch collocation
import approx points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.

1098

CHAPTER 6. KEYWORDS AREA

export approx points file

Keywords Area
method
stoch collocation
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.
Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
stoch collocation
export approx points file

6.2. METHOD

1099

annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1100

CHAPTER 6. KEYWORDS AREA

custom annotated
Keywords Area
method
stoch collocation
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips

6.2. METHOD

1101

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
stoch collocation
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

1102
eval id
Keywords Area
method
stoch collocation
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
stoch collocation
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1103

freeform
Keywords Area
method
stoch collocation
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1104

CHAPTER 6. KEYWORDS AREA

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

fixed seed
Keywords Area
method
stoch collocation
fixed seed
Reuses the same seed value for multiple random sampling sets

Specification
Alias: none
Argument(s): none
Default: not fixed; pattern varies run-to-run

Description
The fixed seed flag is relevant if multiple sampling sets will be generated over the coarse of a Dakota analysis.
This occurs when using advance methods (e.g., surrogate-based optimization, optimization under uncertainty).
The same seed value is reused for each of these multiple sampling sets, which can be important for reducing
variability in the sampling results.
Default Behavior
The default behavior is to not use a fixed seed, as the repetition of the same sampling pattern can result in a
modeling weakness that an optimizer could potentially exploit (resulting in actual reliabilities that are lower than
the estimated reliabilities). For repeatable studies, the seed must also be specified.

Examples
method
sampling
sample_type lhs
samples = 10
fixed_seed

6.2. METHOD

1105

max iterations
Keywords Area
method
stoch collocation
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
stoch collocation
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

1106

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
reliability levels
Keywords Area
method
stoch collocation
reliability levels
Specify reliability levels at which the response values will be estimated

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num reliability levels

Dakota Keyword
Description
Specify which
reliability levels
correspond to
which response

6.2. METHOD

1107

Description
Response levels are calculated for specified CDF/CCDF reliabilities by projecting out the prescribed number of
sample standard deviations from the sample mean.

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num reliability levels
Keywords Area
method
stoch collocation
reliability levels
num reliability levels
Specify which reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: reliability levels evenly distributed among response functions

Description
See parent page
response levels
Keywords Area
method
stoch collocation
response levels
Values at which to estimate desired statistics for each response

1108

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1109
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1

1110

CHAPTER 6. KEYWORDS AREA

complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06

6.2. METHOD
3.5000000000e+05
4.0000000000e+05

1111
4.0000000000e+05
4.5000000000e+05

8.6000000000e-06
1.8000000000e-06

Level mappings for each response function:

Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
stoch collocation
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

1112

CHAPTER 6. KEYWORDS AREA

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
stoch collocation
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities

6.2. METHOD

1113
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
probabilities

Optional

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

reliabilities

Computes
reliabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities

1114

CHAPTER 6. KEYWORDS AREA

Keywords Area
method
stoch collocation
response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

reliabilities
Keywords Area
method
stoch collocation
response levels
compute

6.2. METHOD

1115

reliabilities
Computes reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The reliabilities keyword directs Dakota to compute reliabilities according to the specified distribution for
a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the reliabilities are not computed by default. To change this behavior,
the reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

gen reliabilities
Keywords Area
method
stoch collocation
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

1116

CHAPTER 6. KEYWORDS AREA

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
stoch collocation
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system

6.2. METHOD

1117
parallel

Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
stoch collocation
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
stoch collocation
response levels
compute
system

1118

CHAPTER 6. KEYWORDS AREA

parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
distribution
Keywords Area
method
stoch collocation
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

6.2. METHOD

1119

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

cumulative
Keywords Area
method
stoch collocation
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

1120

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
stoch collocation
distribution
complementary
Computes statistics according to complementary cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
stoch collocation
probability levels
Specify probability levels at which to estimate the corresponding response value

6.2. METHOD

1121

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h

1122

CHAPTER 6. KEYWORDS AREA

histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

6.2. METHOD

1123

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels
Keywords Area
method
stoch collocation
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
stoch collocation
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute

1124

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
stoch collocation
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page

6.2. METHOD

1125

rng
Keywords Area
method
stoch collocation
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method

1126

CHAPTER 6. KEYWORDS AREA

stoch collocation
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
stoch collocation
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

6.2. METHOD

1127

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

samples
Keywords Area
method
stoch collocation
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

1128

CHAPTER 6. KEYWORDS AREA

seed
Keywords Area
method
stoch collocation
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
stoch collocation
model pointer
Identifier for model block to be used by a method

6.2. METHOD

1129

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single

1130

CHAPTER 6. KEYWORDS AREA

interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.48

sampling

Keywords Area

method

sampling

Randomly samples variables according to their distributions

Topics
This keyword is related to the topics:
uncertainty quantification

sampling

Specification
Alias: nond sampling
Argument(s): none

6.2. METHOD

1131
Required/Optional
Optional

Description of
Group

Dakota Keyword
sample type

Dakota Keyword
Description
Selection of
sampling strategy

Optional

variance based decomp

Activates global
sensitivity analysis
based on
decomposition of
response variance
into contributions
from variables

Optional

backfill

Ensures that the

samples of discrete
variables with
finite support are
unique

Optional

principal components

Activates principal
components
analysis of the
response matrix of
N samples L
responses.

Optional

fixed seed

Reuses the same

seed value for
multiple random
sampling sets

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

1132

CHAPTER 6. KEYWORDS AREA

Optional

reliability levels

Optional

response levels

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify reliability
levels at which the
response values
will be estimated
Values at which to
estimate desired
statistics for each
response

Description
This method generates parameter values by drawing samples from the specified uncertain variable probability
distributions. The computational model is executed over all generated parameter values to compute the responses
for which statistics are computed. The statistics support sensitivity analysis and uncertainty quantification.
Default Behavior
By default, sampling methods operate on aleatory and epistemic uncertain variables. The types of variables

6.2. METHOD

1133

can be restricted or expanded (to include design or state variables) through use of the active keyword in the
variables block in the Dakota input file. If continuous design and/or state variables are designated as active, the
sampling algorithm will treat them as parameters with uniform probability distributions between their upper and
lower bounds. Refer to variable support for additional information on supported variable types, with and without
correlation.
The following keywords change how the samples are selected:
sample type
fixed seed
rng
samples
seed
variance based decomp
Expected Outputs
As a default, Dakota provides correlation analyses when running LHS. Correlation tables are printed with the
simple, partial, and rank correlations between inputs and outputs. These can be useful to get a quick sense of how
correlated the inputs are to each other, and how correlated various outputs are to inputs. variance based decomp is used to request more sensitivity information, with additional cost.
Additional statistics can be computed from the samples using the following keywords:
response levels
reliability levels
probability levels
gen reliability levels
response levels computes statistics at the specified response value. The other three allow the specification
of the statistic value, and will estimate the corresponding response value.
distribution is used to specify whether the statistic values are from cumulative or complementary cumulative functions.
Usage Tips
sampling is a robust approach to doing sensitivity analysis and uncertainty quantification that can be applied to any problem. It requires more simulations than newer, advanced methods. Thus, an alternative may be
preferable if the simulation is computationally expensive.

Examples
# tested on Dakota 6.0 on 140501
environment
tabular_data
tabular_data_file = Sampling_basic.dat
method
sampling
sample_type lhs
samples = 20

1134

CHAPTER 6. KEYWORDS AREA

model
single
variables
active uncertain
uniform_uncertain = 2
descriptors =
input1
input2
lower_bounds = -2.0
-2.0
upper_bounds =
2.0
2.0
continuous_state = 1
descriptors =
constant1
initial_state = 100
interface
analysis_drivers text_book
fork
responses
response_functions = 1
no_gradients
no_hessians

This example illustrates a basic sampling Dakota input file.

LHS is used instead of purely random sampling.
The default random number generator is used.
Without a seed specified, this will not be reproducable
In the variables block, two types of variables are used
Only the uncertain variables are varied, this is the default behavior, and is also specified by the active
keyword, w/ the uncertain option

See Also
These keywords may also be of interest:
active
incremental lhs

FAQ
Q: Do I need to keep the LHS and S4 files? A: No
sample type
Keywords Area
method
sampling
sample type
Selection of sampling strategy

6.2. METHOD

1135

Specification
Alias: none
Argument(s): none
Default: lhs
Required/Optional

Description of
Group

Dakota Keyword
random

Required(Choose
One)

Group 1

Dakota Keyword
Description
Uses purely
random Monte
Carlo sampling to
sample variables

lhs

Uses Latin
Hypercube
Sampling (LHS) to
sample variables

incremental lhs

Augments an
existing Latin
Hypercube
Sampling (LHS)
study

incremental random

Augments an
existing random
sampling study

Description
The sample type keyword allows the user to select between multiple random sampling approaches. There are
two primary types of sampling: Monte Carlo (pure random) and Latin Hypercube Sampling. Additionally, these
methods have incremental variants that allow an existing study to be augmented with additional samples to get
better estimates of mean, variance, and percentiles.
Default Behavior
If the sample type keyword is present, it must be accompanied by lhs, random, incremental lhs,
or incremental random. Otherwise, lhs will be used by default.

Examples
method
sampling
sample_type lhs
samples = 20

random
Keywords Area
method
sampling

1136

CHAPTER 6. KEYWORDS AREA

sample type
random
Uses purely random Monte Carlo sampling to sample variables

Specification
Alias: none
Argument(s): none

Description
The random keyword invokes Monte Carlo sampling as the means of drawing samples of uncertain variables
according to their probability distributions.
Default Behavior
Monte Carlo sampling is not used by default. To change this behavior, the random keyword must be specified
in conjuction with the sample type keyword.
Usage Tips
Monte Carlo sampling is more computationally expensive than Latin Hypercube Sampling as it requires a
larger number of samples to accurately estimate statistics.

Examples
method
sampling
sample_type random
samples = 200

lhs
Keywords Area
method
sampling
sample type
lhs
Uses Latin Hypercube Sampling (LHS) to sample variables

Specification
Alias: none
Argument(s): none

6.2. METHOD

1137

Description
The lhs keyword invokes Latin Hypercube Sampling as the means of drawing samples of uncertain variables
according to their probability distributions. This is a stratified, space-filling approach that selects variable values
from a set of equi-probable bins.
Default Behavior
By default, Latin Hypercube Sampling is used. To explicitly specify this in the Dakota input file, however, the
lhs keyword must appear in conjunction with the sample type keyword.
Usage Tips
Latin Hypercube Sampling is very robust and can be applied to any problem. It is fairly effective at estimating
the mean of model responses and linear correlations with a reasonably small number of samples relative to the
number of variables.

Examples
method
sampling
sample_type lhs
samples = 20

incremental lhs
Keywords Area
method
sampling
sample type
incremental lhs
Augments an existing Latin Hypercube Sampling (LHS) study

Specification
Alias: none
Argument(s): none
Default: no sample reuse in coefficient estimation
Required/Description of
Optional
Group
Required

Dakota Keyword
previous samples

Dakota Keyword
Description
Number of
samples from an
already-completed
sampling study

Description
incremental lhs will augment an existing LHS sampling study with more samples to get better estimates
of mean, variance, and percentiles. The number of samples in the second set MUST currently be 2 times the
number of previous samples, although incremental sampling based on any power of two may be supported in
future releases.

1138

CHAPTER 6. KEYWORDS AREA

Default Behavior
Incremental Latin Hypercube Sampling is not used by default. To change this behavior, the incrementallhs keyword must be specified in conjuction with the sample type keyword. Additionally, a previous LHS
(or incremental LHS) sampling study with sample size N must have already been performed, and the dakota
restart file must be available from this previous study. The variables and responses specifications must be
the same in both studies. Incremental LHS sampling support both continuous uncertain variables and discrete
uncertain variables such as discrete distributions (e.g. binomial, Poisson, etc.) as well as histogram variables and
uncertain set types.
Usage Tips
The incremental approach is useful if it is uncertain how many simulations can be completed within available
time.
See the examples below and the Usage and Restarting Dakota Studies pages.

Examples
For example, say a user performs an initial study using lhs as the sample type, and generates 10 samples.
One way to ensure the restart file is saved is to specify a non-default name, via a command line option:
dakota -i LHS_10.in -w LHS_10.rst

which uses the input file:

# LHS_10.in
environment
tabular_data
tabular_data_file = lhs10.dat
method
sampling
sample_type lhs
samples = 10
model
single
variables
uniform_uncertain = 2
descriptors =
input1
input2
lower_bounds = -2.0
-2.0
upper_bounds =
2.0
2.0
interface
analysis_drivers text_book
fork
responses
response_functions = 1
no_gradients
no_hessians

and the restart file is written to LHS 10.rst.

Then an incremental LHS study can be run with:
dakota -i LHS_20.in -r LHS_10.rst -w LHS_20.rst

where LHS 20.in is shown below, and LHS 10.rst is the restart file containing the results of the previous LHS
study.

6.2. METHOD

1139

# LHS_20.in
environment
tabular_data
tabular_data_file = lhs_incremental_20.dat
method
sampling
sample_type incremental_lhs
samples = 20
previous_samples = 10
model
single
variables
uniform_uncertain = 2
descriptors =
input1
input2
lower_bounds = -2.0
-2.0
upper_bounds =
2.0
2.0
interface
analysis_drivers text_book
fork
responses
response_functions = 1
no_gradients
no_hessians

The user will get 10 new LHS samples which maintain both the correlation and stratification of the original
LHS sample. The new samples will be combined with the original samples to generate a combined sample of size
20.
This is clearly seen by comparing the two tabular data files.
previous samples
Keywords Area
method
sampling
sample type
incremental lhs
previous samples
Number of samples from an already-completed sampling study

Specification
Alias: none
Argument(s): INTEGER
Default: 0 (no previous samples)

1140

CHAPTER 6. KEYWORDS AREA

Description
The previous samples keyword allows the user to specify the number of samples in an existing sample set
that is to be augmented using the incremental lhs or incremental random approach.
Default Behavior
If not specified, Dakota will assume that there are no existing samples. If specified, there must be a Dakota
restart file available that contains the samples.

Examples
method
sampling
sample_type incremental_lhs
samples = 20
previous_samples = 10

incremental random
Keywords Area
method
sampling
sample type
incremental random
Augments an existing random sampling study

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
previous samples

Dakota Keyword
Description
Number of
samples from an
already-completed
sampling study

Description
incremental random will augment an existing random sampling study with more samples to get better estimates of mean, variance, and percentiles. There is no constraint on the number of samples in the second set as
there is with incremental LHS. With incremental random, one can have different sample sizes in the original
and incremental set. This method can be used, for example, if you have 50 samples from a first study and find out
that you are able to run 10 more samples.
Default Behavior
Incremental random sampling is not used by default. To change this behavior, the incremental random
keyword must be specified in conjuction with the sample type keyword. Additionally, a previous random

6.2. METHOD

1141

sampling study with sample size N must have already been performed, and the dakota restart file must be available
from this previous study. The variables and responses specifications must be the same in both studies.
Usage Tips
The incremental approach is useful if it is uncertain how many simulations can be completed within available
time.

Examples
For example, say a user performs an initial study using random as the sample type, and generates 50 samples.
If the user creates a new input file where samples is now specified to be 60, the sample type is defined to
be incremental random, and previous samples is specified to be 50, the user will get 10 new random
samples. The M new samples will be combined with the N previous samples to generate a combined sample of
size M+N.
The method block would be the following:
method
sampling
sample_type incremental_random
samples = 60
previous_samples = 50

The syntax for running the second sample set is:

dakota -i input2.in -r dakota.rst

where input2.in is the file which specifies incremental sampling and dakota.rst is the restart file containing
the results of the previous study.
previous samples
Keywords Area
method
sampling
sample type
incremental random
previous samples
Number of samples from an already-completed sampling study

Specification
Alias: none
Argument(s): INTEGER
Default: 0 (no previous samples)

Description
The previous samples keyword allows the user to specify the number of samples in an existing sample set
that is to be augmented using the incremental lhs or incremental random approach.
Default Behavior
If not specified, Dakota will assume that there are no existing samples. If specified, there must be a Dakota
restart file available that contains the samples.

1142

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type incremental_lhs
samples = 20
previous_samples = 10

variance based decomp

Keywords Area
method
sampling
variance based decomp
Activates global sensitivity analysis based on decomposition of response variance into contributions from
variables

Specification
Alias: none
Argument(s): none
Default: no variance-based decomposition
Required/Description of
Optional
Group
Optional

Dakota Keyword
drop tolerance

Dakota Keyword
Description
Suppresses output
of sensitivity
indices with values
lower than this
tolerance

Description
Dakota can calculate sensitivity indices through variance based decomposition using the keyword variancebased decomp. These indicate how important the uncertainty in each input variable is in contributing to the
output variance.
Default Behavior
Because of the computational cost, variance based decomp is turned off as a default.
If the user specified a number of samples, N, and a number of nondeterministic variables, M, variance-based
decomposition requires the evaluation of N(M+2) samples. Note that specifying this keyword will increase the
number of function evaluations above the number requested with the samples keyword since replicated
sets of sample values are evaluated.
Expected Outputs
When variance based decomp is specified, sensitivity indices for main effects and total effects will be
reported. Main effects (roughly) represent the percent contribution of each individual variable to the variance in
the model response. Total effects represent the percent contribution of each individual variable in combination
with all other variables to the variance in the model response
Usage Tips
To obtain sensitivity indices that are reasonably accurate, we recommend that N, the number of samples, be at
least one hundred and preferably several hundred or thousands.

6.2. METHOD

1143

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp

Theory
In this context, we take sensitivity analysis to be global, not local as when calculating derivatives of output
variables with respect to input variables. Our definition is similar to that of[73] : The study of how uncertainty
in the output of a model can be apportioned to different sources of uncertainty in the model input.
Variance based decomposition is a way of using sets of samples to understand how the variance of the output
behaves, with respect to each input variable. A larger value of the sensitivity index, Si , means that the uncertainty
in the input variable i has a larger effect on the variance of the output. More details on the calculations and
interpretation of the sensitivity indices can be found in[73] and[87].
drop tolerance
Keywords Area
method
sampling
variance based decomp
drop tolerance
Suppresses output of sensitivity indices with values lower than this tolerance

Specification
Alias: none
Argument(s): REAL
Default: All VBD indices displayed

Description
The drop tolerance keyword allows the user to specify a value below which sensitivity indices generated by
variance based decomp are not displayed.
Default Behavior
By default, all sensitivity indices generated by variance based decomp are displayed.
Usage Tips
For polynomial chaos, which outputs main, interaction, and total effects by default, the univariateeffects may be a more appropriate option. It allows suppression of the interaction effects since the output
volume of these results can be prohibitive for high dimensional problems. Similar to suppression of these interactions is the covariance control, which can be selected to be diagonal covariance or full covariance, with the
former supporting suppression of the off-diagonal covariance terms (to save compute and memory resources and
reduce output volume).

1144

CHAPTER 6. KEYWORDS AREA

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp
drop_tolerance = 0.001

backfill
Keywords Area
method
sampling
backfill
Ensures that the samples of discrete variables with finite support are unique

Specification
Alias: none
Argument(s): none

Description
Traditional LHS can generate replicate samples when applied to discrete variables. This keyword enforces uniqueness, which is determined only over the set of discrete variables with finite support. This allows one to generate
LHS for a mixed set of continuous and discrete variables whilst still enforcing that the set of discrete LHS components of all the samples are unique.
Default Behavior
Uniqueness of samples over discrete variables is not enforced.
Usage Tips
Uniqueness can be useful when applying discrete LHS to simulations without noise.

Examples
method,
sampling
samples = 12
seed = 123456
sample_type lhs backfill
variables,
active all
uniform_uncertain = 1
lower_bounds = 0.
upper_bounds = 1.
descriptors = continuous-uniform
discrete_uncertain_set
integer = 1
elements_per_variable = 4
elements 1 3 5 7
descriptors =
design-set-int

6.2. METHOD

1145

real = 1
initial_point = 0.50
set_values = 0.25 0.50 0.75 1.00
descriptors = design-set-real
interface,
direct analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

See Also
These keywords may also be of interest:
lhs
principal components
Keywords Area
method
sampling
principal components
Activates principal components analysis of the response matrix of N samples L responses.

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
percent variance explained

Dakota Keyword
Description
Specifies the
number of
components to
retain to explain
the specified
percent variance.

Description
Dakota can calculate the principal components of the response matrix of N samples L responses using the
keyword principal components. Principal components analysis (PCA) is a data reduction method. The
Dakota implementation is under active development: the PCA capability may ultimately be specified elsewhere
or used in different ways. For now, it is performed as a post-processing analysis based on a set of Latin Hypercube
samples.
We now have field responses in Dakota. PCA is an initial approach in Dakota to analyze and represent the
field data. Specifically, if we have a sample ensemble of field data responses, we want to identify the principal

1146

CHAPTER 6. KEYWORDS AREA

components responsible for the spread of that data. Then, we can generate a surrogate model by representing
the overall response as weighted sum of M principal components, where the weights will be determined by GPs
which are a function of the input uncertain variables. This reduced form then can be used for sensitivity analysis,
calibration, etc.
The steps involved when one specifies principal components in Dakota are as follows:
Create an LHS input sample based on the uncertain variable specification and run the user-specified model
at the LHS points to compute the field responses. For notation purposes, there are d input parameters, N
samples, and the field length is L.
Perform PCA on the covariance matrix of the data set from the previous step. This is done by first centering
the data (e.g. subtracting the mean of each column from that column) and performing a singular value
decomposition on the covariance matrix of the centered data. The eigenvectors of the covariance matrix
correspond to the principal components.
Identify M principal components based on the percentage of variance explained. There is an optional keyword for principal components called percent variance explained, which is a threshold
that determines the number of components that are retained to explain at least that amount of variance. For
example, if the user specifies percent variance explained = 0.99, the number of components that
accounts for at least 99 percent of the variance in the responses will be retained. The default for this percentage is 0.95. In many applications, only a few principal components explain the majority of the variance,
resulting in significant data reduction.
Use the principal components in a predictive sense, by constructing a prediction approximation. The basis
functions for this approximation are the principal components. The coefficients of the bases are obtained
by constructing GP surrogates for the factor scores of the M principal components. The GP surrogates will
be functions of the uncertain inputs. The idea is that we have just performed PCA on (for example) the
covariance matrix of 100 samples. Typically, those 100 samples will be generated by sampling over some d
uncertain input parameters denoted by u, so there should be a mapping from u to the field data, specifically to
the loading coefficients and the factor scores. Currently, the final item printed from a Principal Components
Analysis in Dakota is a set of prediction samples based on this prediction approximation or surrogate model
that relies on the principal components.
Default Behavior
principal components is turned off as a default. It may be used with either scalar responses or field
responses, but it is intended to be used with large field responses as a data reduction method. For example,
typically we expect the number of LHS samples, N, to be less than the number of field responses, L (e.g. if there
is one field, the number of responses values is the length of that field).
Expected Outputs
When principal components is specified, the number of significant principal components is printed
along with the predictions based on the principal components. If output debug is specified, additional information is printed, including the original response matrix, the centered data, the principal components, and the
factor scores.
Usage Tips
This is a preliminary capability that is undergoing active development. Please contact the Dakota developers
team if you have problems with using this capability or want to suggest additional features.

Examples
method,
sampling
sample_type lhs

6.2. METHOD

1147

samples = 100
principal_components
percent_variance_explained = 0.98

Theory
There is an extensive statistical literature available on PCA. We recommend that the interested user peruse some
of this in using the PCA capability.
percent variance explained
Keywords Area
method
sampling
principal components
percent variance explained
Specifies the number of components to retain to explain the specified percent variance.

Specification
Alias: none
Argument(s): REAL

Description
Dakota can calculate the principal components of the response matrix of N samples L responses using the keyword principal components. Principal components analysis (PCA) is a data reduction method. percentvariance explained is a threshold that determines the number of components that are retained to explain at
least that amount of variance. For example, if the user specifies percent variance explained = 0.99, the
number of components that accounts for at least 99 percent of the variance in the responses will be retained. The
default for this percentage is 0.95. In many applications, only a few principal components explain the majority of
the variance, resulting in significant data reduction.
Expected Outputs
Usage Tips percent variance explained should be a real number between 0.0 and 1.0. Typically, it
will be between 0.9 and 1.0.

Examples
method,
sampling
sample_type lhs
samples = 100
principal_components
percent_variance_explained = 0.98

Theory
There is an extensive statistical literature available on PCA. We recommend that the interested user peruse some
of this in using the PCA capability.

1148

CHAPTER 6. KEYWORDS AREA

fixed seed
Keywords Area
method
sampling
fixed seed
Reuses the same seed value for multiple random sampling sets

Specification
Alias: none
Argument(s): none
Default: not fixed; pattern varies run-to-run

Description
The fixed seed flag is relevant if multiple sampling sets will be generated over the coarse of a Dakota analysis.
This occurs when using advance methods (e.g., surrogate-based optimization, optimization under uncertainty).
The same seed value is reused for each of these multiple sampling sets, which can be important for reducing
variability in the sampling results.
Default Behavior
The default behavior is to not use a fixed seed, as the repetition of the same sampling pattern can result in a
modeling weakness that an optimizer could potentially exploit (resulting in actual reliabilities that are lower than
the estimated reliabilities). For repeatable studies, the seed must also be specified.

Examples
method
sampling
sample_type lhs
samples = 10
fixed_seed

max iterations
Keywords Area
method
sampling
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

1149

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
sampling
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

1150

CHAPTER 6. KEYWORDS AREA

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
reliability levels
Keywords Area
method
sampling
reliability levels
Specify reliability levels at which the response values will be estimated

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num reliability levels

Dakota Keyword
Description
Specify which
reliability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF reliabilities by projecting out the prescribed number of
sample standard deviations from the sample mean.

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).

6.2. METHOD

1151

num reliability levels

Keywords Area
method
sampling
reliability levels
num reliability levels
Specify which reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: reliability levels evenly distributed among response functions

Description
See parent page
response levels
Keywords Area
method
sampling
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

1152

CHAPTER 6. KEYWORDS AREA

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
=
std_deviations
=
descriptors
=
uniform_uncertain = 2
lower_bounds
=
upper_bounds
=
descriptors
=
weibull_uncertain = 2
alphas
=
betas
=
descriptors
=

248.89, 593.33
12.4,
29.7
TF1n TF2n
199.3,
298.5,
TF1u

474.63
712.
TF2u

12.,
250.,
TF1w

30.
590.
TF2w

6.2. METHOD
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2
counts
= 17 21 0 12 24
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h

1153

.3
12

.4
0

interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index

1154
-------------3.5000000000e+05
4.0000000000e+05
4.5000000000e+05

CHAPTER 6. KEYWORDS AREA

----------------5.2000000000e-01
9.0000000000e-02
0.0000000000e+00

-----------------

-----------------

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
sampling
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

6.2. METHOD

1155

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
sampling
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Optional

Description of
Group

Dakota Keyword
probabilities

Group 1

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

reliabilities

Computes
reliabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

1156

CHAPTER 6. KEYWORDS AREA

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
sampling
response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior

6.2. METHOD

1157

If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

reliabilities
Keywords Area
method
sampling
response levels
compute
reliabilities
Computes reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The reliabilities keyword directs Dakota to compute reliabilities according to the specified distribution for
a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the reliabilities are not computed by default. To change this behavior,
the reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-reliability pairs according to the distribution defined.

1158

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

gen reliabilities
Keywords Area
method
sampling
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

6.2. METHOD

1159

system
Keywords Area
method
sampling
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
sampling
response levels
compute

1160
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
sampling
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
distribution
Keywords Area
method
sampling
distribution
Selection of cumulative or complementary cumulative functions

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)

1161

1162

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

cumulative
Keywords Area
method
sampling
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

6.2. METHOD

1163

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
sampling
distribution
complementary
Computes statistics according to complementary cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

1164

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
sampling
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution

6.2. METHOD
probability_levels =
1. .8 .5
1. .3 .2

1165
1. .66 .33
0.
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06

1166

CHAPTER 6. KEYWORDS AREA

Level mappings for each response function:

Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels
Keywords Area
method
sampling
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page

6.2. METHOD

1167

gen reliability levels

Keywords Area
method
sampling
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
sampling
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

1168

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
sampling
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

6.2. METHOD

1169

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
sampling
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
sampling
rng

1170

CHAPTER 6. KEYWORDS AREA

rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

samples
Keywords Area
method
sampling
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips

6.2. METHOD

1171

To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
sampling
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

1172

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
sampling
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.49

importance sampling

Keywords Area
method
importance sampling
Importance sampling

Topics
This keyword is related to the topics:
uncertainty quantification
aleatory uncertainty quantification methods
sampling

Specification
Alias: nond importance sampling
Argument(s): none

1173

1174

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
import
adapt import

Dakota Keyword
Description
Sampling option
Importance
sampling option
Sampling option
Specify the
number of samples
used to improve a
probabilty
estimate.
Values at which to
estimate desired
statistics for each
response

Optional

mm adapt import
refinement samples

Optional

response levels

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Specify probability
levels at which to
estimate the
corresponding
response value

6.2. METHOD

1175
Optional

gen reliability levels

Optional

rng

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Description
The importance sampling method is based on ideas in reliability modeling.
An initial Latin Hypercube sampling is performed to generate an initial set of samples. These initial samples
are augmented with samples from an importance density as follows:
The variables are transformed to standard normal space.
In the transformed space, the importance density is a set of normal densities centered around points which
are in the failure region.
Note that this is similar in spirit to the reliability methods, in which importance sampling is centered around
a Most Probable Point (MPP).
In the case of the LHS samples, the importance sampling density will simply by a mixture of normal
distributions centered around points in the failure region.
Options
Choose one of the importance sampling options:
import
adapt import
mm adapt import
The options for importance sampling are as follows: import centers a sampling density at one of the initial
LHS samples identified in the failure region. It then generates the importance samples, weights them by their
probability of occurence given the original density, and calculates the required probability (CDF or CCDF level).

1176

CHAPTER 6. KEYWORDS AREA

adapt import is the same as import but is performed iteratively until the failure probability estimate converges. mm adapt import starts with all of the samples located in the failure region to build a multimodal
sampling density. First, it uses a small number of samples around each of the initial samples in the failure region.
Note that these samples are allocated to the different points based on their relative probabilities of occurrence:
more probable points get more samples. This early part of the approach is done to search for representative
points. Once these are located, the multimodal sampling density is set and then mm adapt import proceeds
similarly to adapt import (sample until convergence).

Theory
Importance sampling is a method that allows one to estimate statistical quantities such as failure probabilities (e.g.
the probability that a response quantity will exceed a threshold or fall below a threshold value) in a way that is
more efficient than Monte Carlo sampling. The core idea in importance sampling is that one generates samples
that preferentially samples important regions in the space (e.g. in or near the failure region or user-defined region
of interest), and then appropriately weights the samples to obtain an unbiased estimate of the failure probability
[76]. In importance sampling, the samples are generated from a density which is called the importance density:
it is not the original probability density of the input distributions. The importance density should be centered
near the failure region of interest. For black-box simulations such as those commonly interfaced with Dakota, it
is difficult to specify the importance density a priori: the user often does not know where the failure region lies,
especially in a high-dimensional space.[78]. We have developed two importance sampling approaches which do
not rely on the user explicitly specifying an importance density.

See Also
These keywords may also be of interest:
adaptive sampling
gpais
local reliability
global reliability
sampling
polynomial chaos
stoch collocation
import
Keywords Area
method
importance sampling
import
Sampling option

6.2. METHOD

1177

Specification
Alias: none
Argument(s): none

Description
import centers a sampling density at one of the initial LHS samples identified in the failure region. It then
generates the importance samples, weights them by their probability of occurence given the original density, and
calculates the required probability (CDF or CCDF level).
adapt import
Keywords Area
method
importance sampling
adapt import
Importance sampling option

Specification
Alias: none
Argument(s): none

Description
adapt import centers a sampling density at one of the initial LHS samples identified in the failure region. It
then generates the importance samples, weights them by their probability of occurence given the original density,
and calculates the required probability (CDF or CCDF level). This continues iteratively until the failure probability
estimate converges.
mm adapt import
Keywords Area
method
importance sampling
mm adapt import
Sampling option

Specification
Alias: none
Argument(s): none

1178

CHAPTER 6. KEYWORDS AREA

Description
mm adapt import starts with all of the samples located in the failure region to build a multimodal sampling
density. First, it uses a small number of samples around each of the initial samples in the failure region. Note
that these samples are allocated to the different points based on their relative probabilities of occurrence: more
probable points get more samples. This early part of the approach is done to search for representative points.
Once these are located, the multimodal sampling density is set and then mm adapt import proceeds similarly
to adapt import (sample until convergence).
refinement samples
Keywords Area
method
importance sampling
refinement samples
Specify the number of samples used to improve a probabilty estimate.

Specification
Alias: none
Argument(s): INTEGER

Description
Specify the number of samples used to improve a probabilty estimate. If using uni-modal sampling all samples
are assigned to the sampling center. If using multi-modal sampling the samples are split between mutiple samples
according to some internally computed weights.
response levels
Keywords Area
method
importance sampling
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute

6.2. METHOD

1179
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1

1180

CHAPTER 6. KEYWORDS AREA

complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06

6.2. METHOD
3.5000000000e+05
4.0000000000e+05

1181
4.0000000000e+05
4.5000000000e+05

8.6000000000e-06
1.8000000000e-06

Level mappings for each response function:

Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
importance sampling
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

1182

CHAPTER 6. KEYWORDS AREA

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
importance sampling
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities

6.2. METHOD

1183
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Optional

Dakota Keyword
probabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
importance sampling

1184

CHAPTER 6. KEYWORDS AREA

response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

gen reliabilities
Keywords Area
method
importance sampling
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

6.2. METHOD

1185

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
importance sampling
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none

1186

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
importance sampling
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

6.2. METHOD

1187

parallel
Keywords Area
method
importance sampling
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
max iterations
Keywords Area
method
importance sampling
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

1188

CHAPTER 6. KEYWORDS AREA

convergence tolerance
Keywords Area
method
importance sampling
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

6.2. METHOD

1189

distribution
Keywords Area
method
importance sampling
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

1190

CHAPTER 6. KEYWORDS AREA

cumulative
Keywords Area
method
importance sampling
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
importance sampling
distribution
complementary
Computes statistics according to complementary cumulative functions

6.2. METHOD

1191

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
importance sampling
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

1192

CHAPTER 6. KEYWORDS AREA

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

6.2. METHOD

1193

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels

1194

CHAPTER 6. KEYWORDS AREA

Keywords Area
method
importance sampling
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
importance sampling
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

6.2. METHOD

1195

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
importance sampling
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
importance sampling
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )

1196

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
importance sampling
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

6.2. METHOD

1197

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
importance sampling
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

1198

CHAPTER 6. KEYWORDS AREA

samples
Keywords Area
method
importance sampling
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
importance sampling
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

6.2. METHOD

1199

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
importance sampling
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

1200

CHAPTER 6. KEYWORDS AREA

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.50

gpais

Keywords Area

6.2. METHOD

1201

method
gpais
Gaussian Process Adaptive Importance Sampling

Topics
This keyword is related to the topics:
uncertainty quantification

Specification
Alias: gaussian process adaptive importance sampling
Argument(s): none
Required/Description of
Optional
Group
Optional

Dakota Keyword
emulator samples

Dakota Keyword
Description
Number of data
points used to train
the surrogate
model or emulator
File containing
points you wish to
use to build a
surrogate

Optional

import build points file

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Optional

response levels

Values at which to
estimate desired
statistics for each
response

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

1202

CHAPTER 6. KEYWORDS AREA

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Description
gpais is recommended for problems that have a relatively small number of input variables (e.g. less than 10-20).
This method, Gaussian Process Adaptive Importance Sampling, is outlined in the paper[?].
This method starts with an initial set of LHS samples and adds samples one at a time, with the goal of adaptively improving the estimate of the ideal importance density during the process. The approach uses a mixture of
component densities. An iterative process is used to construct the sequence of improving component densities. At
each iteration, a Gaussian process (GP) surrogate is used to help identify areas in the space where failure is likely
to occur. The GPs are not used to directly calculate the failure probability; they are only used to approximate the
importance density. Thus, the Gaussian process adaptive importance sampling algorithm overcomes limitations
involving using a potentially inaccurate surrogate model directly in importance sampling calculations.

See Also
These keywords may also be of interest:
adaptive sampling
local reliability
global reliability
sampling

6.2. METHOD

1203

importance sampling
polynomial chaos
stoch collocation
emulator samples
Keywords Area
method
gpais
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER
Default: 10000

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
import build points file
Keywords Area
method
gpais
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

1204

CHAPTER 6. KEYWORDS AREA

Optional(Choose
One)

Optional

tabular format
(Group 1)

annotated

Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
gpais
import build points file
annotated
Selects annotated tabular file format

6.2. METHOD

1205

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1206

CHAPTER 6. KEYWORDS AREA

custom annotated
Keywords Area
method
gpais
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips

6.2. METHOD

1207

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
gpais
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

1208
eval id
Keywords Area
method
gpais
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
gpais
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1209

freeform
Keywords Area
method
gpais
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1210

CHAPTER 6. KEYWORDS AREA

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

active only
Keywords Area
method
gpais
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.

6.2. METHOD

1211

export approx points file

Keywords Area
method
gpais
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.
Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
gpais
export approx points file

1212

CHAPTER 6. KEYWORDS AREA

annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1213

custom annotated
Keywords Area
method
gpais
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips

1214

CHAPTER 6. KEYWORDS AREA

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
gpais
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

6.2. METHOD
eval id
Keywords Area
method
gpais
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
gpais
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated

1215

1216

CHAPTER 6. KEYWORDS AREA

freeform
Keywords Area
method
gpais
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1217

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

response levels
Keywords Area
method
gpais
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs

1218

CHAPTER 6. KEYWORDS AREA

If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1

6.2. METHOD

1219

descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.

1220

CHAPTER 6. KEYWORDS AREA

In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
gpais
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

6.2. METHOD

1221

compute
Keywords Area
method
gpais
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Optional

Description of
Group
Group 1

Dakota Keyword
probabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

1222

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
gpais
response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

6.2. METHOD

1223

gen reliabilities
Keywords Area
method
gpais
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
gpais
response levels
compute
system
Compute system reliability (series or parallel)

1224

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
gpais
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

6.2. METHOD

1225

parallel
Keywords Area
method
gpais
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
max iterations
Keywords Area
method
gpais
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

1226

CHAPTER 6. KEYWORDS AREA

distribution
Keywords Area
method
gpais
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

6.2. METHOD

1227

cumulative
Keywords Area
method
gpais
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
gpais
distribution
complementary
Computes statistics according to complementary cumulative functions

1228

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
gpais
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

6.2. METHOD

1229

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

1230

CHAPTER 6. KEYWORDS AREA

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels

6.2. METHOD

1231

Keywords Area
method
gpais
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
gpais
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

1232

CHAPTER 6. KEYWORDS AREA

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
gpais
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
gpais
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )

6.2. METHOD

1233
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
gpais
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

1234

CHAPTER 6. KEYWORDS AREA

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
gpais
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

6.2. METHOD

1235

samples
Keywords Area
method
gpais
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
gpais
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

1236

CHAPTER 6. KEYWORDS AREA

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
gpais
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

6.2. METHOD

1237

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.51

adaptive sampling

Keywords Area

1238

CHAPTER 6. KEYWORDS AREA

method
adaptive sampling
(Experimental) Build a GP surrogate and refine it adaptively

Topics
This keyword is related to the topics:
uncertainty quantification

Specification
Alias: nond adaptive sampling
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
emulator samples

Optional

fitness metric

Optional

batch selection

Optional

batch size

Optional

import build points file

Optional

export approx points file

Dakota Keyword
Description
Number of data
points used to train
the surrogate
model or emulator
(Experimental)
Specify the
fitness metric used to
select the next
point
(Experimental)
How to select new
points
The number of
points to add in
each batch.
File containing
points you wish to
use to build a
surrogate
Output file for
evaluations of a
surrogate model

6.2. METHOD

1239
Optional

response levels

Values at which to
estimate desired
statistics for each
response

Optional

misc options

Optional

max iterations

(Experimental)
This is a capability
used to send the
adaptive sampling
algorithm specific
options.
Stopping criterion
based on number
of iterations

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Optional

samples

Number of
samples for
sampling-based
methods

1240

CHAPTER 6. KEYWORDS AREA

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
This is an experimental capability that is not ready for production use at this point.
The goal in performing adaptive sampling is to construct a surrogate model that can be used as an accurate
predictor to some expensive simulation, thus it is to ones advantage to build a surrogate that minimizes the error
over the entire domain of interest using as little data as possible from the expensive simulation. The adaptive part
alludes to the fact that the surrogate will be refined by focusing samples of the expensive simulation on particular
areas of interest rather than rely on random selection or standard space-filling techniques.
At a high-level, the adaptive sampling pipeline is a four-step process:
Evaluate the expensive simulation (referred to as the true model) at initial sample point
1. Fit a surrogate model
2. Create a candidate set and score based on information from surrogate
3. Select a candidate point to evaluate the true model
4. Loop until done
In terms of the Dakota implementation, the adaptive sampling method currently uses Latin Hypercube sampling (LHS) to generate the initial points in Step 1 above. For Step 2, we use a Gaussian process model.
The default behavior is to add one point at a time. At each iteration (e.g. each loop of Steps 2-4 above), a
Latin Hypercube sample is generated (a new one, different from the initial sample) and the surrogate model is
evaluated at this points. These are the candidate points that are then evaluated according to the fitness metric. The
number of candidates used in practice should be high enough to fill most of the input domain: we recommend at
least hundreds of points for a low-dimensional problem. All of the candidates (samples on the emulator) are given
a score and then the highest-scoring candidate is selected to be evaluated on the true model.
The adaptive sampling method also can generate batches of points to add at a time using the batch selection and batch size keywords.

See Also
These keywords may also be of interest:
gpais
local reliability
global reliability
sampling
importance sampling
polynomial chaos
stoch collocation

6.2. METHOD

1241

emulator samples
Keywords Area
method
adaptive sampling
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER
Default: 400

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
fitness metric
Keywords Area
method
adaptive sampling
fitness metric
(Experimental) Specify the fitness metric used to select the next point

Specification
Alias: none
Argument(s): none
Default: predicted variance
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
predicted variance

Group 1
distance
gradient

Dakota Keyword
Description
Pick points with
highest variance
Space filling
metric
Fill the range space
of the surrogate

1242

CHAPTER 6. KEYWORDS AREA

Description
The adaptive sampling is an experimental capability that is not ready for production use at this time.
The user can specify the fitness metric used to select the next point (or points) to evaluate and add to
the set. The fitness metrics used for scoring candidate points include:
predicted variance
distance
gradient
predicted variance
Keywords Area
method
adaptive sampling
fitness metric
predicted variance
Pick points with highest variance

Specification
Alias: none
Argument(s): none

Description
The predicted variance metric uses the predicted variance of the Gaussian process surrogate as the score of a
candidate point. Thus, the adaptively chosen points will be in areas of highest uncertainty according to the
Gaussian process model.
distance
Keywords Area
method
adaptive sampling
fitness metric
distance
Space filling metric

Specification
Alias: none
Argument(s): none

6.2. METHOD

1243

Description
The distance metric calculates the Euclidean distance in domain space between the candidate and its nearest
neighbor in the set of points already evaluated on the true model. Therefore, the most undersampled area of the
domain will always be selected. Note that this is a space-filling metric.
gradient
Keywords Area
method
adaptive sampling
fitness metric
gradient
Fill the range space of the surrogate

Specification
Alias: none
Argument(s): none

Description
The gradient metric calculates the score as the absolute value of the difference in range space (the outputs) of the
two points. The output values used are predicted from the surrogate model. This method attempts to evenly fill
the range space of the surrogate.
batch selection
Keywords Area
method
adaptive sampling
batch selection
(Experimental) How to select new points

Specification
Alias: none
Argument(s): none
Default: naive

1244

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Dakota Keyword
naive

Required(Choose
One)

Group 1

distance penalty

topology

constant liar

Dakota Keyword
Description
Take the highest
scoring candidates
Add a penalty to
spread out the
points in the batch
In this selection
strategy, we use
information about
the topology of the
space from the
Morse-Smale
complex to
identify next points
to select.
Use information
from the existing
surrogate model to
predict what the
surrogate upgrade
will be with new
points.

Description
The adaptive sampling is an experimental capability that is not ready for production use at this time.
With batch or multi-point selection, the true model can be evaluated in parallel and thus increase throughput
before refitting our surrogate model. This proposes a new challenge as the problem of choosing a single point
and choosing multiple points off a surrogate are fundamentally different. Selecting the n best scoring candidates
is more than likely to generate a set of points clustered in one area which will not be conducive to adapting the
surrogate.
We have implemented several strategies for batch selection of points. These are described in the Users manual
and are the subject of active research.
The batch selection strategies include:
1. naive:
2. distance penalty
3. constant liar
4. topology
naive
Keywords Area
method
adaptive sampling
batch selection

6.2. METHOD

1245

naive
Take the highest scoring candidates

Specification
Alias: none
Argument(s): none

Description
This strategy will select the n highest scoring candidates regardless of their position. This tends to group an entire
round of points in the same area.
distance penalty
Keywords Area
method
adaptive sampling
batch selection
distance penalty
Add a penalty to spread out the points in the batch

Specification
Alias: none
Argument(s): none

Description
In this strategy, the highest scoring candidate is selected and then all remaining candidates are re-scored with a
distance penalization factor added in to the score.
topology
Keywords Area
method
adaptive sampling
batch selection
topology
In this selection strategy, we use information about the topology of the space from the Morse-Smale complex
to identify next points to select.

1246

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
In this strategy we look at the topology of the scoring function and select the n highest maxima in the topology.
To determine local maxima, we construct the approximate Morse-Smale complex. This strategy does require the
user to have the Morse-Smale package.
constant liar
Keywords Area
method
adaptive sampling
batch selection
constant liar
Use information from the existing surrogate model to predict what the surrogate upgrade will be with new
points.

Specification
Alias: none
Argument(s): none

Description
The strategy first selects the highest scoring candidate, and then refits the surrogate using a lie value at the point
selected. The lie value is based on the surrogate predictions and not the simulation. This process repeats until
n points have been selected whereupon the lie values are removed from the surrogate and the selected points are
evaluated on the true model and the surrogate is refit with these values.
batch size
Keywords Area
method
adaptive sampling
batch size
The number of points to add in each batch.

Specification
Alias: none
Argument(s): INTEGER
Default: 1

6.2. METHOD

1247

Description
The number of points to add in each batch.
import build points file
Keywords Area
method
adaptive sampling
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)

1248

CHAPTER 6. KEYWORDS AREA

custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
adaptive sampling
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1249

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
adaptive sampling
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1250

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
header
Keywords Area
method
adaptive sampling
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
adaptive sampling
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1251

1252
interface id
Keywords Area
method
adaptive sampling
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
adaptive sampling
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1253

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
adaptive sampling
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1254

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
adaptive sampling
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.
Usage Tips
Dakota exports tabular data in one of three formats:

6.2. METHOD

1255

annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
adaptive sampling
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1256

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
adaptive sampling
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

6.2. METHOD

1257
Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

header
Keywords Area
method
adaptive sampling

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1258
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
adaptive sampling
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
adaptive sampling
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1259

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
adaptive sampling
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

1260

CHAPTER 6. KEYWORDS AREA

In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

...

response levels
Keywords Area
method
adaptive sampling
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

6.2. METHOD

1261

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
=
std_deviations
=
descriptors
=
uniform_uncertain = 2
lower_bounds
=
upper_bounds
=
descriptors
=
weibull_uncertain = 2
alphas
=
betas
=
descriptors
=

248.89, 593.33
12.4,
29.7
TF1n TF2n
199.3,
298.5,
TF1u

474.63
712.
TF2u

12.,
250.,
TF1w

30.
590.
TF2w

1262
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2
counts
= 17 21 0 12 24
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h

CHAPTER 6. KEYWORDS AREA

.3
12

.4
0

interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index

6.2. METHOD
-------------3.5000000000e+05
4.0000000000e+05
4.5000000000e+05

1263
----------------5.2000000000e-01
9.0000000000e-02
0.0000000000e+00

-----------------

-----------------

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
adaptive sampling
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

1264

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
adaptive sampling
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Optional

Description of
Group
Group 1

Dakota Keyword
probabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

6.2. METHOD

1265

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
adaptive sampling
response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

1266

CHAPTER 6. KEYWORDS AREA

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

gen reliabilities
Keywords Area
method
adaptive sampling
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

6.2. METHOD

1267

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
adaptive sampling
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.

1268
series
Keywords Area
method
adaptive sampling
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
adaptive sampling
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1269

misc options
Keywords Area
method
adaptive sampling
misc options
(Experimental) This is a capability used to send the adaptive sampling algorithm specific options.

Specification
Alias: none
Argument(s): STRINGLIST
Default: no misc options

Description
The adaptive sampling algorithm is an experimental capability and not ready for production use at this time.
max iterations
Keywords Area
method
adaptive sampling
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

1270

CHAPTER 6. KEYWORDS AREA

distribution
Keywords Area
method
adaptive sampling
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

6.2. METHOD

1271

cumulative
Keywords Area
method
adaptive sampling
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
adaptive sampling
distribution
complementary
Computes statistics according to complementary cumulative functions

1272

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
adaptive sampling
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

6.2. METHOD

1273

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3

1274

CHAPTER 6. KEYWORDS AREA

no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).

6.2. METHOD

1275

num probability levels

Keywords Area
method
adaptive sampling
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
adaptive sampling
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

1276

CHAPTER 6. KEYWORDS AREA

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
adaptive sampling
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
adaptive sampling
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )

6.2. METHOD

1277
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
adaptive sampling
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

1278

CHAPTER 6. KEYWORDS AREA

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
adaptive sampling
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

6.2. METHOD

1279

samples
Keywords Area
method
adaptive sampling
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
adaptive sampling
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

1280

CHAPTER 6. KEYWORDS AREA

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
adaptive sampling
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

6.2. METHOD

1281

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.52

pof darts

Keywords Area

1282

CHAPTER 6. KEYWORDS AREA

method
pof darts
Probability-of-Failure (POF) darts is a novel method for estimating the probability of failure based on random
sphere-packing.

Topics
This keyword is related to the topics:
uncertainty quantification

Specification
Alias: nond pof darts
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
lipschitz

Optional

emulator samples

Optional

response levels

Optional

distribution

Dakota Keyword
Description
Select the type of
Lipschitz
estimation (global
or local)
Specify the
number of samples
taken on the
emulator to
estimate the
Probability of
Failure in POF
Darts
Values at which to
estimate desired
statistics for each
response
Selection of
cumulative or
complementary
cumulative
functions

6.2. METHOD

1283
Optional

probability levels

Optional

gen reliability levels

Optional

rng

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Description
pof darts is a novel method for estimating the probability of failure based on random sphere-packing. Random
spheres are sampled from the domain with the constraint that each new sphere center has to be outside prior disks.
The radius of each sphere is chosen such that the entire sphere lie either in the failure or the non-failure region.
This radius depends of the function evaluation at the disk center, the failure threshold and an estimate of the
function gradient at the disk center.
We utilize a global surrogate for evaluating the gradient and hence only one function evaluation is required
for each sphere.
After exhausting the sampling budget specified by samples, which is the number of spheres per failure
threshold, the domain is decomposed into two regions. These regions correspond to failure and non-failure, each
represented by the union of the spheres of each type. The volume of the union of failure spheres gives a lower
bound on the required estimate of the probability of failure, while the volume of the union of the non-failure
spheres subtracted from the volume of the domain gives an upper estimate. We currently report the average of
both estimates.
pof darts handles multiple response functions and allows each to have multiple failure thresholds. For each
failure threshold, pof darts will insert a number of spheres specified by the user-input parameter samples.
However, estimating the probability of failure for each failure threshold would utilize the total number of disks
sampled for all failure thresholds. For each failure threshold, the sphere radii changes to generate the right spatial
decomposition.

1284

CHAPTER 6. KEYWORDS AREA

lipschitz
Keywords Area
method
pof darts
lipschitz
Select the type of Lipschitz estimation (global or local)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
local

global

Dakota Keyword
Description
Specify local
estimation of the
Lipschitz constant
Specify global
estimation of the
Lipschitz estimate

Description
There are two types of Lipschitz estimation used in sizing the disks used in POF Darts: global and local. The
global approach uses one Lipschitz estimate for the entire domain. The local approach calculates the Lipschitz
estimate separately for each Voronoi region based on nearby points. The local method is more expensive but more
accurate.
local
Keywords Area
method
pof darts
lipschitz
local
Specify local estimation of the Lipschitz constant

Specification
Alias: none
Argument(s): none

6.2. METHOD

1285

Description
The local approach to estimate the Lipschitz constant calculates the Lipschitz estimate separately for each Voronoi
region based on nearby points. The local method is more expensive but results in higher accuracy compared to
the global method.
global
Keywords Area
method
pof darts
lipschitz
global
Specify global estimation of the Lipschitz estimate

Specification
Alias: none
Argument(s): none

Description
The global approach uses one Lipschitz estimate for the entire domain. This option is currently deactivated. Please
refer to the local alternative.
emulator samples
Keywords Area
method
pof darts
emulator samples
Specify the number of samples taken on the emulator to estimate the Probability of Failure in POF Darts

Specification
Alias: none
Argument(s): INTEGER

Description
The last step of the POF Darts method involves constructing an emulator over the points identified thus far, and
sampling that emulator extensively to estimate the probability of failure. emulator samples allows one to
specify the number of samples taken on the emulator. The default is 1E+6. If the probability of failure estimate is
zero, the user may want to increase the number of emulator samples.

1286

CHAPTER 6. KEYWORDS AREA

response levels
Keywords Area
method
pof darts
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

6.2. METHOD

1287

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.

1288

CHAPTER 6. KEYWORDS AREA

Probability Density Function (PDF) histograms for each response function:

PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
pof darts

6.2. METHOD

1289

response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
pof darts
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities

1290

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Optional

Dakota Keyword
probabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
pof darts

6.2. METHOD

1291

response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

gen reliabilities
Keywords Area
method
pof darts
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

1292

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
pof darts
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none

6.2. METHOD

1293
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
pof darts
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

1294

CHAPTER 6. KEYWORDS AREA

parallel
Keywords Area
method
pof darts
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
distribution
Keywords Area
method
pof darts
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions

6.2. METHOD

1295
complementary

Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

cumulative
Keywords Area
method
pof darts
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.

1296

CHAPTER 6. KEYWORDS AREA

Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
pof darts
distribution
complementary
Computes statistics according to complementary cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

6.2. METHOD

1297

probability levels
Keywords Area
method
pof darts
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.
variables,
normal_uncertain = 2
means
=
std_deviations
=

0.

248.89, 593.33
12.4,
29.7

1298

CHAPTER 6. KEYWORDS AREA

descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00

6.2. METHOD

1299

Complementary Cumulative Distribution Function (CCDF) for response_fn_2:

Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels
Keywords Area
method
pof darts
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page

1300

CHAPTER 6. KEYWORDS AREA

gen reliability levels

Keywords Area
method
pof darts
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
pof darts
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

6.2. METHOD

1301

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
pof darts
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

1302

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
pof darts
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
pof darts
rng

6.2. METHOD

1303

rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

samples
Keywords Area
method
pof darts
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips

1304

CHAPTER 6. KEYWORDS AREA

To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
pof darts
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

6.2. METHOD

1305

model pointer
Keywords Area
method
pof darts
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

1306

CHAPTER 6. KEYWORDS AREA

surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.53

rkd darts

Keywords Area
method
rkd darts
Recursive k-d (RKD) Darts: Recursive Hyperplane Sampling for Numerical Integration of High-Dimensional
Functions.

Topics
This keyword is related to the topics:
uncertainty quantification

Specification
Alias: nond rkd darts
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

1307
Optional

lipschitz

Optional

emulator samples

Optional

response levels

Optional

distribution

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Specify the
number of samples
taken on the
emulator to
estimate the
Numerical
Integration in RKD
Darts.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

1308

CHAPTER 6. KEYWORDS AREA

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Disclaimer: The RKD method is currently in development mode, for further experimental verification. Please
contact Dakota team if you have further questions about using this method.
Recursive k-d (RKD) darts is an algorithm to evaluate the integration of a d-dimensional black box function
f(x) via recursive sampling over d, using a series of hyperplanes of variable dimensionality k = {d, d-1, , 0}.
Fundamentally, we decompose the d-dimensional integration problem into a series of nested one-dimensional
problems. That is, we start at the root level (the whole domain) and start sampling down using hyperplanes of
one lower dimension, all the way down to zero (points). A d-dimensional domain is subsampled using (d-1) hyperplanes, a (d-1)-dimensional sub-domain is subsampled using (d-2) hyperplanes, and so on. Every hyperplane,
regardless of its dimension, is evaluated using sampled hyperplanes of one lower dimension, as shown in the
set of figures above. Each hyperplane has direct information exchange with its parent hyperplane of one higher
dimension, and its children of one lower dimension.
In each one-dimensional problem, we construct a piecewise approximation surrogate model, using 1-dimensional
Lagrange interpolation. Information is exchanged between different levels, including integration values, as well
as interpolation and evaluation errors, in order to a) find the integration value up to that level, b) estimate the
associated integration error, and c) guide the placement of future samples.
lipschitz
Keywords Area
method
rkd darts
lipschitz
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

1309
Required(Choose
One)

Group 1

local

global

local
Keywords Area
method
rkd darts
lipschitz
local
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
global
Keywords Area
method
rkd darts
lipschitz
global
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none

Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

1310

CHAPTER 6. KEYWORDS AREA

emulator samples
Keywords Area
method
rkd darts
emulator samples
Specify the number of samples taken on the emulator to estimate the Numerical Integration in RKD Darts.

Specification
Alias: none
Argument(s): INTEGER

Description
Disclaimer: The RKD method is currently in development mode, for further experimental verification. Please
contact Dakota team if you have further questions about using this method.
The last step of the RKD Darts method involves constructing an emulator over the points identified thus far,
and sampling that emulator extensively to estimate the value of the numerical integration. emulator samples
allows one to specify the number of samples taken on the emulator. The default is 1E+6.
response levels
Keywords Area
method
rkd darts
response levels
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

6.2. METHOD

1311

num response levels

Keywords Area
method
rkd darts
response levels
num response levels
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions
compute
Keywords Area
method
rkd darts
response levels
compute
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
probabilities

gen reliabilities

Optional

system

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

1312

CHAPTER 6. KEYWORDS AREA

probabilities
Keywords Area
method
rkd darts
response levels
compute
probabilities
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
gen reliabilities
Keywords Area
method
rkd darts
response levels
compute
gen reliabilities
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
system
Keywords Area
method
rkd darts
response levels
compute
system
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

6.2. METHOD

Specification
Alias: none
Argument(s): none

1313

1314

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

series
Keywords Area
method
rkd darts
response levels
compute
system
series
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
parallel
Keywords Area
method
rkd darts
response levels
compute
system
parallel
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

6.2. METHOD

1315

Specification
Alias: none
Argument(s): none
distribution
Keywords Area
method
rkd darts
distribution
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

cumulative
Keywords Area
method
rkd darts
distribution
cumulative
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

1316

CHAPTER 6. KEYWORDS AREA

complementary
Keywords Area
method
rkd darts
distribution
complementary
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
probability levels
Keywords Area
method
rkd darts
probability levels
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

num probability levels

Keywords Area
method
rkd darts
probability levels
num probability levels
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

6.2. METHOD

1317

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions
gen reliability levels
Keywords Area
method
rkd darts
gen reliability levels
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

num gen reliability levels

Keywords Area
method
rkd darts
gen reliability levels
num gen reliability levels
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

1318

CHAPTER 6. KEYWORDS AREA

rng
Keywords Area
method
rkd darts
rng
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

mt19937
Keywords Area
method
rkd darts
rng
mt19937
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none

Dakota Keyword
Description
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.
Undocumented:
Recursive k-d
(RKD) Darts is an
experimental
capability.

6.2. METHOD

1319

rnum2
Keywords Area
method
rkd darts
rng
rnum2
Undocumented: Recursive k-d (RKD) Darts is an experimental capability.

Specification
Alias: none
Argument(s): none
samples
Keywords Area
method
rkd darts
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

1320

CHAPTER 6. KEYWORDS AREA

seed
Keywords Area
method
rkd darts
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
rkd darts
model pointer
Identifier for model block to be used by a method

6.2. METHOD

1321

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single

1322

CHAPTER 6. KEYWORDS AREA

interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.54

efficient subspace

Keywords Area
method
efficient subspace
(Experimental) efficient subspace method (ESM)

Topics
This keyword is related to the topics:
uncertainty quantification

Specification
Alias: nond efficient subspace
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
emulator samples

Optional

batch size

Optional

max iterations

Dakota Keyword
Description
Number of data
points used to train
the surrogate
model or emulator
The number of
points to add in
each batch.
Stopping criterion
based on number
of iterations

6.2. METHOD

1323
Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

distribution

Stopping criteria
based on number
of function
evaluations
Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Description
ESM is experimental and its implementation is incomplete. It is an active subspace method, intended for use with
models with high dimensional input parameter spaces and analytic gradients. The method works by evaluating
the response gradient at a number of points in the input parameter space and using a singular value decomposition
to identify key linear combinations of input directions along which the response varies. Then UQ is performed in

1324

CHAPTER 6. KEYWORDS AREA

the reduced input parameter space.

emulator samples
Keywords Area
method
efficient subspace
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
batch size
Keywords Area
method
efficient subspace
batch size
The number of points to add in each batch.

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
The number of points to add in each batch.

6.2. METHOD

1325

max iterations
Keywords Area
method
efficient subspace
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
efficient subspace
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

1326

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max function evaluations
Keywords Area
method
efficient subspace
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

6.2. METHOD

1327

distribution
Keywords Area
method
efficient subspace
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

1328

CHAPTER 6. KEYWORDS AREA

cumulative
Keywords Area
method
efficient subspace
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
efficient subspace
distribution
complementary
Computes statistics according to complementary cumulative functions

6.2. METHOD

1329

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
efficient subspace
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

1330

CHAPTER 6. KEYWORDS AREA

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

6.2. METHOD

1331

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels

1332

CHAPTER 6. KEYWORDS AREA

Keywords Area
method
efficient subspace
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
efficient subspace
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

6.2. METHOD

1333

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
efficient subspace
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
rng
Keywords Area
method
efficient subspace
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )

1334

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
efficient subspace
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

6.2. METHOD

1335

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
efficient subspace
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

1336

CHAPTER 6. KEYWORDS AREA

samples
Keywords Area
method
efficient subspace
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
efficient subspace
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

6.2. METHOD

1337

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
efficient subspace
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

1338

CHAPTER 6. KEYWORDS AREA

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.55

global evidence

Keywords Area

6.2. METHOD

1339

method
global evidence
Evidence theory with evidence measures computed with global optimization methods

Topics
This keyword is related to the topics:
epistemic uncertainty quantification methods
evidence theory

Specification
Alias: nond global evidence
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
sbo

Optional(Choose
One)

Group 1
ego

ea

lhs

Dakota Keyword
Description
Use the surrogate
based optimization
method
Use the Efficient
Global
Optimization
method
Use an
evolutionary
algorithm
Uses Latin
Hypercube
Sampling (LHS) to
sample variables

Optional

response levels

Values at which to
estimate desired
statistics for each
response

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

1340

CHAPTER 6. KEYWORDS AREA

Optional

probability levels

Optional

gen reliability levels

Optional

rng

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of a
random number
generator

Description
global evidence allows the user to specify several global approaches for calculating the belief and plausibility functions:
lhs - note: this takes the minimum and maximum of the samples as the bounds per interval cell combination.
ego - uses Efficient Global Optimization which is based on an adaptive Gaussian process surrogate.
sbo - uses a Gaussian process surrogate (non-adaptive) within an optimization process.
ea - uses an evolutionary algorithm. This can be expensive as the ea will be run for each interval cell
combination.
Note that to calculate the plausibility and belief cumulative distribution functions, one has to look at all combinations of intervals for the uncertain variables. In terms of implementation, if one is using LHS sampling as
outlined above, this method creates a large sample over the response surface, then examines each cell to determine
the minimum and maximum sample values within each cell. To do this, one needs to set the number of samples
relatively high: the default is 10,000 and we recommend at least that number. If the model you are running is a
simulation that is computationally quite expensive, we recommend that you set up a surrogate model within the
Dakota input file so that global evidence performs its sampling and calculations on the surrogate and not on
the original model. If one uses optimization methods instead to find the minimum and maximum sample values
within each cell, this can also be computationally expensive.

6.2. METHOD

1341

Additional Resources
See the topic page evidence theory for important background information and usage notes.
Refer to variable support for information on supported variable types.

Theory
The basic idea is that one specifies an evidence structure on uncertain inputs and propagates that to obtain
belief and plausibility functions on the response functions. The inputs are defined by sets of intervals and Basic
Probability Assignments (BPAs). Evidence propagation is computationally expensive, since the minimum and
maximum function value must be calculated for each interval cell combination. These bounds are aggregated
into belief and plausibility.

See Also
These keywords may also be of interest:
global interval est
local evidence
local interval est
sbo
Keywords Area
method
global evidence
sbo
Use the surrogate based optimization method

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
gaussian process

use derivatives

Dakota Keyword
Description
Gaussian Process
surrogate model
Use derivative data
to construct
surrogate models

1342

CHAPTER 6. KEYWORDS AREA

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Description
A surrogate-based optimization method will be used. The surrogate employed in sbo is a Gaussian process
surrogate.
The main difference between ego and the sbo approach is the objective function being optimized. ego relies
on an expected improvement function, while in sbo, the optimization proceeds using an evolutionary algorithm
(coliny ea) on the Gaussian process surrogate: it is a standard surrogate-based optimization. Also note that the
sbo option can support optimization over discrete variables (the discrete variables are relaxed) while ego cannot.
This is not the same as surrogate based global.
gaussian process
Keywords Area
method
global evidence
sbo
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

dakota

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate

6.2. METHOD

1343

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
global evidence
sbo
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.

1344

CHAPTER 6. KEYWORDS AREA

4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
global evidence
sbo
gaussian process
dakota
Select the built in Gaussian Process surrogate

6.2. METHOD

1345

Specification
Alias: none
Argument(s): none

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
use derivatives
Keywords Area
method
global evidence
sbo
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.

1346

CHAPTER 6. KEYWORDS AREA

import build points file

Keywords Area
method
global evidence
sbo
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

6.2. METHOD

1347

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
global evidence
sbo
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1348

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global evidence
sbo
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1349
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1350
header
Keywords Area
method
global evidence
sbo
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global evidence
sbo
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD
interface id
Keywords Area
method
global evidence
sbo
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global evidence
sbo
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

1351

1352

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
global evidence
sbo
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1353

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
global evidence
sbo
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.

1354

CHAPTER 6. KEYWORDS AREA

Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
global evidence
sbo
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1355

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
global evidence
sbo
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

1356

CHAPTER 6. KEYWORDS AREA

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

header
Keywords Area
method
global evidence

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
sbo
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global evidence
sbo
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1357

1358
interface id
Keywords Area
method
global evidence
sbo
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global evidence
sbo
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1359

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

ego
Keywords Area
method
global evidence
ego
Use the Efficient Global Optimization method

Specification
Alias: none
Argument(s): none

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1360

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
gaussian process

Dakota Keyword
Description
Gaussian Process
surrogate model

Optional

use derivatives

Use derivative data

to construct
surrogate models

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Description
In the case of ego, the efficient global optimization (EGO) method is used to calculate bounds. By default,
the Surfpack GP (Kriging) model is used, but the Dakota implementation may be selected instead. If use derivatives is specified the GP model will be built using available derivative data (Surfpack GP only).
See efficient global for more information.
gaussian process
Keywords Area
method
global evidence
ego
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

1361
Required(Choose
One)

Group 1

surfpack

dakota

Use the Surfpack

version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
global evidence
ego
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.

1362

CHAPTER 6. KEYWORDS AREA

3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
global evidence
ego
gaussian process
dakota
Select the built in Gaussian Process surrogate

6.2. METHOD

1363

Specification
Alias: none
Argument(s): none

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
use derivatives
Keywords Area
method
global evidence
ego
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.

1364

CHAPTER 6. KEYWORDS AREA

import build points file

Keywords Area
method
global evidence
ego
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

6.2. METHOD

1365

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
global evidence
ego
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1366

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global evidence
ego
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1367
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1368
header
Keywords Area
method
global evidence
ego
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global evidence
ego
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD
interface id
Keywords Area
method
global evidence
ego
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global evidence
ego
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

1369

1370

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
global evidence
ego
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1371

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
global evidence
ego
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.

1372

CHAPTER 6. KEYWORDS AREA

Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
global evidence
ego
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1373

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
global evidence
ego
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

1374

CHAPTER 6. KEYWORDS AREA

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

header
Keywords Area
method
global evidence

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
ego
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global evidence
ego
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1375

1376
interface id
Keywords Area
method
global evidence
ego
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global evidence
ego
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1377

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

ea
Keywords Area
method
global evidence
ea
Use an evolutionary algorithm

Specification
Alias: none
Argument(s): none

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1378

CHAPTER 6. KEYWORDS AREA

Description
In this approach, the evolutionary algorithm from Coliny, coliny ea, is used to perform the interval optimization with no surrogate model involved. Again, this option of ea can support interval optimization over discrete
variables.
lhs
Keywords Area
method
global evidence
lhs
Uses Latin Hypercube Sampling (LHS) to sample variables

Specification
Alias: none
Argument(s): none

Description
The lhs keyword invokes Latin Hypercube Sampling as the means of drawing samples of uncertain variables
according to their probability distributions. This is a stratified, space-filling approach that selects variable values
from a set of equi-probable bins.
Default Behavior
By default, Latin Hypercube Sampling is used. To explicitly specify this in the Dakota input file, however, the
lhs keyword must appear in conjunction with the sample type keyword.
Usage Tips
Latin Hypercube Sampling is very robust and can be applied to any problem. It is fairly effective at estimating
the mean of model responses and linear correlations with a reasonably small number of samples relative to the
number of variables.

Examples
method
sampling
sample_type lhs
samples = 20

response levels
Keywords Area
method
global evidence
response levels
Values at which to estimate desired statistics for each response

6.2. METHOD

1379

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).

1380

CHAPTER 6. KEYWORDS AREA

The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05

6.2. METHOD
7.0000000000e+04
7.8702465755e+04
PDF for response_fn_3:
Bin Lower
Bin Upper
----------------2.3796737090e+05
3.5000000000e+05
3.5000000000e+05
4.0000000000e+05
4.0000000000e+05
4.5000000000e+05

1381
1.0341896485e-05
Density Value
------------4.2844660868e-06
8.6000000000e-06
1.8000000000e-06

Level mappings for each response function:

Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
global evidence
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

1382

CHAPTER 6. KEYWORDS AREA

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
global evidence
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
probabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

6.2. METHOD

1383

Optional

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
global evidence
response levels
compute
probabilities
Computes probabilities associated with response levels

1384

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

gen reliabilities
Keywords Area
method
global evidence
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

6.2. METHOD

1385

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
global evidence
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system

1386

CHAPTER 6. KEYWORDS AREA

parallel

Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
global evidence
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
global evidence
response levels
compute
system

6.2. METHOD

1387

parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
distribution
Keywords Area
method
global evidence
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

1388

CHAPTER 6. KEYWORDS AREA

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

cumulative
Keywords Area
method
global evidence
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

6.2. METHOD

1389

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
global evidence
distribution
complementary
Computes statistics according to complementary cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
global evidence
probability levels
Specify probability levels at which to estimate the corresponding response value

1390

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h

6.2. METHOD

1391

histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

1392

CHAPTER 6. KEYWORDS AREA

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels
Keywords Area
method
global evidence
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
global evidence
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute

6.2. METHOD

1393
Required/Optional
Optional

Description of
Group

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
global evidence
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page

1394

CHAPTER 6. KEYWORDS AREA

rng
Keywords Area
method
global evidence
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method

6.2. METHOD

1395

global evidence
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
global evidence
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

1396

CHAPTER 6. KEYWORDS AREA

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

samples
Keywords Area
method
global evidence
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

6.2. METHOD

1397

seed
Keywords Area
method
global evidence
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
global evidence
model pointer
Identifier for model block to be used by a method

1398

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single

6.2. METHOD

1399

interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.56

global interval est

Keywords Area
method
global interval est
Interval analysis using global optimization methods

Topics
This keyword is related to the topics:
uncertainty quantification
epistemic uncertainty quantification methods
interval estimation

Specification
Alias: nond global interval est
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
sbo

Optional(Choose
One)

Group 1
ego

Dakota Keyword
Description
Use the surrogate
based optimization
method
Use the Efficient
Global
Optimization
method

1400

CHAPTER 6. KEYWORDS AREA

ea

lhs

Use an
evolutionary
algorithm
Uses Latin
Hypercube
Sampling (LHS) to
sample variables

Optional

rng

Selection of a
random number
generator

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max function evaluations

Optional

samples

Stopping criteria
based on number
of function
evaluations
Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
In the global approach to interval estimation, one uses either a global optimization method or a sampling method
to assess the bounds of the responses.
global interval est allows the user to specify several approaches to calculate interval bounds on the
output responses.
lhs - note: this takes the minimum and maximum of the samples as the bounds
ego
sbo

6.2. METHOD

1401

ea
Additional Resources
Refer to variable support for information on supported variable types.

See Also
These keywords may also be of interest:
global evidence
local evidence
local interval est
sbo
Keywords Area
method
global interval est
sbo
Use the surrogate based optimization method

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
gaussian process

Dakota Keyword
Description
Gaussian Process
surrogate model

Optional

use derivatives

Use derivative data

to construct
surrogate models

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

1402

CHAPTER 6. KEYWORDS AREA

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Description
A surrogate-based optimization method will be used. The surrogate employed in sbo is a Gaussian process
surrogate.
The main difference between ego and the sbo approach is the objective function being optimized. ego relies
on an expected improvement function, while in sbo, the optimization proceeds using an evolutionary algorithm
(coliny ea) on the Gaussian process surrogate: it is a standard surrogate-based optimization. Also note that the
sbo option can support optimization over discrete variables (the discrete variables are relaxed) while ego cannot.
This is not the same as surrogate based global.
gaussian process
Keywords Area
method
global interval est
sbo
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

dakota

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.

6.2. METHOD

1403

surfpack
Keywords Area
method
global interval est
sbo
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using

1404

CHAPTER 6. KEYWORDS AREA

5. Gradient Enhanced Kriging (GEK).

The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.

dakota
Keywords Area
method
global interval est
sbo
gaussian process
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

6.2. METHOD

1405

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
use derivatives
Keywords Area
method
global interval est
sbo
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.

1406

CHAPTER 6. KEYWORDS AREA

import build points file

Keywords Area
method
global interval est
sbo
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

6.2. METHOD

1407

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
global interval est
sbo
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1408

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global interval est
sbo
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1409
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1410
header
Keywords Area
method
global interval est
sbo
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global interval est
sbo
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD
interface id
Keywords Area
method
global interval est
sbo
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global interval est
sbo
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

1411

1412

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
global interval est
sbo
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1413

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
global interval est
sbo
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.

1414

CHAPTER 6. KEYWORDS AREA

Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
global interval est
sbo
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1415

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global interval est
sbo
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1416

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
header
Keywords Area
method
global interval est
sbo
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global interval est
sbo
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1417

1418
interface id
Keywords Area
method
global interval est
sbo
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global interval est
sbo
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1419

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

ego
Keywords Area
method
global interval est
ego
Use the Efficient Global Optimization method

Specification
Alias: none
Argument(s): none

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1420

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
gaussian process

Dakota Keyword
Description
Gaussian Process
surrogate model

Optional

use derivatives

Use derivative data

to construct
surrogate models

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Description
In the case of ego, the efficient global optimization (EGO) method is used to calculate bounds. By default,
the Surfpack GP (Kriging) model is used, but the Dakota implementation may be selected instead. If use derivatives is specified the GP model will be built using available derivative data (Surfpack GP only).
See efficient global for more information.

gaussian process
Keywords Area
method
global interval est
ego
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process

6.2. METHOD

1421
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

dakota

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
global interval est
ego
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.

1422

CHAPTER 6. KEYWORDS AREA

2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
global interval est

6.2. METHOD

1423

ego
gaussian process
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
use derivatives
Keywords Area
method
global interval est
ego
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

1424

CHAPTER 6. KEYWORDS AREA

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
import build points file
Keywords Area
method
global interval est
ego
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.

6.2. METHOD

1425

Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
global interval est
ego
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips

1426

CHAPTER 6. KEYWORDS AREA

To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global interval est
ego
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1427
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1428
header
Keywords Area
method
global interval est
ego
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global interval est
ego
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD
interface id
Keywords Area
method
global interval est
ego
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global interval est
ego
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

1429

1430

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
global interval est
ego
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1431

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
global interval est
ego
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.

1432

CHAPTER 6. KEYWORDS AREA

Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
global interval est
ego
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

6.2. METHOD

1433

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
global interval est
ego
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

1434

CHAPTER 6. KEYWORDS AREA

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

header
Keywords Area
method
global interval est

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
ego
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global interval est
ego
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1435

1436
interface id
Keywords Area
method
global interval est
ego
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global interval est
ego
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1437

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

ea
Keywords Area
method
global interval est
ea
Use an evolutionary algorithm

Specification
Alias: none
Argument(s): none

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1438

CHAPTER 6. KEYWORDS AREA

Description
In this approach, the evolutionary algorithm from Coliny, coliny ea, is used to perform the interval optimization with no surrogate model involved. Again, this option of ea can support interval optimization over discrete
variables.
lhs
Keywords Area
method
global interval est
lhs
Uses Latin Hypercube Sampling (LHS) to sample variables

Specification
Alias: none
Argument(s): none

Description
The lhs keyword invokes Latin Hypercube Sampling as the means of drawing samples of uncertain variables
according to their probability distributions. This is a stratified, space-filling approach that selects variable values
from a set of equi-probable bins.
Default Behavior
By default, Latin Hypercube Sampling is used. To explicitly specify this in the Dakota input file, however, the
lhs keyword must appear in conjunction with the sample type keyword.
Usage Tips
Latin Hypercube Sampling is very robust and can be applied to any problem. It is fairly effective at estimating
the mean of model responses and linear correlations with a reasonably small number of samples relative to the
number of variables.

Examples
method
sampling
sample_type lhs
samples = 20

rng
Keywords Area
method
global interval est
rng
Selection of a random number generator

6.2. METHOD

1439

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
global interval est
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

1440

CHAPTER 6. KEYWORDS AREA

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
global interval est
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

6.2. METHOD

1441

max iterations
Keywords Area
method
global interval est
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
global interval est
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

1442

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max function evaluations
Keywords Area
method
global interval est
max function evaluations
Stopping criteria based on number of function evaluations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 1000

Description
The maximum number of function evaluations (default: 1000). See also max iterations.

6.2. METHOD

1443

samples
Keywords Area
method
global interval est
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
global interval est
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

1444

CHAPTER 6. KEYWORDS AREA

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
global interval est
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

6.2. METHOD

1445

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.57

bayes calibration

Keywords Area

1446

CHAPTER 6. KEYWORDS AREA

method
bayes calibration
Bayesian calibration

Topics
This keyword is related to the topics:
bayesian calibration
package queso

Specification
Alias: nond bayes calibration
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
queso

Required(Choose
One)

Group 1

gpmsa

wasabi

Dakota Keyword
Description
Markov Chain
Monte Carlo
algorithms from
the QUESO
package
(Experimental)
Gaussian Process
Models for
Simulation
Analysis
(GPMSA) Markov
Chain Monte Carlo
algorithm with
Gaussian Process
Surrogate
(Experimental
Method)
Non-MCMC
Bayesian inference
using interval
analysis

6.2. METHOD

1447
dream

DREAM
(DiffeRential
Evolution Adaptive
Metropolis)
Perform Bayesian
inference in
standardized
probability space

Optional

standardized space

Optional

calibrate error multipliers

Calibrate
hyper-parameter
multipliers on the
observation error
covariance

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Bayesian calibration methods take prior information on parameter values (in the form of prior distributions) and
observational data (e.g. from experiments) and produce posterior distributions on the parameter values. When
the computational simulation is then executed with samples from the posterior parameter distributions, the results
that are produced are consistent with (agree with) the experimental data. Calibrating parameters from a computational simulation model requires a likelihood function that specifies the likelihood of observing a particular
observation given the model and its associated parameterization; Dakota assumes a Gaussian likelihood function
currently. The algorithms that produce the posterior distributions on model parameters are most commonly Monte
Carlo Markov Chain (MCMC) sampling algorithms. MCMC methods require many samples, often tens of thousands, so in the case of model calibration, often emulators of the computational simulation are used. For more
details on the algorithms underlying the methods, see the Dakota Users manual.

1448

CHAPTER 6. KEYWORDS AREA

Dakota has three Bayesian calibration methods: QUESO, DREAM, and GPMSA, specified with bayescalibration queso, bayes calibration dream, or bayes calibration gpmsa, respectively.
The QUESO method uses components from the QUESO library (Quantification of Uncertainty for Estimation,
Simulation, and Optimization) developed at The University of Texas at Austin. Dakota uses its DRAM (Delayed Rejected Adaptive Metropolis) algorithm, and variants, for the MCMC sampling. DREAM (DiffeRential
Evolution Adaptive Metropolis) is a method that runs multiple different chains simultaneously for global exploration, and automatically tunes the proposal covariance during the process by a self-adaptive randomized subspace
sampling.[86]. GPMSA (Gaussian Process Models for Simulation Analysis) is an approach developed at Los
Alamos National Laboratory. It constructs Gaussian process models to emulate the expensive computational simulation as well as model discrepancy. GPMSA also has extensive features for calibration, such as the capability
to include a model discrepancy term and the capability to model functional data such as time series data.
The Bayesian capabilities are under active development. At this stage, the QUESO methods in Dakota are the
most advanced and robust, followed by DREAM, followed by GPMSA, which is in prototype form at this time.
Dakota also has an experimental WASABI capability for non-MCMC Bayesian inference; it is not yet ready for
production use. Note that as of Dakota 6.2, the field responses and associated field data may be used with QUESO and DREAM. That is, the user can specify field simulation data and field experiment data, and Dakota will
interpolate and provide the proper residuals to the Bayesian calibration.
queso
Keywords Area
method
bayes calibration
queso
Markov Chain Monte Carlo algorithms from the QUESO package

Topics
This keyword is related to the topics:
bayesian calibration
package queso

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
emulator

Dakota Keyword
Description
Use an emulator or
surrogate model to
evaluate the
likelihood function

6.2. METHOD

1449
Optional

logit transform

Utilize the logit

transformation to
reduce sample
rejection for
bounded domains

Optional

export chain points file

Export the MCMC

chain to the
specified filename

dram

Use the DRAM

MCMC algorithm

delayed rejection

Use the Delayed

Rejection MCMC
algorithm

adaptive metropolis

Use the Adaptive

Metropolis MCMC
algorithm

metropolis hastings

Use the
Metropolis-Hastings MCMC
algorithm

multilevel

Use the multilevel

MCMC algorithm.

Optional

rng

Selection of a
random number
generator

Optional

pre solve

Perform
deterministic
optimization for
MAP before
Bayesian
calibration

Optional(Choose
One)

MCMC algorithm
type (Group 1)

1450

CHAPTER 6. KEYWORDS AREA

Optional

proposal covariance

Defines the
technique used to
generate the
MCMC proposal
covariance.

Description
For the QUESO method, one can use an emulator in the MCMC sampling. This will greatly improve the speed,
since the Monte Carlo Markov Chain will generate thousands of samples on the emulator instead of the real
simulation code. However, in the case of fast running evaluations, we recommend the use of no emulator. An
emulator may be specified with the keyword emulator, followed by a gaussian process emulator, a pce
emulator (polynomial chaos expansion), or a sc emulator (stochastic collocation). For the gaussian process
emulator, the user must specify whether to use the surfpack or dakota version of the Gaussian process. The
user can define the number of samples emulator samples from which the emulator should be built. It is
also possible to build the Gaussian process from points read in from the import points file and to export
approximation-based sample evaluations using export points file. For pce or sc, the user can define a
sparse grid level.
In terms of the MCMC sampling, one can specify one of the following MCMC algorithms to use: dram for DRAM (Delayed Rejection Adaptive Metropolis), delayed rejection for delayed rejection only, adaptivemetropolis for adaptive metropolis only, metropolis hastings for Metropolis Hastings, and multilevel
for the multilevel MCMC algorithm.
There are a variety of ways the user can specify the proposal covariance matrix which is very important in
governing the samples generated in the chain. The proposal covariance specifies the covariance structure of a
multivariate normal distribution. The user can specify proposal covariance, followed by derivatives,
prior, values, or filename. The derivative specification involves forming the Hessian of the misfit function
(the negative log likelihood). When derivative information is available inexpensively (e.g. from an emulator), the
derived-based proposal covariance forms a more accurate proposal distribution, resulting in lower rejection rates
and faster chain mixing. The prior setting involves constructing the proposal from the variance of the prior
distributions of the parameters being calibrated. When specifying the proposal covariance with values or from a
file, the user can choose to specify only the diagonals of the covariance matrix with diagonal or to specify the
full covariance matrix with matrix.
There are two other controls for QUESO. The pre solve option enables the user to start the chain at an
optimal point, the Maximum A Posteriori (MAP) point. This is the point in parameter space that maximizes the
log posterior, (defined as the log-likelihood minus the log prior). A deterministic optimization method is used to
obtain the MAP point, and the MCMC chain is then started at the best point found in the optimization. The second
factor is a logit transform, which performs an internal variable transformation from bounded domains to
unbounded domains in order to reduce sample rejection due to an out-of-bounds condition.
Note that as of Dakota 6.2, the field data capability may be used with QUESO. That is, the user can specify
field simulation data and field experiment data, and Dakota will interpolate and provide the proper residuals to the
Bayesian calibration.
emulator
Keywords Area
method
bayes calibration

6.2. METHOD

1451

queso
emulator
Use an emulator or surrogate model to evaluate the likelihood function

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

emulator type
(Group 1)

Optional

Dakota Keyword
gaussian process

Dakota Keyword
Description
Gaussian Process
surrogate model

pce

Polynomial Chaos
Expansion
surrogate model

sc

Stochastic
Collocation
polynomial
surrogate model

use derivatives

Use derivative data

to construct
surrogate models

Description
This keyword describes the type of emulator used when calculating the likelihood function for the Bayesian
calibration. The emulator can be a Gaussian process, polynomial chaos expansion, or stochastic collocation.
gaussian process
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process

1452

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

dakota

Optional

emulator samples

Optional

posterior adaptive

Optional

import build points file

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate
Number of data
points used to train
the surrogate
model or emulator
Adapt the emulator
model to achieve
greater accuracy in
regions of high
posterior
probability.
File containing
points you wish to
use to build a
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

6.2. METHOD

1453

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient

1454

CHAPTER 6. KEYWORDS AREA

information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.

6.2. METHOD

1455

emulator samples
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
posterior adaptive
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

1456

CHAPTER 6. KEYWORDS AREA

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

6.2. METHOD

1457

Optional

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
annotated
Selects annotated tabular file format

1458

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1459

custom annotated
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

1460

CHAPTER 6. KEYWORDS AREA

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
queso
emulator
gaussian process

1461

1462
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1463

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
queso
emulator
gaussian process
import build points file
active only
Import only active variables from tabular data file

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1464

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
pce
Keywords Area
method
bayes calibration
queso
emulator
pce
Polynomial Chaos Expansion surrogate model

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
sparse grid level

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

6.2. METHOD

1465
expansion order

The (initial) order

of a polynomial
expansion

collocation points

Specify the
number of
collocation points
used to estimate
PCE coefficients
using regression or
orthogonal-leastinterpolation.

Description
Selects a polynomial chaos expansion (PCE) surrogate model to use in the Bayesian likelihood calculations.
When using PCE as a surrogate within the Bayesian framework, the PCE coefficients can be computed either
from integration using a sparse grid or from regression using a random/unstructured data set.

See Also
These keywords may also be of interest:
polynomial chaos
sparse grid level
Keywords Area
method
bayes calibration
queso
emulator
pce
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

1466

CHAPTER 6. KEYWORDS AREA

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

expansion order
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
The (initial) order of a polynomial expansion

Specification
Alias: none
Argument(s): INTEGERLIST

6.2. METHOD

1467
Required/Optional
Required

Description of
Group

Dakota Keyword
collocation ratio

Dakota Keyword
Description
Set the number of
points used to
build a PCE via
regression to be
proportional to the
number of terms in
the expansion.

Optional

posterior adaptive

Adapt the emulator

model to achieve
greater accuracy in
regions of high
posterior
probability.

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Description
When the expansion order for a a polynomial chaos expansion is specified, the coefficients may be computed
by integration based on random samples or by regression using either random or sub-sampled tensor product
quadrature points.
Multidimensional integration by Latin hypercube sampling (specified with expansion samples). In this
case, the expansion order p cannot be inferred from the numerical integration specification and it is necessary to
provide an expansion order to specify p for a total-order expansion.
Linear regression (specified with either collocation points or collocation ratio). A total-order
expansion is used and must be specified using expansion order as described in the previous option. To
avoid requiring the user to calculate N from n and p), the collocation ratio allows for specification of a
constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this
case, the number of samples becomes cN o where c is the collocation ratio and o is the ratio order.
The use derivatives flag informs the regression approach to include derivative matching equations (limited
to gradients at present) in the least squares solutions, enabling the use of fewer collocation points for a given
cN o
expansion order and dimension (number of points required becomes n+1
). When admissible, a constrained least
squares approach is employed in which response values are first reproduced exactly and error in reproducing
response derivatives is minimized. Two collocation grid options are supported: the default is Latin hypercube
sampling (point collocation), and an alternate approach of probabilistic collocation is also available through
inclusion of the tensor grid keyword. In this alternate case, the collocation grid is defined using a subset of
tensor-product quadrature points: the order of the tensor-product grid is selected as one more than the expansion
order in each dimension (to avoid sampling at roots of the basis polynomials) and then the tensor multi-index is
uniformly sampled to generate a non-repeated subset of tensor quadrature points.
If collocation points or collocation ratio is specified, the PCE coefficients will be determined
by regression. If no regression specification is provided, appropriate defaults are defined. Specifically SVD-based
least-squares will be used for solving over-determined systems and under-determined systems will be solved

1468

CHAPTER 6. KEYWORDS AREA

using LASSO. For the situation when the number of function values is smaller than the number of terms in a
PCE, but the total number of samples including gradient values is greater than the number of terms, the resulting
over-determined system will be solved using equality constrained least squares. Technical information on the
various methods listed below can be found in the Linear regression section of the Theory Manual. Some of the
regression methods (OMP, LASSO, and LARS) are able to produce a set of possible PCE coefficient vectors
(see the Linear regression section in the Theory Manual). If cross validation is inactive, then only one solution,
consistent with the noise tolerance, will be returned. If cross validation is active, Dakota will choose
between possible coefficient vectors found internally by the regression method across the set of expansion orders
(1,...,expansion order) and the set of specified noise tolerances and return the one with the lowest cross
validation error indicator.
collocation ratio
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
collocation ratio
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion.

Specification
Alias: none
Argument(s): REAL

Description
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion. To avoid requiring the user to calculate N from n and p, the collocation ratio allows for specification
of a constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this case,
the number of samples becomes cN o where c is the collocation ratio and o is the ratio order. The use derivatives
flag informs the regression approach to include derivative matching equations (limited to gradients at present) in
the least squares solutions, enabling the use of fewer collocation points for a given expansion order and dimension
cN o
(number of points required becomes n+1
).

6.2. METHOD

1469

posterior adaptive
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
import build points file
File containing points you wish to use to build a surrogate

1470

CHAPTER 6. KEYWORDS AREA

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method

6.2. METHOD

1471

bayes calibration
queso
emulator
pce
expansion order
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1472

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

1473
Optional

header

Enable header row

in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1474
header
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
queso
emulator

1475

1476

CHAPTER 6. KEYWORDS AREA

pce
expansion order
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991
...

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1477

active only
Keywords Area
method
bayes calibration
queso
emulator
pce
expansion order
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
collocation points
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonalleast-interpolation.

1478

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
posterior adaptive

import build points file

Dakota Keyword
Description
Adapt the emulator
model to achieve
greater accuracy in
regions of high
posterior
probability.
File containing
points you wish to
use to build a
surrogate

Description
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonal-leastinterpolation.
posterior adaptive
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

6.2. METHOD

1479

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

1480

CHAPTER 6. KEYWORDS AREA

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

6.2. METHOD

1481

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

custom annotated
Keywords Area
method
bayes calibration
queso
emulator

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1482

CHAPTER 6. KEYWORDS AREA

pce
collocation points
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.

6.2. METHOD

1483

When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

1484
eval id
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1485

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips

1486

CHAPTER 6. KEYWORDS AREA

Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
queso
emulator
pce
collocation points
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1487

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
sc
Keywords Area
method
bayes calibration
queso
emulator
sc
Stochastic Collocation polynomial surrogate model

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
sparse grid level

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

Description
Selects stochastic collocation (SC) model to use in the Bayesian likelihood calculations. When using SC as
a surrogate within the Bayesian framework, the build points (training points) for the stochastic collocation are
constructed from a sparse grid.

1488

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
stoch collocation
sparse grid level
Keywords Area
method
bayes calibration
queso
emulator
sc
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

6.2. METHOD

1489

use derivatives
Keywords Area
method
bayes calibration
queso
emulator
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
logit transform
Keywords Area
method
bayes calibration
queso
logit transform
Utilize the logit transformation to reduce sample rejection for bounded domains

Specification
Alias: none
Argument(s): none

1490

CHAPTER 6. KEYWORDS AREA

Description
The logit transformation performs an internal variable transformation from bounded domains to unbounded domains in order to reduce sample rejection due to an out-of-bounds condition.
Default Behavior
This option is experimental at present, and is therefore defaulted off.
Usage Tips
This option can be helpful when regions of high posterior density exist in the corners of a multi-dimensional
bounded domain. In these cases, it may be difficult to generate feasible samples from the proposal density, such
that transformation to unbounded domains may greatly reduce sample rejection rates.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
dram
logit_transform

export chain points file

Keywords Area
method
bayes calibration
queso
export chain points file
Export the MCMC chain to the specified filename

Specification
Alias: none
Argument(s): STRING
Default: chain export to default filename
Required/Description of
Optional
Group
Optional(Choose
One)

tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

6.2. METHOD

1491
freeform

Selects freeform
file format

Description
The filename to which the final MCMC posterior chain will be exported.
Default Behavior No export to file.
Expected Output
A tabular data file will be produced in the specified format (annotated by default) containing samples from the
posterior distribution.
Usage Tips
Additional Discussion
annotated
Keywords Area
method
bayes calibration
queso
export chain points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips

1492

CHAPTER 6. KEYWORDS AREA

To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
bayes calibration
queso
export chain points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1493
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1494
header
Keywords Area
method
bayes calibration
queso
export chain points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
queso
export chain points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.2. METHOD
interface id
Keywords Area
method
bayes calibration
queso
export chain points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
queso
export chain points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated

1495

1496

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

dram
Keywords Area
method
bayes calibration
queso
dram
Use the DRAM MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1497

Specification
Alias: none
Argument(s): none
Default: dram

Description
The type of Markov Chain Monte Carlo used. This keyword specifies the use of DRAM, (Delayed Rejection
Adaptive Metropolis)[39].
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user knows very little about the proposal covariance, using dram is a recommended strategy. The
proposal covariance is adaptively updated, and the delayed rejection may help improve low acceptance rates.

Examples
method,
bayes_calibration queso
dram
samples = 10000 seed = 348

delayed rejection
Keywords Area
method
bayes calibration
queso
delayed rejection
Use the Delayed Rejection MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

1498

CHAPTER 6. KEYWORDS AREA

Description
This keyword specifies the use of the Delayed Rejection algorithm in which there can be a delay in rejecting
samples from the chain. That is, the DR part of DRAM is used but the AM part is not, rather a regular
Metropolis-Hastings algorithm is used.
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user knows something about the proposal covariance or the proposal covariance is informed through
derivative information, using delayed rejection is preferred over dram: the proposal covariance is already
being informed by derivative information and the adaptive metropolis is not necessary.

Examples
method,
bayes_calibration queso
delayed_rejection
samples = 10000 seed = 348

See Also
These keywords may also be of interest:
proposal covariance
adaptive metropolis
Keywords Area
method
bayes calibration
queso
adaptive metropolis
Use the Adaptive Metropolis MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

6.2. METHOD

1499

Description
This keyword specifies the use of the Adaptive Metropolis algorithm. That is, the AM part of DRAM is used
but the DR part is not: specifying this keyword activates only the Adaptive Metropolis part of the MCMC
algorithm, in which the covariance of the proposal density is updated adaptively.
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user knows very little about the proposal covariance, but doesnt want to incur the cost of using full
dram with both delayed rejection and adaptive metropolis, specifying only adaptive metropolis offers a
good strategy.

Examples
method,
bayes_calibration queso
adaptive_metropolis
samples = 10000 seed = 348

metropolis hastings
Keywords Area
method
bayes calibration
queso
metropolis hastings
Use the Metropolis-Hastings MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
This keyword specifies the use of a Metropolis-Hastings algorithm for the MCMC chain generation. This means
there is no delayed rejection and no adaptive proposal covariance updating as in DRAM.
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.

1500

CHAPTER 6. KEYWORDS AREA

Usage Tips
If the user wants to use Metropolis-Hastings, possibly as a comparison to the other methods which involve
more chain adaptation, this is the MCMC type to use.

Examples
method,
bayes_calibration queso
metropolis_hastings
samples = 10000 seed = 348

multilevel
Keywords Area
method
bayes calibration
queso
multilevel
Use the multilevel MCMC algorithm.

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
Selects the multilevel algorithm described in[70].
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
The multilevel algorithm is a more experimental algorithm than the other MCMC approaches mentioned
above. It works well in cases where the prior can be evolved to a posterior in a structured way. Currently, the
multilevel option is not in production form.

Examples
method,
bayes_calibration queso
multilevel
samples = 10000 seed = 348

6.2. METHOD

1501

rng
Keywords Area
method
bayes calibration
queso
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

1502

CHAPTER 6. KEYWORDS AREA

mt19937
Keywords Area
method
bayes calibration
queso
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
bayes calibration
queso
rng
rnum2
Generates pseudo-random numbers using the Pecos package

6.2. METHOD

1503

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

pre solve
Keywords Area
method
bayes calibration
queso
pre solve
Perform deterministic optimization for MAP before Bayesian calibration

Specification
Alias: none
Argument(s): none
Default: nip pre-solve for emulators
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
sqp

Dakota Keyword
Description
Uses a sequential
quadratic
programming
method for
underlying
optimization

1504

CHAPTER 6. KEYWORDS AREA

nip

Uses a nonlinear
interior point
method for
underlying
optimization

Description
When specified, Dakota will perform a deterministic gradient-based optimization to maximize the log posterior
(log-likelihood - log prior). The Markov Chain in Bayesian calibration will be started at the best point found in the
optimization (the MAP point). Note that both optimization methods available (sqp and nip) require gradients.
The gradients will be assessed based on the model the user specifies (e.g. if an emulator is used, the gradients will
be taken with respect to the emulator, otherwise they will be based on the user specification for the model, either
finite-difference or analytic gradients.)
Default Behavior No MAP pre-solve; simply start the MCMC process at the user-specified initial value.
Expected Output When pre-solve is enabled, the output will include a deterministic optimization, followed
by a Bayesian calibration. The final results will include the MAP point as well as posterior statistics from the
MCMC chain.

Examples
method
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
pce sparse_grid_level = 2
pre_solve nip

sqp
Keywords Area
method
bayes calibration
queso
pre solve
sqp
Uses a sequential quadratic programming method for underlying optimization

Specification
Alias: none
Argument(s): none

6.2. METHOD

1505

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The sqp
keyword directs Dakota to use a sequential quadratic programming method to solve that problem. A sequential
quadratic programming solves a sequence of linearly constrained quadratic optimization problems to arrive at the
solution to the optimization problem.
nip
Keywords Area
method
bayes calibration
queso
pre solve
nip
Uses a nonlinear interior point method for underlying optimization

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The nip
keyword directs Dakota to use a nonlinear interior point to solve that problem. A nonlinear interior point method
traverses the interior of the feasible region to arrive at the solution to the optimization problem.
proposal covariance
Keywords Area
method
bayes calibration
queso
proposal covariance
Defines the technique used to generate the MCMC proposal covariance.

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none

1506

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Dakota Keyword
derivatives

Required(Choose
One)

Group 1

Dakota Keyword
Description
Use derivatives to
inform the MCMC
proposal
covariance.

prior

Uses the
covariance of the
prior distributions
to define the
MCMC proposal
covariance.

values

Specifies matrix
values to use as the
MCMC proposal
covariance.

filename

Uses a file to
import a
user-specified
MCMC proposal
covariance.

Description
The proposal covariance is used to define a multivariate normal (MVN) jumping distribution used to create new
points within a Markov chain. That is, a new point in the chain is determined by sampling within a MVN
probability density with prescribed covariance that is centered at the current chain point. The accuracy of the
proposal covariance has a significant effect on rejection rates and the efficiency of chain mixing.
Default Behavior
The default proposal covariance is prior when no emulator is present; derivatives when an emulator
is present.
Expected Output
The effect of the proposal covariance is reflected in the MCMC chain values and the rejection rates, which can
be seen in the diagnostic outputs from the QUESO solver within the QuesoDiagnostics directory.
Usage Tips
When derivative information is available inexpensively (e.g., from an emulator model), the derived-based
proposal covariance forms a more accurate proposal distribution, resulting in lower rejection rates and faster
chain mixing.
derivatives
Keywords Area
method
bayes calibration

6.2. METHOD

1507

queso
proposal covariance
derivatives
Use derivatives to inform the MCMC proposal covariance.

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
proposal updates

Dakota Keyword
Description
Restarts the
MCMC chain with
updated
derivative-based
proposal
covariance.

Description
This keyword selection results in definition of the MCMC proposal covariance from the Hessian of the misfit
function (negative log likelihood), where this Hessian is defined from either a Gauss-Newton approximation
(using only first derivatives of the calibration terms) or a full Hessian (using values, first derivatives, and second
derivatives of the calibration terms). If this Hessian is indeterminate, it will be corrected as described in[6]
Default Behavior The default is prior based proposal covariance. This is a more advanced option that
exploits structure in the form of the likelihood.
Expected Output
When derivatives are specified for defining the proposal covariance, the misfit Hessian and its inverse (the
MVN proposal covariance) will be output to the standard output stream.
Usage Tips
The full Hessian of the misfit is used when either supported by the emulator in use (for PCE and surfpack GP,
but not SC or dakota GP) or by the users response specification (Hessian type is not no hessians), in the case of
no emulator. When this full Hessian is indefinite and cannot be inverted to form the proposal covariance, fallback
to the positive semi-definite Gauss-Newton Hessian is employed.
Since this proposal covariance is locally accurate, it should be updated periodically using the proposal updates
option. While the adaptive metropolis option can be used in combination with derivative-based preconditioning,
it is generally preferable to instead increase the proposal update frequency due to the improved local accuracy of
this approach.

1508

CHAPTER 6. KEYWORDS AREA

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator pce sparse_grid_level = 2
proposal_covariance derivatives # default proposal_updates

proposal updates
Keywords Area
method
bayes calibration
queso
proposal covariance
derivatives
proposal updates
Restarts the MCMC chain with updated derivative-based proposal covariance.

Specification
Alias: none
Argument(s): INTEGER

Description
When employing derivative-based proposal covariance, this specification defines the number of restarts that are
performed during the course of the total sample size of the MCMC chain. For each restart, a new chain is initiated
from the final point in the previous acceptance chain using updated proposal covariance corresponding to the
derivatives values at the new starting point.
Default Behavior
If proposal updates is not specified, then the default frequency for restarting the chain with updated proposal
covariance is every 100 samples.
Expected Output
Each restarted chain will generate a new QUESO header and sampling summary, and the chain diagnostics
will be appended within the outputData directory.
Usage Tips
proposal updates should be tailored to the size of the total chain, accounting for the relative expense of
derivative-based proposal updates.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator pce sparse_grid_level = 2
proposal_covariance derivatives
proposal_updates = 50 # restarted chains, each with 40 new points

6.2. METHOD

1509

prior
Keywords Area
method
bayes calibration
queso
proposal covariance
prior
Uses the covariance of the prior distributions to define the MCMC proposal covariance.

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none

Description
This keyword selection results in definition of the MCMC proposal covariance from the covariance of the prior
distributions. This covariance is currently assumed to be diagonal without correlation.
Default Behavior
This is the default proposal covariance option.
Usage Tips
Since this proposal covariance is defined globally, the chain does not need to be periodically restarted using
local updates to this proposal. However, it is usually effective to adapt the proposal using one of the adaptive
metropolis MCMC options.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
dram
proposal_covariance prior

values
Keywords Area
method
bayes calibration
queso

1510

CHAPTER 6. KEYWORDS AREA

proposal covariance
values
Specifies matrix values to use as the MCMC proposal covariance.

Specification
Alias: none
Argument(s): REALLIST
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
diagonal

matrix

Dakota Keyword
Description
Specifies the
diagonal matrix
format when
specifying a
user-specified
proposal
covariance.
Specifies the full
matrix format
when specifying a
user-specified
proposal
covariance.

Description
This keyword selection results in definition of the MCMC proposal covariance from user-specified matrix values.
The matrix input format must be declared as either a full matrix or a matrix diagonal.
Default Behavior
This option is not the default, and generally implies special a priori knowledge from the user.
Usage Tips
This option is not supported for the case of transformations to standardized probability space.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
values ... # See leaf nodes for required format option

diagonal
Keywords Area
method
bayes calibration

6.2. METHOD

1511

queso
proposal covariance
values
diagonal
Specifies the diagonal matrix format when specifying a user-specified proposal covariance.

Specification
Alias: none
Argument(s): none

Description
When specifying the MCMC proposal covariance in an input file, this keyword declares the use of a diagonal
matrix format, i.e., the user only provides the (positive) values along the diagonal.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
diagonal values 1.0e6 1.0e-1

matrix
Keywords Area
method
bayes calibration
queso
proposal covariance
values
matrix
Specifies the full matrix format when specifying a user-specified proposal covariance.

Specification
Alias: none
Argument(s): none

1512

CHAPTER 6. KEYWORDS AREA

Description
When specifying the MCMC proposal covariance in an input file, this keyword declares the use of a full matrix
format, i.e., the user provides all values of the matrix, not just the diagonal. The matrix must be symmetric,
positive-definite.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
matrix values 1.0 0.1
0.1 2.0

filename
Keywords Area
method
bayes calibration
queso
proposal covariance
filename
Uses a file to import a user-specified MCMC proposal covariance.

Specification
Alias: none
Argument(s): STRING
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
diagonal

Dakota Keyword
Description
Specifies the
diagonal matrix
format when
importing a
user-specified
proposal
covariance.

6.2. METHOD

1513
matrix

Specifies the full

matrix format
when importing a
user-specified
proposal
covariance.

Description
This keyword selection results in definition of the MCMC proposal covariance from importing data a userspecified filename. This import must be declared as either a full matrix or a matrix diagonal.
Default Behavior
This option is not the default, and generally implies special a priori knowledge from the user.
Usage Tips
This option is not supported for the case of transformations to standardized probability space.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
filename ... # See leaf nodes for required format option

diagonal
Keywords Area
method
bayes calibration
queso
proposal covariance
filename
diagonal
Specifies the diagonal matrix format when importing a user-specified proposal covariance.

Specification
Alias: none
Argument(s): none

Description
When importing the MCMC proposal covariance from a user-specified filename, this keyword declares the use of
a diagonal matrix format, i.e., the user only provides the (positive) values along the diagonal.

1514

CHAPTER 6. KEYWORDS AREA

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
diagonal filename dakota_cantilever_queso.diag.dat

matrix
Keywords Area
method
bayes calibration
queso
proposal covariance
filename
matrix
Specifies the full matrix format when importing a user-specified proposal covariance.

Specification
Alias: none
Argument(s): none

Description
When importing the MCMC proposal covariance from a user-specified filename, this keyword declares the use
of a full matrix format, i.e., the user provides all values of the matrix, not just the diagonal. The matrix must be
symmetric, positive-definite.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
matrix filename dakota_cantilever_queso.matrix.dat

gpmsa
Keywords Area
method
bayes calibration
gpmsa
(Experimental) Gaussian Process Models for Simulation Analysis (GPMSA) Markov Chain Monte Carlo
algorithm with Gaussian Process Surrogate

6.2. METHOD

1515

Topics
This keyword is related to the topics:
package queso
bayesian calibration

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

emulator samples

Optional

Optional(Choose
One)

Optional

Dakota Keyword

import build points file

MCMC algorithm
type (Group 1)

Dakota Keyword
Description
Number of data
points used to train
the surrogate
model or emulator
File containing
points you wish to
use to build a
surrogate

dram

Use the DRAM

MCMC algorithm

delayed rejection

Use the Delayed

Rejection MCMC
algorithm

adaptive metropolis

Use the Adaptive

Metropolis MCMC
algorithm

metropolis hastings

Use the
Metropolis-Hastings MCMC
algorithm

multilevel

Use the multilevel

MCMC algorithm.

rng

Selection of a
random number
generator

1516

CHAPTER 6. KEYWORDS AREA

Optional

pre solve

Perform
deterministic
optimization for
MAP before
Bayesian
calibration

Optional

proposal covariance

Defines the
technique used to
generate the
MCMC proposal
covariance.

Description
GPMSA (Gaussian Process Models for Simulation Analysis) is another approach that provides the capability
for Bayesian calibration. The GPMSA implementation currently is an experimental capability and not ready
for production use at this time. A key part of GPMSA is the construction of an emulator from simulation runs
collected at various settings of input parameters. The emulator is a statistical model of the system response, and it
is used to incorporate the observational data to improve system predictions and constrain or calibrate the unknown
parameters. The GPMSA code draws heavily on the theory developed in the seminal Bayesian calibration paper
by Kennedy and OHagan[55]. The particular approach in GPMSA has been developed by the Los Alamos group
and document in[48]. GPMSA uses Gaussian process models in the emulation, but the emulator is actually a set
of basis functions (e.g. from a singular value decomposition) which have GPs as the coefficients.
For the GPMSA method, one can define the number of samples which will be used in construction of the
emulator, emulator samples. The emulator involves Gaussian processes in GPMSA, so the user does not
specify anything about emulator type. At this point, the only controls active for GPMSA are emulator samples, seed and rng, and samples (the number of MCMC samples) and the type of MCMC algorithm (e.g. dram, delayed rejection, adaptive metropolis, metropolis hastings, or multilevel).
NOTE: the GPMSA method is in a very preliminary, prototype state at this time. The user will need to modify
certain data structures in the code for their particular application and recompile to run with GPMSA.
emulator samples
Keywords Area
method
bayes calibration
gpmsa
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER

6.2. METHOD

1517

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
import build points file
Keywords Area
method
bayes calibration
gpmsa
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips

1518

CHAPTER 6. KEYWORDS AREA

Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
gpmsa
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips

6.2. METHOD

1519

To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
bayes calibration
gpmsa
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1520

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
header
Keywords Area
method
bayes calibration
gpmsa
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
gpmsa
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1521

1522
interface id
Keywords Area
method
bayes calibration
gpmsa
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
gpmsa
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1523

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
gpmsa
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1524

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
dram
Keywords Area
method
bayes calibration
gpmsa
dram
Use the DRAM MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
The type of Markov Chain Monte Carlo used. This keyword specifies the use of DRAM, (Delayed Rejection
Adaptive Metropolis)[39].
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user knows very little about the proposal covariance, using dram is a recommended strategy. The
proposal covariance is adaptively updated, and the delayed rejection may help improve low acceptance rates.

6.2. METHOD

1525

Examples
method,
bayes_calibration queso
dram
samples = 10000 seed = 348

delayed rejection
Keywords Area
method
bayes calibration
gpmsa
delayed rejection
Use the Delayed Rejection MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
This keyword specifies the use of the Delayed Rejection algorithm in which there can be a delay in rejecting
samples from the chain. That is, the DR part of DRAM is used but the AM part is not, rather a regular
Metropolis-Hastings algorithm is used.
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user knows something about the proposal covariance or the proposal covariance is informed through
derivative information, using delayed rejection is preferred over dram: the proposal covariance is already
being informed by derivative information and the adaptive metropolis is not necessary.

Examples
method,
bayes_calibration queso
delayed_rejection
samples = 10000 seed = 348

1526

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
proposal covariance
adaptive metropolis
Keywords Area
method
bayes calibration
gpmsa
adaptive metropolis
Use the Adaptive Metropolis MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
This keyword specifies the use of the Adaptive Metropolis algorithm. That is, the AM part of DRAM is used
but the DR part is not: specifying this keyword activates only the Adaptive Metropolis part of the MCMC
algorithm, in which the covariance of the proposal density is updated adaptively.
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user knows very little about the proposal covariance, but doesnt want to incur the cost of using full
dram with both delayed rejection and adaptive metropolis, specifying only adaptive metropolis offers a
good strategy.

Examples
method,
bayes_calibration queso
adaptive_metropolis
samples = 10000 seed = 348

6.2. METHOD

1527

metropolis hastings
Keywords Area
method
bayes calibration
gpmsa
metropolis hastings
Use the Metropolis-Hastings MCMC algorithm

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
This keyword specifies the use of a Metropolis-Hastings algorithm for the MCMC chain generation. This means
there is no delayed rejection and no adaptive proposal covariance updating as in DRAM.
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
If the user wants to use Metropolis-Hastings, possibly as a comparison to the other methods which involve
more chain adaptation, this is the MCMC type to use.

Examples
method,
bayes_calibration queso
metropolis_hastings
samples = 10000 seed = 348

multilevel
Keywords Area
method
bayes calibration
gpmsa
multilevel
Use the multilevel MCMC algorithm.

1528

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Default: dram

Description
Selects the multilevel algorithm described in[70].
Default Behavior
Five MCMC algorithm variants are supported: dram, delayed rejection, adaptive metropolis,
metropolis hastings, and multilevel. The default is dram.
Usage Tips
The multilevel algorithm is a more experimental algorithm than the other MCMC approaches mentioned
above. It works well in cases where the prior can be evolved to a posterior in a structured way. Currently, the
multilevel option is not in production form.

Examples
method,
bayes_calibration queso
multilevel
samples = 10000 seed = 348

rng
Keywords Area
method
bayes calibration
gpmsa
rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )

6.2. METHOD

1529
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
bayes calibration
gpmsa
rng
mt19937
Generates random numbers using the Mersenne twister

Specification
Alias: none
Argument(s): none

1530

CHAPTER 6. KEYWORDS AREA

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
bayes calibration
gpmsa
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

6.2. METHOD

1531

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

pre solve
Keywords Area
method
bayes calibration
gpmsa
pre solve
Perform deterministic optimization for MAP before Bayesian calibration

Specification
Alias: none
Argument(s): none
Default: nip pre-solve for emulators
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
sqp

nip

Dakota Keyword
Description
Uses a sequential
quadratic
programming
method for
underlying
optimization
Uses a nonlinear
interior point
method for
underlying
optimization

Description
When specified, Dakota will perform a deterministic gradient-based optimization to maximize the log posterior
(log-likelihood - log prior). The Markov Chain in Bayesian calibration will be started at the best point found in the
optimization (the MAP point). Note that both optimization methods available (sqp and nip) require gradients.
The gradients will be assessed based on the model the user specifies (e.g. if an emulator is used, the gradients will
be taken with respect to the emulator, otherwise they will be based on the user specification for the model, either
finite-difference or analytic gradients.)
Default Behavior No MAP pre-solve; simply start the MCMC process at the user-specified initial value.

1532

CHAPTER 6. KEYWORDS AREA

Expected Output When pre-solve is enabled, the output will include a deterministic optimization, followed
by a Bayesian calibration. The final results will include the MAP point as well as posterior statistics from the
MCMC chain.

Examples
method
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
pce sparse_grid_level = 2
pre_solve nip

sqp
Keywords Area
method
bayes calibration
gpmsa
pre solve
sqp
Uses a sequential quadratic programming method for underlying optimization

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The sqp
keyword directs Dakota to use a sequential quadratic programming method to solve that problem. A sequential
quadratic programming solves a sequence of linearly constrained quadratic optimization problems to arrive at the
solution to the optimization problem.
nip
Keywords Area
method
bayes calibration
gpmsa
pre solve
nip
Uses a nonlinear interior point method for underlying optimization

6.2. METHOD

1533

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The nip
keyword directs Dakota to use a nonlinear interior point to solve that problem. A nonlinear interior point method
traverses the interior of the feasible region to arrive at the solution to the optimization problem.
proposal covariance
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
Defines the technique used to generate the MCMC proposal covariance.

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
derivatives

Required(Choose
One)

Group 1

prior

Dakota Keyword
Description
Use derivatives to
inform the MCMC
proposal
covariance.
Uses the
covariance of the
prior distributions
to define the
MCMC proposal
covariance.

1534

CHAPTER 6. KEYWORDS AREA

values

Specifies matrix
values to use as the
MCMC proposal
covariance.

filename

Uses a file to
import a
user-specified
MCMC proposal
covariance.

Description
The proposal covariance is used to define a multivariate normal (MVN) jumping distribution used to create new
points within a Markov chain. That is, a new point in the chain is determined by sampling within a MVN
probability density with prescribed covariance that is centered at the current chain point. The accuracy of the
proposal covariance has a significant effect on rejection rates and the efficiency of chain mixing.
Default Behavior
The default proposal covariance is prior when no emulator is present; derivatives when an emulator
is present.
Expected Output
The effect of the proposal covariance is reflected in the MCMC chain values and the rejection rates, which can
be seen in the diagnostic outputs from the QUESO solver within the QuesoDiagnostics directory.
Usage Tips
When derivative information is available inexpensively (e.g., from an emulator model), the derived-based
proposal covariance forms a more accurate proposal distribution, resulting in lower rejection rates and faster
chain mixing.
derivatives
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
derivatives
Use derivatives to inform the MCMC proposal covariance.

Topics
This keyword is related to the topics:
bayesian calibration

6.2. METHOD

Specification
Alias: none
Argument(s): none

1535

1536

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
proposal updates

Dakota Keyword
Description
Restarts the
MCMC chain with
updated
derivative-based
proposal
covariance.

Description
This keyword selection results in definition of the MCMC proposal covariance from the Hessian of the misfit
function (negative log likelihood), where this Hessian is defined from either a Gauss-Newton approximation
(using only first derivatives of the calibration terms) or a full Hessian (using values, first derivatives, and second
derivatives of the calibration terms). If this Hessian is indeterminate, it will be corrected as described in[6]
Default Behavior The default is prior based proposal covariance. This is a more advanced option that
exploits structure in the form of the likelihood.
Expected Output
When derivatives are specified for defining the proposal covariance, the misfit Hessian and its inverse (the
MVN proposal covariance) will be output to the standard output stream.
Usage Tips
The full Hessian of the misfit is used when either supported by the emulator in use (for PCE and surfpack GP,
but not SC or dakota GP) or by the users response specification (Hessian type is not no hessians), in the case of
no emulator. When this full Hessian is indefinite and cannot be inverted to form the proposal covariance, fallback
to the positive semi-definite Gauss-Newton Hessian is employed.
Since this proposal covariance is locally accurate, it should be updated periodically using the proposal updates
option. While the adaptive metropolis option can be used in combination with derivative-based preconditioning,
it is generally preferable to instead increase the proposal update frequency due to the improved local accuracy of
this approach.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator pce sparse_grid_level = 2
proposal_covariance derivatives # default proposal_updates

proposal updates
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
derivatives

6.2. METHOD

1537

proposal updates
Restarts the MCMC chain with updated derivative-based proposal covariance.

Specification
Alias: none
Argument(s): INTEGER

Description
When employing derivative-based proposal covariance, this specification defines the number of restarts that are
performed during the course of the total sample size of the MCMC chain. For each restart, a new chain is initiated
from the final point in the previous acceptance chain using updated proposal covariance corresponding to the
derivatives values at the new starting point.
Default Behavior
If proposal updates is not specified, then the default frequency for restarting the chain with updated proposal
covariance is every 100 samples.
Expected Output
Each restarted chain will generate a new QUESO header and sampling summary, and the chain diagnostics
will be appended within the outputData directory.
Usage Tips
proposal updates should be tailored to the size of the total chain, accounting for the relative expense of
derivative-based proposal updates.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator pce sparse_grid_level = 2
proposal_covariance derivatives
proposal_updates = 50 # restarted chains, each with 40 new points

prior
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
prior
Uses the covariance of the prior distributions to define the MCMC proposal covariance.

Topics
This keyword is related to the topics:
bayesian calibration

1538

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
This keyword selection results in definition of the MCMC proposal covariance from the covariance of the prior
distributions. This covariance is currently assumed to be diagonal without correlation.
Default Behavior
This is the default proposal covariance option.
Usage Tips
Since this proposal covariance is defined globally, the chain does not need to be periodically restarted using
local updates to this proposal. However, it is usually effective to adapt the proposal using one of the adaptive
metropolis MCMC options.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
dram
proposal_covariance prior

values
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
values
Specifies matrix values to use as the MCMC proposal covariance.

Specification
Alias: none
Argument(s): REALLIST

6.2. METHOD

1539
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
diagonal

matrix

Dakota Keyword
Description
Specifies the
diagonal matrix
format when
specifying a
user-specified
proposal
covariance.
Specifies the full
matrix format
when specifying a
user-specified
proposal
covariance.

Description
This keyword selection results in definition of the MCMC proposal covariance from user-specified matrix values.
The matrix input format must be declared as either a full matrix or a matrix diagonal.
Default Behavior
This option is not the default, and generally implies special a priori knowledge from the user.
Usage Tips
This option is not supported for the case of transformations to standardized probability space.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
values ... # See leaf nodes for required format option

diagonal
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
values
diagonal
Specifies the diagonal matrix format when specifying a user-specified proposal covariance.

1540

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
When specifying the MCMC proposal covariance in an input file, this keyword declares the use of a diagonal
matrix format, i.e., the user only provides the (positive) values along the diagonal.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
diagonal values 1.0e6 1.0e-1

matrix
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
values
matrix
Specifies the full matrix format when specifying a user-specified proposal covariance.

Specification
Alias: none
Argument(s): none

Description
When specifying the MCMC proposal covariance in an input file, this keyword declares the use of a full matrix
format, i.e., the user provides all values of the matrix, not just the diagonal. The matrix must be symmetric,
positive-definite.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
matrix values 1.0 0.1
0.1 2.0

6.2. METHOD

1541

filename
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
filename
Uses a file to import a user-specified MCMC proposal covariance.

Specification
Alias: none
Argument(s): STRING
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
diagonal

matrix

Dakota Keyword
Description
Specifies the
diagonal matrix
format when
importing a
user-specified
proposal
covariance.
Specifies the full
matrix format
when importing a
user-specified
proposal
covariance.

Description
This keyword selection results in definition of the MCMC proposal covariance from importing data a userspecified filename. This import must be declared as either a full matrix or a matrix diagonal.
Default Behavior
This option is not the default, and generally implies special a priori knowledge from the user.
Usage Tips
This option is not supported for the case of transformations to standardized probability space.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
filename ... # See leaf nodes for required format option

1542

CHAPTER 6. KEYWORDS AREA

diagonal
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
filename
diagonal
Specifies the diagonal matrix format when importing a user-specified proposal covariance.

Specification
Alias: none
Argument(s): none

Description
When importing the MCMC proposal covariance from a user-specified filename, this keyword declares the use of
a diagonal matrix format, i.e., the user only provides the (positive) values along the diagonal.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
diagonal filename dakota_cantilever_queso.diag.dat

matrix
Keywords Area
method
bayes calibration
gpmsa
proposal covariance
filename
matrix
Specifies the full matrix format when importing a user-specified proposal covariance.

6.2. METHOD

1543

Specification
Alias: none
Argument(s): none

Description
When importing the MCMC proposal covariance from a user-specified filename, this keyword declares the use
of a full matrix format, i.e., the user provides all values of the matrix, not just the diagonal. The matrix must be
symmetric, positive-definite.

Examples
method,
bayes_calibration queso
samples = 1000 seed = 348
dram
proposal_covariance
matrix filename dakota_cantilever_queso.matrix.dat

wasabi
Keywords Area
method
bayes calibration
wasabi
(Experimental Method) Non-MCMC Bayesian inference using interval analysis

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Required

Description of
Group

Dakota Keyword
emulator

data distribution

Dakota Keyword
Description
Use an emulator or
surrogate model to
evaluate the
likelihood function
(Experimental
Capability)
Specify the
distribution of the
experimental data

1544

CHAPTER 6. KEYWORDS AREA

Optional

posterior density export filename

Optional

posterior samplesexport filename

Optional

posterior samplesimport filename

Optional

generate posteriorsamples

(Experimental
Capability)
Filename for the
exported posterior
density
(Experimental
Capability)
Filename for the
exported posterior
samples
(Experimental
Capability)
Filename for
imported posterior
samples
(Experimental
Capability)
Generate random
samples from the
posterior density

Description
Offers an alternative to Markov Chain Monte Carlo-based Bayesian inference. This is a nascent capability, not
yet ready for production use.
Usage Guidelines: The WASABI method requires an emulator model.
Attention: While the emulator specification for WASABI includes the keyword posterior adaptive, it is
not yet operational.

Examples
method
bayes_calibration
wasabi

emulator
Keywords Area
method
bayes calibration
wasabi
emulator
Use an emulator or surrogate model to evaluate the likelihood function

Specification
Alias: none
Argument(s): none

6.2. METHOD

1545
Required/Optional

Description of
Group

Required(Choose
One)

emulator type
(Group 1)

Optional

Dakota Keyword
gaussian process

Dakota Keyword
Description
Gaussian Process
surrogate model

pce

Polynomial Chaos
Expansion
surrogate model

sc

Stochastic
Collocation
polynomial
surrogate model

use derivatives

Use derivative data

to construct
surrogate models

Description
This keyword describes the type of emulator used when calculating the likelihood function for the Bayesian
calibration. The emulator can be a Gaussian process, polynomial chaos expansion, or stochastic collocation.

gaussian process
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process

1546

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

dakota

Optional

emulator samples

Optional

posterior adaptive

Optional

import build points file

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate
Number of data
points used to train
the surrogate
model or emulator
Adapt the emulator
model to achieve
greater accuracy in
regions of high
posterior
probability.
File containing
points you wish to
use to build a
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

6.2. METHOD

1547

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient

1548

CHAPTER 6. KEYWORDS AREA

information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.

6.2. METHOD

1549

emulator samples
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
posterior adaptive
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

1550

CHAPTER 6. KEYWORDS AREA

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

6.2. METHOD

1551

Optional

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
annotated
Selects annotated tabular file format

1552

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1553

custom annotated
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

1554

CHAPTER 6. KEYWORDS AREA

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process

1555

1556
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1557

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
wasabi
emulator
gaussian process
import build points file
active only
Import only active variables from tabular data file

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1558

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
pce
Keywords Area
method
bayes calibration
wasabi
emulator
pce
Polynomial Chaos Expansion surrogate model

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
sparse grid level

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

6.2. METHOD

1559
expansion order

The (initial) order

of a polynomial
expansion

collocation points

Specify the
number of
collocation points
used to estimate
PCE coefficients
using regression or
orthogonal-leastinterpolation.

Description
Selects a polynomial chaos expansion (PCE) surrogate model to use in the Bayesian likelihood calculations.
When using PCE as a surrogate within the Bayesian framework, the PCE coefficients can be computed either
from integration using a sparse grid or from regression using a random/unstructured data set.

See Also
These keywords may also be of interest:
polynomial chaos
sparse grid level
Keywords Area
method
bayes calibration
wasabi
emulator
pce
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

1560

CHAPTER 6. KEYWORDS AREA

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

expansion order
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
The (initial) order of a polynomial expansion

Specification
Alias: none
Argument(s): INTEGERLIST

6.2. METHOD

1561
Required/Optional
Required

Description of
Group

Dakota Keyword
collocation ratio

Dakota Keyword
Description
Set the number of
points used to
build a PCE via
regression to be
proportional to the
number of terms in
the expansion.

Optional

posterior adaptive

Adapt the emulator

model to achieve
greater accuracy in
regions of high
posterior
probability.

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Description
When the expansion order for a a polynomial chaos expansion is specified, the coefficients may be computed
by integration based on random samples or by regression using either random or sub-sampled tensor product
quadrature points.
Multidimensional integration by Latin hypercube sampling (specified with expansion samples). In this
case, the expansion order p cannot be inferred from the numerical integration specification and it is necessary to
provide an expansion order to specify p for a total-order expansion.
Linear regression (specified with either collocation points or collocation ratio). A total-order
expansion is used and must be specified using expansion order as described in the previous option. To
avoid requiring the user to calculate N from n and p), the collocation ratio allows for specification of a
constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this
case, the number of samples becomes cN o where c is the collocation ratio and o is the ratio order.
The use derivatives flag informs the regression approach to include derivative matching equations (limited
to gradients at present) in the least squares solutions, enabling the use of fewer collocation points for a given
cN o
expansion order and dimension (number of points required becomes n+1
). When admissible, a constrained least
squares approach is employed in which response values are first reproduced exactly and error in reproducing
response derivatives is minimized. Two collocation grid options are supported: the default is Latin hypercube
sampling (point collocation), and an alternate approach of probabilistic collocation is also available through
inclusion of the tensor grid keyword. In this alternate case, the collocation grid is defined using a subset of
tensor-product quadrature points: the order of the tensor-product grid is selected as one more than the expansion
order in each dimension (to avoid sampling at roots of the basis polynomials) and then the tensor multi-index is
uniformly sampled to generate a non-repeated subset of tensor quadrature points.
If collocation points or collocation ratio is specified, the PCE coefficients will be determined
by regression. If no regression specification is provided, appropriate defaults are defined. Specifically SVD-based
least-squares will be used for solving over-determined systems and under-determined systems will be solved

1562

CHAPTER 6. KEYWORDS AREA

using LASSO. For the situation when the number of function values is smaller than the number of terms in a
PCE, but the total number of samples including gradient values is greater than the number of terms, the resulting
over-determined system will be solved using equality constrained least squares. Technical information on the
various methods listed below can be found in the Linear regression section of the Theory Manual. Some of the
regression methods (OMP, LASSO, and LARS) are able to produce a set of possible PCE coefficient vectors
(see the Linear regression section in the Theory Manual). If cross validation is inactive, then only one solution,
consistent with the noise tolerance, will be returned. If cross validation is active, Dakota will choose
between possible coefficient vectors found internally by the regression method across the set of expansion orders
(1,...,expansion order) and the set of specified noise tolerances and return the one with the lowest cross
validation error indicator.
collocation ratio
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
collocation ratio
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion.

Specification
Alias: none
Argument(s): REAL

Description
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion. To avoid requiring the user to calculate N from n and p, the collocation ratio allows for specification
of a constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this case,
the number of samples becomes cN o where c is the collocation ratio and o is the ratio order. The use derivatives
flag informs the regression approach to include derivative matching equations (limited to gradients at present) in
the least squares solutions, enabling the use of fewer collocation points for a given expansion order and dimension
cN o
(number of points required becomes n+1
).

6.2. METHOD

1563

posterior adaptive
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
import build points file
File containing points you wish to use to build a surrogate

1564

CHAPTER 6. KEYWORDS AREA

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method

6.2. METHOD

1565

bayes calibration
wasabi
emulator
pce
expansion order
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1566

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.2. METHOD

1567
Optional

header

Enable header row

in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1568
header
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
wasabi
emulator

1569

1570

CHAPTER 6. KEYWORDS AREA

pce
expansion order
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991
...

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1571

active only
Keywords Area
method
bayes calibration
wasabi
emulator
pce
expansion order
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
collocation points
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonalleast-interpolation.

1572

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
posterior adaptive

import build points file

Dakota Keyword
Description
Adapt the emulator
model to achieve
greater accuracy in
regions of high
posterior
probability.
File containing
points you wish to
use to build a
surrogate

Description
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonal-leastinterpolation.
posterior adaptive
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

6.2. METHOD

1573

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

1574

CHAPTER 6. KEYWORDS AREA

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

6.2. METHOD

1575

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

custom annotated
Keywords Area
method
bayes calibration
wasabi
emulator

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1576

CHAPTER 6. KEYWORDS AREA

pce
collocation points
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.

6.2. METHOD

1577

When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

1578
eval id
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1579

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips

1580

CHAPTER 6. KEYWORDS AREA

Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
wasabi
emulator
pce
collocation points
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1581

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
sc
Keywords Area
method
bayes calibration
wasabi
emulator
sc
Stochastic Collocation polynomial surrogate model

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
sparse grid level

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

Description
Selects stochastic collocation (SC) model to use in the Bayesian likelihood calculations. When using SC as
a surrogate within the Bayesian framework, the build points (training points) for the stochastic collocation are
constructed from a sparse grid.

1582

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
stoch collocation
sparse grid level
Keywords Area
method
bayes calibration
wasabi
emulator
sc
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

6.2. METHOD

1583

use derivatives
Keywords Area
method
bayes calibration
wasabi
emulator
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
data distribution
Keywords Area
method
bayes calibration
wasabi
data distribution
(Experimental Capability) Specify the distribution of the experimental data

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

1584

CHAPTER 6. KEYWORDS AREA

Required(Choose
One)

Group 1

gaussian

obs data filename

(Experimental
Capability)
Gaussian error
distribution
(Experimental
Capability)
Filename from
which to read
experimental data

gaussian
Keywords Area
method
bayes calibration
wasabi
data distribution
gaussian
(Experimental Capability) Gaussian error distribution

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Required

means
Keywords Area
method
bayes calibration
wasabi
data distribution

Description of
Group

Dakota Keyword
means

covariance

Dakota Keyword
Description
(Experimental
Capability) Means
of Gaussian error
distribution
(Experimental
Capability)
Covariance of a
Gaussian error
distribution

6.2. METHOD

1585

gaussian
means
(Experimental Capability) Means of Gaussian error distribution

Specification
Alias: none
Argument(s): REALLIST
covariance
Keywords Area
method
bayes calibration
wasabi
data distribution
gaussian
covariance
(Experimental Capability) Covariance of a Gaussian error distribution

Specification
Alias: none
Argument(s): REALLIST
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
diagonal

matrix

diagonal
Keywords Area
method
bayes calibration
wasabi

Dakota Keyword
Description
(Experimental
Capability)
Diagonal error
covariance
(Experimental
Capability)
Symmetric positive
definite error
covariance

1586

CHAPTER 6. KEYWORDS AREA

data distribution
gaussian
covariance
diagonal
(Experimental Capability) Diagonal error covariance

Specification
Alias: none
Argument(s): none
matrix
Keywords Area
method
bayes calibration
wasabi
data distribution
gaussian
covariance
matrix
(Experimental Capability) Symmetric positive definite error covariance

Specification
Alias: none
Argument(s): none
obs data filename
Keywords Area
method
bayes calibration
wasabi
data distribution
obs data filename
(Experimental Capability) Filename from which to read experimental data

6.2. METHOD

Specification
Alias: none
Argument(s): STRING
posterior density export filename
Keywords Area
method
bayes calibration
wasabi
posterior density export filename
(Experimental Capability) Filename for the exported posterior density

Specification
Alias: none
Argument(s): STRING
posterior samples export filename
Keywords Area
method
bayes calibration
wasabi
posterior samples export filename
(Experimental Capability) Filename for the exported posterior samples

Specification
Alias: none
Argument(s): STRING
posterior samples import filename
Keywords Area
method
bayes calibration
wasabi
posterior samples import filename
(Experimental Capability) Filename for imported posterior samples

1587

1588

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
generate posterior samples
Keywords Area
method
bayes calibration
wasabi
generate posterior samples
(Experimental Capability) Generate random samples from the posterior density

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
evaluate posteriordensity

evaluate posterior density

Keywords Area
method
bayes calibration
wasabi
generate posterior samples
evaluate posterior density
(Experimental Capability) Evaluate the posterior density and output to the specified file

Specification
Alias: none
Argument(s): none

Dakota Keyword
Description
(Experimental
Capability)
Evaluate the
posterior density
and output to the
specified file

6.2. METHOD

1589

dream
Keywords Area
method
bayes calibration
dream
DREAM (DiffeRential Evolution Adaptive Metropolis)

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
chains

Optional

num cr

Optional
Optional

crossover chain pairs

gr threshold

Optional

jump step

Optional

emulator

Dakota Keyword
Description
Number of chains
in DREAM
Number of
candidate points
for each crossover.
Number of chains
used in crossover.
Convergence
tolerance for the
Gelman-Rubin
statistic
Number of
generations a long
jump step is taken
Use an emulator or
surrogate model to
evaluate the
likelihood function

Description
The DiffeRential Evolution Adaptive Metropolis algorithm is described in[86]. For the DREAM method, one can
define the number of chains used with chains (minimum 3). The total number of generations per chain in DREAM is the number of samples (samples) divided by the number of chains (chains). The number of chains
randomly selected to be used in the crossover each time a crossover occurs is crossover chain pairs.
There is an extra adaptation during burn-in, in which DREAM estimates a distribution of crossover probabilities
that favors large jumps over smaller ones in each of the chains. Normalization is required to ensure that all of

1590

CHAPTER 6. KEYWORDS AREA

the input dimensions contribute equally. In this process, a discrete number of candidate points for each crossover
value is generated. This parameter is num cr. The gr threshold is the convergence tolerance for the GelmanRubin statistic which will govern the convergence of the multiple chain process. The integer jump step forces
a long jump every jump step generations. For more details about these parameters, see[86].
Attention: While the emulator specification for DREAM includes the keyword posterior adaptive, it is
not yet operational.
chains
Keywords Area
method
bayes calibration
dream
chains
Number of chains in DREAM

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): INTEGER
Default: 3

Description
Number of chains in DREAM
num cr
Keywords Area
method
bayes calibration
dream
num cr
Number of candidate points for each crossover.

Topics
This keyword is related to the topics:
bayesian calibration

6.2. METHOD

1591

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
In DREAM, there is an extra adaptation during burn-in, in which DREAM estimates a distribution of crossover
probabilities that favors large jumps over smaller ones in each of the chains. Normalization is required to ensure
that all of the input dimensions contribute equally. In this process, a discrete number of candidate points for each
crossover value is generated. This parameter is num cr.
crossover chain pairs
Keywords Area
method
bayes calibration
dream
crossover chain pairs
Number of chains used in crossover.

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): INTEGER
Default: 3

Description
The number of chains randomly selected to be used in the crossover each time a crossover occurs.
gr threshold
Keywords Area
method
bayes calibration
dream
gr threshold
Convergence tolerance for the Gelman-Rubin statistic

1592

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): REAL
Default: 1.2

Description
The gr threshold is the convergence tolerance for the Gelman-Rubin statistic which will govern the convergence
of the multiple chain process.
jump step
Keywords Area
method
bayes calibration
dream
jump step
Number of generations a long jump step is taken

Topics
This keyword is related to the topics:
bayesian calibration

Specification
Alias: none
Argument(s): INTEGER
Default: 5

Description
The integer jump step forces a long jump every jump step generations in DREAM.

6.2. METHOD

1593

emulator
Keywords Area
method
bayes calibration
dream
emulator
Use an emulator or surrogate model to evaluate the likelihood function

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

emulator type
(Group 1)

Optional

Dakota Keyword
gaussian process

Dakota Keyword
Description
Gaussian Process
surrogate model

pce

Polynomial Chaos
Expansion
surrogate model

sc

Stochastic
Collocation
polynomial
surrogate model

use derivatives

Use derivative data

to construct
surrogate models

Description
This keyword describes the type of emulator used when calculating the likelihood function for the Bayesian
calibration. The emulator can be a Gaussian process, polynomial chaos expansion, or stochastic collocation.
gaussian process
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
Gaussian Process surrogate model

1594

CHAPTER 6. KEYWORDS AREA

Specification
Alias: kriging
Argument(s): none
Default: Surfpack Gaussian process
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
surfpack

dakota

Optional

emulator samples

Optional

posterior adaptive

Optional

import build points file

Dakota Keyword
Description
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate
Number of data
points used to train
the surrogate
model or emulator
Adapt the emulator
model to achieve
greater accuracy in
regions of high
posterior
probability.
File containing
points you wish to
use to build a
surrogate

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
surfpack
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

6.2. METHOD

1595

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also

1596

CHAPTER 6. KEYWORDS AREA

significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.

6.2. METHOD

1597

This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
emulator samples
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
emulator samples
Number of data points used to train the surrogate model or emulator

Specification
Alias: none
Argument(s): INTEGER

Description
This keyword refers to the number of build points or training points used to construct a Gaussian process emulator.
If the user specifies a number of emulator samples that is less than the minimum number of points required
to build the GP surrogate, Dakota will augment the samples to obtain the minimum required.
posterior adaptive
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

1598

CHAPTER 6. KEYWORDS AREA

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

6.2. METHOD

1599

Optional

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
annotated
Selects annotated tabular file format

1600

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1601

custom annotated
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

1602

CHAPTER 6. KEYWORDS AREA

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
dream
emulator
gaussian process

1603

1604
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1605

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
dream
emulator
gaussian process
import build points file
active only
Import only active variables from tabular data file

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1606

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.

pce
Keywords Area
method
bayes calibration
dream
emulator
pce
Polynomial Chaos Expansion surrogate model

Specification
Alias: none
Argument(s): none

6.2. METHOD

1607
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
sparse grid level

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

expansion order

The (initial) order

of a polynomial
expansion

collocation points

Specify the
number of
collocation points
used to estimate
PCE coefficients
using regression or
orthogonal-leastinterpolation.

Description
Selects a polynomial chaos expansion (PCE) surrogate model to use in the Bayesian likelihood calculations.
When using PCE as a surrogate within the Bayesian framework, the PCE coefficients can be computed either
from integration using a sparse grid or from regression using a random/unstructured data set.

See Also
These keywords may also be of interest:
polynomial chaos
sparse grid level
Keywords Area
method
bayes calibration
dream
emulator
pce
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

1608

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.
expansion order
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
The (initial) order of a polynomial expansion

Specification
Alias: none
Argument(s): INTEGERLIST

6.2. METHOD

1609
Required/Optional
Required

Description of
Group

Dakota Keyword
collocation ratio

Dakota Keyword
Description
Set the number of
points used to
build a PCE via
regression to be
proportional to the
number of terms in
the expansion.

Optional

posterior adaptive

Adapt the emulator

model to achieve
greater accuracy in
regions of high
posterior
probability.

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Description
When the expansion order for a a polynomial chaos expansion is specified, the coefficients may be computed
by integration based on random samples or by regression using either random or sub-sampled tensor product
quadrature points.
Multidimensional integration by Latin hypercube sampling (specified with expansion samples). In this
case, the expansion order p cannot be inferred from the numerical integration specification and it is necessary to
provide an expansion order to specify p for a total-order expansion.
Linear regression (specified with either collocation points or collocation ratio). A total-order
expansion is used and must be specified using expansion order as described in the previous option. To
avoid requiring the user to calculate N from n and p), the collocation ratio allows for specification of a
constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this
case, the number of samples becomes cN o where c is the collocation ratio and o is the ratio order.
The use derivatives flag informs the regression approach to include derivative matching equations (limited
to gradients at present) in the least squares solutions, enabling the use of fewer collocation points for a given
cN o
expansion order and dimension (number of points required becomes n+1
). When admissible, a constrained least
squares approach is employed in which response values are first reproduced exactly and error in reproducing
response derivatives is minimized. Two collocation grid options are supported: the default is Latin hypercube
sampling (point collocation), and an alternate approach of probabilistic collocation is also available through
inclusion of the tensor grid keyword. In this alternate case, the collocation grid is defined using a subset of
tensor-product quadrature points: the order of the tensor-product grid is selected as one more than the expansion
order in each dimension (to avoid sampling at roots of the basis polynomials) and then the tensor multi-index is
uniformly sampled to generate a non-repeated subset of tensor quadrature points.
If collocation points or collocation ratio is specified, the PCE coefficients will be determined
by regression. If no regression specification is provided, appropriate defaults are defined. Specifically SVD-based
least-squares will be used for solving over-determined systems and under-determined systems will be solved

1610

CHAPTER 6. KEYWORDS AREA

using LASSO. For the situation when the number of function values is smaller than the number of terms in a
PCE, but the total number of samples including gradient values is greater than the number of terms, the resulting
over-determined system will be solved using equality constrained least squares. Technical information on the
various methods listed below can be found in the Linear regression section of the Theory Manual. Some of the
regression methods (OMP, LASSO, and LARS) are able to produce a set of possible PCE coefficient vectors
(see the Linear regression section in the Theory Manual). If cross validation is inactive, then only one solution,
consistent with the noise tolerance, will be returned. If cross validation is active, Dakota will choose
between possible coefficient vectors found internally by the regression method across the set of expansion orders
(1,...,expansion order) and the set of specified noise tolerances and return the one with the lowest cross
validation error indicator.
collocation ratio
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
collocation ratio
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion.

Specification
Alias: none
Argument(s): REAL

Description
Set the number of points used to build a PCE via regression to be proportional to the number of terms in the
expansion. To avoid requiring the user to calculate N from n and p, the collocation ratio allows for specification
of a constant factor applied to N (e.g., collocation ratio = 2. produces samples = 2N). In addition, the default
linear relationship with N can be overridden using a real-valued exponent specified using ratio order. In this case,
the number of samples becomes cN o where c is the collocation ratio and o is the ratio order. The use derivatives
flag informs the regression approach to include derivative matching equations (limited to gradients at present) in
the least squares solutions, enabling the use of fewer collocation points for a given expansion order and dimension
cN o
(number of points required becomes n+1
).

6.2. METHOD

1611

posterior adaptive
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
import build points file
File containing points you wish to use to build a surrogate

1612

CHAPTER 6. KEYWORDS AREA

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method

6.2. METHOD

1613

bayes calibration
dream
emulator
pce
expansion order
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1614

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1615
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1616
header
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
dream
emulator

1617

1618

CHAPTER 6. KEYWORDS AREA

pce
expansion order
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991
...

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1619

active only
Keywords Area
method
bayes calibration
dream
emulator
pce
expansion order
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
collocation points
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonalleast-interpolation.

1620

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
posterior adaptive

import build points file

Dakota Keyword
Description
Adapt the emulator
model to achieve
greater accuracy in
regions of high
posterior
probability.
File containing
points you wish to
use to build a
surrogate

Description
Specify the number of collocation points used to estimate PCE coefficients using regression or orthogonal-leastinterpolation.
posterior adaptive
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
posterior adaptive
Adapt the emulator model to achieve greater accuracy in regions of high posterior probability.

Specification
Alias: none
Argument(s): none

Description
Following an emulator-based MCMC process, this option refines the emulator by selecting points in regions of
high posterior probability, performing truth evaluations at these points, updating the emulator, and reperforming
the MCMC process. The adaptation is continued until the maximum number of iterations is exceeded or the
convergence tolerance is met.

6.2. METHOD

1621

Examples
bayes_calibration queso
samples = 2000 seed = 348
delayed_rejection
emulator
gaussian_process surfpack emulator_samples = 30
posterior_adaptive max_iterations = 10
proposal_covariance derivatives

import build points file

Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

1622

CHAPTER 6. KEYWORDS AREA

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

6.2. METHOD

1623

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

custom annotated
Keywords Area
method
bayes calibration
dream
emulator

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1624

CHAPTER 6. KEYWORDS AREA

pce
collocation points
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.

6.2. METHOD

1625

When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated

1626
eval id
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1627

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips

1628

CHAPTER 6. KEYWORDS AREA

Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
bayes calibration
dream
emulator
pce
collocation points
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1629

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
sc
Keywords Area
method
bayes calibration
dream
emulator
sc
Stochastic Collocation polynomial surrogate model

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
sparse grid level

Dakota Keyword
Description
Set the sparse grid
level to be used
when peforming
sparse grid
integration or
sparse grid
interpolation

Description
Selects stochastic collocation (SC) model to use in the Bayesian likelihood calculations. When using SC as
a surrogate within the Bayesian framework, the build points (training points) for the stochastic collocation are
constructed from a sparse grid.

1630

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
stoch collocation
sparse grid level
Keywords Area
method
bayes calibration
dream
emulator
sc
sparse grid level
Set the sparse grid level to be used when peforming sparse grid integration or sparse grid interpolation

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Multi-dimensional integration by the Smolyak sparse grid method (specified with sparse grid level and, optionally, dimension preference). The underlying one-dimensional integration rules are the same as for the tensorproduct quadrature case; however, the default rule selection is nested for sparse grids (Genz-Keister for normals/transformed normals and Gauss-Patterson for uniforms/transformed uniforms). This default can be overridden with an explicit non nested specification (resulting in Gauss-Hermite for normals/transformed normals
and Gauss-Legendre for uniforms/transformed uniforms). As for tensor quadrature, the dimension preference
specification enables the use of anisotropic sparse grids (refer to the PCE description in the Users Manual for
the anisotropic index set constraint definition). Similar to anisotropic tensor grids, the dimension with greatest
preference will have resolution at the full sparse grid level and all other dimension resolutions will be reduced in
proportion to their reduced preference. For PCE with either isotropic or anisotropic sparse grids, a summation of
tensor-product expansions is used, where each anisotropic tensor-product quadrature rule underlying the sparse
grid construction results in its own anisotropic tensor-product expansion as described in case 1. These anisotropic
tensor-product expansions are summed into a sparse PCE using the standard Smolyak summation (again, refer to
the Users Manual for additional details). As for quadrature order, the sparse grid level specification admits an
array input for enabling specification of multiple grid resolutions used by certain advanced solution methodologies.
This keyword can be used when using sparse grid integration to calculate PCE coefficients or when generating
samples for sparse grid collocation.

6.2. METHOD

1631

use derivatives
Keywords Area
method
bayes calibration
dream
emulator
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.

standardized space
Keywords Area
method
bayes calibration
standardized space
Perform Bayesian inference in standardized probability space

Specification
Alias: none
Argument(s): none

1632

CHAPTER 6. KEYWORDS AREA

Description
This option transforms the inference process (MCMC sampling and any emulator model management) into a
standardized probability space.
The variable transformations performed are as described in askey.
Default Behavior
The default for the Gaussian process and no emulator options is to perform inference in the original probability
space (no transformation). Polynomial chaos and stochastic collocation emulators, on the other hand, are always
formed in standardized probability space, such that the inference process is also performed in this standardized
space.
Expected Output
The user will see the truth model evaluations performed in the original space, whereas any method diagnostics
relating to the MCMC samples (e.g., QUESO data in the outputData directory) will report points and response
data (response gradients and Hessians, if present, will differ but response values will not) that correspond to the
transformed space.
Usage Tips
Selecting standardized space generally has the effect of scaling the random variables to be of comparable
magnitude, which can improve the efficiency of the Bayesian inference process.

Examples
method,
bayes_calibration queso
samples = 2000 seed = 348
dram
standardized_space

calibrate error multipliers

Keywords Area
method
bayes calibration
calibrate error multipliers
Calibrate hyper-parameter multipliers on the observation error covariance

Specification
Alias: none
Argument(s): none
Default: none

6.2. METHOD

1633
Required/Optional

Description of
Group

Dakota Keyword
one

Required(Choose
One)

Optional

Group 1

Dakota Keyword
Description
Calibrate one
hyper-parameter
multiplier across
all responses/experiments

per experiment

Calibrate one
hyper-parameter
multiplier per
experiment

per response

Calibrate one
hyper-parameter
multiplier per
response

both

Calibrate one
hyper-parameter
multiplier for each
response/experiment
pair

hyperprior alphas

Shape (alpha) of
the inverse gamma
hyper-parameter
prior

Description
Calibrate one or more multipliers on the user-provided observation error covariance (variance type). Options
include one multiplier on the whole block-diagonal covariance structure, one multiplier per experiment covariance block, one multiplier per response covariance block, or separate multipliers for each response/experiment
pair (for a total of number experiments X number response groups).
Default Behavior: No hyper-parameter calibration. When hyper-parameter calibration is enabled, the default
prior on the multiplier is a diffuse inverse gamma, with mean and mode approximately 1.0.
Expected Output: Final calibration results will include both inference parameters and one or more calibrated
hyper-parameters.
Usage Tips: The per response option can be useful when each response has its own measurement error
process, but all experiments were gathered with the same equipment and conditions. The per experiment option
might be used when working with data from multiple independent laboratories.

Examples
Perform Bayesian calibration with 2 calibration variables and two hyper-parameter multipliers, one per each of
two responses. The multipliers are assumed the same across the 10 experiments. The priors on the multipliers are
specified using the hyperprior alphas and hyperprior betas keywords.

1634

CHAPTER 6. KEYWORDS AREA

bayes_calibration queso
samples = 1000 seed = 348
dram
calibrate_error_multipliers per_response
hyperprior_alphas = 27.0
hyperprior_betas = 26.0
variables
uniform_uncertain 2
upper_bounds 1.e8 10.0
lower_bounds 1.e6 0.1
initial_point 2.85e7 2.5
descriptors E w
responses
calibration_terms = 2
calibration_data_file = expdata.withsigma.dat
freeform
num_experiments = 10
variance_type = scalar

one
Keywords Area
method
bayes calibration
calibrate error multipliers
one
Calibrate one hyper-parameter multiplier across all responses/experiments

Specification
Alias: none
Argument(s): none

Description
A single hyper-parameter multiplying all response/experiment covariance blocks will be estimated.
per experiment
Keywords Area
method
bayes calibration
calibrate error multipliers
per experiment
Calibrate one hyper-parameter multiplier per experiment

6.2. METHOD

Specification
Alias: none
Argument(s): none

Description
One hyper-parameter multiplying each experiment covariance block will be estimated.
per response
Keywords Area
method
bayes calibration
calibrate error multipliers
per response
Calibrate one hyper-parameter multiplier per response

Specification
Alias: none
Argument(s): none

Description
One hyper-parameter multiplying each response covariance block will be estimated.
both
Keywords Area
method
bayes calibration
calibrate error multipliers
both
Calibrate one hyper-parameter multiplier for each response/experiment pair

Specification
Alias: none
Argument(s): none

Description
One hyper-parameter multiplying each experiment/response covariance block will be estimated.

1635

1636

CHAPTER 6. KEYWORDS AREA

hyperprior alphas
Keywords Area
method
bayes calibration
calibrate error multipliers
hyperprior alphas
Shape (alpha) of the inverse gamma hyper-parameter prior

Specification
Alias: none
Argument(s): REALLIST
Required/Optional
Required

Description of
Group

Dakota Keyword
hyperprior betas

Dakota Keyword
Description
Scale (beta) of the
inverse gamma
hyper-parameter
prior

Description
Shape of the prior distribution for calibrated error multipliers. Either a single value or number of hyper-parameters
values may be specified.
Default: 102.0 (with beta = 103.0) so mean and mode are approximately 1.0 and standard deviation is about
0.1.
hyperprior betas
Keywords Area
method
bayes calibration
calibrate error multipliers
hyperprior alphas
hyperprior betas
Scale (beta) of the inverse gamma hyper-parameter prior

Specification
Alias: none
Argument(s): REALLIST

6.2. METHOD

1637

Description
Scale of the prior distribution for calibrated error multipliers. Either a single value or number of hyper-parameters
values may be specified.
Defaults to 103.0 (with alpha = 102.0) so mean and mode are approximately 1.0 and standard deviation is
about 0.1.
convergence tolerance
Keywords Area
method
bayes calibration
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations

1638

CHAPTER 6. KEYWORDS AREA

NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
bayes calibration
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
samples
Keywords Area
method
bayes calibration
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

6.2. METHOD

1639

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
bayes calibration
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

1640

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
bayes calibration
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10

6.2. METHOD
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.58

dace

Keywords Area
method
dace
Design and Analysis of Computer Experiments

Topics
This keyword is related to the topics:
package ddace
design and analysis of computer experiments

1641

1642

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
grid
random

Required(Choose
One)

DACE type
(Group 1)
oas
lhs

oa lhs

box behnken
central composite
Optional
Optional

main effects
quality metrics

Optional

variance based decomp

Dakota Keyword
Description
Grid Sampling
Uses purely
random Monte
Carlo sampling to
sample variables
Orthogonal Array
Sampling
Uses Latin
Hypercube
Sampling (LHS) to
sample variables
Orthogonal Array
Latin Hypercube
Sampling
Box-Behnken
Design
Central Composite
Design
ANOVA
Calculate metrics
to assess the
quality of
quasi-Monte Carlo
samples
Activates global
sensitivity analysis
based on
decomposition of
response variance
into contributions
from variables

6.2. METHOD

1643
Optional

fixed seed

Reuses the same

seed value for
multiple random
sampling sets

Optional

symbols

Optional

samples

Number of
replications in the
sample set
Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The Distributed Design and Analysis of Computer Experiments (DDACE) library provides the following DACE
techniques:
1. grid sampling (grid)
2. pure random sampling (random)
3. orthogonal array sampling (oas)
4. latin hypercube sampling (lhs)
5. orthogonal array latin hypercube sampling (oa lhs)
6. Box-Behnken (box behnken)
7. central composite design (central composite)
These methods all generate point sets that may be used to drive a set of computer experiments. Note that all
of the DACE methods generated randomized designs, except for Box-Behnken and Central composite which are
classical designs. That is, the grid sampling will generate a randomized grid, not what one typically thinks of as a
grid of uniformly spaced points over a rectangular grid. Similar, the orthogonal array is a randomized version of
an orthogonal array: it does not generate discrete, fixed levels.
In addition to the selection of the method, there are keywords that affect the method outputs:
1. main effects
2. quality metrics
3. variance based decomp
And keywords that affect the sampling:

1644

CHAPTER 6. KEYWORDS AREA

1. fixed seed
2. symbols
3. samples
4. seed

See Also
These keywords may also be of interest:
fsu cvt
fsu quasi mc
psuade moat
grid
Keywords Area
method
dace
grid
Grid Sampling

Specification
Alias: none
Argument(s): none

Description
The grid option in DACE will produce a randomized grid of points. If you are interested in a regular grid of
points, use the multidimensional parameter study (under Parameter Studies) instead. Grid Sampling
random
Keywords Area
method
dace
random
Uses purely random Monte Carlo sampling to sample variables

Specification
Alias: none
Argument(s): none

6.2. METHOD

1645

Description
The random keyword invokes Monte Carlo sampling as the means of drawing samples of uncertain variables
according to their probability distributions.
Default Behavior
Monte Carlo sampling is not used by default. To change this behavior, the random keyword must be specified
in conjuction with the sample type keyword.
Usage Tips
Monte Carlo sampling is more computationally expensive than Latin Hypercube Sampling as it requires a
larger number of samples to accurately estimate statistics.

Examples
method
sampling
sample_type random
samples = 200

oas
Keywords Area
method
dace
oas
Orthogonal Array Sampling

Specification
Alias: none
Argument(s): none

Description
Orthogonal array sampling (OAS) is a widely used technique for running experiments and systematically testing
factor effects. An orthogonal array sample can be described as a 4-tuple (m; n; s; r), where m is the number
of sample points, n is the number of input variables, s is the number of symbols, and r is the strength of the
orthogonal array. The number of sample points, m, must be a multiple of the number of symbols, s. The number
of symbols refers to the number of levels per input variable. The strength refers to the number of columns where
we are guaranteed to see all the possibilities an equal number of times. Note that the DACE OAS capability
produces a randomized orthogonal array: the samples for a particular level are randomized within that level.
If one examines the sample sets in an orthogonal array by looking at the rows as individual samples and
columns as the variables sampled, one sees that the columns are orthogonal to each other in an orthogonal array.
This feature is important in main effects analysis, which is a sensitivity analysis technique that identifies which
variables have the most influence on the output.

1646

CHAPTER 6. KEYWORDS AREA

lhs
Keywords Area
method
dace
lhs
Uses Latin Hypercube Sampling (LHS) to sample variables

Specification
Alias: none
Argument(s): none

Description
The lhs keyword invokes Latin Hypercube Sampling as the means of drawing samples of uncertain variables
according to their probability distributions. This is a stratified, space-filling approach that selects variable values
from a set of equi-probable bins.
Default Behavior
By default, Latin Hypercube Sampling is used. To explicitly specify this in the Dakota input file, however, the
lhs keyword must appear in conjunction with the sample type keyword.
Usage Tips
Latin Hypercube Sampling is very robust and can be applied to any problem. It is fairly effective at estimating
the mean of model responses and linear correlations with a reasonably small number of samples relative to the
number of variables.

Examples
method
sampling
sample_type lhs
samples = 20

oa lhs
Keywords Area
method
dace
oa lhs
Orthogonal Array Latin Hypercube Sampling

Specification
Alias: none
Argument(s): none

6.2. METHOD

1647

Description
The Orthogonal Array Latin Hypercube Sampling option in DACE produces a latinized version of an orthogonal
array. That is, after the orthgonal array is generated, the samples go through a stratification process to produce
samples that have been both orthogonalized and stratified.

See Also
These keywords may also be of interest:
oas
box behnken
Keywords Area
method
dace
box behnken
Box-Behnken Design

Specification
Alias: none
Argument(s): none

Description
The Box-Behnken design is similar to a Central Composite design, with some differences. The Box-Behnken
design is a quadratic design in that it does not contain an embedded factorial or fractional factorial design. In
this design the treatment combinations are at the midpoints of edges of the process space and at the center, as
compared with CCD designs where the extra points are placed at star points on a circle outside of the process
space. Box- Behken designs are rotatable (or near rotatable) and require 3 levels of each factor.
central composite
Keywords Area
method
dace
central composite
Central Composite Design

Specification
Alias: none
Argument(s): none

1648

CHAPTER 6. KEYWORDS AREA

Description
A central composite design (CCD), contains an embedded factorial or fractional factorial design with a center
points that is augmented with a group of star points that allow estimation of curvature.

Examples
See the Users Manual for an example.
main effects
Keywords Area
method
dace
main effects
ANOVA

Specification
Alias: none
Argument(s): none
Default: No main effects

Description
The main effects control prints Analysis-of-Variance main effects results (e.g. ANOVA tables with p-values
per variable). The main effects control is only operational with the orthogonal arrays or Latin Hypercube
designs, not for Box Behnken or Central Composite designs.
Main effects is a sensitivity analysis method which identifies the input variables that have the most influence on
the output. In main effects, the idea is to look at the mean of the response function when variable A (for example)
is at level 1 vs. when variable A is at level 2 or level 3. If these mean responses of the output are statistically
significantly different at different levels of variable A, this is an indication that variable A has a significant effect
on the response. The orthogonality of the columns is critical in performing main effects analysis, since the column
orthogonality means that the effects of the other variables cancel out when looking at the overall effect from
one variable at its different levels.
quality metrics
Keywords Area
method
dace
quality metrics
Calculate metrics to assess the quality of quasi-Monte Carlo samples

6.2. METHOD

1649

Topics
This keyword is related to the topics:
package fsudace

Specification
Alias: none
Argument(s): none
Default: No quality metrics

Description
quality metrics calculates four quality metrics relating to the volumetric spacing of the samples. The four
quality metrics measure different aspects relating to the uniformity of point samples in hypercubes. Desirable
properties of such point samples are:
are the points equally spaced
do the points cover the region
and are they isotropically distributed
with no directional bias in the spacing
The four quality metrics we report are:
h: the point distribution norm, which is a measure of uniformity of the point distribution
chi: a regularity measure, and provides a measure of local uniformity of a set of points
tau: the second moment trace measure
d: the second moment determinant measure
All of these values are scaled so that smaller is better (the smaller the metric, the better the uniformity of the point
distribution).

Examples
Complete explanation of these measures can be found in [38].
variance based decomp
Keywords Area
method
dace
variance based decomp
Activates global sensitivity analysis based on decomposition of response variance into contributions from
variables

1650

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: no variance-based decomposition
Required/Description of
Optional
Group
Optional

Dakota Keyword
drop tolerance

Dakota Keyword
Description
Suppresses output
of sensitivity
indices with values
lower than this
tolerance

Description
Dakota can calculate sensitivity indices through variance based decomposition using the keyword variancebased decomp. These indicate how important the uncertainty in each input variable is in contributing to the
output variance.
Default Behavior
Because of the computational cost, variance based decomp is turned off as a default.
If the user specified a number of samples, N, and a number of nondeterministic variables, M, variance-based
decomposition requires the evaluation of N(M+2) samples. Note that specifying this keyword will increase the
number of function evaluations above the number requested with the samples keyword since replicated
sets of sample values are evaluated.
Expected Outputs
When variance based decomp is specified, sensitivity indices for main effects and total effects will be
reported. Main effects (roughly) represent the percent contribution of each individual variable to the variance in
the model response. Total effects represent the percent contribution of each individual variable in combination
with all other variables to the variance in the model response
Usage Tips
To obtain sensitivity indices that are reasonably accurate, we recommend that N, the number of samples, be at
least one hundred and preferably several hundred or thousands.

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp

Theory
In this context, we take sensitivity analysis to be global, not local as when calculating derivatives of output
variables with respect to input variables. Our definition is similar to that of[73] : The study of how uncertainty
in the output of a model can be apportioned to different sources of uncertainty in the model input.
Variance based decomposition is a way of using sets of samples to understand how the variance of the output
behaves, with respect to each input variable. A larger value of the sensitivity index, Si , means that the uncertainty
in the input variable i has a larger effect on the variance of the output. More details on the calculations and
interpretation of the sensitivity indices can be found in[73] and[87].

6.2. METHOD

1651

drop tolerance
Keywords Area
method
dace
variance based decomp
drop tolerance
Suppresses output of sensitivity indices with values lower than this tolerance

Specification
Alias: none
Argument(s): REAL
Default: All VBD indices displayed

Description
The drop tolerance keyword allows the user to specify a value below which sensitivity indices generated by
variance based decomp are not displayed.
Default Behavior
By default, all sensitivity indices generated by variance based decomp are displayed.
Usage Tips
For polynomial chaos, which outputs main, interaction, and total effects by default, the univariateeffects may be a more appropriate option. It allows suppression of the interaction effects since the output
volume of these results can be prohibitive for high dimensional problems. Similar to suppression of these interactions is the covariance control, which can be selected to be diagonal covariance or full covariance, with the
former supporting suppression of the off-diagonal covariance terms (to save compute and memory resources and
reduce output volume).

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp
drop_tolerance = 0.001

fixed seed
Keywords Area
method
dace
fixed seed
Reuses the same seed value for multiple random sampling sets

1652

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: not fixed; pattern varies run-to-run

Description
The fixed seed flag is relevant if multiple sampling sets will be generated over the coarse of a Dakota analysis.
This occurs when using advance methods (e.g., surrogate-based optimization, optimization under uncertainty).
The same seed value is reused for each of these multiple sampling sets, which can be important for reducing
variability in the sampling results.
Default Behavior
The default behavior is to not use a fixed seed, as the repetition of the same sampling pattern can result in a
modeling weakness that an optimizer could potentially exploit (resulting in actual reliabilities that are lower than
the estimated reliabilities). For repeatable studies, the seed must also be specified.

Examples
method
sampling
sample_type lhs
samples = 10
fixed_seed

symbols
Keywords Area
method
dace
symbols
Number of replications in the sample set

Specification
Alias: none
Argument(s): INTEGER
Default: default for sampling algorithm

Description
symbols is related to the number of levels per variable in the sample set (a larger number of symbols equates
to more stratification and fewer replications). For example, if symbols = 7, each variable would be divided into
seven levels.

6.2. METHOD

1653

samples
Keywords Area
method
dace
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
dace
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

1654

CHAPTER 6. KEYWORDS AREA

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
dace
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.

6.2. METHOD

1655

Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.59

fsu cvt

Keywords Area

1656

CHAPTER 6. KEYWORDS AREA

method
fsu cvt
Design of Computer Experiments - Centroidal Voronoi Tessellation

Topics
This keyword is related to the topics:
package fsudace
design and analysis of computer experiments

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
latinize

Optional

quality metrics

Optional

variance based decomp

Dakota Keyword
Description
Adjust samples to
improve the
discrepancy of the
marginal
distributions
Calculate metrics
to assess the
quality of
quasi-Monte Carlo
samples
Activates global
sensitivity analysis
based on
decomposition of
response variance
into contributions
from variables

6.2. METHOD

1657
Optional

fixed seed

Reuses the same

seed value for
multiple random
sampling sets

Optional

trial type

Optional

num trials

Optional

max iterations

Specify how the

trial samples are
generated
The number of
secondary sample
points generated to
adjust the location
of the primary
sample points
Stopping criterion
based on number
of iterations

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The FSU Centroidal Voronoi Tessellation method (fsu cvt) produces a set of sample points that are (approximately) a Centroidal Voronoi Tessellation. The primary feature of such a set of points is that they have good
volumetric spacing; the points tend to arrange themselves in a pattern of cells that are roughly the same shape.
To produce this set of points, an almost arbitrary set of initial points is chosen, and then an internal set of
iterations is carried out. These iterations repeatedly replace the current set of sample points by an estimate of the
centroids of the corresponding Voronoi subregions. [18].
The user may generally ignore the details of this internal iteration. If control is desired, however, there are a
few variables with which the user can influence the iteration. The user may specify:
max iterations, the number of iterations carried out
num trials, the number of secondary sample points generated to adjust the location of the primary sample
points
trial type, which controls how these secondary sample points are generated
This method generates sets of uniform random variables on the interval [0,1]. If the user specifies lower and upper
bounds for a variable, the [0,1] samples are mapped to the [lower, upper] interval.

1658

CHAPTER 6. KEYWORDS AREA

Theory
This method is designed to generate samples with the goal of low discrepancy. Discrepancy refers to the nonuniformity of the sample points within the hypercube.
Discrepancy is defined as the difference between the actual number and the expected number of points one
would expect in a particular set B (such as a hyper-rectangle within the unit hypercube), maximized over all such
sets. Low discrepancy sequences tend to cover the unit hypercube reasonably uniformly.
Centroidal Voronoi Tessellation does very well volumetrically: it spaces the points fairly equally throughout
the space, so that the points cover the region and are isotropically distributed with no directional bias in the
point placement. There are various measures of volumetric uniformity which take into account the distances
between pairs of points, regularity measures, etc. Note that Centroidal Voronoi Tessellation does not produce
low-discrepancy sequences in lower dimensions. The lower-dimension (such as 1-D) projections of Centroidal
Voronoi Tessellation can have high discrepancy.

See Also
These keywords may also be of interest:
dace
fsu quasi mc
psuade moat
latinize
Keywords Area
method
fsu cvt
latinize
Adjust samples to improve the discrepancy of the marginal distributions

Specification
Alias: none
Argument(s): none
Default: No latinization

Description
The latinize control takes the samples and latinizes them, meaning that each original sample is moved so
that it falls into one strata or bin in each dimension as in Latin Hypercube sampling. The default setting is NOT
to latinize. However, one may be interested in doing this in situations where one wants better discrepancy of the
1-dimensional projections (the marginal distributions).

6.2. METHOD

1659

quality metrics
Keywords Area
method
fsu cvt
quality metrics
Calculate metrics to assess the quality of quasi-Monte Carlo samples

Topics
This keyword is related to the topics:
package fsudace

Specification
Alias: none
Argument(s): none
Default: No quality metrics

Description
quality metrics calculates four quality metrics relating to the volumetric spacing of the samples. The four
quality metrics measure different aspects relating to the uniformity of point samples in hypercubes. Desirable
properties of such point samples are:
are the points equally spaced
do the points cover the region
and are they isotropically distributed
with no directional bias in the spacing
The four quality metrics we report are:
h: the point distribution norm, which is a measure of uniformity of the point distribution
chi: a regularity measure, and provides a measure of local uniformity of a set of points
tau: the second moment trace measure
d: the second moment determinant measure
All of these values are scaled so that smaller is better (the smaller the metric, the better the uniformity of the point
distribution).

Examples
Complete explanation of these measures can be found in [38].

1660

CHAPTER 6. KEYWORDS AREA

variance based decomp

Keywords Area
method
fsu cvt
variance based decomp
Activates global sensitivity analysis based on decomposition of response variance into contributions from
variables

Specification
Alias: none
Argument(s): none
Default: no variance-based decomposition
Required/Description of
Optional
Group
Optional

Dakota Keyword
drop tolerance

Dakota Keyword
Description
Suppresses output
of sensitivity
indices with values
lower than this
tolerance

Description
Dakota can calculate sensitivity indices through variance based decomposition using the keyword variancebased decomp. These indicate how important the uncertainty in each input variable is in contributing to the
output variance.
Default Behavior
Because of the computational cost, variance based decomp is turned off as a default.
If the user specified a number of samples, N, and a number of nondeterministic variables, M, variance-based
decomposition requires the evaluation of N(M+2) samples. Note that specifying this keyword will increase the
number of function evaluations above the number requested with the samples keyword since replicated
sets of sample values are evaluated.
Expected Outputs
When variance based decomp is specified, sensitivity indices for main effects and total effects will be
reported. Main effects (roughly) represent the percent contribution of each individual variable to the variance in
the model response. Total effects represent the percent contribution of each individual variable in combination
with all other variables to the variance in the model response
Usage Tips
To obtain sensitivity indices that are reasonably accurate, we recommend that N, the number of samples, be at
least one hundred and preferably several hundred or thousands.

Examples
method,
sampling
sample_type lhs

6.2. METHOD

1661

samples = 100
variance_based_decomp

Theory
In this context, we take sensitivity analysis to be global, not local as when calculating derivatives of output
variables with respect to input variables. Our definition is similar to that of[73] : The study of how uncertainty
in the output of a model can be apportioned to different sources of uncertainty in the model input.
Variance based decomposition is a way of using sets of samples to understand how the variance of the output
behaves, with respect to each input variable. A larger value of the sensitivity index, Si , means that the uncertainty
in the input variable i has a larger effect on the variance of the output. More details on the calculations and
interpretation of the sensitivity indices can be found in[73] and[87].
drop tolerance
Keywords Area
method
fsu cvt
variance based decomp
drop tolerance
Suppresses output of sensitivity indices with values lower than this tolerance

Specification
Alias: none
Argument(s): REAL
Default: All VBD indices displayed

Description
The drop tolerance keyword allows the user to specify a value below which sensitivity indices generated by
variance based decomp are not displayed.
Default Behavior
By default, all sensitivity indices generated by variance based decomp are displayed.
Usage Tips
For polynomial chaos, which outputs main, interaction, and total effects by default, the univariateeffects may be a more appropriate option. It allows suppression of the interaction effects since the output
volume of these results can be prohibitive for high dimensional problems. Similar to suppression of these interactions is the covariance control, which can be selected to be diagonal covariance or full covariance, with the
former supporting suppression of the off-diagonal covariance terms (to save compute and memory resources and
reduce output volume).

1662

CHAPTER 6. KEYWORDS AREA

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp
drop_tolerance = 0.001

fixed seed
Keywords Area
method
fsu cvt
fixed seed
Reuses the same seed value for multiple random sampling sets

Specification
Alias: none
Argument(s): none
Default: not fixed; pattern varies run-to-run

Description
The fixed seed flag is relevant if multiple sampling sets will be generated over the coarse of a Dakota analysis.
This occurs when using advance methods (e.g., surrogate-based optimization, optimization under uncertainty).
The same seed value is reused for each of these multiple sampling sets, which can be important for reducing
variability in the sampling results.
Default Behavior
The default behavior is to not use a fixed seed, as the repetition of the same sampling pattern can result in a
modeling weakness that an optimizer could potentially exploit (resulting in actual reliabilities that are lower than
the estimated reliabilities). For repeatable studies, the seed must also be specified.

Examples
method
sampling
sample_type lhs
samples = 10
fixed_seed

trial type
Keywords Area
method
fsu cvt
trial type
Specify how the trial samples are generated

6.2. METHOD

1663

Specification
Alias: none
Argument(s): none
Default: random
Required/Optional

Description of
Group

Required(Choose
One)

trial type (Group

1)

Dakota Keyword
grid
halton

random

Dakota Keyword
Description
Samples on a
regular grid
Generate samples
from a Halton
sequence
Uses purely
random Monte
Carlo sampling to
sample variables

Description
The user has the option to specify the method by which the trials are created to adjust the centroids. The trialtype can be one of three types:
random, where points are generated randomly
halton, where points are generated according to the Halton sequence
grid, where points are placed on a regular grid over the hyperspace.
grid
Keywords Area
method
fsu cvt
trial type
grid
Samples on a regular grid

Specification
Alias: none
Argument(s): none

Description
Points are placed on a regular grid over the hyperspace.

1664

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
trial type
halton
Keywords Area
method
fsu cvt
trial type
halton
Generate samples from a Halton sequence

Topics
This keyword is related to the topics:
package fsudace

Specification
Alias: none
Argument(s): none

Description
The quasi-Monte Carlo sequences of Halton are deterministic sequences determined by a set of prime bases.
These sequences generate random numbers with the goal of filling a unit hypercube uniformly.
Generally, we recommend that the user leave the default setting for the bases, which are the lowest primes.
Thus, if one wants to generate a sample set for 3 random variables, the default bases used are 2, 3, and 5 in the
Halton sequence. To give an example of how these sequences look, the Halton sequence in base 2 starts with
points 0.5, 0.25, 0.75, 0.125, 0.625, etc. The first few points in a Halton base 3 sequence are 0.33333, 0.66667,
0.11111, 0.44444, 0.77777, etc. Notice that the Halton sequence tends to alternate back and forth, generating a
point closer to zero then a point closer to one. An individual sequence is based on a radix inverse function defined
on a prime base. The prime base determines how quickly the [0,1] interval is filled in.

Theory
For more information about these sequences, see[43], [44], and [1].

6.2. METHOD

1665

random
Keywords Area
method
fsu cvt
trial type
random
Uses purely random Monte Carlo sampling to sample variables

Specification
Alias: none
Argument(s): none

Description
The random keyword invokes Monte Carlo sampling as the means of drawing samples of uncertain variables
according to their probability distributions.
Default Behavior
Monte Carlo sampling is not used by default. To change this behavior, the random keyword must be specified
in conjuction with the sample type keyword.
Usage Tips
Monte Carlo sampling is more computationally expensive than Latin Hypercube Sampling as it requires a
larger number of samples to accurately estimate statistics.

Examples
method
sampling
sample_type random
samples = 200

num trials
Keywords Area
method
fsu cvt
num trials
The number of secondary sample points generated to adjust the location of the primary sample points

Specification
Alias: none
Argument(s): INTEGER
Default: 10000

1666

CHAPTER 6. KEYWORDS AREA

Description
In general, the variable with the most influence on the quality of the final sample set is num trials, which
determines how well the Voronoi subregions are sampled.
Generally, num trials should be large, certainly much bigger than the number of sample points being
requested; a reasonable value might be 10,000, but values of 100,000 or 1 million are not unusual.
max iterations
Keywords Area
method
fsu cvt
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
samples
Keywords Area
method
fsu cvt
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

6.2. METHOD

1667

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
fsu cvt
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

1668

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
fsu cvt
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10

6.2. METHOD
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.60

psuade moat

Keywords Area
method
psuade moat
Morris One-at-a-Time

Topics
This keyword is related to the topics:
package psuade
design and analysis of computer experiments

1669

1670

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
partitions

Dakota Keyword
Description
Number of
partitions of each
variable

Optional

samples

Number of
samples for
sampling-based
methods

Optional

seed

Seed of the random

number generator

Optional

model pointer

Identifier for
model block to be
used by a method

Description
The Morris One-At-A-Time (MOAT) method, originally proposed by Morris [62], is a screening method, designed to explore a computational model to distinguish between input variables that have negligible, linear and
additive, or nonlinear or interaction effects on the output. The computer experiments performed consist of individually randomized designs which vary one input factor at a time to create a sample of its elementary effects.
The number of samples (samples) must be a positive integer multiple of (number of continuous design
variable + 1) and will be automatically adjusted if misspecified.
The number of partitions (partitions) applies to each variable being studied and must be odd (the number
of MOAT levels per variable is partitions + 1). This will also be adjusted at runtime as necessary.
For information on practical use of this method, see [73].

Theory
With MOAT, each dimension of a kdimensional input space is uniformly partitioned into p levels, creating
a grid of pk points x Rk at which evaluations of the model y(x) might take place. An elementary effect
corresponding to input i is computed by a forward difference
y(x + ei ) y(x)
,

where ei is the ith coordinate vector, and the step is typically taken to be large (this is not intended to be a
local derivative approximation). In the present implementation of MOAT, for an input variable scaled to [0, 1],
p
= 2(p1)
, so the step used to find elementary effects is slightly larger than half the input range.
The distribution of elementary effects di over the input space characterizes the effect of input i on the output
of interest. After generating r samples from this distribution, their mean,
di (x) =

i =

1 X (j)
d
r j=1 i

6.2. METHOD

1671

modified mean

i =

1 X (j)
|d |,
r j=1 i

(using absolute value) and standard deviation

v
u X
2
u 1 r  (j)
i = t
di i
r j=1
are computed for each input i. The mean and modified mean give an indication of the overall effect of an input
on the output. Standard deviation indicates nonlinear effects or interactions, since it is an indicator of elementary
effects varying throughout the input space.
partitions
Keywords Area
method
psuade moat
partitions
Number of partitions of each variable

Specification
Alias: none
Argument(s): INTEGERLIST
Default: 3

Description
Described on the parent page, psuade moat
samples
Keywords Area
method
psuade moat
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: method-dependent

1672

CHAPTER 6. KEYWORDS AREA

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

seed
Keywords Area
method
psuade moat
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

6.2. METHOD

1673

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

model pointer
Keywords Area
method
psuade moat
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10

1674

CHAPTER 6. KEYWORDS AREA

seed = 98765 rng rnum2

response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.61

local evidence

Keywords Area
method
local evidence
Evidence theory with evidence measures computed with local optimization methods

Topics
This keyword is related to the topics:
epistemic uncertainty quantification methods
evidence theory

6.2. METHOD

1675

Specification
Alias: nond local evidence
Argument(s): none
Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
sqp

Dakota Keyword
Description
Uses a sequential
quadratic
programming
method for
underlying
optimization

nip

Uses a nonlinear
interior point
method for
underlying
optimization

Optional

response levels

Values at which to
estimate desired
statistics for each
response

Optional

probability levels

Optional

gen reliability levels

Optional

distribution

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Selection of
cumulative or
complementary
cumulative
functions

1676

CHAPTER 6. KEYWORDS AREA

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Two local optimization methods are available: sqp (sequential quadratic programming or nip (nonlinear interior
point method).
Additional Resources
See the topic page evidence theory for important background information and usage notes.
Refer to variable support for information on supported variable types.

See Also
These keywords may also be of interest:
global evidence
global interval est
local interval est
sqp
Keywords Area
method
local evidence
sqp
Uses a sequential quadratic programming method for underlying optimization

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The sqp
keyword directs Dakota to use a sequential quadratic programming method to solve that problem. A sequential
quadratic programming solves a sequence of linearly constrained quadratic optimization problems to arrive at the
solution to the optimization problem.

6.2. METHOD

1677

nip
Keywords Area
method
local evidence
nip
Uses a nonlinear interior point method for underlying optimization

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The nip
keyword directs Dakota to use a nonlinear interior point to solve that problem. A nonlinear interior point method
traverses the interior of the feasible region to arrive at the solution to the optimization problem.
response levels
Keywords Area
method
local evidence
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num response levels

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response

1678

CHAPTER 6. KEYWORDS AREA

Optional

compute

Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
=
std_deviations
=
descriptors
=

248.89, 593.33
12.4,
29.7
TF1n TF2n

6.2. METHOD

1679

uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01

1680

CHAPTER 6. KEYWORDS AREA

Complementary Cumulative Distribution Function (CCDF) for response_fn_2:

Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
local evidence
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs

6.2. METHOD

1681

The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
local evidence
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
probabilities

gen reliabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels
Computes
generalized
reliabilities
associated with
response levels

1682

CHAPTER 6. KEYWORDS AREA

Optional

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
local evidence
response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

6.2. METHOD

1683

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

gen reliabilities
Keywords Area
method
local evidence
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

1684

CHAPTER 6. KEYWORDS AREA

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
local evidence
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.

6.2. METHOD
series
Keywords Area
method
local evidence
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
local evidence
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

1685

1686

CHAPTER 6. KEYWORDS AREA

probability levels
Keywords Area
method
local evidence
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.
variables,
normal_uncertain = 2
means
=
std_deviations
=

0.

248.89, 593.33
12.4,
29.7

6.2. METHOD

1687

descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00

1688

CHAPTER 6. KEYWORDS AREA

Complementary Cumulative Distribution Function (CCDF) for response_fn_2:

Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels
Keywords Area
method
local evidence
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page

6.2. METHOD

1689

gen reliability levels

Keywords Area
method
local evidence
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
local evidence
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

1690

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
distribution
Keywords Area
method
local evidence
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

6.2. METHOD

1691

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

cumulative
Keywords Area
method
local evidence
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
local evidence
distribution

1692

CHAPTER 6. KEYWORDS AREA

complementary
Computes statistics according to complementary cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

model pointer
Keywords Area
method
local evidence
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

1693

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

1694

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.62

local interval est

Keywords Area
method
local interval est
Interval analysis using local optimization

Topics
This keyword is related to the topics:
uncertainty quantification
epistemic uncertainty quantification methods
interval estimation

Specification
Alias: nond local interval est
Argument(s): none
Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
sqp

nip

Dakota Keyword
Description
Uses a sequential
quadratic
programming
method for
underlying
optimization
Uses a nonlinear
interior point
method for
underlying
optimization

6.2. METHOD

1695
Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Interval analysis using local methods (local interval est). If the problem is amenable to local optimization
methods (e.g. can provide derivatives or use finite difference method to calculate derivatives), then one can use
one of two local methods to calculate these bounds.
sqp
nip
Additional Resources
Refer to variable support for information on supported variable types.

Theory
In interval analysis, one assumes that nothing is known about an epistemic uncertain variable except that its value
lies somewhere within an interval. In this situation, it is NOT assumed that the value has a uniform probability
of occuring within the interval. Instead, the interpretation is that any value within the interval is a possible value
or a potential realization of that variable. In interval analysis, the uncertainty quantification problem is one of
determining the resulting bounds on the output (defining the output interval) given interval bounds on the inputs.
Again, any output response that falls within the output interval is a possible output with no frequency information
assigned to it.

See Also
These keywords may also be of interest:
global evidence
global interval est
local evidence
sqp
Keywords Area
method
local interval est
sqp
Uses a sequential quadratic programming method for underlying optimization

1696

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The sqp
keyword directs Dakota to use a sequential quadratic programming method to solve that problem. A sequential
quadratic programming solves a sequence of linearly constrained quadratic optimization problems to arrive at the
solution to the optimization problem.
nip
Keywords Area
method
local interval est
nip
Uses a nonlinear interior point method for underlying optimization

Specification
Alias: none
Argument(s): none

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The nip
keyword directs Dakota to use a nonlinear interior point to solve that problem. A nonlinear interior point method
traverses the interior of the feasible region to arrive at the solution to the optimization problem.
convergence tolerance
Keywords Area
method
local interval est
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

6.2. METHOD

1697

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
model pointer
Keywords Area
method
local interval est
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

1698

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

1699

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.63

local reliability

Keywords Area
method
local reliability
Local reliability method

Topics
This keyword is related to the topics:
uncertainty quantification
reliability methods

Specification
Alias: nond local reliability
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
mpp search

Optional

response levels

Optional

reliability levels

Dakota Keyword
Description
Specify which
MPP search option
to use
Values at which to
estimate desired
statistics for each
response
Specify reliability
levels at which the
response values
will be estimated

1700

CHAPTER 6. KEYWORDS AREA

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Optional

model pointer

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Identifier for
model block to be
used by a method

Description
Local reliability methods compute approximate response function distribution statistics based on specified uncertain variable probability distributions. Each of the local reliability methods can compute forward and inverse
mappings involving response, probability, reliability, and generalized reliability levels.
The forward reliability analysis algorithm of computing reliabilities/probabilities for specified response levels is called the Reliability Index Approach (RIA), and the inverse reliability analysis algorithm of computing
response levels for specified probability levels is called the Performance Measure Approach (PMA).
The different RIA/PMA algorithm options are specified using the mpp search specification which selects
among different limit state approximations that can be used to reduce computational expense during the MPP
searches.

Theory
The Mean Value method (MV, also known as MVFOSM in [42]) is the simplest, least-expensive method in that it
estimates the response means, response standard deviations, and all CDF/CCDF forward/inverse mappings from
a single evaluation of response functions and gradients at the uncertain variable means. This approximation can

6.2. METHOD

1701

have acceptable accuracy when the response functions are nearly linear and their distributions are approximately
Gaussian, but can have poor accuracy in other situations.
All other reliability methods perform an internal nonlinear optimization to compute a most probable point (MPP) of failure. A sign convention and the distance of the MPP from the origin in the transformed standard normal
space (u-space) define the reliability index, as explained in the section on Reliability Methods in the Uncertainty
Quantification chapter of the Users Manual [4]. Also refer to variable support for additional information on
supported variable types for transformations to standard normal space. The reliability can then be converted to
a probability using either first- or second-order integration, may then be refined using importance sampling, and
finally may be converted to a generalized reliability index.

See Also
These keywords may also be of interest:
adaptive sampling
gpais
global reliability
sampling
importance sampling
polynomial chaos
stoch collocation
mpp search
Keywords Area
method
local reliability
mpp search
Specify which MPP search option to use

Topics
This keyword is related to the topics:
uncertainty quantification
reliability methods

Specification
Alias: none
Argument(s): none
Default: No MPP search (MV method)

1702

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Dakota Keyword
x taylor mean

Required(Choose
One)

Group 1
u taylor mean

x taylor mpp

u taylor mpp

x two point

u two point

no approx

Dakota Keyword
Description
Form Taylor series
approximation in
x-space at
variable means
Form Taylor series
approximation in
u-space at
variable means
X-space Taylor
series
approximation
with iterative
updates
U-space Taylor
series
approximation
with iterative
updates
Predict MPP using
Two-point
Adaptive
Nonlinear
Approximation in
x-space
Predict MPP using
Two-point
Adaptive
Nonlinear
Approximation in
u-space
Perform MPP
search on original
response functions
(use no
approximation)

6.2. METHOD

1703
Optional(Choose
One)

Optional

Group 2

sqp

Uses a sequential
quadratic
programming
method for
underlying
optimization

nip

Uses a nonlinear
interior point
method for
underlying
optimization

integration

Integration
approach

Description
The x taylor mean MPP search option performs a single Taylor series approximation in the space of the original uncertain variables (x-space) centered at the uncertain variable means, searches for the MPP for each response/probability level using this approximation, and performs a validation response evaluation at each predicted
MPP. This option is commonly known as the Advanced Mean Value (AMV) method. The u taylor mean option is identical to the x taylor mean option, except that the approximation is performed in u-space. The
x taylor mpp approach starts with an x-space Taylor series at the uncertain variable means, but iteratively updates the Taylor series approximation at each MPP prediction until the MPP converges. This option is commonly
known as the AMV+ method. The u taylor mpp option is identical to the x taylor mpp option, except
that all approximations are performed in u-space. The order of the Taylor-series approximation is determined by
the corresponding responses specification and may be first or second-order. If second-order (methods named
AM V 2 and AM V 2 + in [22]), the series may employ analytic, finite difference, or quasi Hessians (BFGS or SR1). The x two point MPP search option uses an x-space Taylor series approximation at the uncertain variable
means for the initial MPP prediction, then utilizes the Two-point Adaptive Nonlinear Approximation (TANA) outlined in[91] for all subsequent MPP predictions. The u two point approach is identical to x two point, but
all the approximations are performed in u-space. The x taylor mpp and u taylor mpp, x two point and
u two point approaches utilize the max iterations and convergence tolerance method independent controls to control the convergence of the MPP iterations (the maximum number of MPP iterations per level
is limited by max iterations, and the MPP iterations are considered converged when k u(k+1) u(k) k2 <
convergence tolerance). And, finally, the no approx option performs the MPP search on the original
response functions without the use of any approximations. The optimization algorithm used to perform these
MPP searches can be selected to be either sequential quadratic programming (uses the npsol sqp optimizer) or
nonlinear interior point (uses the optpp q newton optimizer) algorithms using the sqp or nip keywords.
In addition to the MPP search specifications, one may select among different integration approaches for computing probabilities at the MPP by using the integration keyword followed by either first order or
second order. Second-order integration employs the formulation of[50] (the approach of[13] and the correction of[51] are also implemented, but are not active). Combining the no approx option of the MPP search with
first- and second-order integrations results in the traditional first- and second-order reliability methods (FORM
and SORM). These integration approximations may be subsequently refined using importance sampling. The
refinement specification allows the seletion of basic importance sampling (import), adaptive importance
sampling (adapt import), or multimodal adaptive importance sampling (mm adapt import), along with
the specification of number of samples (samples) and random seed (seed). Additional details on these methods are available in[24] and[22] and in the Uncertainty Quantification Capabilities chapter of the Users Manual

1704

CHAPTER 6. KEYWORDS AREA

[4].
x taylor mean
Keywords Area
method
local reliability
mpp search
x taylor mean
Form Taylor series approximation in x-space at variable means

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

Description
This mpp search option performs a single Taylor series approximation in the space of the original uncertain
variables (x-space) centered at the uncertain variable means, searches for the MPP for each response/probability
level using this approximation, and performs a validation response evaluation at each predicted MPP. This option
is commonly known as the Advanced Mean Value (AMV) method.
u taylor mean
Keywords Area
method
local reliability
mpp search
u taylor mean
Form Taylor series approximation in u-space at variable means

Topics
This keyword is related to the topics:
reliability methods

6.2. METHOD

1705

Specification
Alias: none
Argument(s): none

Description
This mpp search option performs a single Taylor series approximation in the transformed space of the uncertain
variables (u-space) centered at the uncertain variable means. This option is commonly known as the Advanced
Mean Value (AMV) method, but is performed in u-space instead of x-space.
x taylor mpp
Keywords Area
method
local reliability
mpp search
x taylor mpp
X-space Taylor series approximation with iterative updates

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

Description
This mpp search option starts with an x-space Taylor series at the uncertain variable means, but iteratively updates
the Taylor series approximation at each MPP prediction until the MPP converges. This option is commonly known
as the AMV+ method.
u taylor mpp
Keywords Area
method
local reliability
mpp search
u taylor mpp
U-space Taylor series approximation with iterative updates

1706

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

Description
This mpp search option starts with a u-space Taylor series at the uncertain variable means, and iteratively updates
the Taylor series approximation at each MPP prediction until the MPP converges. This option is commonly known
as the AMV+ method and is identify to x taylor mpp except that it is performed in u-space.
x two point
Keywords Area
method
local reliability
mpp search
x two point
Predict MPP using Two-point Adaptive Nonlinear Approximation in x-space

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

Description
This mpp search option uses an x-space Taylor series approximation at the uncertain variable means for the initial
MPP prediction, then utilizes the Two-point Adaptive Nonlinear Approximation (TANA) outlined in [ Xu98 Xu
and Grandhi, 1998] for all subsequent MPP predictions.

6.2. METHOD

1707

u two point
Keywords Area
method
local reliability
mpp search
u two point
Predict MPP using Two-point Adaptive Nonlinear Approximation in u-space

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

Description
This mpp search option is identical to x two point, but it performs the Two-point Adaptive Nonlinear Approximation (TANA) in u-space instead of x-space.
no approx
Keywords Area
method
local reliability
mpp search
no approx
Perform MPP search on original response functions (use no approximation)

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

1708

CHAPTER 6. KEYWORDS AREA

Description
This mpp search option performs the MPP search on the original response functions without the use of any
approximations. Note that the use of the no approx MPP search with first-order probability integration results in
the traditional reliability method called FORM (First-Order Reliability Method). Similarly, the use of no approx
with second-order probability integration results in SORM (Second-Order Reliability Method).
sqp
Keywords Area
method
local reliability
mpp search
sqp
Uses a sequential quadratic programming method for underlying optimization

Specification
Alias: none
Argument(s): none
Default: sqp

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The sqp
keyword directs Dakota to use a sequential quadratic programming method to solve that problem. A sequential
quadratic programming solves a sequence of linearly constrained quadratic optimization problems to arrive at the
solution to the optimization problem.
nip
Keywords Area
method
local reliability
mpp search
nip
Uses a nonlinear interior point method for underlying optimization

Specification
Alias: none
Argument(s): none
Default: sqp

6.2. METHOD

1709

Description
Many uncertainty quantification methods solve a constrained optimization problem under the hood. The nip
keyword directs Dakota to use a nonlinear interior point to solve that problem. A nonlinear interior point method
traverses the interior of the feasible region to arrive at the solution to the optimization problem.
integration
Keywords Area
method
local reliability
mpp search
integration
Integration approach

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none
Default: First-order integration
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
first order
second order

Optional

probability refinement

Dakota Keyword
Description
First-order
integration scheme
Second-order
integration scheme
Allow refinement
of probability and
generalized
reliability results
using importance
sampling

Description
This keyword controls how the probabilities at the MPP are computed: integration is followed by either first order
or second order, indicating the order of the probability integration.

1710

CHAPTER 6. KEYWORDS AREA

first order
Keywords Area
method
local reliability
mpp search
integration
first order
First-order integration scheme

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: none
Argument(s): none

Description
First-order integration in local reliability methods uses the minimum Euclidean distance from the origin to the
most probable point (MPP) in transformed space to compute the probability of failure. This distance, commonly
called the reliability index Beta, is used to calculate the probability of failure by calculating the standard normal
cumulative distribution function at -Beta.
second order
Keywords Area
method
local reliability
mpp search
integration
second order
Second-order integration scheme

Topics
This keyword is related to the topics:
reliability methods

6.2. METHOD

1711

Specification
Alias: none
Argument(s): none

Description
Second-order integration in local reliability methods modifies the first-order integration approach to apply a curvature correction. This correction is based on the formulation of [ Hoh88 Hohenbichler and Rackwitz, 1988].

probability refinement
Keywords Area
method
local reliability
mpp search
integration
probability refinement
Allow refinement of probability and generalized reliability results using importance sampling

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: sample refinement
Argument(s): none
Required/Optional
Required(Choose
One)
Optional

Description of
Group
Group 1

Dakota Keyword
import
adapt import
mm adapt import
refinement samples

Dakota Keyword
Description
Sampling option
Importance
sampling option
Sampling option
Specify the
number of samples
used to improve a
probabilty
estimate.

1712

CHAPTER 6. KEYWORDS AREA

Optional

seed

Seed of the random

number generator

Description
The probability refinement allows refinement of probability and generalized reliability results using
importance sampling. If one specifies probability refinement, there are some additional options. One
can specify which type of importance sampling to use (import, adapt import, or mm adapt import).
Additionally, one can specify the number of refinement samples to use with refinement samples and the
seed to use with seed.
The probability refinement density reweighting accounts originally was developed based on Gaussian distributions. It now accounts for additional non-Gaussian cases.
import
Keywords Area
method
local reliability
mpp search
integration
probability refinement
import
Sampling option

Specification
Alias: none
Argument(s): none

Description
import centers a sampling density at one of the initial LHS samples identified in the failure region. It then
generates the importance samples, weights them by their probability of occurence given the original density, and
calculates the required probability (CDF or CCDF level).
adapt import
Keywords Area
method
local reliability
mpp search
integration

6.2. METHOD

1713

probability refinement
adapt import
Importance sampling option

Specification
Alias: none
Argument(s): none

Description
adapt import centers a sampling density at one of the initial LHS samples identified in the failure region. It
then generates the importance samples, weights them by their probability of occurence given the original density,
and calculates the required probability (CDF or CCDF level). This continues iteratively until the failure probability
estimate converges.
mm adapt import
Keywords Area
method
local reliability
mpp search
integration
probability refinement
mm adapt import
Sampling option

Specification
Alias: none
Argument(s): none

Description
mm adapt import starts with all of the samples located in the failure region to build a multimodal sampling
density. First, it uses a small number of samples around each of the initial samples in the failure region. Note
that these samples are allocated to the different points based on their relative probabilities of occurrence: more
probable points get more samples. This early part of the approach is done to search for representative points.
Once these are located, the multimodal sampling density is set and then mm adapt import proceeds similarly
to adapt import (sample until convergence).

1714

CHAPTER 6. KEYWORDS AREA

refinement samples
Keywords Area
method
local reliability
mpp search
integration
probability refinement
refinement samples
Specify the number of samples used to improve a probabilty estimate.

Specification
Alias: none
Argument(s): INTEGER

Description
Specify the number of samples used to improve a probabilty estimate. If using uni-modal sampling all samples
are assigned to the sampling center. If using multi-modal sampling the samples are split between mutiple samples
according to some internally computed weights.
seed
Keywords Area
method
local reliability
mpp search
integration
probability refinement
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

6.2. METHOD

1715

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

response levels
Keywords Area
method
local reliability
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num response levels

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response

1716

CHAPTER 6. KEYWORDS AREA

Optional

compute

Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
=
std_deviations
=
descriptors
=

248.89, 593.33
12.4,
29.7
TF1n TF2n

6.2. METHOD

1717

uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01

1718

CHAPTER 6. KEYWORDS AREA

Complementary Cumulative Distribution Function (CCDF) for response_fn_2:

Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.
num response levels
Keywords Area
method
local reliability
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs

6.2. METHOD

1719

The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
local reliability
response levels
compute
Selection of statistics to compute at each response level

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
probabilities

Group 1

reliabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels
Computes
reliabilities
associated with
response levels

1720

CHAPTER 6. KEYWORDS AREA

Optional

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities
Keywords Area
method
local reliability
response levels
compute
probabilities
Computes probabilities associated with response levels

6.2. METHOD

1721

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

reliabilities
Keywords Area
method
local reliability
response levels
compute
reliabilities
Computes reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

1722

CHAPTER 6. KEYWORDS AREA

Description
The reliabilities keyword directs Dakota to compute reliabilities according to the specified distribution for
a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the reliabilities are not computed by default. To change this behavior,
the reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

gen reliabilities
Keywords Area
method
local reliability
response levels
compute
gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

6.2. METHOD

1723

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
local reliability
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.

1724
series
Keywords Area
method
local reliability
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
parallel
Keywords Area
method
local reliability
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1725

reliability levels
Keywords Area
method
local reliability
reliability levels
Specify reliability levels at which the response values will be estimated

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num reliability levels

Dakota Keyword
Description
Specify which
reliability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF reliabilities by projecting out the prescribed number of
sample standard deviations from the sample mean.

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num reliability levels
Keywords Area
method
local reliability
reliability levels
num reliability levels
Specify which reliability levels correspond to which response

1726

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Default: reliability levels evenly distributed among response functions

Description
See parent page
max iterations
Keywords Area
method
local reliability
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.
convergence tolerance
Keywords Area
method
local reliability
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

6.2. METHOD

1727

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
distribution
Keywords Area
method
local reliability
distribution
Selection of cumulative or complementary cumulative functions

1728

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1729
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

cumulative
Keywords Area
method
local reliability
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

1730

CHAPTER 6. KEYWORDS AREA

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
local reliability
distribution
complementary
Computes statistics according to complementary cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

6.2. METHOD

1731

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
local reliability
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution

1732

CHAPTER 6. KEYWORDS AREA

probability_levels =
1. .8 .5
1. .3 .2

1. .66 .33
0.
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06

6.2. METHOD

1733

Level mappings for each response function:

Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels
Keywords Area
method
local reliability
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page

1734

CHAPTER 6. KEYWORDS AREA

gen reliability levels

Keywords Area
method
local reliability
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
local reliability
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

6.2. METHOD

1735

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
model pointer
Keywords Area
method
local reliability
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

1736

CHAPTER 6. KEYWORDS AREA

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.64

global reliability

Keywords Area
method
global reliability
Global reliability methods

6.2. METHOD

1737

Topics
This keyword is related to the topics:
uncertainty quantification
reliability methods

Specification
Alias: nond global reliability
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
x gaussian process

u gaussian process

Optional(Choose
One)

Group 2

surfpack

dakota

Dakota Keyword
Description
Create GP
surrogate in
x-space
Create GP
surrogate in
u-space
Use the Surfpack
version of
Gaussian Process
surrogates
Select the built in
Gaussian Process
surrogate
File containing
points you wish to
use to build a
surrogate

Optional

import build points file

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Optional

use derivatives

Use derivative data

to construct
surrogate models

Optional

seed

Seed of the random

number generator

1738

CHAPTER 6. KEYWORDS AREA

Optional

rng

Selection of a
random number
generator

Optional

response levels

Values at which to
estimate desired
statistics for each
response

Optional

max iterations

Stopping criterion
based on number
of iterations

Optional

convergence tolerance

Stopping criterion
based on
convergence of the
objective function
or statistics

Optional

distribution

Selection of
cumulative or
complementary
cumulative
functions

Optional

probability levels

Optional

gen reliability levels

Optional

model pointer

Specify probability
levels at which to
estimate the
corresponding
response value
Specify
generalized
relability levels at
which to estimate
the corresponding
response value
Identifier for
model block to be
used by a method

Description
These methods do not support forward/inverse mappings involving reliability levels, since they never
form a reliability index based on distance in u-space. Rather they use a Gaussian process model to form an approximation to the limit state (based either in x-space via the x gaussian process specification or in u-space
via the u gaussian process specification), followed by probability estimation based on multimodal adaptive
importance sampling (see [11]) and [12]). These probability estimates may then be transformed into generalized
reliability levels if desired. At this time, inverse reliability analysis (mapping probability or generalized reliability
levels into response levels) is not implemented.

6.2. METHOD

1739

The Gaussian process model approximation to the limit state is formed over the aleatory uncertain variables
by default, but may be extended to also capture the effect of design, epistemic uncertain, and state variables. If
this is desired, one must use the appropriate controls to specify the active variables in the variables specification
block. Refer to variable support for additional information on supported variable types.

See Also
These keywords may also be of interest:
adaptive sampling
gpais
local reliability
sampling
importance sampling
polynomial chaos
stoch collocation
x gaussian process
Keywords Area
method
global reliability
x gaussian process
Create GP surrogate in x-space

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: x kriging
Argument(s): none
u gaussian process
Keywords Area
method
global reliability
u gaussian process
Create GP surrogate in u-space

1740

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
reliability methods

Specification
Alias: u kriging
Argument(s): none
surfpack
Keywords Area
method
global reliability
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.

6.2. METHOD

1741

4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use
derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
dakota
Keywords Area
method
global reliability
dakota
Select the built in Gaussian Process surrogate

Specification
Alias: none
Argument(s): none

1742

CHAPTER 6. KEYWORDS AREA

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
import build points file
Keywords Area
method
global reliability
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

6.2. METHOD

1743

Optional

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
method
global reliability
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

1744

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global reliability
import build points file
custom annotated
Selects custom-annotated tabular file format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1745

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:

1746

CHAPTER 6. KEYWORDS AREA

environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
global reliability
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global reliability
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

6.2. METHOD

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated
interface id
Keywords Area
method
global reliability
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global reliability
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

1747

1748

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
global reliability
import build points file
active only
Import only active variables from tabular data file

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1749

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
method
global reliability
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

custom annotated

Dakota Keyword
Description
Selects annotated
tabular file format
Selects
custom-annotated
tabular file format

1750

CHAPTER 6. KEYWORDS AREA

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.
Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
method
global reliability
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips

6.2. METHOD

1751

To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
global reliability
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1752

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD
header
Keywords Area
method
global reliability
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
eval id
Keywords Area
method
global reliability
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no eval id column

Description
See description of parent custom annotated

1753

1754
interface id
Keywords Area
method
global reliability
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no interface id column

Description
See description of parent custom annotated
freeform
Keywords Area
method
global reliability
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

CHAPTER 6. KEYWORDS AREA

6.2. METHOD

1755

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

use derivatives
Keywords Area
method
global reliability
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1756

CHAPTER 6. KEYWORDS AREA

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
seed
Keywords Area
method
global reliability
seed
Seed of the random number generator

Specification
Alias: none
Argument(s): INTEGER
Default: system-generated (non-repeatable)

Description
The random seed control provides a mechanism for making a stochastic method repeatable. That is, the use of
the same random seed in identical studies will generate identical results.
Default Behavior
If not specified, the seed is randomly generated.
Expected Output
If seed is specified, a stochastic study will generate identical results when repeated using the same seed
value. Otherwise, results are not guaranteed to be the same.
Usage Tips
If a stochastic study was run without seed specified, and the user later wishes to repeat the study using the
same seed, the value of the seed used in the original study can be found in the output Dakota prints to the screen.
That value can then be added to the Dakota input file.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 15347

rng
Keywords Area
method
global reliability

6.2. METHOD

1757

rng
Selection of a random number generator

Specification
Alias: none
Argument(s): none
Default: Mersenne twister ( mt19937 )
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
mt19937

rnum2

Dakota Keyword
Description
Generates random
numbers using the
Mersenne twister
Generates
pseudo-random
numbers using the
Pecos package

Description
The rng keyword is used to indicate a choice of random number generator.
Default Behavior
If specified, the rng keyword must be accompanied by either rnum2 (pseudo-random numbers) or mt19937
(random numbers generated by the Mersenne twister). Otherwise, mt19937, the Mersenne twister is used by
default.
Usage Tips
The default is recommended, as the Mersenne twister is a higher quality random number generator.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

mt19937
Keywords Area
method
global reliability
rng
mt19937
Generates random numbers using the Mersenne twister

1758

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
The mt19937 keyword directs Dakota to use the Mersenne twister to generate random numbers. Additional
information can be found on wikipedia: http://en.wikipedia.org/wiki/Mersenne twister.
Default Behavior
mt19937 is the default random number generator. To specify it explicitly in the Dakota input file, however,
it must be specified in conjuction with the rng keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended.

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng mt19937

rnum2
Keywords Area
method
global reliability
rng
rnum2
Generates pseudo-random numbers using the Pecos package

Specification
Alias: none
Argument(s): none

Description
The rnum2 keyword directs Dakota to use pseudo-random numbers generated by the Pecos package.
Default Behavior
rnum2 is not used by default. To change this behavior, it must be specified in conjuction with the rng
keyword.
Usage Tips
Use of the Mersenne twister random number generator (mt19937) is recommended over rnum2.

6.2. METHOD

1759

Examples
method
sampling
sample_type lhs
samples = 10
seed = 98765
rng rnum2

response levels
Keywords Area
method
global reliability
response levels
Values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF probabilities/reliabilities to compute
Required/Description of
Optional
Group
Optional

Optional

Dakota Keyword
num response levels

compute

Dakota Keyword
Description
Number of values
at which to
estimate desired
statistics for each
response
Selection of
statistics to
compute at each
response level

Description
The response levels specification provides the target response values for which to compute probabilities,
reliabilities, or generalized reliabilities (forward mapping).
Default Behavior
If response levels are not specified, no statistics will be computed. If they are, probabilities will be
computed by default.
Expected Outputs
If response levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or

1760

CHAPTER 6. KEYWORDS AREA

spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.
Usage Tips
The num response levels is used to specify which arguments of the response level correspond to
which response.

Examples
For example, specifying a response level of 52.3 followed with compute probabilities will result
in the calculation of the probability that the response value is less than or equal to 52.3, given the uncertain
distributions on the inputs.
For an example with multiple responses, the following specification
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3

would assign the first two response levels (1., 2.) to response function 1, the next four response levels (.1, .2, .3,
.4) to response function 2, and the final three response levels (10., 20., 30.) to response function 3. If the num response levels key were omitted from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with response levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book

6.2. METHOD

1761

responses,
response_functions = 3
no_gradients
no_hessians

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values specified in the input file. The probability
levels corresponding to those response values are shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.6000000000e+11
5.3601733194e-12
3.6000000000e+11
4.0000000000e+11
4.2500000000e-12
4.0000000000e+11
4.4000000000e+11
3.7500000000e-12
4.4000000000e+11
5.4196114379e+11
2.2557612778e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
6.0000000000e+04
2.8742313192e-05
6.0000000000e+04
6.5000000000e+04
6.4000000000e-05
6.5000000000e+04
7.0000000000e+04
4.0000000000e-05
7.0000000000e+04
7.8702465755e+04
1.0341896485e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.5000000000e+05
4.2844660868e-06
3.5000000000e+05
4.0000000000e+05
8.6000000000e-06
4.0000000000e+05
4.5000000000e+05
1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.6000000000e+11
5.5000000000e-01
4.0000000000e+11
3.8000000000e-01
4.4000000000e+11
2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------6.0000000000e+04
6.1000000000e-01
6.5000000000e+04
2.9000000000e-01
7.0000000000e+04
9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------3.5000000000e+05
5.2000000000e-01
4.0000000000e+05
9.0000000000e-02
4.5000000000e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
A forward mapping involves computing the belief and plausibility probability level for a specified response
level.

1762

CHAPTER 6. KEYWORDS AREA

num response levels

Keywords Area
method
global reliability
response levels
num response levels
Number of values at which to estimate desired statistics for each response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: response levels evenly distributed among response functions

Description
The num response levels keyword allows the user to specify the number of response values, for each response, at which estimated statistics are of interest. Statistics that can be computed are probabilities and reliabilities, both according to either a cumulative distribution function or a complementary cumulative distribution
function.
Default Behavior
If num response levels is not specified, the response levels will be evenly distributed among the responses.
Expected Outputs
The specific output will be determined by the type of statistics that are specified. In a general sense, the output
will be a list of response level-statistic pairs that show the estimated value of the desired statistic for each response
level specified.

Examples
method
sampling
samples = 100
seed = 34785
num_response_levels = 1 1 1
response_levels = 0.5 0.5 0.5

compute
Keywords Area
method
global reliability
response levels
compute
Selection of statistics to compute at each response level

6.2. METHOD

1763

Specification
Alias: none
Argument(s): none
Default: probabilities
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Optional

Dakota Keyword
probabilities

Dakota Keyword
Description
Computes
probabilities
associated with
response levels

gen reliabilities

Computes
generalized
reliabilities
associated with
response levels

system

Compute system
reliability (series
or parallel)

Description
The compute keyword is used to select which forward stastical mapping is calculated at each response level.
Default Behavior
If response levels is not specified, no statistics are computed. If response levels is specified
but compute is not, probabilities will be computed by default. If both response levels and compute
are specified, then on of the following must be specified: probabilities, reliabilities, or gen reliabilities.
Expected Output
The type of statistics specified by compute will be reported for each response level.
Usage Tips
CDF/CCDF probabilities are calculated for specified response levels using a simple binning approach.
CDF/CCDF reliabilities are calculated for specified response levels by computing the number of sample standard deviations separating the sample mean from the response level.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute reliabilities

probabilities

1764

CHAPTER 6. KEYWORDS AREA

Keywords Area
method
global reliability
response levels
compute
probabilities
Computes probabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The probabilities keyword directs Dakota to compute the probability that the model response will be below
(cumulative) or above (complementary cumulative) a specified response value. This is done for every response
level designated for each response.
Default Behavior
If response levels is specified, the probabilities are computed by default. To explicitly specify it in the
Dakota input file, though, the probabilities keyword should be specified in conjunction with the compute
keyword.
Expected Outputs
The Dakota output is a set of response level-probability pairs that give the probability that the model response
will be below or above the corresponding response level, depending on the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute probabilities

gen reliabilities
Keywords Area
method
global reliability
response levels
compute

6.2. METHOD

1765

gen reliabilities
Computes generalized reliabilities associated with response levels

Specification
Alias: none
Argument(s): none

Description
The gen reliabilities keyword directs Dakota to compute generalized reliabilities according to the specified distribution for a specified response value. This is done for every response level designated for each response.
Default Behavior
If response levels is specified, the generalized reliabilities are not computed by default. To change this
behavior, the gen reliabilities keyword should be specified in conjunction with the compute keyword.
Expected Outputs
The Dakota output is a set of response level-generalized reliability pairs according to the distribution defined.

Examples
method
sampling
sample_type random
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
compute gen_reliabilities

system
Keywords Area
method
global reliability
response levels
compute
system
Compute system reliability (series or parallel)

Specification
Alias: none
Argument(s): none

1766

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
series

parallel

Dakota Keyword
Description
Aggregate
response statistics
assuming a series
system
Aggregate
response statistics
assuming a parallel
system

Description
With the system probability/reliability option, statistics for specified response levels are calculated and
reported assuming the response functions combine either in series or parallel to produce a total system response.
For a series system, the system fails when any one component (response) fails. The probability of failure is
the complement of the product of the individual response success probabilities.
For a parallel system, the system fails only when all components (responses) fail. The probability of failure is
the product of the individual response failure probabilities.
series
Keywords Area
method
global reliability
response levels
compute
system
series
Aggregate response statistics assuming a series system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.

6.2. METHOD

1767

parallel
Keywords Area
method
global reliability
response levels
compute
system
parallel
Aggregate response statistics assuming a parallel system

Specification
Alias: none
Argument(s): none

Description
See parent keyword system for description.
max iterations
Keywords Area
method
global reliability
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

1768

CHAPTER 6. KEYWORDS AREA

convergence tolerance
Keywords Area
method
global reliability
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol

6.2. METHOD

1769

distribution
Keywords Area
method
global reliability
distribution
Selection of cumulative or complementary cumulative functions

Specification
Alias: none
Argument(s): none
Default: cumulative (CDF)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
cumulative

complementary

Dakota Keyword
Description
Computes statistics
according to
cumulative
functions
Computes statistics
according to
complementary
cumulative
functions

Description
The distribution keyword allows the user to select between a cumulative distribution/belief/plausibility
function and a complementary cumulative distribution/belief/plausibility function. This choice affects how probabilities and reliability indices are reported.
Default Behavior
If the distribution keyword is present, it must be accompanied by either cumulative or complementary.
Otherwise, a cumulative distribution will be used by default.
Expected Outputs
Output will be a set of model response-probability pairs determined according to the choice of distribution.
The choice of distribution also defines the sign of the reliability or generalized reliability indices.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

1770

CHAPTER 6. KEYWORDS AREA

cumulative
Keywords Area
method
global reliability
distribution
cumulative
Computes statistics according to cumulative functions

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a cumulative distribution/belief/plausibility function.
Default Behavior
By default, a cumulative distribution/belief/plausibility function will be used. To explicitly specify it in the
Dakota input file, however, the cumulative keyword must be appear in conjunction with the distribution
keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a cumulative distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response falls
below given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution cumulative

complementary
Keywords Area
method
global reliability
distribution
complementary
Computes statistics according to complementary cumulative functions

6.2. METHOD

1771

Specification
Alias: none
Argument(s): none

Description
Statistics on model responses will be computed according to a complementary cumulative distribution/belief/plausibility
function.
Default Behavior
By default, a complementary cumulative distribution/belief/plausibility function will not be used. To change
that behavior, the complementary keyword must be appear in conjunction with the distribution keyword.
Expected Outputs
Output will be a set of model response-probability pairs determined according to a complementary cumulative
distribution/belief/plausibility function. The probabilities reported are the probabilities that the model response
falls above given response threshholds.

Examples
method
sampling
sample_type lhs
samples = 10
distribution complementary

probability levels
Keywords Area
method
global reliability
probability levels
Specify probability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num probability levels

Dakota Keyword
Description
Specify which
probability levels
correspond to
which response

1772

CHAPTER 6. KEYWORDS AREA

Description
Response levels are calculated for specified CDF/CCDF probabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).
Expected Output
If probability levels are specified, Dakota will create two tables in the standard output: a Probability
Density function (PDF) histogram and a Cumulative Distribution Function (CDF) table. The PDF histogram has
the lower and upper endpoints of each bin and the corresponding density of that bin. Note that the PDF histogram
has bins defined by the probability levels and/or response levels in the Dakota input file. If there
are not very many levels, the histogram will be coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the corresponding probability that the response value
is less than or equal to each response level threshold.

Examples
The Dakota input file below specifies a sampling method with probability levels of interest.
method,
sampling,
samples = 100 seed = 1
complementary distribution
probability_levels = 1. .66 .33
1. .8 .5
0.
1. .3 .2
0.

0.

variables,
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations
=
12.4,
29.7
descriptors
= TF1n TF2n
uniform_uncertain = 2
lower_bounds
= 199.3, 474.63
upper_bounds
= 298.5, 712.
descriptors
= TF1u TF2u
weibull_uncertain = 2
alphas
=
12.,
30.
betas
= 250.,
590.
descriptors
= TF1w TF2w
histogram_bin_uncertain = 2
num_pairs
= 3
4
abscissas
= 5 8 10 .1 .2 .3 .4
counts
= 17 21 0 12 24 12
0
descriptors = TF1h TF2h
histogram_point_uncertain
real = 1
num_pairs
=
2
abscissas
= 3 4
counts
= 1 1
descriptors = TF3h
interface,
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses,
response_functions = 3
no_gradients
no_hessians

6.2. METHOD

1773

Given the above Dakota input file, the following excerpt from the output shows the PDF and CCDF generated.
Note that the bounds on the bins of the PDF are the response values that correspond the probability levels specified
in the input file. Those response values are also shown in the CCDF.
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower
Bin Upper
Density Value
----------------------------2.7604749078e+11
3.4221494996e+11
5.1384774972e-12
3.4221494996e+11
4.0634975300e+11
5.1454122311e-12
4.0634975300e+11
5.4196114379e+11
2.4334239039e-12
PDF for response_fn_2:
Bin Lower
Bin Upper
Density Value
----------------------------4.6431154744e+04
5.6511827775e+04
1.9839945149e-05
5.6511827775e+04
6.1603813790e+04
5.8916108390e-05
6.1603813790e+04
7.8702465755e+04
2.9242071306e-05
PDF for response_fn_3:
Bin Lower
Bin Upper
Density Value
----------------------------2.3796737090e+05
3.6997214153e+05
5.3028386523e-06
3.6997214153e+05
3.8100966235e+05
9.0600055634e-06
3.8100966235e+05
4.4111498127e+05
3.3274925348e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.7604749078e+11
1.0000000000e+00
3.4221494996e+11
6.6000000000e-01
4.0634975300e+11
3.3000000000e-01
5.4196114379e+11
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------4.6431154744e+04
1.0000000000e+00
5.6511827775e+04
8.0000000000e-01
6.1603813790e+04
5.0000000000e-01
7.8702465755e+04
0.0000000000e+00
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- ----------------2.3796737090e+05
1.0000000000e+00
3.6997214153e+05
3.0000000000e-01
3.8100966235e+05
2.0000000000e-01
4.4111498127e+05
0.0000000000e+00

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num probability levels

1774

CHAPTER 6. KEYWORDS AREA

Keywords Area
method
global reliability
probability levels
num probability levels
Specify which probability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: probability levels evenly distributed among response functions

Description
See parent page
gen reliability levels
Keywords Area
method
global reliability
gen reliability levels
Specify generalized relability levels at which to estimate the corresponding response value

Specification
Alias: none
Argument(s): REALLIST
Default: No CDF/CCDF response levels to compute
Required/Description of
Optional
Group
Optional

Dakota Keyword
num gen reliability levels

Dakota Keyword
Description
Specify which
gen reliability levels
correspond to
which response

Description
Response levels are calculated for specified generalized reliabilities by indexing into a sorted samples array (the
response levels computed are not interpolated and will correspond to one of the sampled values).

6.2. METHOD

1775

Theory
Sets of response-probability pairs computed with the forward/inverse mappings define either a cumulative distribution function (CDF) or a complementary cumulative distribution function (CCDF) for each response function.
In the case of evidence-based epistemic methods, this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative belief and plausibility functions (CCBF and
CCPF) for each response function.
An inverse mapping involves computing the belief and plausibility response level for either a specified probability level or a specified generalized reliability level (two results for each level mapping in the evidence-based
epistemic case, instead of the one result for each level mapping in the aleatory case).
num gen reliability levels
Keywords Area
method
global reliability
gen reliability levels
num gen reliability levels
Specify which gen reliability levels correspond to which response

Specification
Alias: none
Argument(s): INTEGERLIST
Default: gen reliability levels evenly distributed among response functions

Description
See parent page
model pointer
Keywords Area
method
global reliability
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

1776

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

1777

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.65

fsu quasi mc

Keywords Area
method
fsu quasi mc
Design of Computer Experiments - Quasi-Monte Carlo sampling

Topics
This keyword is related to the topics:
package fsudace
design and analysis of computer experiments

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
sequence type
(Group 1)

Dakota Keyword
halton

hammersley
Optional

latinize

Dakota Keyword
Description
Generate samples
from a Halton
sequence
Use Hammersley
sequences
Adjust samples to
improve the
discrepancy of the
marginal
distributions

1778

CHAPTER 6. KEYWORDS AREA

Optional

quality metrics

Optional

variance based decomp

Optional

samples

Number of
samples for
sampling-based
methods

Optional

fixed sequence

Optional

sequence start

Optional

sequence leap

Optional

prime base

Optional

max iterations

Reuse the same

sequence and
samples for
multiple sampling
sets
Choose where to
start sampling the
sequence
Specify how often
the sequence is
sampled
The prime
numbers used to
generate the
sequence
Stopping criterion
based on number
of iterations

Optional

model pointer

Calculate metrics
to assess the
quality of
quasi-Monte Carlo
samples
Activates global
sensitivity analysis
based on
decomposition of
response variance
into contributions
from variables

Identifier for
model block to be
used by a method

Description
Quasi-Monte Carlo methods produce low discrepancy sequences, especially if one is interested in the uniformity
of projections of the point sets onto lower dimensional faces of the hypercube (usually 1-D: how well do the
marginal distributions approximate a uniform?)
This method generates sets of uniform random variables on the interval [0,1]. If the user specifies lower and
upper bounds for a variable, the [0,1] samples are mapped to the [lower, upper] interval.
The user must first choose the sequence type:

6.2. METHOD

1779

halton or
hammersley
Then three keywords are used to define the sequence and how it is sampled:
prime base
sequence start
sequence leap
Each of these has defaults, so specification is optional.

Theory
The quasi-Monte Carlo sequences of Halton and Hammersley are deterministic sequences determined by a set of
prime bases. Generally, we recommend that the user leave the default setting for the bases, which are the lowest
primes. Thus, if one wants to generate a sample set for 3 random variables, the default bases used are 2, 3, and 5 in
the Halton sequence. To give an example of how these sequences look, the Halton sequence in base 2 starts with
points 0.5, 0.25, 0.75, 0.125, 0.625, etc. The first few points in a Halton base 3 sequence are 0.33333, 0.66667,
0.11111, 0.44444, 0.77777, etc. Notice that the Halton sequence tends to alternate back and forth, generating a
point closer to zero then a point closer to one. An individual sequence is based on a radix inverse function defined
on a prime base. The prime base determines how quickly the [0,1] interval is filled in. Generally, the lowest
primes are recommended.
The Hammersley sequence is the same as the Halton sequence, except the values for the first random variable
are equal to 1/N, where N is the number of samples. Thus, if one wants to generate a sample set of 100 samples
for 3 random variables, the first random variable has values 1/100, 2/100, 3/100, etc. and the second and third
variables are generated according to a Halton sequence with bases 2 and 3, respectively.
For more information about these sequences, see[43], [44], and [1].

See Also
These keywords may also be of interest:
dace
fsu cvt
psuade moat
halton
Keywords Area
method
fsu quasi mc
halton
Generate samples from a Halton sequence

1780

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
package fsudace

Specification
Alias: none
Argument(s): none

Description
The quasi-Monte Carlo sequences of Halton are deterministic sequences determined by a set of prime bases.
These sequences generate random numbers with the goal of filling a unit hypercube uniformly.
Generally, we recommend that the user leave the default setting for the bases, which are the lowest primes.
Thus, if one wants to generate a sample set for 3 random variables, the default bases used are 2, 3, and 5 in the
Halton sequence. To give an example of how these sequences look, the Halton sequence in base 2 starts with
points 0.5, 0.25, 0.75, 0.125, 0.625, etc. The first few points in a Halton base 3 sequence are 0.33333, 0.66667,
0.11111, 0.44444, 0.77777, etc. Notice that the Halton sequence tends to alternate back and forth, generating a
point closer to zero then a point closer to one. An individual sequence is based on a radix inverse function defined
on a prime base. The prime base determines how quickly the [0,1] interval is filled in.

Theory
For more information about these sequences, see[43], [44], and [1].
hammersley
Keywords Area
method
fsu quasi mc
hammersley
Use Hammersley sequences

Topics
This keyword is related to the topics:
package fsudace
design and analysis of computer experiments

Specification
Alias: none
Argument(s): none

6.2. METHOD

1781

Description
The Hammersley sequence is the same as the Halton sequence, except the values for the first random variable are
equal to 1/N, where N is the number of samples. Thus, if one wants to generate a sample set of 100 samples for 3
random variables, the first random variable has values 1/100, 2/100, 3/100, etc. and the second and third variables
are generated according to a Halton sequence with bases 2 and 3, respectively.

See Also
These keywords may also be of interest:
fsu quasi mc
latinize
Keywords Area
method
fsu quasi mc
latinize
Adjust samples to improve the discrepancy of the marginal distributions

Specification
Alias: none
Argument(s): none
Default: No latinization

Description
The latinize control takes the samples and latinizes them, meaning that each original sample is moved so
that it falls into one strata or bin in each dimension as in Latin Hypercube sampling. The default setting is NOT
to latinize. However, one may be interested in doing this in situations where one wants better discrepancy of the
1-dimensional projections (the marginal distributions).
quality metrics
Keywords Area
method
fsu quasi mc
quality metrics
Calculate metrics to assess the quality of quasi-Monte Carlo samples

Topics
This keyword is related to the topics:
package fsudace

1782

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: No quality metrics

Description
quality metrics calculates four quality metrics relating to the volumetric spacing of the samples. The four
quality metrics measure different aspects relating to the uniformity of point samples in hypercubes. Desirable
properties of such point samples are:
are the points equally spaced
do the points cover the region
and are they isotropically distributed
with no directional bias in the spacing
The four quality metrics we report are:
h: the point distribution norm, which is a measure of uniformity of the point distribution
chi: a regularity measure, and provides a measure of local uniformity of a set of points
tau: the second moment trace measure
d: the second moment determinant measure
All of these values are scaled so that smaller is better (the smaller the metric, the better the uniformity of the point
distribution).

Examples
Complete explanation of these measures can be found in [38].
variance based decomp
Keywords Area
method
fsu quasi mc
variance based decomp
Activates global sensitivity analysis based on decomposition of response variance into contributions from
variables

Specification
Alias: none
Argument(s): none
Default: no variance-based decomposition

6.2. METHOD

1783
Required/Optional
Optional

Description of
Group

Dakota Keyword
drop tolerance

Dakota Keyword
Description
Suppresses output
of sensitivity
indices with values
lower than this
tolerance

Description
Dakota can calculate sensitivity indices through variance based decomposition using the keyword variancebased decomp. These indicate how important the uncertainty in each input variable is in contributing to the
output variance.
Default Behavior
Because of the computational cost, variance based decomp is turned off as a default.
If the user specified a number of samples, N, and a number of nondeterministic variables, M, variance-based
decomposition requires the evaluation of N(M+2) samples. Note that specifying this keyword will increase the
number of function evaluations above the number requested with the samples keyword since replicated
sets of sample values are evaluated.
Expected Outputs
When variance based decomp is specified, sensitivity indices for main effects and total effects will be
reported. Main effects (roughly) represent the percent contribution of each individual variable to the variance in
the model response. Total effects represent the percent contribution of each individual variable in combination
with all other variables to the variance in the model response
Usage Tips
To obtain sensitivity indices that are reasonably accurate, we recommend that N, the number of samples, be at
least one hundred and preferably several hundred or thousands.

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp

Theory
In this context, we take sensitivity analysis to be global, not local as when calculating derivatives of output
variables with respect to input variables. Our definition is similar to that of[73] : The study of how uncertainty
in the output of a model can be apportioned to different sources of uncertainty in the model input.
Variance based decomposition is a way of using sets of samples to understand how the variance of the output
behaves, with respect to each input variable. A larger value of the sensitivity index, Si , means that the uncertainty
in the input variable i has a larger effect on the variance of the output. More details on the calculations and
interpretation of the sensitivity indices can be found in[73] and[87].
drop tolerance
Keywords Area
method

1784

CHAPTER 6. KEYWORDS AREA

fsu quasi mc
variance based decomp
drop tolerance
Suppresses output of sensitivity indices with values lower than this tolerance

Specification
Alias: none
Argument(s): REAL
Default: All VBD indices displayed

Description
The drop tolerance keyword allows the user to specify a value below which sensitivity indices generated by
variance based decomp are not displayed.
Default Behavior
By default, all sensitivity indices generated by variance based decomp are displayed.
Usage Tips
For polynomial chaos, which outputs main, interaction, and total effects by default, the univariateeffects may be a more appropriate option. It allows suppression of the interaction effects since the output
volume of these results can be prohibitive for high dimensional problems. Similar to suppression of these interactions is the covariance control, which can be selected to be diagonal covariance or full covariance, with the
former supporting suppression of the off-diagonal covariance terms (to save compute and memory resources and
reduce output volume).

Examples
method,
sampling
sample_type lhs
samples = 100
variance_based_decomp
drop_tolerance = 0.001

samples
Keywords Area
method
fsu quasi mc
samples
Number of samples for sampling-based methods

Specification
Alias: none
Argument(s): INTEGER
Default: 0 (or min req for surrogate build)

6.2. METHOD

1785

Description
The samples keyword is used to define the number of samples (i.e., randomly chosen sets of variable values) at
which to execute a model.
Default Behavior
By default, Dakota will use the minimum number of samples required by the chosen method.
Usage Tips
To obtain linear sensitivities or to construct a linear response surface, at least dim+1 samples should be used,
where dim is the number of variables. For sensitivities to quadratic terms or quadratic response surfaces, at least
(dim+1)(dim+2)/2 samples are needed. For uncertainty quantification, we recommend at least 10dim samples.
For variance based decomp, we recommend hundreds to thousands of samples. Note that for variancebased decomp, the number of simulations performed will be N(dim+2).

Examples
method
sampling
sample_type lhs
samples = 20

fixed sequence
Keywords Area
method
fsu quasi mc
fixed sequence
Reuse the same sequence and samples for multiple sampling sets

Specification
Alias: none
Argument(s): none
Default: sequence not fixed: sampling patterns are variable among multiple QMC runs

Description
The fixed sequence control is similar to fixed seed for other sampling methods. If fixed sequence
is specified, the user will get the same sequence (meaning the same set of samples) for subsequent calls of the
QMC sampling method (for example, this might be used in a surrogate based optimization method or a parameter
study where one wants to fix the uncertain variables).
sequence start
Keywords Area
method
fsu quasi mc
sequence start
Choose where to start sampling the sequence

1786

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGERLIST
Default: Vector of zeroes

Description
sequence start determines where in the sequence the samples will start.
The default sequence start is a vector with 0 for each variable, specifying that each sequence start with
the first term.

Examples
For example, for the Halton sequence in base 2, if the user specifies sequence start = 2, the sequence would not
include 0.5 and 0.25, but instead would start at 0.75.
sequence leap
Keywords Area
method
fsu quasi mc
sequence leap
Specify how often the sequence is sampled

Specification
Alias: none
Argument(s): INTEGERLIST
Default: Vector of ones

Description
sequence leap controls the leaping of terms in the sequence. The default is 1 for each variable, meaning
that each term in the sequence be returned.

Examples
If the user specifies a sequence leap of 2 for a variable, the points returned would be every other term from the
QMC sequence.

Theory
The advantage to using a leap value greater than one is mainly for high-dimensional sets of random deviates.
In this case, setting a leap value to the next prime number larger than the largest prime base can help maintain
uniformity when generating sample sets for high dimensions. For more information about the efficacy of leaped
Halton sequences, see[71].

6.2. METHOD

1787

prime base
Keywords Area
method
fsu quasi mc
prime base
The prime numbers used to generate the sequence

Specification
Alias: none
Argument(s): INTEGERLIST
Default: Vector of the first s primes for s-dimensions in Halton, First (s-1) primes for Hammersley

Description
It is recommended that the user not specify this and use the default values.
For the Halton sequence, the default bases are primes in increasing order, starting with 2, 3, 5, etc.
For the Hammersley sequence, the user specifies (s-1) primes if one is generating an s-dimensional set of
random variables.
max iterations
Keywords Area
method
fsu quasi mc
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

Description
The maximum number of iterations (default: 100). See also max function evaluations.

1788

CHAPTER 6. KEYWORDS AREA

model pointer
Keywords Area
method
fsu quasi mc
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR

6.2. METHOD

1789

surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.66

vector parameter study

Keywords Area
method
vector parameter study
Samples variables along a user-defined vector

Topics
This keyword is related to the topics:
parameter studies

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

1790

CHAPTER 6. KEYWORDS AREA

Required(Choose
One)

Group 1

final point

Final variable
values defining
vector in vector
parameter study

step vector

Size of step for

each variable
Number of
sampling steps
along the vector in
a vector parameter
study

Required

num steps

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Dakotas vector parameter study computes response data sets at selected intervals along a vector in parameter
space. It is often used for single-coordinate parameter studies (to study the effect of a single variable on a response
set), but it can be used more generally for multiple coordinate vector studies (to investigate the response variations
along some n-dimensional vector such as an optimizer search direction).
Default Behavior
By default, the multidimensional parameter study operates over all types of variables.
Expected Outputs
A multidimensional parameter study produces a set of responses for each parameter set that is generated.
Usage Tips
Group 1 is used to define the vector along which the parameters are varied. Both cases also rely on the
variables specification of an initial value, through:
the initial point keyword
the initial state keyword
relying on the default initial value, based on the rest of the variables specification
From the initial value, the vector can be defined using one of the two keyword choices.
Once the vector is defined, the samples are then fully specifed by num steps.

Examples
The following example is a good comparison to the examples on multidim parameter study and centered parameterstudy.
# tested on Dakota 6.0 on 140501
environment
tabular_data
tabular_data_file = rosen_vector.dat
method
vector_parameter_study
num_steps = 10

6.2. METHOD
final_point =
model
single

1791
2.0

variables
continuous_design = 2
initial_point =
-2.0
descriptors =
x1

2.0

-2.0
"x2"

interface
analysis_driver = rosenbrock
fork
responses
response_functions = 1
no_gradients
no_hessians

See Also
These keywords may also be of interest:
centered parameter study
multidim parameter study
list parameter study
final point
Keywords Area
method
vector parameter study
final point
Final variable values defining vector in vector parameter study

Specification
Alias: none
Argument(s): REALLIST

Description
The final point keyword is used to define the final values for each variable on the vector to be used in the
vector parameter study. The vectors direction and magnitude are determined by the initial value from the variables
specification, and the final point.
Default Behavior
The user is required to specify either final point or step vector. There is no default definition for the
vector.
Usage Tips
The actual points are determined based on this vector and the number of points chosen is given in num points.

1792

CHAPTER 6. KEYWORDS AREA

Examples
method
vector_parameter_study
num_steps = 10
final_point =
2.0

2.0

step vector
Keywords Area
method
vector parameter study
step vector
Size of step for each variable

Specification
Alias: none
Argument(s): REALLIST

Description
The step vector keyword specifies how much each variable will be incremented in a single step.
step vector works in conjunction with num steps, which determines the number of steps taken during
the vector parameter study. If instead of step vector, final point is specified with num steps,
Dakota will infer the step sizes.
Entries in the step vector are the actual amounts by which continuous and range variables are incremented. For set variables, step vector entries are interpreted as indexes into the underlying set.
Default Behavior
The user is required to specify either final point or step vector. There is no default definition for the
vector.

Examples
variables
continuous_design 1
initial_point 1.0
descriptors x1
discrete_design_set
string 1
elements bar baz foo fuzz
initial_point bar
descriptors s1
method
vector_parameter_study
num_steps = 3
# Add 2.0 to x1 and increment s1 by 1 element in each step
step_vector =
2.0
1

6.2. METHOD

1793

num steps
Keywords Area
method
vector parameter study
num steps
Number of sampling steps along the vector in a vector parameter study

Specification
Alias: none
Argument(s): INTEGER

Description
num steps defines the number of steps that are taken in the direction of the vector. The magnitude of each step
is determined in conjuction with the rest of the method specification.
Default Behavior
The user is required to specify num steps for a vector parameter study. There is no default value.
This study performs function evaluations at both ends, making the total number of evaluations equal to numsteps+1.
Usage Tips
The study has stringent requirements on performing appropriate steps with any discrete range and discrete
set variables. A num steps specification must result in discrete range and set index steps that are integers: no
remainder is currently permitted in the integer step calculation and no rounding to integer steps will occur.

Examples
method
vector_parameter_study
num_steps = 10
final_point =
2.0

2.0

model pointer
Keywords Area
method
vector parameter study
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

1794

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2

6.2. METHOD

1795

interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.67

list parameter study

Keywords Area
method
list parameter study
Samples variables as a specified values

Topics
This keyword is related to the topics:
parameter studies

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Optional

Description of
Group
Group 1

Dakota Keyword
list of points

Dakota Keyword
Description
List of variable
values to evaluate
in a list parameter
study

import points file

File containing list

of variable values
to evaluate in a list
parameter study

model pointer

Identifier for
model block to be
used by a method

Description
Dakotas list parameter study allows for evaluations at user selected points of interest.
Default Behavior
By default, the list parameter study operates over all types of variables.

1796

CHAPTER 6. KEYWORDS AREA

The number of real values in the list of points specification or file referenced by import points file must be a multiple of the total number of variables (including continuous and discrete types) contained in
the variables specification.
Expected Outputs
A list parameter study produces a set of responses for each parameter set that is specified.
Usage Tips
This parameter study simply performs simulations for the first parameter set (the first n entries in the list),
followed by the next parameter set (the next n entries), and so on, until the list of points has been exhausted.
Since the initial values from the variables specification will not be used, they need not be specified.
When the points are specified in the Dakota input file using the list of points keyword, discrete set
values must be referred to using 0-based indexes, and not the values themselves. However, when using
import points file, refer to discrete set values directly, not by index.
For both list of points and import points file, Dakota expects the values for each evaluation
to be ordered by type. The type ordering matches that of the variables section of this Reference Manual and
of the listing in the Parameters file format section of the Dakota Users Manual[4]. When multiple variables
are present for a single type, the ordering within that type must match the order specified by the user in the
variables section of her input file.

Examples
This shows the method and variables block of a Dakota input file that runs a list parameter study.
method
list_parameter_study
list_of_points =
3.1e6
3.2e6
3.3e6
3.3e6
variables
continuous_design = 3
descriptors = E

0.0029
0.0028
0.0027
0.0026

MASS

0.31
0.32
0.34
0.36

DENSITY

Note that because of the way Dakota treats whitespace, the above example is equivalent to:
method
list_parameter_study
list_of_points =
3.1e6
0.0029
0.31
0.32
3.3e6
0.0027
0.34 3.3e6
0.0026

3.2e6

0.0028

0.36

variables
continuous_design = 3
descriptors = E MASS

DENSITY

Although the first example is much more readable.

And heres a full input file:
# tested on Dakota 6.0 on 140501
environment
tabular_data
tabular_data_file List_param_study.dat

6.2. METHOD

method
list_parameter_study
list_of_points =

1797

0.1
0.2
0.3
0.3

0.1
0.1
0.0
1.0

model
single
variables
active design
continuous_design = 2
descriptors
x1 x2
continuous_state = 1
descriptors =
constant1
initial_state = 100
interface
analysis_drivers text_book
fork
asynchronous
evaluation_concurrency 2
responses
response_functions = 1
no_gradients
no_hessians

This example illustrates the list parameter study.

The function evaluations are independent, so any level of evaluation concurrency can be used
Default behavior for parameter studies is to iterate on all variables. However, because active design is
specified, this study will only iterate on the continuous design variables.

See Also
These keywords may also be of interest:
centered parameter study
multidim parameter study
vector parameter study
list of points
Keywords Area
method
list parameter study
list of points
List of variable values to evaluate in a list parameter study

1798

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): REALLIST

Description
The list of points keyword allows the user to specify, in a freeform format, a list of variable values at which
to compute a model response.
Default Behavior
The user is required to provide a list of points for a list parameter study either by specifying it with list of points or by providing a file from which such a list can be read via import points file. There is no
default list of points.
Usage Tips
The number of values in the list must be an integer multiple of the number of variables. Dakota will verify
that this condition is met.

Examples
method
list_parameter_study
list_of_points =
3.1e6
3.2e6
3.3e6
3.3e6

0.0029
0.0028
0.0027
0.0026

0.31
0.32
0.34
0.36

import points file

Keywords Area
method
list parameter study
import points file
File containing list of variable values to evaluate in a list parameter study

Specification
Alias: none
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

6.2. METHOD

1799

Optional

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import points file specifies a file containing a list of variable values at which to compute a model
response.
Default Behavior
By default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import points file must be in one of three
formats:
annotated (default)
custom annotated
freeform

Examples
method
list_parameter_study
import_points_file = dakota_pstudy.3.dat

annotated
Keywords Area
method
list parameter study
import points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

1800

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
method
list parameter study
import points file
custom annotated
Selects custom-annotated tabular file format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.2. METHOD

1801

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:

1802

CHAPTER 6. KEYWORDS AREA

environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
method
list parameter study
import points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
eval id
Keywords Area
method
list parameter study
import points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

6.2. METHOD

Description
See description of parent custom annotated
interface id
Keywords Area
method
list parameter study
import points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
freeform
Keywords Area
method
list parameter study
import points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

1803

1804

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
method
list parameter study
import points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.2. METHOD

1805

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
model pointer
Keywords Area
method
list parameter study
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

1806

CHAPTER 6. KEYWORDS AREA

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.68

centered parameter study

Keywords Area
method
centered parameter study
Samples variables along points moving out from a center point

6.2. METHOD

1807

Topics
This keyword is related to the topics:
parameter studies

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
step vector

Dakota Keyword
Description
Size of steps to be
taken in each
dimension of a
centered parameter
study

Required

steps per variable

Number of steps to
take in each
dimension of a
centered parameter
study

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Dakotas centered parameter study computes response data sets along multiple coordinate-based vectors, one
per parameter, centered about the initial values from the variables specification. This is useful for investigation
of function contours with respect to each parameter individually in the vicinity of a specific point (e.g., postoptimality analysis for verification of a minimum), thereby avoiding the cost associated with a multidimensional
grid.
Default Behavior
By default, the centered parameter study operates over all types of variables.
The centered parameter study takes steps along each orthogonal dimension. Each dimension is
treated independently. The P
number of steps are taken in each direction, so that the total number of points in
the parameter study is 1 + 2 n.
Expected Outputs
A centered parameter study produces a set of responses for each parameter set that is generated.

Examples
The following example is a good comparison to the examples on multidim parameter study and vector parameterstudy.
# tested on Dakota 6.0 on 140501
environment

1808

CHAPTER 6. KEYWORDS AREA

tabular_data
tabular_data_file = rosen_centered.dat
method
centered_parameter_study
steps_per_variable = 5 4
step_vector = 0.4 0.5
model
single
variables
continuous_design = 2
initial_point =
0
descriptors =
x1

0
"x2"

interface
analysis_driver = rosenbrock
fork
responses
response_functions = 1
no_gradients
no_hessians

See Also
These keywords may also be of interest:
multidim parameter study
list parameter study
vector parameter study
step vector
Keywords Area
method
centered parameter study
step vector
Size of steps to be taken in each dimension of a centered parameter study

Specification
Alias: none
Argument(s): REALLIST

Description
The step vector keyword defines the individual step size in each dimension, treated separately.
Default Behavior

6.2. METHOD

1809

The user is required to define the number of step sizes for a centered parameter study. There are no default
values.
Steps are taken in the plus and minus directions, and are defined in either actual values (continuous and
discrete range) or index offsets (discrete set).

Examples
method
centered_parameter_study
steps_per_variable = 5 4
step_vector = 0.4 0.5

steps per variable

Keywords Area
method
centered parameter study
steps per variable
Number of steps to take in each dimension of a centered parameter study

Specification
Alias: deltas per variable
Argument(s): INTEGERLIST

Description
The steps per variable keyword allows the user to define the number of steps in each dimesion of a centered parameter study. Because they are taken independently, the number of steps can be specified for each.
Default Behavior
The user is required to define the number of steps per variable for a centered parameter study. There are no
default values.
Steps are taken in the plus and minus directions, and are defined in either actual values (continuous and
discrete range) or index offsets (discrete set).

Examples
method
centered_parameter_study
steps_per_variable = 5 4
step_vector = 0.4 0.5

model pointer
Keywords Area
method
centered parameter study

1810

CHAPTER 6. KEYWORDS AREA

model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs

6.2. METHOD

1811

samples = 121 seed = 5034 rng rnum2

model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.2.69

multidim parameter study

Keywords Area
method
multidim parameter study
Samples variables on full factorial grid of study points

Topics
This keyword is related to the topics:
parameter studies

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Description of
Group

Dakota Keyword
partitions

Dakota Keyword
Description
Samples variables
on full factorial
grid of study points

1812

CHAPTER 6. KEYWORDS AREA

Optional

model pointer

Identifier for
model block to be
used by a method

Description
Dakotas multidimensional parameter study computes response data sets for an n-dimensional grid of points. Each
continuous and discrete range variable is partitioned into equally spaced intervals between its upper and lower
bounds, each discrete set variable is partitioned into equally spaced index intervals. The partition boundaries in
n-dimensional space define a grid of points, and every point is evaluated.
Default Behavior
By default, the multidimensional parameter study operates over all types of variables.
Expected Outputs
A multidimensional parameter study produces a set of responses for each parameter set that is generated.
Usage Tips
Since the initial values from the variables specification will not be used, they need not be specified.

Examples
This example is taken from the Users Manual and is a good comparison to the examples on centered parameter study and vector parameter study.
# tested on Dakota 6.0 on 140501
environment
tabular_data
tabular_data_file = rosen_multidim.dat
method
multidim_parameter_study
partitions = 10 8
model
single
variables
continuous_design = 2
lower_bounds
-2.0
upper_bounds
2.0
descriptors
x1

-2.0
2.0
"x2"

interface
analysis_driver = rosenbrock
fork
responses
response_functions = 1
no_gradients
no_hessians

This example illustrates the full factorial combinations of parameter values created by the multidim parameterstudy. With 10 and 8 partitions, there are actually 11 and 9 values for each variable. This means that 11 9 = 99
function evaluations will be required.

See Also
These keywords may also be of interest:

6.2. METHOD

1813

centered parameter study

list parameter study
vector parameter study
partitions
Keywords Area
method
multidim parameter study
partitions
Samples variables on full factorial grid of study points

Topics
This keyword is related to the topics:
parameter studies

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Dakotas multidimensional parameter study computes response data sets for an n-dimensional grid of points. Each
continuous and discrete range variable is partitioned into equally spaced intervals between its upper and lower
bounds, each discrete set variable is partitioned into equally spaced index intervals. The partition boundaries in
n-dimensional space define a grid of points, and every point is evaluated.
Default Behavior
By default, the multidimensional parameter study operates over all types of variables.
Expected Outputs
A multidimensional parameter study produces a set of responses for each parameter set that is generated.
Usage Tips
Since the initial values from the variables specification will not be used, they need not be specified.

Examples
This example is taken from the Users Manual and is a good comparison to the examples on centered parameter study and vector parameter study.
# tested on Dakota 6.0 on 140501
environment
tabular_data
tabular_data_file = rosen_multidim.dat
method
multidim_parameter_study
partitions = 10 8

1814

CHAPTER 6. KEYWORDS AREA

model
single
variables
continuous_design = 2
lower_bounds
-2.0
upper_bounds
2.0
descriptors
x1

-2.0
2.0
"x2"

interface
analysis_driver = rosenbrock
fork
responses
response_functions = 1
no_gradients
no_hessians

This example illustrates the full factorial combinations of parameter values created by the multidim parameterstudy. With 10 and 8 partitions, there are actually 11 and 9 values for each variable. This means that 11 9 = 99
function evaluations will be required.

See Also
These keywords may also be of interest:
centered parameter study
list parameter study
vector parameter study
model pointer
Keywords Area
method
multidim parameter study
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

6.2. METHOD

1815

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6
sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses

1816

CHAPTER 6. KEYWORDS AREA

response_functions = 3
no_gradients
no_hessians

6.2.70

richardson extrap

Keywords Area
method
richardson extrap
Estimate order of convergence of a response as model fidelity increases

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Required(Choose
One)

Group 1

Dakota Keyword
estimate order

converge order

converge qoi
Optional

refinement rate

Optional

convergence tolerance

Optional

max iterations

Dakota Keyword
Description
Compute the best
estimate of the
convergence order
from three points
Refine until the
estimated
covergence order
converges
Refine until the
response converges
Rate at which the
state variables are
refined
Stopping criterion
based on
convergence of the
objective function
or statistics
Stopping criterion
based on number
of iterations

6.2. METHOD

1817
Optional

model pointer

Identifier for
model block to be
used by a method

Description
Solution verification procedures estimate the order of convergence of the simulation response data during the
course of a refinement study. This branch of methods is new and currently only contains one algorithm: Richardson extrapolation.
Refinement of the model
The model fidelity must be parameterized by one or more continuous state variable(s).
The refinement path is determined from the initial state of the continuous state variables specification in combination with the refinement rate, where each of the state variables is treated as an independent refinement factor and each of the initial state values is repeatedly divided by the refinement rate value to
define new discretization states.
Results
Three algorithm options are currently provided:
1. estimate order
2. converge order
3. converge qoi
Stopping Criteria
The method employs the max iterations and convergence tolerance method independent controls as stopping criteria.

Theory
In each of these cases, convergence order for a response quantity of interest (QoI) is estimated from


QoI3 QoI2
p = ln
/ln(r)
QoI2 QoI1
where r is the uniform refinement rate specified by refinement rate.
estimate order
Keywords Area
method
richardson extrap
estimate order
Compute the best estimate of the convergence order from three points

Specification
Alias: none
Argument(s): none

1818

CHAPTER 6. KEYWORDS AREA

Description
The estimate order option is the simplest option. For each of the refinement factors, it evaluates three points
along the refinement path and uses these results to perform an estimate of the convergence order for each response
function.
converge order
Keywords Area
method
richardson extrap
converge order
Refine until the estimated covergence order converges

Specification
Alias: none
Argument(s): none

Description
The converge order option is initialized using the estimate order aproach, and additional refinements
are performed along the refinement path until the convergence order estimates converge (two-norm of the change
in response orders is less than the convergence tolerance).
converge qoi
Keywords Area
method
richardson extrap
converge qoi
Refine until the response converges

Specification
Alias: none
Argument(s): none

Description
The converge qoi option is similar to the converge order option, except that the convergence criterion
is that the two-norm of the response discretization errors (computed from extrapolation) must be less than the
convergence tolerance.

6.2. METHOD
refinement rate
Keywords Area
method
richardson extrap
refinement rate
Rate at which the state variables are refined

Specification
Alias: none
Argument(s): REAL
Default: 2.

Description
Described on parent page
convergence tolerance
Keywords Area
method
richardson extrap
convergence tolerance
Stopping criterion based on convergence of the objective function or statistics

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): REAL
Default: 1.e-4

1819

1820

CHAPTER 6. KEYWORDS AREA

Description
The convergence tolerance specification provides a real value for controlling the termination of iteration.
For optimization, it is most commonly a relative convergence tolerance for the objective function; i.e., if
the change in the objective function between successive iterations divided by the previous objective function is
less than the amount specified by convergence tolerance, then this convergence criterion is satisfied on the current
iteration.
Therefore, permissible values are between 0 and 1, non-inclusive.
Behavior Varies by Package/Library
This control is used with most optimization and least squares iterators (DOT, CONMIN, NPSOL, NLSSOL,
OPT++, and SCOLIB). Most other Dakota methods (such as DACE or parameter studies) do not use this control,
but some adaptive methods, such as adaptive UQ, do.
Since no progress may be made on one iteration followed by significant progress on a subsequent iteration,
some libraries require that the convergence tolerance be satisfied on two or more consecutive iterations prior to
termination of iteration.
Notes on each library:
DOT: must be satisfied for two consecutive iterations
NPSOL: defines an internal optimality tolerance which is used in evaluating if an iterate satisfies the firstorder Kuhn-Tucker conditions for a minimum. The magnitude of convergence tolerance approximately specifies the number of significant digits of accuracy desired in the final objective function (e.g.,
convergence tolerance = 1.e-6 will result in approximately six digits of accuracy in the final
objective function).
NL2SOL: See nl2sol
max iterations
Keywords Area
method
richardson extrap
max iterations
Stopping criterion based on number of iterations

Topics
This keyword is related to the topics:
method independent controls

Specification
Alias: none
Argument(s): INTEGER
Default: 100 (exceptions: fsu cvt , local reliability: 25; global {reliability , interval est , evidence} / efficientglobal: 25n)

6.2. METHOD

1821

Description
The maximum number of iterations (default: 100). See also max function evaluations.
model pointer
Keywords Area
method
richardson extrap
model pointer
Identifier for model block to be used by a method

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed (or use of default model if none parsed)

Description
The model pointer is used to specify which model block will be used to perform the function evaluations
needed by the Dakota method.
Default Behavior
If not specified, a Dakota method will use the last model block parsed. If specified, there must be a model
block in the Dakota input file that has a corresponding id model with the same name.
Usage Tips
When doing advanced analyses that involve using multiple methods and multiple models, defining a modelpointer for each method is imperative.
See block pointer for details about pointers.

Examples
environment
tabular_graphics_data
method_pointer = UQ
method
id_method = UQ
model_pointer = SURR
sampling,
samples = 10
seed = 98765 rng rnum2
response_levels = 0.1 0.2 0.6
0.1 0.2 0.6
0.1 0.2 0.6

1822

CHAPTER 6. KEYWORDS AREA

sample_type lhs
distribution cumulative
model
id_model = SURR
surrogate global,
dace_method_pointer = DACE
polynomial quadratic
method
id_method = DACE
model_pointer = DACE_M
sampling sample_type lhs
samples = 121 seed = 5034 rng rnum2
model
id_model = DACE_M
single
interface_pointer = I1
variables
uniform_uncertain = 2
lower_bounds = 0.
0.
upper_bounds = 1.
1.
descriptors = x1 x2
interface
id_interface = I1
system asynch evaluation_concurrency = 5
analysis_driver = text_book
responses
response_functions = 3
no_gradients
no_hessians

6.3

model

Keywords Area
model
Specifies how variables are mapped into a set of responses

Topics
This keyword is related to the topics:
block

Specification
Alias: none
Argument(s): none

6.3. MODEL

1823
Required/Optional
Optional

Description of
Group

Dakota Keyword
id model

Optional

variables pointer

Optional

responses pointer

Optional

hierarchical tagging

Required(Choose
One)

single
Group 1

surrogate

nested

Dakota Keyword
Description
Give the model
block an
identifying name,
in case of multiple
model blocks
Specify which
variables block
will be included
with this model
block
Specify which
reponses block will
be used by this
model block
Enables
hierarchical
evaluation tagging
A model with one
of each block:
variable, interface,
and response
An empirical
model that is
created from data
or the results of a
submodel
A model whose
responses are
computed through
the use of a
sub-iterator

Description
A model is comprised of a mapping from variables, through an interface, to responses.
Model Group 1 The type of model can be:
1. single
2. nested
3. surrogate
The input file must specify one of these types. If the type is not specified, Dakota will assume a single model.
Block Pointers and ID
Each of these model types supports variables pointer and responses pointer strings for identifying the variables and responses specifications used in constructing the model by cross-referencing with id variables and id responses strings from particular variables and responses keyword specifications.
These pointers are valid for each model type since each model contains a set of variables that is mapped into
a set of responses only the specifics of the mapping differ.

1824

CHAPTER 6. KEYWORDS AREA

Additional pointers are used for each model type for constructing the components of the variable to response
mapping. As an environment specification identifies a top-level method and a method specification identifies a
model, a model specification identifies variables, responses, and (for some types) interface specifications. This
top-down flow specifies all of the object interrelationships.

Examples
The next example displays a surrogate model specification which selects a quadratic polynomial from among the
global approximation methods. It uses a pointer to a design of experiments method for generating the data needed
for building the global approximation, reuses any old data available for the current approximation region, and
employs the first-order multiplicative approach to correcting the approximation each time correction is requested.
model,
id_model = M1
variables_pointer = V1
responses_pointer = R1
surrogate
global
polynomial quadratic
dace_method_pointer = DACE
reuse_samples region
correction multiplicative first_order

This example demonstrates the use of identifiers and pointers. It provides the optional model independent specifications for model identifier, variables pointer, and responses pointer as well as model dependent specifications
for global surrogates (see global).
Finally, an advanced nested model example would be
model
id_model = M1
variables_pointer = V1
responses_pointer = R1
nested
optional_interface_pointer = OI1
optional_interface_responses_pointer = OIR1
sub_method_pointer = SM1
primary_variable_mapping = X
Y
secondary_variable_mapping = mean mean
primary_response_mapping = 1. 0. 0. 0. 0. 0. 0. 0. 0.
secondary_response_mapping = 0. 0. 0. 1. 3. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0. 1. 3. 0.

This example also supplies model independent controls for model identifier, variables pointer, and responses
pointer and supplies model dependent controls for specifying details of the nested mapping.

6.3.1

id model

Keywords Area
model
id model
Give the model block an identifying name, in case of multiple model blocks

6.3. MODEL

1825

Topics
This keyword is related to the topics:
block identifier

Specification
Alias: none
Argument(s): STRING
Default: method use of last model parsed

Description
The model identifier string is supplied with id model and is used to provide a unique identifier string for use
within method specifications (refer to any of the keywords: model pointer in under one of the methods in the
method block, for example: model pointer)
This is used to determine which model the method will run.

See Also
These keywords may also be of interest:
model pointer

6.3.2

variables pointer

Keywords Area
model
variables pointer
Specify which variables block will be included with this model block

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: model use of last variables parsed

Description
The variables pointer is used to specify which variables block will be used by the model, by crossreferencing with id variables keyword in the variables block.
See block pointer for details about pointers.

1826

6.3.3

CHAPTER 6. KEYWORDS AREA

responses pointer

Keywords Area
model
responses pointer
Specify which reponses block will be used by this model block

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: model use of last responses parsed

Description
The responses pointer is used to specify which responses block will be used by the model, by crossreferencing with id responses keyword in the responses block.
See block pointer for details about pointers.

6.3.4

hierarchical tagging

Keywords Area
model
hierarchical tagging
Enables hierarchical evaluation tagging

Specification
Alias: none
Argument(s): none
Default: no hierarchical tagging

Description
The hierarchical tagging option is useful for studies involving multiple models with a nested or hierarchical relationship. For example a nested model has a sub-method, which itself likely operates on a sub-model, or a
hierarchical approximation involves coordination of low and high fidelity models. Specifying hierarchicaltagging will yield function evaluation identifiers (tags) composed of the evaluation IDs of the models involved, e.g., outermodel.innermodel.interfaceid = 4.9.2. This communicates the outer contexts to the analysis
driver when performing a function evaluation.

6.3. MODEL

1827

Examples
test/dakota uq timeseries ivp optinterf.in test/dakota uq timeseries sop optinterf.in

See Also
These keywords may also be of interest:
file tag model-nested

6.3.5

single

Keywords Area
model
single
A model with one of each block: variable, interface, and response

Specification
Alias: none
Argument(s): none
Default: N/A ( single if no model specification)
Required/Description of
Optional
Group
Optional

Dakota Keyword
interface pointer

Dakota Keyword
Description
Interface block
pointer for the
single model type

Description
The single model is the simplest model type. It uses a single interface instance to map variables into responses.
There is no recursion in this case.
The optional interface pointer specification identifies the interface block by cross-referencing with the id interface string input from a particular interface keyword specification. This is only necessary when the input
file has multiple interface blocks, and you wish to explicitly point to the desired block. The same logic follows
for responses and variables blocks and pointers.

Examples
The example shows a minimal specification for a single model, which is the default model when no models are
specified by the user.
model
single

This example does not provide any pointer strings and therefore relies on the default behavior of constructing the
model with the last variables, interface, and responses specifications parsed.

1828

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
surrogate
nested
interface pointer
Keywords Area
model
single
interface pointer
Interface block pointer for the single model type

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: model use of last interface parsed

Description
In the single model case, a single interface is used to map the variables into responses. The optional interfacepointer specification identifies this interface by cross-referencing with the id interface string input from
a particular interface keyword specification.
See block pointer for details about pointers.

6.3.6

surrogate

Keywords Area
model
surrogate
An empirical model that is created from data or the results of a submodel

Specification
Alias: none
Argument(s): none

6.3. MODEL

1829
Required/Optional
Optional

Description of
Group

Dakota Keyword
id surrogates

global
Required(Choose
One)

Group 1
multipoint

local

hierarchical

Dakota Keyword
Description
Identifies the
subset of the
response functions
by number that are
to be approximated
(the default is all
functions).
Select a surrogate
model with global
support
Construct a
surrogate from
multiple existing
training points
Build a locally
accurate surrogate
from data at a
single point
Hierarchical
approximations
use corrected
results from a low
fidelity model as
an approximation
to the results of a
high fidelity
truth model.

Description
Surrogate models are inexpensive approximate models that are intended to capture the salient features of an
expensive high-fidelity model. They can be used to explore the variations in response quantities over regions
of the parameter space, or they can serve as inexpensive stand-ins for optimization or uncertainty quantification
studies (see, for example, the surrogate-based optimization methods, surrogate based global and surrogate basedlocal).
Surrogate models supported in Dakota are categorized as Data Fitting or Hierarchical, as shown below. Each
of these surrogate types provides an approximate representation of a truth model which is used to perform the
parameter to response mappings. This approximation is built and updated using results from the truth model,
called the training data.
Data fits:
Data fitting methods involve construction of an approximation or surrogate model using data (response
values, gradients, and Hessians) generated from the original truth model. Data fit methods can be further
categorized as local, multipoint, and global approximation techniques, based on the number of points used
in generating the data fit.
1. Local: built from response data from a single point in parameter space
Taylor series expansion: taylor series

1830

CHAPTER 6. KEYWORDS AREA

Training data consists of a single point, plus gradient and Hessian information.
2. Multipoint: built from two or more points in parameter space, often involving the current and previous
iterates of a minimization algorithm.
TANA-3: tana
Training Data comes from a few previously evaluated points
3. Global full space response surface methods:

Polynomial regression: polynomial

Gaussian process (Kriging): gaussian process
Artifical neutral network: neural network
MARS: mars
Radial Basis Functions: radial basis
Orthogonal polynomials (only supported in PCE/SC for now): polynomial chaos and stoch collocation

Training data is generated using either a design of experiments method applied to the truth model (
specified by dace method pointer), or from saved data (specified by reuse points ) in a restart database,
or an import file.
Multifidelity/hierarchical:
Multifidelity modeling involves the use of a low-fidelity physics-based model as a surrogate for the original high-fidelity model. The low-fidelity model typically involves a coarser mesh, looser convergence
tolerances, reduced element order, or omitted physics.
See hierarchical.
The global and hierarchal surrogates have a correction feature in order to improve the local accuracy of the
surrogate models. The correction factors force the surrogate models to match the true function values and possibly
true function derivatives at the center point of each trust region. Details can be found on global correction or
hierarchical correction.

Theory
Surrogate models are used extensively in the surrogate-based optimization and least squares methods, in which
the goals are to reduce expense by minimizing the number of truth function evaluations and to smooth out noisy
data with a global data fit. However, the use of surrogate models is not restricted to optimization techniques;
uncertainty quantification and optimization under uncertainty methods are other primary users.
Data Fit Surrogate Models
A surrogate of the {data fit} type is a non-physics-based approximation typically involving interpolation or
regression of a set of data generated from the original model. Data fit surrogates can be further characterized by
the number of data points used in the fit, where a local approximation (e.g., first or second-order Taylor series)
uses data from a single point, a multipoint approximation (e.g., two-point exponential approximations (TPEA) or
two-point adaptive nonlinearity approximations (TANA)) uses a small number of data points often drawn from
the previous iterates of a particular algorithm, and a global approximation (e.g., polynomial response surfaces,
kriging/gaussian process, neural networks, radial basis functions, splines) uses a set of data points distributed over
the domain of interest, often generated using a design of computer experiments.
Dakota contains several types of surface fitting methods that can be used with optimization and uncertainty
quantification methods and strategies such as surrogate-based optimization and optimization under uncertainty.
These are: polynomial models (linear, quadratic, and cubic), first-order Taylor series expansion, kriging spatial interpolation, artificial neural networks, multivariate adaptive regression splines, radial basis functions, and moving

6.3. MODEL

1831

least squares. With the exception of Taylor series methods, all of the above methods listed in the previous sentence are accessed in Dakota through the Surfpack library. All of these surface fitting methods can be applied to
problems having an arbitrary number of design parameters. However, surface fitting methods usually are practical
only for problems where there are a small number of parameters (e.g., a maximum of somewhere in the range of
30-50 design parameters). The mathematical models created by surface fitting methods have a variety of names in
the engineering community. These include surrogate models, meta-models, approximation models, and response
surfaces. For this manual, the terms surface fit model and surrogate model are used.
The data fitting methods in Dakota include software developed by Sandia researchers and by various researchers in the academic community.
Multifidelity Surrogate Models
A second type of surrogate is the {model hierarchy} type (also called multifidelity, variable fidelity, variable
complexity, etc.). In this case, a model that is still physics-based but is of lower fidelity (e.g., coarser discretization,
reduced element order, looser convergence tolerances, omitted physics) is used as the surrogate in place of the
high-fidelity model. For example, an inviscid, incompressible Euler CFD model on a coarse discretization could
be used as a low-fidelity surrogate for a high-fidelity Navier-Stokes model on a fine discretization.
Surrogate Model Selection
This section offers some guidance on choosing from among the available surrogate model types.
For Surrogate Based Local Optimization, using the surrogate based local method with a trust region:
using the keywords:
1. surrogate local taylor series or
2. surrogate multipoint tana
will probably work best.
If for some reason you wish or need to use a global surrogate (not recommended) then the best of these
options is likely to be either:
1. surrogate global gaussian process surfpack or
2. surrogate global moving least squares.
For Efficient Global Optimization (EGO), the efficient global method:
the default surrogate is: gaussian process surfpack which is likely to find a more optimal value and/or
require fewer true function evaluations than the alternative, gaussian process dakota. However, the surfpack will likely take more time to build than the dakota version. Note that currently the use derivatives
keyword is not recommended for use with EGO based methods.
For EGO based global interval estimation, the global interval est ego method:
the default gaussian process surfpack will likely work better than the alternative gaussian process dakota.
For Efficient Global Reliability Analysis (EGRA), the global reliability method:
the surfpack and dakota versions of the gaussian process tend to give similar answers with the dakota
version tending to use fewer true function evaluations. Since this is based on EGO, it is likely that the
default surfpack is more accurate, although this has not been rigorously demonstrated.
For EGO based Dempster-Shafer Theory of Evidence, i.e. the global evidence ego method, the default
gaussian process surfpack often use significantly fewer true function evaluations than the alternative gaussianprocess dakota.
When using a global surrogate to extrapolate, any of the surrogates:

1832

CHAPTER 6. KEYWORDS AREA

gaussian process surfpack
polynomial quadratic
polynomial cubic
are recommended.

When there is over roughly two or three thousand data points and you wish to interpolate (or approximately interpolate) then a Taylor series, Radial Basis Function Network, or Moving Least Squares fit is
recommended. The only reason that the gaussian process surfpack is not recommended is that it can take
a considerable amount of time to construct when the number of data points is very large. Use of the third
party MARS package included in Dakota is generally discouraged.
In other situations that call for a global surrogate, the gaussian process surfpack is generally recommended.
The use derivatives keyword will only be useful if accurate and inexpensive derivatives are available.
Finite difference derivatives are disqualified on both counts. However, derivatives generated by analytical,
automatic differentiation, or continuous adjoint techniques can be appropriate. Currently, first order derivatives, i.e. gradients, are the highest order derivatives that can be used to construct the gaussian process
surfpack model; Hessians will not be used even if they are available.

See Also
These keywords may also be of interest:
single
nested
id surrogates
Keywords Area
model
surrogate
id surrogates
Identifies the subset of the response functions by number that are to be approximated (the default is all functions).

Specification
Alias: none
Argument(s): INTEGERLIST
Default: All response functions are approximated

Description
In the surrogate model case, the specification first allows a mixture of surrogate and actual response mappings
through the use of the optional id surrogates specification. This identifies the subset of the response functions by number that are to be approximated (the default is all functions). The valid response function identifiers
range from 1 through the total number of response functions (see response functions).

6.3. MODEL

1833

global
Keywords Area
model
surrogate
global
Select a surrogate model with global support

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword
gaussian process

Required(Choose
One)

Optional

Group 1

Dakota Keyword
Description
Gaussian Process
surrogate model

mars

Multivariate
Adaptive
Regression Spline
(MARS)

moving least squares

Moving Least
Squares surrogate
models

neural network

Artificial neural
network model

radial basis

Radial basis
function (RBF)
model

polynomial

Polynomial
surrogate model

domain decomposition

Piecewise Domain
Decomposition for
Global Surrogate
Models

1834

CHAPTER 6. KEYWORDS AREA

Optional(Choose
One)

Optional(Choose
One)

total points

Specified number
of training points

minimum points

Construct
surrogate with
minimum number
of points

recommended points

Construct
surrogate with
recommended
number of points

dace method pointer

Specify a method
to gather training
data
A surrogate model
pointer that guides
a method to
whether it should
use a surrogate
model or compute
truth function
evaluations

Group 2

Group 3

actual model pointer

Optional

reuse points

Surrogate model
training data reuse
control

Optional

import build points file

File containing
points you wish to
use to build a
surrogate

Optional

export approx points file

Output file for

evaluations of a
surrogate model

Optional

use derivatives

Use derivative data

to construct
surrogate models

6.3. MODEL

1835
Optional

correction

Optional

metrics

Optional

import challenge points file

Correction
approaches for
surrogate models
Compute surrogate
quality metrics
Datafile of points
to assess surrogate
quality

Description
The global surrogate model requires specification of one of the following approximation types:
1. Polynomial
2. Gaussian process (Kriging interpolation)
3. Layered perceptron artificial neural network approximation
4. MARS
5. Moving least squares
6. Radial basis function
7. Voronoi Piecewise Surrogate (VPS)
All these approximations are implemented in SurfPack[36], except for VPS. In addition, a second version of
Gaussian process is implemented directly in Dakota.
Training Data
Training data can be taken from prior runs, stored in a datafile, or by running a Design of Experiments method.
The keywords listed below are used to determine how to collect training data:
dace method pointer
reuse points
import points file
use derivatives The source of training data is determined by the contents of a provided import points file, whether reuse points and use derivatives are specified, and the contents of the
method block specified by dace method pointer. use derivatives is a special case, the other
keywords are discussed below.
The number of training data points used in building a global approximation is determined by specifying one of
three point counts:
1. minimum points: minimum required or minimum reasonable amount of training data. Defaults
to d+1 for d input dimensions for most models, e.g., polynomials override to the number of coefficients
required to estimate the requested order.
2. recommended points: recommended number of training data, (this is the default option, if none of
the keywords is specified). Defaults to 5d, except for polynomials where its equal to the minimum.

1836

CHAPTER 6. KEYWORDS AREA

3. total points: specify the number of training data points. However, if the total points value is
less than the default minimum points value, the minimum points value is used.
The sources of training data depend on the number of training points, Ntp , the number of points in the import
file, Nif , and the value of reuse points.
If there is no import file, all training data come from the DACE method
If there is an import file, all Nif points from the file are used, and the remaining Ntp Nif points come
from the DACE method
If there is an import file and reuse points is:
none - all Ntp points from DACE method
region - only the points within a trust region are taken from the import file, and all remaining points
are from the DACE method.
all - (Default) all Nif points from the file are used, and the remaining Ntp Nif points come from
the DACE method
Surrogate Correction
A correction model can be added to the constructed surrogate in order to better match the training data.
The specified correction method will be applied to the surrogate, and then the corrected surrogate model is used
by the method.
Finally, the quality of the surrogate can be tested using the metrics and challenge points file
keywords.

Theory
Global methods, also referred to as response surface methods, involve many points spread over the parameter
ranges of interest. These surface fitting methods work in conjunction with the sampling methods and design of
experiments methods.
Procedures for Surface Fitting
The surface fitting process consists of three steps:
1. selection of a set of design points
2. evaluation of the true response quantities (e.g., from a user-supplied simulation code) at these design points,
3. using the response data to solve for the unknown coefficients (e.g., polynomial coefficients, neural network
weights, kriging correlation factors) in the surface fit model.
In cases where there is more than one response quantity (e.g., an objective function plus one or more constraints),
then a separate surface is built for each response quantity. Currently, the surface fit models are built using only 0
th
-order information (function values only), although extensions to using higher-order information (gradients and
Hessians) are possible.
Each surface fitting method employs a different numerical method for computing its internal coefficients.
For example, the polynomial surface uses a least-squares approach that employs a singular value decomposition
to compute the polynomial coefficients, whereas the kriging surface uses Maximum Likelihood Estimation to
compute its correlation coefficients. More information on the numerical methods used in the surface fitting codes
is provided in the Dakota Developers Manual.

6.3. MODEL

1837

See Also
These keywords may also be of interest:
local
hierarchical
multipoint
gaussian process
Keywords Area
model
surrogate
global
gaussian process
Gaussian Process surrogate model

Specification
Alias: kriging
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
dakota

surfpack

Dakota Keyword
Description
Select the built in
Gaussian Process
surrogate
Use the Surfpack
version of
Gaussian Process
surrogates

Description
Use the Gaussian process (GP) surrogate from Surfpack, which is specified using the surfpack keyword.
An alternate version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
dakota
Keywords Area
model
surrogate
global
gaussian process
dakota
Select the built in Gaussian Process surrogate

1838

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
point selection

trend

Dakota Keyword
Description
Enable greedy
selection of
well-spaced build
points
Choose a trend
function for a
Gaussian process
surrogate

Description
A second version of GP surrogates was available in prior versions of Dakota. For now, both versions are
supported but the dakota version is deprecated and intended to be removed in a future release.
Historically these models were drastically different, but in Dakota 5.1, they became quite similar. They now
differ in that the Surfpack GP has a richer set of features/options and tends to be more accurate than the Dakota
version. Due to how the Surfpack GP handles ill-conditioned correlation matrices (which significantly contributes
to its greater accuracy), the Surfpack GP can be a factor of two or three slower than Dakotas. As of Dakota
5.2, the Surfpack implementation is the default in all contexts except Bayesian calibration.
More details on the gaussian process dakota model can be found in[58].
Dakotas GP deals with ill-conditioning in two ways. First, when it encounters a non-invertible correlation
matrix it iteratively increases the size of a nugget, but in such cases the resulting approximation smooths rather
than interpolates the data. Second, it has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
This differs from the point selection option of the Dakota GP which initially chooses a well-spaced
subset of points and finds the correlation parameters that are most likely for that one subset.
point selection
Keywords Area
model
surrogate
global
gaussian process
dakota
point selection
Enable greedy selection of well-spaced build points

6.3. MODEL

1839

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Default: no point selection

Description
The Dakota Gaussian Process model has a point selection option (default off) that uses a greedy algorithm
to select a well-spaced subset of points prior to the construction of the GP. In this case, the GP will only interpolate the selected subset. Typically, one should not need point selection in trust-region methods because a small
number of points are used to develop a surrogate within each trust region. Point selection is most beneficial when
constructing with a large number of points, typically more than order one hundred, though this depends on the
number of variables and spacing of the sample points.
trend
Keywords Area
model
surrogate
global
gaussian process
dakota
trend
Choose a trend function for a Gaussian process surrogate

Specification
Alias: none
Argument(s): none
Default: reduced quadratic
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
constant

Group 1

Dakota Keyword
Description
Constant trend
function

1840

CHAPTER 6. KEYWORDS AREA

linear

Use a linear
polynomial or
trend function

reduced quadratic

Quadratic
polynomials - main
effects only

Description
The only trend functions that are currently supported are polynomials.
The trend function is selected using the trend keyword, with options constant, linear, or reducedquadratic. The reduced quadratic trend function includes the main effects, but not mixed/interaction
terms. The Surfpack GP (See surfpack) has the additional option of (a full) quadratic.
constant
Keywords Area
model
surrogate
global
gaussian process
dakota
trend
constant
Constant trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
linear
Keywords Area
model
surrogate
global

6.3. MODEL
gaussian process
dakota
trend
linear
Use a linear polynomial or trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
reduced quadratic
Keywords Area
model
surrogate
global
gaussian process
dakota
trend
reduced quadratic
Quadratic polynomials - main effects only

Specification
Alias: none
Argument(s): none

Description
In 2 or more dimensions, this polynomial omits the interaction, or mixed, terms.

1841

1842

CHAPTER 6. KEYWORDS AREA

surfpack
Keywords Area
model
surrogate
global
gaussian process
surfpack
Use the Surfpack version of Gaussian Process surrogates

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
trend

Optional

optimization method

Optional

max trials

Optional(Choose
One)

Group 1

nugget

find nugget

Optional

correlation lengths

Dakota Keyword
Description
Choose a trend
function for a
Gaussian process
surrogate
Change the
optimization
method used to
compute
hyperparameters
Max number of
likelihood function
evaluations
Specify a nugget to
handle
ill-conditioning
Have Surfpack
compute a nugget
to handle
ill-conditioning
Specify the
correlation lengths
for the Gaussian
process

6.3. MODEL

1843
Optional

export model

Exports surrogate
model in
user-selected
format

Description
This keyword specifies the use of the Gaussian process that is incorporated in our surface fitting library called
Surfpack.
Several user options are available:
1. Optimization methods:
Maximum Likelihood Estimation (MLE) is used to find the optimal values of the hyper-parameters governing the trend and correlation functions. By default the global optimization method DIRECT is used for
MLE, but other options for the optimization method are available. See optimization method.
The total number of evaluations of the likelihood function can be controlled using the max trials keyword followed by a positive integer. Note that the likelihood function does not require running the truth
model, and is relatively inexpensive to compute.
2. Trend Function:
The GP models incorporate a parametric trend function whose purpose is to capture large-scale variations.
See trend.
3. Correlation Lengths:
Correlation lengths are usually optimized by Surfpack, however, the user can specify the lengths manually.
See correlation lengths.
4. Ill-conditioning
One of the major problems in determining the governing values for a Gaussian process or Kriging model is
the fact that the correlation matrix can easily become ill-conditioned when there are too many input points
close together. Since the predictions from the Gaussian process model involve inverting the correlation
matrix, ill-conditioning can lead to poor predictive capability and should be avoided.
Note that a sufficiently bad sample design could require correlation lengths to be so short that any interpolatory GP model would become inept at extrapolation and interpolation.
The surfpack model handles ill-conditioning internally by default, but behavior can be modified using
5. Gradient Enhanced Kriging (GEK).
The use derivatives keyword will cause the Surfpack GP to be constructed from a combination of
function value and gradient information (if available).
See notes in the Theory section.

Theory
Gradient Enhanced Kriging
Incorporating gradient information will only be beneficial if accurate and inexpensive derivative information
is available, and the derivatives are not infinite or nearly so. Here inexpensive means that the cost of evaluating a
function value plus gradient is comparable to the cost of evaluating only the function value, for example gradients
computed by analytical, automatic differentiation, or continuous adjoint techniques. It is not cost effective to use

1844

CHAPTER 6. KEYWORDS AREA

derivatives computed by finite differences. In tests, GEK models built from finite difference derivatives were also
significantly less accurate than those built from analytical derivatives. Note that GEKs correlation matrix tends
to have a significantly worse condition number than Kriging for the same sample design.
This issue was addressed by using a pivoted Cholesky factorization of Krigings correlation matrix (which is a
small sub-matrix within GEKs correlation matrix) to rank points by how much unique information they contain.
This reordering is then applied to whole points (the function value at a point immediately followed by gradient
information at the same point) in GEKs correlation matrix. A standard non-pivoted Cholesky is then applied to the
reordered GEK correlation matrix and a bisection search is used to find the last equation that meets the constraint
on the (estimate of) condition number. The cost of performing pivoted Cholesky on Krigings correlation matrix
is usually negligible compared to the cost of the non-pivoted Cholesky factorization of GEKs correlation matrix.
In tests, it also resulted in more accurate GEK models than when pivoted Cholesky or whole-point-block pivoted
Cholesky was performed on GEKs correlation matrix.
trend
Keywords Area
model
surrogate
global
gaussian process
surfpack
trend
Choose a trend function for a Gaussian process surrogate

Specification
Alias: none
Argument(s): none
Default: reduced quadratic
Required/Optional

Description of
Group

Dakota Keyword
constant

Required(Choose
One)

Group 1
linear

Dakota Keyword
Description
Constant trend
function
Use a linear
polynomial or
trend function

6.3. MODEL

1845
reduced quadratic

Quadratic
polynomials - main
effects only

quadratic

Use a quadratic
polynomial or
trend function

Description
The only trend functions that are currently supported are polynomials.
The trend function is selected using the trend keyword, with options constant, linear, or reducedquadratic. The reduced quadratic trend function includes the main effects, but not mixed/interaction
terms. The Surfpack GP (See surfpack) has the additional option of (a full) quadratic.
constant
Keywords Area
model
surrogate
global
gaussian process
surfpack
trend
constant
Constant trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
linear
Keywords Area
model
surrogate
global

1846

CHAPTER 6. KEYWORDS AREA

gaussian process
surfpack
trend
linear
Use a linear polynomial or trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
reduced quadratic
Keywords Area
model
surrogate
global
gaussian process
surfpack
trend
reduced quadratic
Quadratic polynomials - main effects only

Specification
Alias: none
Argument(s): none

Description
In 2 or more dimensions, this polynomial omits the interaction, or mixed, terms.

6.3. MODEL
quadratic
Keywords Area
model
surrogate
global
gaussian process
surfpack
trend
quadratic
Use a quadratic polynomial or trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
optimization method
Keywords Area
model
surrogate
global
gaussian process
surfpack
optimization method
Change the optimization method used to compute hyperparameters

Specification
Alias: none
Argument(s): STRING
Default: global

1847

1848

CHAPTER 6. KEYWORDS AREA

Description
Select the optimization method to compute hyperparameters of the Gaussian Process by specifying one of these
arguments:
global (default) - DIRECT method
local - CONMIN method
sampling - generates several random guesses and picks the candidate with greatest likelihood
none - no optimization, pick the center of the feasible region
The none option, and the starting location of the local optimization, default to the center, in log(correlation
length) scale, of the of feasible region.
Surfpack picks a small feasible region of correlation parameters.
Note that we have found the global optimization method to be the most robust.
max trials
Keywords Area
model
surrogate
global
gaussian process
surfpack
max trials
Max number of likelihood function evaluations

Specification
Alias: none
Argument(s): INTEGER

Description
See parent page
nugget
Keywords Area
model
surrogate
global
gaussian process

6.3. MODEL

1849

surfpack
nugget
Specify a nugget to handle ill-conditioning

Specification
Alias: none
Argument(s): REAL
Default: None

Description
By default, the Surfpack GP handles ill-conditioning and does not use a nugget. If the user wishes to specify a
nugget, there are two approaches.
The user can specify the value of a nugget with nugget.
Have Surfpack find the optimal value of the nugget. This is specified by find nugget. There are two options
for find nugget.
find nugget = 1: assume that the reciprocal condition number of the correlation matrix R, rcondR,
is zero and calculate the nugget needed to make the worst case of R not ill-conditioned.
find nugget = 2: calculate rcondR, which requires a Cholesky factorization. If rcondR indicates
that R is not ill-conditioned, then kriging uses the Cholesky factorization. Otherwise, if rcondR says
R is ill conditioned, then kriging will calculate the nugget needed to make the worst case of R not ill
conditioned.
find nugget = 1 and 2 are similar, the second option just takes more computation (the initial Cholesky
factorization) for larger problems.
find nugget
Keywords Area
model
surrogate
global
gaussian process
surfpack
find nugget
Have Surfpack compute a nugget to handle ill-conditioning

Specification
Alias: none
Argument(s): INTEGER
Default: None

1850

CHAPTER 6. KEYWORDS AREA

Description
By default, the Surfpack GP handles ill-conditioning and does not use a nugget. If the user wishes to specify a
nugget, there are two approaches.
The user can specify the value of a nugget with nugget.
Have Surfpack find the optimal value of the nugget. This is specified by find nugget. There are two options
for find nugget.
find nugget = 1: assume that the reciprocal condition number of the correlation matrix R, rcondR,
is zero and calculate the nugget needed to make the worst case of R not ill-conditioned.
find nugget = 2: calculate rcondR, which requires a Cholesky factorization. If rcondR indicates
that R is not ill-conditioned, then kriging uses the Cholesky factorization. Otherwise, if rcondR says
R is ill conditioned, then kriging will calculate the nugget needed to make the worst case of R not ill
conditioned.
find nugget = 1 and 2 are similar, the second option just takes more computation (the initial Cholesky
factorization) for larger problems.
correlation lengths
Keywords Area
model
surrogate
global
gaussian process
surfpack
correlation lengths
Specify the correlation lengths for the Gaussian process

Specification
Alias: none
Argument(s): REALLIST
Default: internally computed correlation lengths

Description
Directly specify correlation lengths as a list of N real numbers where N is the number of input dimensions.

6.3. MODEL

1851

export model
Keywords Area
model
surrogate
global
gaussian process
surfpack
export model
Exports surrogate model in user-selected format

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Required

Description of
Group

Dakota Keyword
filename prefix

formats

Dakota Keyword
Description
User-customizable
portion of exported
model filenames
Formats for
surrogate model
export

Description
Export the surrogate for later evaluation using the surfpack exectuable (bin/surfpack) or a user-developed
tool. Export format is controlled using the formats specification. Four formats are available in Dakota; however,
not all have been enabled for all surrogates.
The four formats are:
text archive - Plain-text, machine-readable archive for use with the surfpack executable
binary archive - Binary, machine-readable archive for use with the surfpack executable
algebraic file - Plain-text, human-readable file intended for use with user-created tools; not compatible with the surfpack executable
algebraic console - Print the model in algebraic format to the screen; not compatible with the surfpack executable

1852

CHAPTER 6. KEYWORDS AREA

Most global surrogates can be exported in all four formats. These include:
Gaussian process (keyword gaussian process surfpack)
Artificial neural network (keyword neural network)
Radial basis Funtions (keyword radial basis)
Polynomial (keyword polynomial)
However, for Multivariate Adaptive Regression Spline (keyword mars) and moving least squares (keyword
moving least squares) models, only text archive and binary archive formats may be used.
Currently, no other surrogate models can be exported. In addition, Dakota cannot import models that have
been exported. They are strictly for use with external tools.
Default Behavior
No export.
Expected Output
Output depends on selected format; see the formats specification.
Additional Discussion
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
filename prefix
Keywords Area
model
surrogate
global
gaussian process
surfpack
export model
filename prefix
User-customizable portion of exported model filenames

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): STRING
Default: exported surrogate

6.3. MODEL

1853

Description
When a file-based export of a surrogate model is specified, Dakota writes one file per response, per requested
format. The files are named using the pattern {prefix}.{response descriptor}.{extension}.
The response descriptor portion of the pattern is filled in using the response descriptors provided by
the user (or, if none are specified, descriptors automatically generated by Dakota). Extension is a three or four
letter string that depends on the format. The filename prefix keyword is used to supply the prefix portion
of the pattern.

Examples
This input snippet directs Dakota to write one algebraic format file and one binary archive file for each response.
The names of the files will follow the patterns my surrogate.{response descriptor}.alg (for the algebraic files)
and my surrogate.{response descriptor}.bsps (for the binary files).
surrogate global gaussian_process surfpack
export_model
filename_prefix = my_surrogate
formats
algebraic_file
binary_archive

formats
Keywords Area
model
surrogate
global
gaussian process
surfpack
export model
formats
Formats for surrogate model export

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

1854

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
text archive

Optional

binary archive

Optional

algebraic file

Optional

algebraic console

Dakota Keyword
Description
Export surrogate
model to a
plain-text archive
file
Export surrogate
model to a binary
archive file
Export surrogate
model in algebraic
format to a file
Export surrogate
model in algebraic
format to the
console

Description
Select from among the 2-4 available export formats available for this surrogate. Multiple selections are permitted.
See export model and the entries for the format selection keywords for further information.
text archive
Keywords Area
model
surrogate
global
gaussian process
surfpack
export model
formats
text archive
Export surrogate model to a plain-text archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

6.3. MODEL

1855

Description
After the surrogate model has been built, Dakota will export it to a plain-text archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.sps, in which sps stands for Surfpack Surrogate. See filename prefix for further information
about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
binary archive
Keywords Area
model
surrogate
global
gaussian process
surfpack
export model
formats
binary archive
Export surrogate model to a binary archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a binary archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.bsps, in which bsps stands for Binary Surfpack Surrogate. See filename prefix for further
information about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.

1856

CHAPTER 6. KEYWORDS AREA

algebraic file
Keywords Area
model
surrogate
global
gaussian process
surfpack
export model
formats
algebraic file
Export surrogate model in algebraic format to a file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a file in a human-readable algebraic format. The file is named using the pattern {prefix}.{response descriptor}.alg. See filename prefix for
further information about exported surrogate file naming. The file contains sufficient information for the user to
(re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the file matches exactly the output written to the console when algebraic console
is specified.
algebraic console
Keywords Area
model
surrogate
global

6.3. MODEL

1857

gaussian process
surfpack
export model
formats
algebraic console
Export surrogate model in algebraic format to the console

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to the console (screen, or output file if Dakota was
run using the -o option) in a human-readable algebraic format. The output contains sufficient information for
the user to (re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the screen for the exported model matches exactly the output written to file when
algebraic file is specified. Use of algebraic file is preferred over algebraic console, which
exists largely to provide a measure of backward compatibility.
mars
Keywords Area
model
surrogate
global
mars
Multivariate Adaptive Regression Spline (MARS)

Specification
Alias: none
Argument(s): none

1858

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
max bases

Dakota Keyword
Description
Maximum number
of MARS bases

Optional

interpolation

MARS model
interpolation type

Optional

export model

Exports surrogate
model in
user-selected
format

Description
This surface fitting method uses multivariate adaptive regression splines from the MARS3.5 package[27] developed at Stanford University.
The MARS reference material does not indicate the minimum number of data points that are needed to create
a MARS surface model. However, in practice it has been found that at least ncquad , and sometimes as many as 2
to 4 times ncquad , data points are needed to keep the MARS software from terminating. Provided that sufficient
data samples can be obtained, MARS surface models can be useful in SBO and OUU applications, as well as in
the prediction of global trends throughout the parameter space.

Theory
The form of the MARS model is based on the following expression:
f(x) =

M
X

am Bm (x)

m=1

where the am are the coefficients of the truncated power basis functions Bm , and M is the number of basis
functions. The MARS software partitions the parameter space into subregions, and then applies forward and
backward regression methods to create a local surface model in each subregion. The result is that each subregion
contains its own basis functions and coefficients, and the subregions are joined together to produce a smooth,
C 2 -continuous surface model.
MARS is a nonparametric surface fitting method and can represent complex multimodal data trends. The regression component of MARS generates a surface model that is not guaranteed to pass through all of the response
data values. Thus, like the quadratic polynomial model, it provides some smoothing of the data.
max bases
Keywords Area
model
surrogate
global
mars

6.3. MODEL

1859

max bases
Maximum number of MARS bases

Specification
Alias: none
Argument(s): INTEGER

Description
The maximum number of basis functions allowed in the MARS approximation model.
interpolation
Keywords Area
model
surrogate
global
mars
interpolation
MARS model interpolation type

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
linear

cubic

Description
The MARS model interpolation type: linear or cubic.
linear
Keywords Area
model
surrogate
global

Dakota Keyword
Description
Linear
interpolation
Cubic interpolation

1860
mars
interpolation
linear
Linear interpolation

Specification
Alias: none
Argument(s): none

Description
Use linear interpolation in the MARS model.
cubic
Keywords Area
model
surrogate
global
mars
interpolation
cubic
Cubic interpolation

Specification
Alias: none
Argument(s): none

Description
Use cubic interpolation in the MARS model.
export model
Keywords Area
model
surrogate
global
mars
export model
Exports surrogate model in user-selected format

CHAPTER 6. KEYWORDS AREA

6.3. MODEL

1861

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Required

Dakota Keyword
filename prefix

formats

Dakota Keyword
Description
User-customizable
portion of exported
model filenames
Formats for
surrogate model
export

Description
Export the surrogate for later evaluation using the surfpack exectuable (bin/surfpack) or a user-developed
tool. Export format is controlled using the formats specification. Four formats are available in Dakota; however,
not all have been enabled for all surrogates.
The four formats are:
text archive - Plain-text, machine-readable archive for use with the surfpack executable
binary archive - Binary, machine-readable archive for use with the surfpack executable
algebraic file - Plain-text, human-readable file intended for use with user-created tools; not compatible with the surfpack executable
algebraic console - Print the model in algebraic format to the screen; not compatible with the surfpack executable
Most global surrogates can be exported in all four formats. These include:
Gaussian process (keyword gaussian process surfpack)
Artificial neural network (keyword neural network)
Radial basis Funtions (keyword radial basis)
Polynomial (keyword polynomial)
However, for Multivariate Adaptive Regression Spline (keyword mars) and moving least squares (keyword
moving least squares) models, only text archive and binary archive formats may be used.
Currently, no other surrogate models can be exported. In addition, Dakota cannot import models that have
been exported. They are strictly for use with external tools.
Default Behavior
No export.
Expected Output

1862

CHAPTER 6. KEYWORDS AREA

Output depends on selected format; see the formats specification.

Additional Discussion
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
filename prefix
Keywords Area
model
surrogate
global
mars
export model
filename prefix
User-customizable portion of exported model filenames

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): STRING
Default: exported surrogate

Description
When a file-based export of a surrogate model is specified, Dakota writes one file per response, per requested
format. The files are named using the pattern {prefix}.{response descriptor}.{extension}.
The response descriptor portion of the pattern is filled in using the response descriptors provided by
the user (or, if none are specified, descriptors automatically generated by Dakota). Extension is a three or four
letter string that depends on the format. The filename prefix keyword is used to supply the prefix portion
of the pattern.

Examples
This input snippet directs Dakota to write one algebraic format file and one binary archive file for each response.
The names of the files will follow the patterns my surrogate.{response descriptor}.alg (for the algebraic files)
and my surrogate.{response descriptor}.bsps (for the binary files).
surrogate global gaussian_process surfpack
export_model
filename_prefix = my_surrogate
formats
algebraic_file
binary_archive

6.3. MODEL

1863

formats
Keywords Area
model
surrogate
global
mars
export model
formats
Formats for surrogate model export

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
text archive

binary archive

Dakota Keyword
Description
Export surrogate
model to a
plain-text archive
file
Export surrogate
model to a binary
archive file

Description
Select from among the 2-4 available export formats available for this surrogate. Multiple selections are permitted.
See export model and the entries for the format selection keywords for further information.
text archive
Keywords Area
model
surrogate
global
mars

1864

CHAPTER 6. KEYWORDS AREA

export model
formats
text archive
Export surrogate model to a plain-text archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a plain-text archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.sps, in which sps stands for Surfpack Surrogate. See filename prefix for further information
about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
binary archive
Keywords Area
model
surrogate
global
mars
export model
formats
binary archive
Export surrogate model to a binary archive file

Topics
This keyword is related to the topics:
surrogate models

6.3. MODEL

1865

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a binary archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.bsps, in which bsps stands for Binary Surfpack Surrogate. See filename prefix for further
information about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
moving least squares
Keywords Area
model
surrogate
global
moving least squares
Moving Least Squares surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
basis order

Dakota Keyword
Description
Polynomial order
for the MLS bases

Optional

weight function

Selects the weight

function for the
MLS model

Optional

export model

Exports surrogate
model in
user-selected
format

Description
Moving least squares is a further generalization of weighted least squares where the weighting is moved or
recalculated for every new point where a prediction is desired[64].

1866

CHAPTER 6. KEYWORDS AREA

The implementation of moving least squares is still under development. It tends to work well in trust
region optimization methods where the surrogate model is constructed in a constrained region over a few points.
The present implementation may not work as well globally.

Theory
Moving Least Squares can be considered a more specialized version of linear regression models. In linear regression, one usually attempts to minimize the sum of the squared residuals, where the residual is defined as the
difference between the surrogate model and the true model at a fixed number of points.
In weighted least squares, the residual terms are weighted so the determination of the optimal coefficients
governing the polynomial regression function, denoted by f(x), are obtained by minimizing the weighted sum of
squares at N data points:
N
X

wn (k f(xn ) f (xn ) k)

n=1

basis order
Keywords Area
model
surrogate
global
moving least squares
basis order
Polynomial order for the MLS bases

Specification
Alias: poly order
Argument(s): INTEGER

Description
The polynomial order for the moving least squares basis function (default = 2).
weight function
Keywords Area
model
surrogate
global
moving least squares
weight function
Selects the weight function for the MLS model

6.3. MODEL

1867

Specification
Alias: none
Argument(s): INTEGER

Description
The weight function decays as a function of distance from the training data. Specify one of:
1 (default): exponential decay in weight function; once differentiable MLS model
2: twice differentiable MLS model
3: three times differentiable MLS model
export model
Keywords Area
model
surrogate
global
moving least squares
export model
Exports surrogate model in user-selected format

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
filename prefix

Dakota Keyword
Description
User-customizable
portion of exported
model filenames

1868

CHAPTER 6. KEYWORDS AREA

Required

formats

Formats for
surrogate model
export

Description
Export the surrogate for later evaluation using the surfpack exectuable (bin/surfpack) or a user-developed
tool. Export format is controlled using the formats specification. Four formats are available in Dakota; however,
not all have been enabled for all surrogates.
The four formats are:
text archive - Plain-text, machine-readable archive for use with the surfpack executable
binary archive - Binary, machine-readable archive for use with the surfpack executable
algebraic file - Plain-text, human-readable file intended for use with user-created tools; not compatible with the surfpack executable
algebraic console - Print the model in algebraic format to the screen; not compatible with the surfpack executable
Most global surrogates can be exported in all four formats. These include:
Gaussian process (keyword gaussian process surfpack)
Artificial neural network (keyword neural network)
Radial basis Funtions (keyword radial basis)
Polynomial (keyword polynomial)
However, for Multivariate Adaptive Regression Spline (keyword mars) and moving least squares (keyword
moving least squares) models, only text archive and binary archive formats may be used.
Currently, no other surrogate models can be exported. In addition, Dakota cannot import models that have
been exported. They are strictly for use with external tools.
Default Behavior
No export.
Expected Output
Output depends on selected format; see the formats specification.
Additional Discussion
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
filename prefix
Keywords Area
model
surrogate
global
moving least squares
export model
filename prefix
User-customizable portion of exported model filenames

6.3. MODEL

1869

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): STRING
Default: exported surrogate

Description
When a file-based export of a surrogate model is specified, Dakota writes one file per response, per requested
format. The files are named using the pattern {prefix}.{response descriptor}.{extension}.
The response descriptor portion of the pattern is filled in using the response descriptors provided by
the user (or, if none are specified, descriptors automatically generated by Dakota). Extension is a three or four
letter string that depends on the format. The filename prefix keyword is used to supply the prefix portion
of the pattern.

Examples
This input snippet directs Dakota to write one algebraic format file and one binary archive file for each response.
The names of the files will follow the patterns my surrogate.{response descriptor}.alg (for the algebraic files)
and my surrogate.{response descriptor}.bsps (for the binary files).
surrogate global gaussian_process surfpack
export_model
filename_prefix = my_surrogate
formats
algebraic_file
binary_archive

formats
Keywords Area
model
surrogate
global
moving least squares
export model
formats
Formats for surrogate model export

1870

CHAPTER 6. KEYWORDS AREA

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
text archive

binary archive

Dakota Keyword
Description
Export surrogate
model to a
plain-text archive
file
Export surrogate
model to a binary
archive file

Description
Select from among the 2-4 available export formats available for this surrogate. Multiple selections are permitted.
See export model and the entries for the format selection keywords for further information.
text archive
Keywords Area
model
surrogate
global
moving least squares
export model
formats
text archive
Export surrogate model to a plain-text archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

6.3. MODEL

1871

Description
After the surrogate model has been built, Dakota will export it to a plain-text archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.sps, in which sps stands for Surfpack Surrogate. See filename prefix for further information
about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
binary archive
Keywords Area
model
surrogate
global
moving least squares
export model
formats
binary archive
Export surrogate model to a binary archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a binary archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.bsps, in which bsps stands for Binary Surfpack Surrogate. See filename prefix for further
information about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.

1872

CHAPTER 6. KEYWORDS AREA

neural network
Keywords Area
model
surrogate
global
neural network
Artificial neural network model

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
max nodes

Dakota Keyword
Description
Maximum number
of hidden layer
nodes

Optional

range

Range for neural

network random
weights

Optional

random weight

(Inactive) Random
weight control

Optional

export model

Exports surrogate
model in
user-selected
format

Description
Dakotas artificial neural network surrogate is a stochastic layered perceptron network, with a single hidden layer.
Weights for the input layer are chosen randomly, while those in the hidden layer are estimated from data using a
variant of the Zimmerman direct training approach[92].
This typically yields lower training cost than traditional neural networks, yet good out-of-sample performance.
This is helpful in surrogate-based optimization and optimization under uncertainty, where multiple surrogates
may be repeatedly constructed during the optimization process, e.g., a surrogate per response function, and a new
surrogate for each optimization iteration.
The neural network is a non parametric surface fitting method. Thus, along with Kriging (Gaussian Process)
and MARS, it can be used to model data trends that have slope discontinuities as well as multiple maxima and
minima. However, unlike Kriging, the neural network surrogate is not guaranteed to interpolate the data from
which it was constructed.
This surrogate can be constructed from fewer than ncquad data points, however, it is a good rule of thumb to
use at least ncquad data points when possible.

6.3. MODEL

1873

Theory
The form of the neural network model is




f(x) tanh A1 tanh AT0 x + 0T + 1
where x is the evaluation point in n-dimensional parameter space; the terms A0 , 0 are the random input layer
weight matrix and bias vector, respectively; and A1 , 1 are a weight vector and bias scalar, respectively, estimated
from training data. These coefficients are analogous to the polynomial coefficients obtained from regression to
training data. The neural network uses a cross validation-based orthogonal matching pursuit solver to determine
the optimal number of nodes and to solve for the weights and offsets.
max nodes
Keywords Area
model
surrogate
global
neural network
max nodes
Maximum number of hidden layer nodes

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: nodes
Argument(s): INTEGER
Default: numTrainingData - 1

Description
Limits the maximum number of hidden layer nodes in the neural network model. The default is to use one less
node than the number of available training data points yielding a fully-determined linear least squares problem.
However, reducing the number of nodes can help reduce overfitting and more importantly, can drastically reduce
surrogate construction time when building from a large data set. (Historically, Dakota limited the number of nodes
to 100.)
The keyword max nodes provides an upper bound. Dakotas orthogonal matching pursuit algorithm may
further reduce the effective number of nodes in the final model to achieve better generalization to unseen points.

1874

CHAPTER 6. KEYWORDS AREA

range
Keywords Area
model
surrogate
global
neural network
range
Range for neural network random weights

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): REAL

Description
Controls the range of the input layer random weights in the neural network model. The default range is 2.0,
resulting in weights in (-1, 1). These weights are applied after the training inputs have been scaled into [-0.8, 0.8].
random weight
Keywords Area
model
surrogate
global
neural network
random weight
(Inactive) Random weight control

Topics
This keyword is related to the topics:
surrogate models

6.3. MODEL

1875

Specification
Alias: none
Argument(s): INTEGER

Description
This option is not currently in use and is likely to be removed
export model
Keywords Area
model
surrogate
global
neural network
export model
Exports surrogate model in user-selected format

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Required

Description of
Group

Dakota Keyword
filename prefix

formats

Dakota Keyword
Description
User-customizable
portion of exported
model filenames
Formats for
surrogate model
export

Description
Export the surrogate for later evaluation using the surfpack exectuable (bin/surfpack) or a user-developed
tool. Export format is controlled using the formats specification. Four formats are available in Dakota; however,
not all have been enabled for all surrogates.
The four formats are:
text archive - Plain-text, machine-readable archive for use with the surfpack executable

1876

CHAPTER 6. KEYWORDS AREA

binary archive - Binary, machine-readable archive for use with the surfpack executable
algebraic file - Plain-text, human-readable file intended for use with user-created tools; not compatible with the surfpack executable
algebraic console - Print the model in algebraic format to the screen; not compatible with the surfpack executable
Most global surrogates can be exported in all four formats. These include:
Gaussian process (keyword gaussian process surfpack)
Artificial neural network (keyword neural network)
Radial basis Funtions (keyword radial basis)
Polynomial (keyword polynomial)
However, for Multivariate Adaptive Regression Spline (keyword mars) and moving least squares (keyword
moving least squares) models, only text archive and binary archive formats may be used.
Currently, no other surrogate models can be exported. In addition, Dakota cannot import models that have
been exported. They are strictly for use with external tools.
Default Behavior
No export.
Expected Output
Output depends on selected format; see the formats specification.
Additional Discussion
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
filename prefix
Keywords Area
model
surrogate
global
neural network
export model
filename prefix
User-customizable portion of exported model filenames

Topics
This keyword is related to the topics:
surrogate models

6.3. MODEL

1877

Specification
Alias: none
Argument(s): STRING
Default: exported surrogate

Description
When a file-based export of a surrogate model is specified, Dakota writes one file per response, per requested
format. The files are named using the pattern {prefix}.{response descriptor}.{extension}.
The response descriptor portion of the pattern is filled in using the response descriptors provided by
the user (or, if none are specified, descriptors automatically generated by Dakota). Extension is a three or four
letter string that depends on the format. The filename prefix keyword is used to supply the prefix portion
of the pattern.

Examples
This input snippet directs Dakota to write one algebraic format file and one binary archive file for each response.
The names of the files will follow the patterns my surrogate.{response descriptor}.alg (for the algebraic files)
and my surrogate.{response descriptor}.bsps (for the binary files).
surrogate global gaussian_process surfpack
export_model
filename_prefix = my_surrogate
formats
algebraic_file
binary_archive

formats
Keywords Area
model
surrogate
global
neural network
export model
formats
Formats for surrogate model export

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

1878

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
text archive

Optional

binary archive

Optional

algebraic file

Optional

algebraic console

Dakota Keyword
Description
Export surrogate
model to a
plain-text archive
file
Export surrogate
model to a binary
archive file
Export surrogate
model in algebraic
format to a file
Export surrogate
model in algebraic
format to the
console

Description
Select from among the 2-4 available export formats available for this surrogate. Multiple selections are permitted.
See export model and the entries for the format selection keywords for further information.
text archive
Keywords Area
model
surrogate
global
neural network
export model
formats
text archive
Export surrogate model to a plain-text archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

6.3. MODEL

1879

Description
After the surrogate model has been built, Dakota will export it to a plain-text archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.sps, in which sps stands for Surfpack Surrogate. See filename prefix for further information
about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
binary archive
Keywords Area
model
surrogate
global
neural network
export model
formats
binary archive
Export surrogate model to a binary archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a binary archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.bsps, in which bsps stands for Binary Surfpack Surrogate. See filename prefix for further
information about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.

1880

CHAPTER 6. KEYWORDS AREA

algebraic file
Keywords Area
model
surrogate
global
neural network
export model
formats
algebraic file
Export surrogate model in algebraic format to a file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a file in a human-readable algebraic format. The file is named using the pattern {prefix}.{response descriptor}.alg. See filename prefix for
further information about exported surrogate file naming. The file contains sufficient information for the user to
(re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the file matches exactly the output written to the console when algebraic console
is specified.
algebraic console
Keywords Area
model
surrogate
global
neural network

6.3. MODEL

1881

export model
formats
algebraic console
Export surrogate model in algebraic format to the console

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to the console (screen, or output file if Dakota was
run using the -o option) in a human-readable algebraic format. The output contains sufficient information for
the user to (re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the screen for the exported model matches exactly the output written to file when
algebraic file is specified. Use of algebraic file is preferred over algebraic console, which
exists largely to provide a measure of backward compatibility.
radial basis
Keywords Area
model
surrogate
global
radial basis
Radial basis function (RBF) model

Specification
Alias: none
Argument(s): none

1882

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
bases

Dakota Keyword
Description
Initial number of
radial basis
functions

Optional

max pts

Maximum number
of RBF CVT
points

Optional

min partition

(Inactive)
Minimum RBF
partition

Optional

max subsets

Number of trial
RBF subsets

Optional

export model

Exports surrogate
model in
user-selected
format

Description
Radial basis functions are functions whose value typically depends on the distance from a center point, called
the centroid, c.
The surrogate model approximation comprises a sum of K weighted radial basis functions:
f(x) =

K
X

wk (k x ck k)

k=1

These basis functions take many forms, but Gaussian kernels or splines are most common. The Dakota
implementation uses a Gaussian radial basis function. The weights are determined via a linear least squares
solution approach. See[67] for more details.
bases
Keywords Area
model
surrogate
global
radial basis
bases
Initial number of radial basis functions

6.3. MODEL

1883

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): INTEGER

Description
Initial number of radial basis functions. The default value is the smaller of the number of training points and 100.
max pts
Keywords Area
model
surrogate
global
radial basis
max pts
Maximum number of RBF CVT points

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): INTEGER

Description
Maximum number of CVT points to use in generating each RBF center. basis computing centroid of each.
Defaults to 10 (bases). Reducing this will reduce model build time.

1884
min partition
Keywords Area
model
surrogate
global
radial basis
min partition
(Inactive) Minimum RBF partition

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): INTEGER

Description
This option currently has no effect and will likely be removed.
max subsets
Keywords Area
model
surrogate
global
radial basis
max subsets
Number of trial RBF subsets

Topics
This keyword is related to the topics:
surrogate models

CHAPTER 6. KEYWORDS AREA

6.3. MODEL

1885

Specification
Alias: none
Argument(s): INTEGER

Description
Number of passes to take to identify the best subset of basis functions to use. Defaults to the smaller of 3 (bases)
and 100.
export model
Keywords Area
model
surrogate
global
radial basis
export model
Exports surrogate model in user-selected format

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Required

Description of
Group

Dakota Keyword
filename prefix

formats

Dakota Keyword
Description
User-customizable
portion of exported
model filenames
Formats for
surrogate model
export

Description
Export the surrogate for later evaluation using the surfpack exectuable (bin/surfpack) or a user-developed
tool. Export format is controlled using the formats specification. Four formats are available in Dakota; however,
not all have been enabled for all surrogates.
The four formats are:
text archive - Plain-text, machine-readable archive for use with the surfpack executable

1886

CHAPTER 6. KEYWORDS AREA

binary archive - Binary, machine-readable archive for use with the surfpack executable
algebraic file - Plain-text, human-readable file intended for use with user-created tools; not compatible with the surfpack executable
algebraic console - Print the model in algebraic format to the screen; not compatible with the surfpack executable
Most global surrogates can be exported in all four formats. These include:
Gaussian process (keyword gaussian process surfpack)
Artificial neural network (keyword neural network)
Radial basis Funtions (keyword radial basis)
Polynomial (keyword polynomial)
However, for Multivariate Adaptive Regression Spline (keyword mars) and moving least squares (keyword
moving least squares) models, only text archive and binary archive formats may be used.
Currently, no other surrogate models can be exported. In addition, Dakota cannot import models that have
been exported. They are strictly for use with external tools.
Default Behavior
No export.
Expected Output
Output depends on selected format; see the formats specification.
Additional Discussion
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
filename prefix
Keywords Area
model
surrogate
global
radial basis
export model
filename prefix
User-customizable portion of exported model filenames

Topics
This keyword is related to the topics:
surrogate models

6.3. MODEL

1887

Specification
Alias: none
Argument(s): STRING
Default: exported surrogate

Description
When a file-based export of a surrogate model is specified, Dakota writes one file per response, per requested
format. The files are named using the pattern {prefix}.{response descriptor}.{extension}.
The response descriptor portion of the pattern is filled in using the response descriptors provided by
the user (or, if none are specified, descriptors automatically generated by Dakota). Extension is a three or four
letter string that depends on the format. The filename prefix keyword is used to supply the prefix portion
of the pattern.

Examples
This input snippet directs Dakota to write one algebraic format file and one binary archive file for each response.
The names of the files will follow the patterns my surrogate.{response descriptor}.alg (for the algebraic files)
and my surrogate.{response descriptor}.bsps (for the binary files).
surrogate global gaussian_process surfpack
export_model
filename_prefix = my_surrogate
formats
algebraic_file
binary_archive

formats
Keywords Area
model
surrogate
global
radial basis
export model
formats
Formats for surrogate model export

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

1888

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
text archive

Optional

binary archive

Optional

algebraic file

Optional

algebraic console

Dakota Keyword
Description
Export surrogate
model to a
plain-text archive
file
Export surrogate
model to a binary
archive file
Export surrogate
model in algebraic
format to a file
Export surrogate
model in algebraic
format to the
console

Description
Select from among the 2-4 available export formats available for this surrogate. Multiple selections are permitted.
See export model and the entries for the format selection keywords for further information.
text archive
Keywords Area
model
surrogate
global
radial basis
export model
formats
text archive
Export surrogate model to a plain-text archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

6.3. MODEL

1889

Description
After the surrogate model has been built, Dakota will export it to a plain-text archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.sps, in which sps stands for Surfpack Surrogate. See filename prefix for further information
about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
binary archive
Keywords Area
model
surrogate
global
radial basis
export model
formats
binary archive
Export surrogate model to a binary archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a binary archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.bsps, in which bsps stands for Binary Surfpack Surrogate. See filename prefix for further
information about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.

1890

CHAPTER 6. KEYWORDS AREA

algebraic file
Keywords Area
model
surrogate
global
radial basis
export model
formats
algebraic file
Export surrogate model in algebraic format to a file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a file in a human-readable algebraic format. The file is named using the pattern {prefix}.{response descriptor}.alg. See filename prefix for
further information about exported surrogate file naming. The file contains sufficient information for the user to
(re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the file matches exactly the output written to the console when algebraic console
is specified.
algebraic console
Keywords Area
model
surrogate
global
radial basis

6.3. MODEL

1891

export model
formats
algebraic console
Export surrogate model in algebraic format to the console

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to the console (screen, or output file if Dakota was
run using the -o option) in a human-readable algebraic format. The output contains sufficient information for
the user to (re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the screen for the exported model matches exactly the output written to file when
algebraic file is specified. Use of algebraic file is preferred over algebraic console, which
exists largely to provide a measure of backward compatibility.
polynomial
Keywords Area
model
surrogate
global
polynomial
Polynomial surrogate model

Specification
Alias: none
Argument(s): none

1892

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Dakota Keyword

Required(Choose
One)

polynomial order
(Group 1)

basis order

Optional

Dakota Keyword
Description
Polynomial order

linear

Use a linear
polynomial or
trend function

quadratic

Use a quadratic
polynomial or
trend function

cubic

Use a cubic
polynomial
Exports surrogate
model in
user-selected
format

export model

Description
Linear, quadratic, and cubic polynomial surrogate models are available in Dakota. The utility of the simple
polynomial models stems from two sources:
over a small portion of the parameter space, a low-order polynomial model is often an accurate approximation to the true data trends
the least-squares procedure provides a surface fit that smooths out noise in the data.
Local surrogate-based optimization methods (surrogate based local) are often successful when using polynomial
models, particularly quadratic models. However, a polynomial surface fit may not be the best choice for modeling
data trends globally over the entire parameter space, unless it is known a priori that the true data trends are close
to linear, quadratic, or cubic. See[63] for more information on polynomial models.

Theory
The form of the linear polynomial model is
f(x) c0 +

n
X

ci xi

i=1

the form of the quadratic polynomial model is:

f(x) c0 +

n
X

ci xi +

i=1

n X
n
X

cij xi xj

i=1 ji

and the form of the cubic polynomial model is:

f(x) c0 +

n
X
i=1

ci xi +

n X
n
X
i=1 ji

cij xi xj +

n X
n X
n
X
i=1 ji kj

cijk xi xj xk

6.3. MODEL

1893

In all of the polynomial models, f(x) is the response of the polynomial model; the xi , xj , xk terms are
the components of the n-dimensional design parameter values; the c0 , ci , cij , cijk terms are the polynomial
coefficients, and n is the number of design parameters. The number of coefficients, nc , depends on the order of
polynomial model and the number of design parameters. For the linear polynomial:
nclinear = n + 1
for the quadratic polynomial:
ncquad =

(n + 1)(n + 2)
2

and for the cubic polynomial:

(n3 + 6n2 + 11n + 6)
6
There must be at least nc data samples in order to form a fully determined linear system and solve for the
polynomial coefficients. In Dakota, a least-squares approach involving a singular value decomposition numerical
method is applied to solve the linear system.
nccubic =

basis order
Keywords Area
model
surrogate
global
polynomial
basis order
Polynomial order

Specification
Alias: none
Argument(s): INTEGER

Description
The polynomial order for the polynomial regression model (default = 2).
linear
Keywords Area
model
surrogate
global

1894
polynomial
linear
Use a linear polynomial or trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
quadratic
Keywords Area
model
surrogate
global
polynomial
quadratic
Use a quadratic polynomial or trend function

Specification
Alias: none
Argument(s): none

Description
See parent page
cubic
Keywords Area
model
surrogate
global
polynomial
cubic
Use a cubic polynomial

CHAPTER 6. KEYWORDS AREA

6.3. MODEL

1895

Specification
Alias: none
Argument(s): none

Description
See parent page
export model
Keywords Area
model
surrogate
global
polynomial
export model
Exports surrogate model in user-selected format

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Required

Description of
Group

Dakota Keyword
filename prefix

formats

Dakota Keyword
Description
User-customizable
portion of exported
model filenames
Formats for
surrogate model
export

Description
Export the surrogate for later evaluation using the surfpack exectuable (bin/surfpack) or a user-developed
tool. Export format is controlled using the formats specification. Four formats are available in Dakota; however,
not all have been enabled for all surrogates.
The four formats are:
text archive - Plain-text, machine-readable archive for use with the surfpack executable

1896

CHAPTER 6. KEYWORDS AREA

binary archive - Binary, machine-readable archive for use with the surfpack executable
algebraic file - Plain-text, human-readable file intended for use with user-created tools; not compatible with the surfpack executable
algebraic console - Print the model in algebraic format to the screen; not compatible with the surfpack executable
Most global surrogates can be exported in all four formats. These include:
Gaussian process (keyword gaussian process surfpack)
Artificial neural network (keyword neural network)
Radial basis Funtions (keyword radial basis)
Polynomial (keyword polynomial)
However, for Multivariate Adaptive Regression Spline (keyword mars) and moving least squares (keyword
moving least squares) models, only text archive and binary archive formats may be used.
Currently, no other surrogate models can be exported. In addition, Dakota cannot import models that have
been exported. They are strictly for use with external tools.
Default Behavior
No export.
Expected Output
Output depends on selected format; see the formats specification.
Additional Discussion
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
filename prefix
Keywords Area
model
surrogate
global
polynomial
export model
filename prefix
User-customizable portion of exported model filenames

Topics
This keyword is related to the topics:
surrogate models

6.3. MODEL

1897

Specification
Alias: none
Argument(s): STRING
Default: exported surrogate

Description
When a file-based export of a surrogate model is specified, Dakota writes one file per response, per requested
format. The files are named using the pattern {prefix}.{response descriptor}.{extension}.
The response descriptor portion of the pattern is filled in using the response descriptors provided by
the user (or, if none are specified, descriptors automatically generated by Dakota). Extension is a three or four
letter string that depends on the format. The filename prefix keyword is used to supply the prefix portion
of the pattern.

Examples
This input snippet directs Dakota to write one algebraic format file and one binary archive file for each response.
The names of the files will follow the patterns my surrogate.{response descriptor}.alg (for the algebraic files)
and my surrogate.{response descriptor}.bsps (for the binary files).
surrogate global gaussian_process surfpack
export_model
filename_prefix = my_surrogate
formats
algebraic_file
binary_archive

formats
Keywords Area
model
surrogate
global
polynomial
export model
formats
Formats for surrogate model export

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

1898

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
text archive

Optional

binary archive

Optional

algebraic file

Optional

algebraic console

Dakota Keyword
Description
Export surrogate
model to a
plain-text archive
file
Export surrogate
model to a binary
archive file
Export surrogate
model in algebraic
format to a file
Export surrogate
model in algebraic
format to the
console

Description
Select from among the 2-4 available export formats available for this surrogate. Multiple selections are permitted.
See export model and the entries for the format selection keywords for further information.
text archive
Keywords Area
model
surrogate
global
polynomial
export model
formats
text archive
Export surrogate model to a plain-text archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

6.3. MODEL

1899

Description
After the surrogate model has been built, Dakota will export it to a plain-text archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.sps, in which sps stands for Surfpack Surrogate. See filename prefix for further information
about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.
binary archive
Keywords Area
model
surrogate
global
polynomial
export model
formats
binary archive
Export surrogate model to a binary archive file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a binary archival file suitable only for use
with the surfpack executable (bin/surfpack). The file is named using the pattern {prefix}.{response descriptor}.bsps, in which bsps stands for Binary Surfpack Surrogate. See filename prefix for further
information about exported surrogate file naming.
The Dakota examples folder includes a demonstration of using the surfpack executable with an exported model
file.

1900

CHAPTER 6. KEYWORDS AREA

algebraic file
Keywords Area
model
surrogate
global
polynomial
export model
formats
algebraic file
Export surrogate model in algebraic format to a file

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to a file in a human-readable algebraic format. The file is named using the pattern {prefix}.{response descriptor}.alg. See filename prefix for
further information about exported surrogate file naming. The file contains sufficient information for the user to
(re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the file matches exactly the output written to the console when algebraic console
is specified.
algebraic console
Keywords Area
model
surrogate
global
polynomial

6.3. MODEL

1901

export model
formats
algebraic console
Export surrogate model in algebraic format to the console

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none

Description
After the surrogate model has been built, Dakota will export it to the console (screen, or output file if Dakota was
run using the -o option) in a human-readable algebraic format. The output contains sufficient information for
the user to (re)construct and evaluate the model outside of Dakota.
Expected Output
The format depends on the type of surrogate model, but in general will include a LaTeX-like representation of
the analytic form of the model to aid tool development, all needed model hyperparameters, and headers describing
the shape or dimension of the provided data.
The output written to the screen for the exported model matches exactly the output written to file when
algebraic file is specified. Use of algebraic file is preferred over algebraic console, which
exists largely to provide a measure of backward compatibility.
domain decomposition
Keywords Area
model
surrogate
global
domain decomposition
Piecewise Domain Decomposition for Global Surrogate Models

Specification
Alias: none
Argument(s): none

1902

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
cell type

Dakota Keyword
Description
Type of the
Geometric Cells
Used for the
Piecewise
Decomposition
Option of Global
Surrogates

Optional

support layers

Optional Number
of Support Layers
for the Piecewise
Decomposition
Option of Global
Surrogates

Optional

discontinuity detection

Optional
Discontinuity
Detection
Capability for the
Piecewise
Decomposition
Option of Global
Surrogates

Description
Typical regression techniques use all available sample points to build continuous approximations the underlying
function.
An alternative option is to use piecewise decomposition to locally approximate the function at some point
using a few sample points from its neighborhood only. This option currently supports Polynomial Regression,
Gaussian Process (GP) Interpolation, and Radial Basis Functions (RBF) Regression. It requires a decomposition
cell type (currently set to be Voronoi cells). Optional parameters are: the number of layers of neighbors used to
solve the regression problem (default is one layer), and an optional discontinuity detection capability (identified
by a user-input jump or gradient threshold).
The method can also make use of the gradient and Hessian information, if available. The user needs to specify
the keyword user derivatives.
cell type
Keywords Area
model
surrogate
global
domain decomposition

6.3. MODEL

1903

cell type
Type of the Geometric Cells Used for the Piecewise Decomposition Option of Global Surrogates

Specification
Alias: none
Argument(s): STRING

Description
The piecewise decomposition option for global surrogates is used to locally approximate a function at some point
using a few sample points from its neighborhood.
This option requires a decomposition cell type that can vary from structured grid boxes, to polygonal Voronoi
cells. Currently, this option only supports Voronoi cells.
support layers
Keywords Area
model
surrogate
global
domain decomposition
support layers
Optional Number of Support Layers for the Piecewise Decomposition Option of Global Surrogates

Specification
Alias: none
Argument(s): INTEGER

Description
The piecewise decomposition option for global surrogates is used to locally approximate a function at some point
using a few sample points from its neighborhood.
The neighborhood of a cell is parameterized via a number of (support layers). The default value is set to one
layer of neighbors (cells that share direct edges with the cell under study). One more support layer would include
the neighbors of that cells neighbors, and so on.
discontinuity detection
Keywords Area
model
surrogate
global

1904

CHAPTER 6. KEYWORDS AREA

domain decomposition
discontinuity detection
Optional Discontinuity Detection Capability for the Piecewise Decomposition Option of Global Surrogates

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
jump threshold

gradient threshold

Dakota Keyword
Description
Gradient Threshold
Parameter of the
Optional
Discontinuity
Detection
Capability for the
Piecewise
Decomposition
Option of Global
Surrogates
Gradient Threshold
Parameter of the
Optional
Discontinuity
Detection
Capability for the
Piecewise
Decomposition
Option of Global
Surrogates

Description
The piecewise decomposition option for global surrogates is used to locally approximate a function at some point
using a few sample points from its neighborhood.
The domain decomposition algorithm supports an optional discontinuity detection capability where seeds
across a user-input discontinuity threshold are not considered neighbors when building the approximate connectivity Delaunay graph. Alternatively, the domain is split into patches that trap discontinuities between them. This
capability is specified by either jump or gradient threshold values in the input spec.
jump threshold
Keywords Area
model
surrogate

6.3. MODEL

1905

global
domain decomposition
discontinuity detection
jump threshold
Gradient Threshold Parameter of the Optional Discontinuity Detection Capability for the Piecewise Decomposition Option of Global Surrogates

Specification
Alias: none
Argument(s): REAL

Description
The piecewise decomposition option for global surrogates is used to locally approximate a function at some point
using a few sample points from its neighborhood.
The domain decomposition algorithm supports an optional discontinuity detection capability where seeds
across a user-input discontinuity threshold are not considered neighbors when building the approximate connectivity Delaunay graph. Alternatively, the domain is split into patches that trap discontinuities between them. This
capability can be specified using a jump threshold value in the input spec.
gradient threshold
Keywords Area
model
surrogate
global
domain decomposition
discontinuity detection
gradient threshold
Gradient Threshold Parameter of the Optional Discontinuity Detection Capability for the Piecewise Decomposition Option of Global Surrogates

Specification
Alias: none
Argument(s): REAL

1906

CHAPTER 6. KEYWORDS AREA

Description
The piecewise decomposition option for global surrogates is used to locally approximate a function at some point
using a few sample points from its neighborhood.
The domain decomposition algorithm supports an optional discontinuity detection capability where seeds
across a user-input discontinuity threshold are not considered neighbors when building the approximate connectivity Delaunay graph. Alternatively, the domain is split into patches that trap discontinuities between them. This
capability can be specified using a gradient threshold value in the input spec.
total points
Keywords Area
model
surrogate
global
total points
Specified number of training points

Specification
Alias: none
Argument(s): INTEGER
Default: recommended points

Description
See parent page.
minimum points
Keywords Area
model
surrogate
global
minimum points
Construct surrogate with minimum number of points

Specification
Alias: none
Argument(s): none

Description
The minimum is d+1, for d input dimensions, except for polynomials. See parent page.

6.3. MODEL

1907

recommended points
Keywords Area
model
surrogate
global
recommended points
Construct surrogate with recommended number of points

Specification
Alias: none
Argument(s): none

Description
This is the default option. It requires 5d build points for d input dimensions, except for polynomial models. See
parent page.
dace method pointer
Keywords Area
model
surrogate
global
dace method pointer
Specify a method to gather training data

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: no design of experiments data

1908

CHAPTER 6. KEYWORDS AREA

Description
The number of training points and the sources are specified on global, as well as the number of new training points
required.
New training points are gathered by running the truth model using the method specified by dace methodpointer. The DACE method will only be invoked if it has new samples to perform, and if new samples are
required and no DACE iterator has been provided, an error will result.
The dace method pointer points to design of experiments method block used to generate truth model
data.
Permissible methods include: Monte Carlo (random) sampling, Latin hypercube sampling, orthogonal array
sampling, central composite design sampling, and Box-Behnken sampling.
Note that the number of samples specified in the method block may be overwritten, if the requested number
of samples is less than minimum points.
actual model pointer
Keywords Area
model
surrogate
global
actual model pointer
A surrogate model pointer that guides a method to whether it should use a surrogate model or compute truth
function evaluations

Specification
Alias: none
Argument(s): STRING

Description
Dakota methods use global surrogate models to compute surrogate function approximations. They also need to
know the true function evaluations. A global surrogate model now must have an actual model pointer keyword to
decide for the method whether to evaluate the global surrogate model, or compute the true function evaluations if
actual model pointer = TRUTH.
reuse points
Keywords Area
model
surrogate
global
reuse points
Surrogate model training data reuse control

6.3. MODEL

1909

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: reuse samples
Argument(s): none
Default: all for import; none otherwise
Required/Optional
Required(Choose
One)

Description of
Group

Dakota Keyword
all

Group 1
region
none

Dakota Keyword
Description
Option for
reuse points
Option for
reuse points
Option for
reuse points

Description
Dakotas global surrogate methods rely on training data, which can either come from evaluation of a truth
model, which is generated by the method specified with dace method pointer, from a file of existing training data,
identified by import build points file, or both.
The reuse points keyword controls the amount of training data used in building a surrogate model, either
initially, or during iterative rebuild, as in surrogate-based optimization. If import build points file is specified,
reuse points controls how the file contents are used. If used during iterative rebuild, it controls what data
from previous surrogate builds is reused in building the current model.
all (default for file import) - use all points in the file or available from previous builds
region - use only the points falling in the current trust region (see surrogate based local)
none (default when no import) - ignore the contents of the file or previous build points, and gather new
training data using the specified DACE method
all
Keywords Area
model
surrogate
global
reuse points
all
Option for reuse points

1910

Specification
Alias: none
Argument(s): none

Description
This is described on the parent page.
region
Keywords Area
model
surrogate
global
reuse points
region
Option for reuse points

Specification
Alias: none
Argument(s): none

Description
This is described on the parent page.
none
Keywords Area
model
surrogate
global
reuse points
none
Option for reuse points

Specification
Alias: none
Argument(s): none

CHAPTER 6. KEYWORDS AREA

6.3. MODEL

1911

Description
This is described on the parent page.
import build points file
Keywords Area
model
surrogate
global
import build points file
File containing points you wish to use to build a surrogate

Specification
Alias: import points file samples file
Argument(s): STRING
Default: no point import from a file
Required/Optional
Optional(Choose
One)

Optional

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
The import build points file allows the user to specify a file that contains a list of points and truth model
responses used to construct a surrogate model. These can be used by all methods that (explicitly, e.g. surrogatebased optimization, or implicitly, e.g. efficient global optimization) operate on a surrogate. In particular, these
points and responses are used in place of truth model evaluations to construct the initial surrogate. When used to
construct surrogate models or emulators these are often called build points or training data.
Default Behavior
Be default, methods do not import points from a file.
Usage Tips
Dakota parses input files without regard to whitespace, but the import build points file must be in one of three
formats:

1912

CHAPTER 6. KEYWORDS AREA

annotated (default)
custom annotated
freeform

Examples
method
polynomial_chaos
expansion_order = 4
import_build_points_file = dakota_uq_rosenbrock_pce_import.annot.pts.dat

annotated
Keywords Area
model
surrogate
global
import build points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id

6.3. MODEL

1913

Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
model
surrogate
global
import build points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1914

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.3. MODEL
header
Keywords Area
model
surrogate
global
import build points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
eval id
Keywords Area
model
surrogate
global
import build points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated

1915

1916
interface id
Keywords Area
model
surrogate
global
import build points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
freeform
Keywords Area
model
surrogate
global
import build points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated

CHAPTER 6. KEYWORDS AREA

6.3. MODEL

1917

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
model
surrogate
global
import build points file
active only
Import only active variables from tabular data file

Topics
This keyword is related to the topics:
file formats

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

1918

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
export approx points file
Keywords Area
model
surrogate
global
export approx points file
Output file for evaluations of a surrogate model

Specification
Alias: export points file
Argument(s): STRING
Default: no point export to a file
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

Description
The export approx points file keyword allows the user to specify a file in which the points (input variable values) at which the surrogate model is evaluated and corresponding response values computed by the surrogate model will be written. The response values are the surrogates predicted approximation to the truth model
responses at those points.

6.3. MODEL

1919

Usage Tips
Dakota exports tabular data in one of three formats:
annotated (default)
custom annotated
freeform
annotated
Keywords Area
model
surrogate
global
export approx points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

1920

CHAPTER 6. KEYWORDS AREA

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

custom annotated
Keywords Area
model
surrogate
global
export approx points file
custom annotated
Selects custom-annotated tabular file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

6.3. MODEL

1921
Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

header
Keywords Area
model
surrogate

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

1922
global
export approx points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
eval id
Keywords Area
model
surrogate
global
export approx points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated

CHAPTER 6. KEYWORDS AREA

6.3. MODEL
interface id
Keywords Area
model
surrogate
global
export approx points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
freeform
Keywords Area
model
surrogate
global
export approx points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated

1923

1924

CHAPTER 6. KEYWORDS AREA

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

use derivatives
Keywords Area
model
surrogate
global
use derivatives
Use derivative data to construct surrogate models

Specification
Alias: none
Argument(s): none
Default: use function values only

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.3. MODEL

1925

Description
The use derivatives flag specifies that any available derivative information should be used in global approximation builds, for those global surrogate types that support it (currently, polynomial regression and the Surfpack
Gaussian process).
However, its use with Surfpack Gaussian process is not recommended.
correction
Keywords Area
model
surrogate
global
correction
Correction approaches for surrogate models

Specification
Alias: none
Argument(s): none
Default: no surrogate correction
Required/Optional
Required(Choose
One)

Required(Choose
One)

Description of
Group
correction order
(Group 1)

correction type
(Group 2)

Dakota Keyword
zeroth order

Dakota Keyword
Description
Specify that truth
values must be
matched.

first order

Specify that truth

values and
gradients must be
matched.

second order

Specify that truth

values, gradients
and Hessians must
be matched.

additive

Additive correction
factor for local
surrogate accuracy

1926

CHAPTER 6. KEYWORDS AREA

multiplicative

Multiplicative
correction factor
for local surrogate
accuracy.

combined

Multipoint
correction for a
hierarchical
surrogate

Description
Some of the surrogate model types support the use of correction factors that improve the local accuracy of the
surrogate models.
The correction specification specifies that the approximation will be corrected to match truth data, either
matching truth values in the case of zeroth order matching, matching truth values and gradients in the case
of first order matching, or matching truth values, gradients, and Hessians in the case of second order
matching. For additive and multiplicative corrections, the correction is local in that the truth data is
matched at a single point, typically the center of the approximation region. The additive correction adds a
scalar offset (zeroth order), a linear function (first order), or a quadratic function (second order)
to the approximation to match the truth data at the point, and the multiplicative correction multiplies
the approximation by a scalar (zeroth order), a linear function (first order), or a quadratic function
(second order) to match the truth data at the point. The additive first order case is due to[57] and
the multiplicative first order case is commonly known as beta correction[40]. For the combined
correction, the use of both additive and multiplicative corrections allows the satisfaction of an additional matching
condition, typically the truth function values at the previous correction point (e.g., the center of the previous trust
region). The combined correction is then a multipoint correction, as opposed to the local additive and
multiplicative corrections. Each of these correction capabilities is described in detail in[24].
The correction factors force the surrogate models to match the true function values and possibly true function
derivatives at the center point of each trust region. Currently, Dakota supports either zeroth-, first-, or second-order
accurate correction methods, each of which can be applied using either an additive, multiplicative, or combined
correction function. For each of these correction approaches, the correction is applied to the surrogate model and
the corrected model is then interfaced with whatever algorithm is being employed. The default behavior is that no
correction factor is applied.
The simplest correction approaches are those that enforce consistency in function values between the surrogate
and original models at a single point in parameter space through use of a simple scalar offset or scaling applied
to the surrogate model. First-order corrections such as the first-order multiplicative correction (also known as
beta correction[15]) and the first-order additive correction[57] also enforce consistency in the gradients and provide a much more substantial correction capability that is sufficient for ensuring provable convergence in SBO
algorithms. SBO convergence rates can be further accelerated through the use of second-order corrections which
also enforce consistency in the Hessians[24], where the second-order information may involve analytic, finitedifference, or quasi-Newton Hessians.
Correcting surrogate models with additive corrections involves
(x) = flo (x) + (x)
fhi

(6.1)

where multifidelity notation has been adopted for clarity. For multiplicative approaches, corrections take the form
(x) = flo (x)(x)
fhi

(6.2)

6.3. MODEL

1927

where, for local corrections, (x) and (x) are first or second-order Taylor series approximations to the exact
correction functions:

(x)

(x)

1
A(xc ) + A(xc )T (x xc ) + (x xc )T 2 A(xc )(x xc )
2
1
B(xc ) + B(xc )T (x xc ) + (x xc )T 2 B(xc )(x xc )
2

(6.3)
(6.4)

where the exact correction functions are

= fhi (x) flo (x)

fhi (x)
B(x) =
flo (x)
A(x)

(6.5)
(6.6)

Refer to[24] for additional details on the derivations.

A combination of additive and multiplicative corrections can provide for additional flexibility in minimizing
the impact of the correction away from the trust region center. In other words, both additive and multiplicative
corrections can satisfy local consistency, but through the combination, global accuracy can be addressed as well.
This involves a convex combination of the additive and multiplicative corrections:
(x) = fhi
(x) + (1 )fhi
(x)
fhi

where is calculated to satisfy an additional matching condition, such as matching values at the previous design
iterate.
It should be noted that in both first order correction methods, the function f(x) matches the function value and
gradients of ft (x) at x = xc . This property is necessary in proving that the first order-corrected SBO algorithms
are provably convergent to a local minimum of ft (x). However, the first order correction methods are significantly
more expensive than the zeroth order correction methods, since the first order methods require computing both
ft (xc ) and fs (xc ). When the SBO strategy is used with either of the zeroth order correction methods, or
with no correction method, convergence is not guaranteed to a local minimum of ft (x). That is, the SBO strategy
becomes a heuristic optimization algorithm. From a mathematical point of view this is undesirable, but as a
practical matter, the heuristic variants of SBO are often effective in finding local minima.
Usage guidelines
Both the additive zeroth order and multiplicative zeroth order correction methods are free
since they use values of ft (xc ) that are normally computed by the SBO strategy.
The use of either the additive first order method or the multiplicative first order method does
not necessarily improve the rate of convergence of the SBO algorithm.
When using the first order correction methods, the gradient-related response keywords must be modified
to allow either analytic or numerical gradients to be computed. This provides the gradient data needed to
compute the correction function.
For many computationally expensive engineering optimization problems, gradients often are too expensive
to obtain or are discontinuous (or may not exist at all). In such cases the heuristic SBO algorithm has been
an effective approach at identifying optimal designs[35].

1928

CHAPTER 6. KEYWORDS AREA

zeroth order
Keywords Area
model
surrogate
global
correction
zeroth order
Specify that truth values must be matched.

Specification
Alias: none
Argument(s): none

Description
The correction specification specifies that the approximation will be corrected to match truth data. The keyword
zeroth order matching ensures that truth values are matched.
first order
Keywords Area
model
surrogate
global
correction
first order
Specify that truth values and gradients must be matched.

Specification
Alias: none
Argument(s): none

Description
This correction specification specifies that the approximation will be corrected to match truth data. The keyword
first order matching ensures that truth values and gradients are matched.

6.3. MODEL

1929

second order
Keywords Area
model
surrogate
global
correction
second order
Specify that truth values, gradients and Hessians must be matched.

Specification
Alias: none
Argument(s): none

Description
The correction specification specifies that the approximation will be corrected to match truth data. The keyword
second order matching ensures that truth values, gradients and Hessians are matched.
additive
Keywords Area
model
surrogate
global
correction
additive
Additive correction factor for local surrogate accuracy

Specification
Alias: none
Argument(s): none

Description
Use an additive correction factor to improve the local accuracy of a surrogate.

1930

CHAPTER 6. KEYWORDS AREA

multiplicative
Keywords Area
model
surrogate
global
correction
multiplicative
Multiplicative correction factor for local surrogate accuracy.

Specification
Alias: none
Argument(s): none

Description
Use a multiplicative correction factor to improve the local accuracy of a surrogate.
combined
Keywords Area
model
surrogate
global
correction
combined
Multipoint correction for a hierarchical surrogate

Specification
Alias: none
Argument(s): none

Description
For the combined correction, the use of both additive and multiplicative corrections allows the satisfaction of an
additional matching condition, typically the truth function values at the previous correction point (e.g., the center
of the previous trust region). The combined correction is then a multipoint correction, as opposed to the local
additive and multiplicative corrections.

6.3. MODEL

1931

metrics
Keywords Area
model
surrogate
global
metrics
Compute surrogate quality metrics

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: diagnostics
Argument(s): STRINGLIST
Default: No diagnostics
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
cross validation

press

Dakota Keyword
Description
Perform k-fold
cross validation
Leave-one-out
cross validation

Description
A variety of diagnostic metrics are available to assess the goodness of fit of a global surrogate to its training data.
The default diagnostics are:
root mean squared
mean abs
rsquared
Additional available diagnostics include
sum squared
mean squared
sum abs
max abs
The keywords press and cross validation further specify leave-one-out or k-fold cross validation, respectively, for all of the active metrics from above.

1932

CHAPTER 6. KEYWORDS AREA

Theory
Most of these diagnostics refer to some operation on the residuals (the difference between the surrogate model
and the truth model at the data points upon which the surrogate is built).
For example, sum squared refers to the sum of the squared residuals, and mean abs refers to the mean of
the absolute value of the residuals. rsquared refers to the R-squared value typically used in regression analysis
(the proportion of the variability in the response that can be accounted for by the surrogate model). Care should
be taken when interpreting metrics, for example, errors may be near zero for interpolatory models or rsquared
may not be applicable for non-polynomial models.
cross validation
Keywords Area
model
surrogate
global
metrics
cross validation
Perform k-fold cross validation

Topics
This keyword is related to the topics:
surrogate models

Specification
Alias: none
Argument(s): none
Default: No cross validation
Required/Optional
Optional(Choose
One)

Description of
Group
Group 1

Dakota Keyword
folds

percent

Dakota Keyword
Description
Number of cross
validation folds
Percent data per
cross validation
fold

Description
General k-fold cross validation may be performed by specifying cross validation. The cross-validation
statistics will be calculated for all metrics.
Cross validation may further specify:
folds, the number of folds into which to divide the build data (between 2 and number of data points) or

6.3. MODEL

1933

percent, the fraction of data (between 0 and 0.5) to use in each fold.
These will be adjusted as needed based on the number of available training points. The default number of folds k
= 10, or 0.1
folds
Keywords Area
model
surrogate
global
metrics
cross validation
folds
Number of cross validation folds

Specification
Alias: none
Argument(s): INTEGER
Default: 10

Description
Number of folds (partitions) of the training data to use in cross validation (default 10).
percent
Keywords Area
model
surrogate
global
metrics
cross validation
percent
Percent data per cross validation fold

Specification
Alias: none
Argument(s): REAL
Default: 0.1

1934

CHAPTER 6. KEYWORDS AREA

Description
Percent of the training data to use in each cross validation fold (default 0.1).
press
Keywords Area
model
surrogate
global
metrics
press
Leave-one-out cross validation

Specification
Alias: none
Argument(s): none
Default: No PRESS cross validation

Description
Leave-one-out (PRESS) cross validation may be performed by specifying press. The cross-validation statistics
will be calculated for all metrics.
import challenge points file
Keywords Area
model
surrogate
global
import challenge points file
Datafile of points to assess surrogate quality

Specification
Alias: challenge points file
Argument(s): STRING
Default: no user challenge data

6.3. MODEL

1935
Required/Optional

Description of
Group

Optional(Choose
One)

tabular format
(Group 1)

Optional

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format

custom annotated

Selects
custom-annotated
tabular file format

freeform

Selects freeform
file format

active only

Import only active

variables from
tabular data file

Description
Specifies a data file containing variable and response (truth) values, in one of three formats:
annotated (default)
custom annotated
freeform
The surrogate is evaluated at the points in the file, and the surrogate (approximate) responses are compared against
the truth results from the file. All metrics specified with metrics will be computed for the challenge data.
annotated
Keywords Area
model
surrogate
global
import challenge points file
annotated
Selects annotated tabular file format

Topics
This keyword is related to the topics:
file formats

1936

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. Each subsequent row contains an evaluation ID and interface ID, followed by data for variables, or variables
followed by responses, depending on context.
Default Behavior
By default, Dakota imports and exports tabular files in annotated format. The annotated keyword can be
used to explicitly specify this.
Usage Tips
To specify pre-Dakota 6.1 tabular format, which did not include interface id, specify custom annotated
header eval id
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export an annotated top-level tabular data file containing a header row, leading eval id and interface id columns,
and data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
annotated

Resulting tabular file:

%eval_id interface
1
NO_ID
2
NO_ID
3
NO_ID
...

x1
0.9
0.90009
0.89991

custom annotated
Keywords Area
model
surrogate
global
import challenge points file
custom annotated
Selects custom-annotated tabular file format

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

6.3. MODEL

1937

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

Optional

eval id

Enable evaluation
ID column in
custom-annotated
tabular file

Optional

interface id

Enable interface
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file typically containing row data for variables, or
variables followed by responses, though the format is used for other tabular exports/imports as well. Customannotated allows user options for whether header row, eval id column, and interface id column appear
in the tabular file, thus bridging freeform and (fully) annotated.
Default Behavior
The annotated format is the default for tabular export/import. To control which header row and columns
are in the input/output, specify custom annotated, followed by options, in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a custom-annotated tabular file in Dakota 6.0 format, which contained only header and eval id (no interfaceid), and data for variables and responses. Input file fragment:

1938

CHAPTER 6. KEYWORDS AREA

environment
tabular_data
tabular_data_file = dakota_summary.dat
custom_annotated header eval_id

Resulting tabular file:

%eval_id
1
2
3
...

x1
0.9
0.90009
0.89991

x2
obj_fn nln_ineq_con_1 nln_ineq_con_2
1.1
0.0002
0.26
0.76
1.1 0.0001996404857
0.2601620081
0.759955
1.1 0.0002003604863
0.2598380081
0.760045

header
Keywords Area
model
surrogate
global
import challenge points file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
eval id
Keywords Area
model
surrogate
global
import challenge points file
custom annotated
eval id
Enable evaluation ID column in custom-annotated tabular file

6.3. MODEL

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
interface id
Keywords Area
model
surrogate
global
import challenge points file
custom annotated
interface id
Enable interface ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none

Description
See description of parent custom annotated
freeform
Keywords Area
model
surrogate
global
import challenge points file
freeform
Selects freeform file format

Topics
This keyword is related to the topics:
file formats

1939

1940

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. Most
commonly, each row contains data for variables, or variables followed by responses, though the format is used for
other tabular exports/imports as well.
Default Behavior
The annotated format is the default for tabular export/import. To change this behavior, specify freeform
in the relevant export/import context.
Usage Tips
Prior to October 2011, calibration and surrogate data files were free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.
In freeform, the num rows x num cols total data entries may be separated with any whitespace including
spaces, tabs, and newlines. In this format, vectors may therefore appear as a single row or single column
(or mixture; entries will populate the vector in order).
Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the freeform option.

Examples
Export a freeform tabular file containing only data for variables and responses. Input file fragment:
environment
tabular_data
tabular_data_file = dakota_summary.dat
freeform

Resulting tabular file:

0.9
0.90009
0.89991

1.1
0.0002
1.1 0.0001996404857
1.1 0.0002003604863

...

active only
Keywords Area
model
surrogate
global
import challenge points file
active only
Import only active variables from tabular data file

0.26
0.2601620081
0.2598380081

0.76
0.759955
0.760045

6.3. MODEL

1941

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none

Description
By default, files for tabular data imports are expected to contain columns for all variables, active and inactive. The
keyword active only indicates that the file to import contains only the active variables.
This option should only be used in contexts where the inactive variables have no influence, for example,
building a surrogate over active variables, with the state variables held at nominal. It should not be used in more
complex nested contexts, where the values of inactive variables are relevant to the function evaluations used to
build the surrogate.
multipoint
Keywords Area
model
surrogate
multipoint
Construct a surrogate from multiple existing training points

Specification
Alias: none
Argument(s): none
Required/Optional
Required

Required

Description of
Group

Dakota Keyword
tana

actual model pointer

Dakota Keyword
Description
Local multi-point
model via
two-point
nonlinear
approximation
Pointer to specify a
truth model,
from which to
construct a
surrogate

1942

CHAPTER 6. KEYWORDS AREA

Description
Multipoint approximations use data from previous design points to improve the accuracy of local approximations.
The data often comes from the current and previous iterates of a minimization algorithm.
Currently, only the Two-point Adaptive Nonlinearity Approximation (TANA-3) method of [91] is supported
with the tana keyword.
The truth model to be used to generate the value/gradient data used in the approximation is identified through
the required actual model pointer specification.

See Also
These keywords may also be of interest:
local
global
hierarchical
tana
Keywords Area
model
surrogate
multipoint
tana
Local multi-point model via two-point nonlinear approximation

Specification
Alias: none
Argument(s): none

Description
TANA stands for Two Point Adaptive Nonlinearity Approximation.
The TANA-3 method[91] is a multipoint approximation method based on the two point exponential approximation[25].
This approach involves a Taylor series approximation in intermediate variables where the powers used for the intermediate variables are selected to match information at the current and previous expansion points.

Theory
The form of the TANA model is:
f(x) f (x2 ) +

n
n
i
X
X
x1p
1
f
i,2
i
i 2
(x2 )
(xpi i xpi,2
) + (x)
(xpi i xpi,2
)
x
p
2
i
i
i=1
i=1

where n is the number of variables and:

6.3. MODEL

"
pi = 1+ln

f
xi (x1 )
f
xi (x2 )

1943

#

"

n
X
x1p
f
xi,1
H
i,2
P
H
=
2
f
(x
)

f
(x
)

ln
(x) = Pn
(x
)
1
2
2
n
pi 2
pi
pi 2
pi
xi,2
x
pi
)

x
(x
)
+

x
(x
i
i,2
i,1
i=1 i
i=1 i
i=1


and x2 and x1 are the current and previous expansion points. Prior to the availability of two expansion points,
a first-order Taylor series is used.
actual model pointer
Keywords Area
model
surrogate
multipoint
actual model pointer
Pointer to specify a truth model, from which to construct a surrogate

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
This must point to a model block, identified by id model. That model will be run to generate training data, from
which a surrogate model will be constructed.
See block pointer for details about pointers.
local
Keywords Area
model
surrogate
local
Build a locally accurate surrogate from data at a single point

Specification
Alias: none
Argument(s): none

1944

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required

Description of
Group

Required

Dakota Keyword
taylor series

actual model pointer

Dakota Keyword
Description
Construct a Taylor
Series expansion
around a point
Pointer to specify a
truth model,
from which to
construct a
surrogate

Description
Local approximations use value, gradient, and possibly Hessian data from a single point to form a series expansion
for approximating data in the vicinity of this point.
The currently available local approximation is the taylor series selection.
The truth model to be used to generate the value/gradient/Hessian data used in the series expansion is identified through the required actual model pointer specification. The use of a model pointer (as opposed
to an interface pointer) allows additional flexibility in defining the approximation. In particular, the derivative
specification for the truth model may differ from the derivative specification for the approximation, and the truth
model results being approximated may involve a model recursion (e.g., the values/gradients from a nested model).

See Also
These keywords may also be of interest:
global
hierarchical
multipoint
taylor series
Keywords Area
model
surrogate
local
taylor series
Construct a Taylor Series expansion around a point

Specification
Alias: none
Argument(s): none

6.3. MODEL

1945

Description
The Taylor series model is purely a local approximation method. That is, it provides local trends in the vicinity of
a single point in parameter space.
The order of the Taylor series may be either first-order or second-order, which is automatically determined
from the gradient and Hessian specifications in the responses specification (see responses for info on how to
specify gradients and Hessians) for the truth model.

Theory
The first-order Taylor series expansion is:
f(x) f (x0 ) + x f (x0 )T (x x0 )

(6.7)

1
f(x) f (x0 ) + x f (x0 )T (x x0 ) + (x x0 )T 2x f (x0 )(x x0 )
2

(6.8)

and the second-order expansion is:

where x0 is the expansion point in n-dimensional parameter space and f (x0 ), x f (x0 ), and 2x f (x0 ) are
the computed response value, gradient, and Hessian at the expansion point, respectively.
As dictated by the responses specification used in building the local surrogate, the gradient may be analytic or
numerical and the Hessian may be analytic, numerical, or based on quasi-Newton secant updates.
In general, the Taylor series model is accurate only in the region of parameter space that is close to x0 .
While the accuracy is limited, the first-order Taylor series model reproduces the correct value and gradient at
the point x0 , and the second-order Taylor series model reproduces the correct value, gradient, and Hessian. This
consistency is useful in provably-convergent surrogate-based optimization. The other surface fitting methods do
not use gradient information directly in their models, and these methods rely on an external correction procedure
in order to satisfy the consistency requirements of provably-convergent SBO.
actual model pointer
Keywords Area
model
surrogate
local
actual model pointer
Pointer to specify a truth model, from which to construct a surrogate

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

1946

CHAPTER 6. KEYWORDS AREA

Description
This must point to a model block, identified by id model. That model will be run to generate training data, from
which a surrogate model will be constructed.
See block pointer for details about pointers.

hierarchical
Keywords Area
model
surrogate
hierarchical
Hierarchical approximations use corrected results from a low fidelity model as an approximation to the results
of a high fidelity truth model.

Specification
Alias: none
Argument(s): none
Required/Optional
Required
Required
Required

Description of
Group

Dakota Keyword
low fidelity model pointer
high fidelity model pointer
correction

Dakota Keyword
Description
Pointer to low
fidelity model
Pointer to high
fidelity model
Correction
approaches for
surrogate models

Description
Hierarchical approximations use corrected results from a low fidelity model as an approximation to the results
of a high fidelity truth model. These approximations are also known as model hierarchy, multifidelity, variable
fidelity, and variable complexity approximations. The required low fidelity model pointer specification
points to the low fidelity model specification. This model is used to generate low fidelity responses which are then
corrected and returned to an iterator. The required high fidelity model pointer specification points
to the specification for the high fidelity truth model. This model is used only for verifying low fidelity results
and updating low fidelity corrections. The correction specification specifies which correction technique will
be applied to the low fidelity results in order to match the high fidelity results at one or more points. In the
hierarchical case (as compared to the global case), the correction specification is required, since the omission
of a correction technique would effectively eliminate the purpose of the high fidelity model. If it is desired to use
a low fidelity model without corrections, then a hierarchical approximation is not needed and a single model
should be used. Refer to global for additional information on available correction approaches.

6.3. MODEL

1947

Theory
Multifidelity Surrogates : Multifidelity modeling involves the use of a low-fidelity physics-based model as a
surrogate for the original high-fidelity model. The low-fidelity model typically involves a coarser mesh, looser
convergence tolerances, reduced element order, or omitted physics. It is a separate model in its own right and
does not require data from the high-fidelity model for construction. Rather, the primary need for high-fidelity
evaluations is for defining correction functions that are applied to the low-fidelity results.
Multifidelity Surrogate Models
A second type of surrogate is the {model hierarchy} type (also called multifidelity, variable fidelity, variable
complexity, etc.). In this case, a model that is still physics-based but is of lower fidelity (e.g., coarser discretization,
reduced element order, looser convergence tolerances, omitted physics) is used as the surrogate in place of the
high-fidelity model. For example, an inviscid, incompressible Euler CFD model on a coarse discretization could
be used as a low-fidelity surrogate for a high-fidelity Navier-Stokes model on a fine discretization.

See Also
These keywords may also be of interest:
global
local
multipoint
low fidelity model pointer
Keywords Area
model
surrogate
hierarchical
low fidelity model pointer
Pointer to low fidelity model

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
low fidelity model pointer points to the model (using its id model label) to use for generating low
fidelity responses, which are corrected and returned to an iterator as explained on the parent page.

1948

CHAPTER 6. KEYWORDS AREA

high fidelity model pointer

Keywords Area
model
surrogate
hierarchical
high fidelity model pointer
Pointer to high fidelity model

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING

Description
high fidelity model pointer points to the model (using its id model label) to use for verifying low
fidelity results and updating low fidelity corrections, as explained on the parent page.
correction
Keywords Area
model
surrogate
hierarchical
correction
Correction approaches for surrogate models

Specification
Alias: none
Argument(s): none
Default: no surrogate correction
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.3. MODEL

1949
Required(Choose
One)

Required(Choose
One)

correction order
(Group 1)

correction type
(Group 2)

zeroth order

Specify that truth

values must be
matched.

first order

Specify that truth

values and
gradients must be
matched.

second order

Specify that truth

values, gradients
and Hessians must
be matched.

additive

Additive correction
factor for local
surrogate accuracy

multiplicative

Multiplicative
correction factor
for local surrogate
accuracy.

combined

Multipoint
correction for a
hierarchical
surrogate

Description
Some of the surrogate model types support the use of correction factors that improve the local accuracy of the
surrogate models.
The correction specification specifies that the approximation will be corrected to match truth data, either
matching truth values in the case of zeroth order matching, matching truth values and gradients in the case
of first order matching, or matching truth values, gradients, and Hessians in the case of second order
matching. For additive and multiplicative corrections, the correction is local in that the truth data is
matched at a single point, typically the center of the approximation region. The additive correction adds a
scalar offset (zeroth order), a linear function (first order), or a quadratic function (second order)
to the approximation to match the truth data at the point, and the multiplicative correction multiplies
the approximation by a scalar (zeroth order), a linear function (first order), or a quadratic function
(second order) to match the truth data at the point. The additive first order case is due to[57] and
the multiplicative first order case is commonly known as beta correction[40]. For the combined
correction, the use of both additive and multiplicative corrections allows the satisfaction of an additional matching
condition, typically the truth function values at the previous correction point (e.g., the center of the previous trust
region). The combined correction is then a multipoint correction, as opposed to the local additive and
multiplicative corrections. Each of these correction capabilities is described in detail in[24].
The correction factors force the surrogate models to match the true function values and possibly true function
derivatives at the center point of each trust region. Currently, Dakota supports either zeroth-, first-, or second-order
accurate correction methods, each of which can be applied using either an additive, multiplicative, or combined

1950

CHAPTER 6. KEYWORDS AREA

correction function. For each of these correction approaches, the correction is applied to the surrogate model and
the corrected model is then interfaced with whatever algorithm is being employed. The default behavior is that no
correction factor is applied.
The simplest correction approaches are those that enforce consistency in function values between the surrogate
and original models at a single point in parameter space through use of a simple scalar offset or scaling applied
to the surrogate model. First-order corrections such as the first-order multiplicative correction (also known as
beta correction[15]) and the first-order additive correction[57] also enforce consistency in the gradients and provide a much more substantial correction capability that is sufficient for ensuring provable convergence in SBO
algorithms. SBO convergence rates can be further accelerated through the use of second-order corrections which
also enforce consistency in the Hessians[24], where the second-order information may involve analytic, finitedifference, or quasi-Newton Hessians.
Correcting surrogate models with additive corrections involves
(x) = flo (x) + (x)
fhi

(6.9)

where multifidelity notation has been adopted for clarity. For multiplicative approaches, corrections take the form
(x) = flo (x)(x)
fhi

(6.10)

where, for local corrections, (x) and (x) are first or second-order Taylor series approximations to the exact
correction functions:
1
A(xc ) + A(xc )T (x xc ) + (x xc )T 2 A(xc )(x xc )
2
1
(x) = B(xc ) + B(xc )T (x xc ) + (x xc )T 2 B(xc )(x xc )
2
where the exact correction functions are
(x)

= fhi (x) flo (x)

fhi (x)
B(x) =
flo (x)
A(x)

(6.11)
(6.12)

(6.13)
(6.14)

Refer to[24] for additional details on the derivations.

A combination of additive and multiplicative corrections can provide for additional flexibility in minimizing
the impact of the correction away from the trust region center. In other words, both additive and multiplicative
corrections can satisfy local consistency, but through the combination, global accuracy can be addressed as well.
This involves a convex combination of the additive and multiplicative corrections:
(x) = fhi
(x) + (1 )fhi
(x)
fhi

where is calculated to satisfy an additional matching condition, such as matching values at the previous design
iterate.
It should be noted that in both first order correction methods, the function f(x) matches the function value and
gradients of ft (x) at x = xc . This property is necessary in proving that the first order-corrected SBO algorithms
are provably convergent to a local minimum of ft (x). However, the first order correction methods are significantly
more expensive than the zeroth order correction methods, since the first order methods require computing both
ft (xc ) and fs (xc ). When the SBO strategy is used with either of the zeroth order correction methods, or
with no correction method, convergence is not guaranteed to a local minimum of ft (x). That is, the SBO strategy
becomes a heuristic optimization algorithm. From a mathematical point of view this is undesirable, but as a
practical matter, the heuristic variants of SBO are often effective in finding local minima.
Usage guidelines

6.3. MODEL

1951

Both the additive zeroth order and multiplicative zeroth order correction methods are free
since they use values of ft (xc ) that are normally computed by the SBO strategy.
The use of either the additive first order method or the multiplicative first order method does
not necessarily improve the rate of convergence of the SBO algorithm.
When using the first order correction methods, the gradient-related response keywords must be modified
to allow either analytic or numerical gradients to be computed. This provides the gradient data needed to
compute the correction function.
For many computationally expensive engineering optimization problems, gradients often are too expensive
to obtain or are discontinuous (or may not exist at all). In such cases the heuristic SBO algorithm has been
an effective approach at identifying optimal designs[35].
zeroth order
Keywords Area
model
surrogate
hierarchical
correction
zeroth order
Specify that truth values must be matched.

Specification
Alias: none
Argument(s): none

Description
The correction specification specifies that the approximation will be corrected to match truth data. The keyword
zeroth order matching ensures that truth values are matched.
first order
Keywords Area
model
surrogate
hierarchical
correction
first order
Specify that truth values and gradients must be matched.

1952

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
This correction specification specifies that the approximation will be corrected to match truth data. The keyword
first order matching ensures that truth values and gradients are matched.
second order
Keywords Area
model
surrogate
hierarchical
correction
second order
Specify that truth values, gradients and Hessians must be matched.

Specification
Alias: none
Argument(s): none

Description
The correction specification specifies that the approximation will be corrected to match truth data. The keyword
second order matching ensures that truth values, gradients and Hessians are matched.
additive
Keywords Area
model
surrogate
hierarchical
correction
additive
Additive correction factor for local surrogate accuracy

Specification
Alias: none
Argument(s): none

6.3. MODEL

1953

Description
Use an additive correction factor to improve the local accuracy of a surrogate.
multiplicative
Keywords Area
model
surrogate
hierarchical
correction
multiplicative
Multiplicative correction factor for local surrogate accuracy.

Specification
Alias: none
Argument(s): none

Description
Use a multiplicative correction factor to improve the local accuracy of a surrogate.
combined
Keywords Area
model
surrogate
hierarchical
correction
combined
Multipoint correction for a hierarchical surrogate

Specification
Alias: none
Argument(s): none

Description
For the combined correction, the use of both additive and multiplicative corrections allows the satisfaction of an
additional matching condition, typically the truth function values at the previous correction point (e.g., the center
of the previous trust region). The combined correction is then a multipoint correction, as opposed to the local
additive and multiplicative corrections.

1954

6.3.7

CHAPTER 6. KEYWORDS AREA

nested

Keywords Area
model
nested
A model whose responses are computed through the use of a sub-iterator

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Required

Dakota Keyword
optional interfacepointer

sub method pointer

Dakota Keyword
Description
Pointer to interface
that provides
non-nested
responses
The
sub method pointer
specifies the
method block for
the sub-iterator

Description
Instead of appealing directly to a primary interface, a nested model maps variables to responses by executing a
secondary iterator, or a sub-iterator. In other words, a function evaluation of the primary study consists of a
solution of an entire secondary study - potentially many secondary function evaluations.
The sub-iterator in turn operates on a sub-model. The sub-iterator responses may be combined with non-nested
contributions from an optional interface specification.
A sub method pointer must be provided in order to specify the method block describing the sub-iterator.
The remainder of the model is specified under that keyword.
A optional interface pointer points to the interface specification and optional interfaceresponses pointer points to a responses specification describing the data to be returned by this interface).
This interface is used to provide non-nested data, which is then combined with data from the nested iterator using
the primary response mapping and secondary response mapping inputs (see mapping discussion
below).

Examples
An example of variable and response mappings is provided below:
primary_variable_mapping = X
Y
secondary_variable_mapping = mean mean
primary_response_mapping = 1. 0. 0. 0. 0. 0. 0. 0. 0.
secondary_response_mapping = 0. 0. 0. 1. 3. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0. 1. 3. 0.

6.3. MODEL

1955

The variable mappings correspond to 4 top-level variables, the first two of which employ the default mappings
from active top-level variables to sub-model variables of the same type (option 3 above) and the latter two of
which are inserted into the mean distribution parameters of sub-model variables X and Y (option 1 above).
The response mappings define a 3 by 9 matrix corresponding to 9 inner loop response attributes and 3 outer
loop response functions (one primary response function and 2 secondary functions, such as one objective and
two constraints). Each row of the response mapping is a vector which is multiplied (i.e, with a dot-product)
against the 9 sub-iterator values to determine the outer loop function. Consider a UQ example with 3 response
functions, each providing a mean, a standard deviation, and one level mapping (if no level mappings are specified,
the responses would only have a mean and standard deviation). The primary response mapping can be seen to
extract the first value from the inner loop, which would correspond to the mean of the first response function.
This mapped sub-iterator response becomes a single objective function, least squares term, or generic response
function at the outer level, as dictated by the top-level response specification. The secondary response mapping
maps the fourth sub-iterator response function plus 3 times the fifth sub-iterator response function (mean plus 3
standard deviations) into one top-level nonlinear constraint and the seventh sub-iterator response function plus 3
times the eighth sub-iterator response function (mean plus 3 standard deviations) into another top-level nonlinear
constraint, where these top-level nonlinear constraints may be inequality or equality, as dictated by the top-level
response specification. Note that a common case is for each sub-iterator response to be mapped to a unique outer
loop response (for example, in the nested UQ case where one wants to determine an interval on each inner loop
statistic). In these simple cases, the response mapping would define an identity matrix.

See Also
These keywords may also be of interest:
single
surrogate
optional interface pointer
Keywords Area
model
nested
optional interface pointer
Pointer to interface that provides non-nested responses

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: no optional interface

1956

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
optional interfaceresponses pointer

Dakota Keyword
Description
Pointer to
responses block
that defines
non-nested
responses

Description
optional interface pointer is used to specify an optional inferface (using that interface blocks id interface label) to provide non-nested responses, which will be combined with respones from the nested subiterator. The primary response mapping and secondary response mapping keywords control how
responses are combined.
optional interface responses pointer
Keywords Area
model
nested
optional interface pointer
optional interface responses pointer
Pointer to responses block that defines non-nested responses

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Default: reuse of top-level responses specification

Description
optional interface responses pointer points to the reponses block (specifically, its id responses
label) that defines the non-nested response to return to the nested model. The primary response mapping
and secondary response mapping keywords control how these non-nested respones are combined with
responses from the nested sub-iterator. If optional interface responses pointer is not provided,
the top-level responses specification is reused.

6.3. MODEL

1957

sub method pointer

Keywords Area
model
nested
sub method pointer
The sub method pointer specifies the method block for the sub-iterator

Topics
This keyword is related to the topics:
block pointer

Specification
Alias: none
Argument(s): STRING
Required/Optional
Optional

Description of
Group

Dakota Keyword
iterator servers

Optional

iterator scheduling

Optional

processors per iterator

Optional

primary variable mapping

Dakota Keyword
Description
Specify the
number of iterator
servers when
Dakota is run in
parallel
Specify the
scheduling of
concurrent iterators
when Dakota is run
in parallel
Specify the
number of
processors per
iterator server
when Dakota is run
in parallel
Primary mappning
of top-level
variables to
sub-model
variables

1958

CHAPTER 6. KEYWORDS AREA

Optional

secondary variable mapping

Optional

primary response mapping

Optional

secondary response mapping

Secondary
mappning of
top-level variables
to sub-model
variables
Primary mappning
of sub-model
responses to
top-level responses
Secondary
mappning of
sub-model
responses to
top-level responses

Description
The sub method pointer specifies the method block for the sub-iterator.
See block pointer for details about pointers.
Nested models may employ mappings for both the variable inputs to the sub-model and the response outputs
from the sub-model. In the former case, the primary variable mapping and secondary variablemapping specifications are used to map from the active top-level variables into the sub-model variables, and
in the latter case, the primary response mapping and secondary response mapping specifications
are used to compute the sub-model response contributions to the top-level responses.
For the variable mappings, the primary and secondary specifications provide lists of strings which are used
to target specific sub-model variables and their sub-parameters, respectively. The primary strings are matched to
continuous or discrete variable labels such as cdv 1 (either user-supplied or default labels), and the secondary
strings are matched to either real or integer random variable distribution parameters such as mean or numtrials (the form of the uncertain distribution parameter keyword that is appropriate for a single variable
instance) or continuous or discrete design/state variable sub-parameters such as lower bound or upperbound (again, keyword form appropriate for a single variable instance). No coercion of types is supported, so
real-valued top-level variables should map to either real-valued sub-model variables or real-valued sub-parameters
and integer-valued top-level variables should map to either integer-valued sub-model variables or integer-valued
sub-parameters. As long as these real versus integer constraints are satisfied, mappings are free to cross variable types (design, aleatory uncertain, epistemic uncertain, state) and domain types (continuous, discrete). Both
primary variable mapping and secondary variable mapping specifications are optional, which
is designed to support the following three possibilities:
1. If both primary and secondary variable mappings are specified, then an active top-level variable value will
be inserted into the identified sub-parameter (the secondary mapping) for the identified sub-model variable
(the primary mapping).
2. If a primary mapping is specified but a secondary mapping is not, then an active top-level variable value
will be inserted into the identified sub-model variable value (the primary mapping).
3. If a primary mapping is not specified (corresponding secondary mappings, if specified, are ignored), then
an active top-level variable value will be inserted into a corresponding sub-model variable, based on
matching of variable types (e.g., top-level and sub-model variable specifications both allocate a set of
continuous design variables which are active at the top level). Multiple sub-model variable types
may be updated in this manner, provided that they are all active in the top-level variables. Since there is a
direct variable correspondence for these default insertions, sub-model bounds and labels are also updated

6.3. MODEL

1959

from the top-level bounds and labels in order to eliminate the need for redundant input file specifications.
Thus, it is typical for the sub-model variables specification to only contain the minimal required information, such as the number of variables, for these insertion targets. The sub-model must allocate enough space
for each of the types that will accept default insertions, and the leading set of matching sub-model variables
are updated (i.e., the sub-model may allocate more than needed and the trailing set will be unmodified).
These different variable mapping possibilities may be used in any combination by employing empty strings
() for particular omitted mappings (the number of strings in user-supplied primary and secondary variable
mapping specifications must equal the total number of active top-level variables, including both continuous and
discrete types). The ordering of the active variables is the same as shown in dakota.input.summary on Input Spec
Summary and as presented in variables.
If inactive variables are present at the outer level, then the default type 3 mapping is used for these variables;
that is, outer loop inactive variables are inserted into inner loop variables (active or inactive) based on matching
of variable types, top-level bounds and labels are also propagated, the inner loop must allocate sufficient space to
receive the outer loop values, and the leading subset within this inner loop allocation is updated. This capability
is important for allowing nesting beyond two levels, since an active variable at the outer-most loop may become
inactive at the next lower level, but still needs to be further propagated down to lower levels in the recursion.
For the response mappings, the primary and secondary specifications provide real-valued multipliers to be
applied to sub-iterator response results so that the responses from the inner loop can be mapped into a new
set of responses at the outer loop. For example, if the nested model is being employed within a mixed aleatoryepistemic uncertainty quantification, then aleatory statistics from the inner loop (such as moments of the response)
are mapped to the outer level, where minima and maxima of these aleatory statistics are computed as functions of
the epistemic parameters. The response mapping defines a matrix which scales the values from the inner loop and
determines their position in the outer loop response vector. Each row of the mapping corresponds to one outer
loop response, where each column of the mapping corresponds to a value from the inner loop. Depending on the
number of responses and the particular attributes calculated on the inner loop, there will be a vector of inner loop
response values that need to be accounted for in the mapping. This vector of inner loop response results is defined
as follows for different sub-iterator types:
optimization: the final objective function(s) and nonlinear constraints
nonlinear least squares: the final least squares terms and nonlinear constraints
aleatory uncertainty quantification (UQ): for each response function, a mean statistic, a standard deviation
statistic, and all probability/reliability/generalized reliability/response level results for any user-specified
response levels, probability levels, reliability levels, and/or gen reliabilitylevels, in that order.
epistemic and mixed aleatory/epistemic UQ using interval estimation methods: lower and upper interval
bounds for each response function.
epistemic and mixed aleatory/epistemic UQ using evidence methods: for each response function, lower and
upper interval bounds (belief and plausibility) for all probability/reliability/generalized reliability/response
level results computed from any user-specified response levels, probability levels, reliabilitylevels, and/or gen reliability levels, in that order.
parameter studies and design of experiments: for optimization and least squares response data sets, the best
solution found (lowest constraint violation if infeasible, lowest composite objective function if feasible).
For generic response data sets, a best solution metric is not defined, so the sub-iterator response vector is
empty in this case.

1960

CHAPTER 6. KEYWORDS AREA

The primary values map sub-iterator response results into top-level objective functions, least squares terms,
or generic response functions, depending on the declared top-level response set. The secondary values map subiterator response results into top-level nonlinear inequality and equality constraints.
Nested models utilize a sub-iterator and a sub-model to perform a complete iterative study as part of every
evaluation of the model. This sub-iteration accepts variables from the outer level, performs the sub-level analysis,
and computes a set of sub-level responses which are passed back up to the outer level. Mappings are employed
for both the variable inputs to the sub-model and the response outputs from the sub-model.
In the variable mapping case, primary and secondary variable mapping specifications are used to map from the
top-level variables into the sub-model variables. These mappings support three possibilities in any combination: (1) insertion of an active top-level variable value into an identified sub-model distribution parameter for an
identified active sub-model variable, (2) insertion of an active top-level variable value into an identified active
sub-model variable value, and (3) addition of an active top-level variable value as an inactive sub-model variable,
augmenting the active sub-model variables.
In the response mapping case, primary and secondary response mapping specifications are used to map from
the sub-model responses back to the top-level responses. These specifications provide real-valued multipliers that
are applied to the sub-iterator response results to define the outer level response set. These nested data results may
be combined with non-nested data through use of the optional interface component within nested models.
The nested model constructs admit a wide variety of multi-iterator, multi-model solution approaches. For
example, optimization within optimization (for hierarchical multidisciplinary optimization), uncertainty quantification within uncertainty quantification (for second-order probability), uncertainty quantification within optimization (for optimization under uncertainty), and optimization within uncertainty quantification (for uncertainty of
optima) are all supported, with and without surrogate model indirection. Several examples of nested model usage
are provided in the Users Manual, most notably mixed epistemic-aleatory UQ, optimization under uncertainty
(OUU), and surrogate-based UQ.
iterator servers
Keywords Area
model
nested
sub method pointer
iterator servers
Specify the number of iterator servers when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

6.3. MODEL

1961

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator servers specification supports user override of the automatic parallel configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.
iterator scheduling
Keywords Area
model
nested
sub method pointer
iterator scheduling
Specify the scheduling of concurrent iterators when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
master

peer

Dakota Keyword
Description
Specify a
dedicated master
partition for
parallel iterator
scheduling
Specify a peer
partition for
parallel iterator
scheduling

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional iterator scheduling specification supports user override of the automatic parallel
configuration for the number of iterator servers. That is, if the automatic configuration is undesirable for some
reason, the user can enforce a desired number of partitions at the iterator parallelism level. Currently, hybrid,
multi start, and pareto set component-based iterators support concurrency in their sub-iterators. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.

1962

CHAPTER 6. KEYWORDS AREA

master
Keywords Area
model
nested
sub method pointer
iterator scheduling
master
Specify a dedicated master partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a dedicated master partition.
In a dedicated master partition, one processor (the master) dynamically schedules work on the iterator servers.
This reduces the number of processors available to create servers by 1.
peer
Keywords Area
model
nested
sub method pointer
iterator scheduling
peer
Specify a peer partition for parallel iterator scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

6.3. MODEL

1963

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a peer partition. In a peer partition, all processors are available to be assigned to iterator servers. Note that unlike the case of evaluation scheduling, it is not possible to specify static or dynamic.
processors per iterator
Keywords Area
model
nested
sub method pointer
processors per iterator
Specify the number of processors per iterator server when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

Description
An important feature for component-based iterators is that execution of sub-iterator runs may be performed concurrently. The optional processors per iterator specification supports user override of the automatic
parallel configuration for the number of processors in each iterator server. That is, if the automatic configuration is undesirable for some reason, the user can enforce a desired server size at the iterator parallelism level.
Currently, hybrid, multi start, and pareto set component-based iterators support concurrency in their
sub-iterators. Refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual[4] for additional
information.
primary variable mapping
Keywords Area
model
nested

1964

CHAPTER 6. KEYWORDS AREA

sub method pointer

primary variable mapping
Primary mappning of top-level variables to sub-model variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: default variable insertions based on variable type

Description
The primary variable mapping, secondary variable mapping, primary response mapping,
and secondary response mapping keywords control how top-level variables and responses are mapped to
variables and responses in the sub-model. Their usage is explained on the parent keyword (sub method pointer) page.
secondary variable mapping
Keywords Area
model
nested
sub method pointer
secondary variable mapping
Secondary mappning of top-level variables to sub-model variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: primary mappings into sub-model variables are value-based

Description
The primary variable mapping, secondary variable mapping, primary response mapping,
and secondary response mapping keywords control how top-level variables and responses are mapped to
variables and responses in the sub-model. Their usage is explained on the parent keyword (sub method pointer) page.

6.3. MODEL

1965

primary response mapping

Keywords Area
model
nested
sub method pointer
primary response mapping
Primary mappning of sub-model responses to top-level responses

Specification
Alias: none
Argument(s): REALLIST
Default: no sub-iterator contribution to primary functions

Description
The primary variable mapping, secondary variable mapping, primary response mapping,
and secondary response mapping keywords control how top-level variables and responses are mapped to
variables and responses in the sub-model. Their usage is explained on the parent keyword (sub method pointer) page.
secondary response mapping
Keywords Area
model
nested
sub method pointer
secondary response mapping
Secondary mappning of sub-model responses to top-level responses

Specification
Alias: none
Argument(s): REALLIST
Default: no sub-iterator contribution to secondary functions

Description
The primary variable mapping, secondary variable mapping, primary response mapping,
and secondary response mapping keywords control how top-level variables and responses are mapped to
variables and responses in the sub-model. Their usage is explained on the parent keyword (sub method pointer) page.

1966

6.4

CHAPTER 6. KEYWORDS AREA

variables

Keywords Area
variables
Specifies the parameter set to be iterated by a particular method.

Topics
This keyword is related to the topics:
block

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

id variables

Optional

Optional(Choose
One)

Optional

Dakota Keyword

Group 1

Dakota Keyword
Description
Name the variables
block; helpful
when there are
multiple

active

Set the active

variables view a
method will see

mixed

Maintain
continuous/discrete
variable distinction

relaxed

Allow treatment of
discrete variables
as continuous

continuous design

Continuous design
variables; each
defined by a real
interval

6.4. VARIABLES

1967
Optional

discrete design range

Discrete design
variables; each
defined by an
integer interval

Optional

discrete design set

Set-valued discrete
design variables

Optional

normal uncertain

Optional

lognormal uncertain

Optional

uniform uncertain

Optional

loguniform uncertain

Optional

triangular uncertain

Optional

exponential uncertain

Optional

beta uncertain

Optional

gamma uncertain

Optional

gumbel uncertain

Optional

frechet uncertain

Optional

weibull uncertain

Optional

histogram bin uncertain

Aleatory uncertain
variable - normal
(Gaussian)
Aleatory uncertain
variable lognormal
Aleatory uncertain
variable - uniform
Aleatory uncertain
variable loguniform
Aleatory uncertain
variable triangular
Aleatory uncertain
variable exponential
Aleatory uncertain
variable - beta
Aleatory uncertain
variable - gamma
Aleatory uncertain
variable - gumbel
Aleatory uncertain
variable - Frechet
Aleatory uncertain
variable - Weibull
Aleatory uncertain
variable continuous
histogram

1968

CHAPTER 6. KEYWORDS AREA

Optional

poisson uncertain

Optional

binomial uncertain

Optional

negative binomialuncertain

Optional

geometric uncertain

Optional

hypergeometric uncertain

Optional

histogram point uncertain

Optional

uncertain correlation matrix

Correlation among
aleatory uncertain
variables

Optional

continuous interval uncertain

Epistemic
uncertain variable values from one or
more continuous
intervals

Optional

discrete interval uncertain

Epistemic
uncertain variable values from one or
more discrete
intervals

Optional

discrete uncertainset

Set-valued discrete
uncertain variables

Optional

continuous state

Optional

discrete state range

Continuous state
variables
Discrete state
variables; each
defined by an
integer interval

Aleatory uncertain
discrete variable Poisson
Aleatory uncertain
discrete variable binomial
Aleatory uncertain
discrete variable negative binomial
Aleatory uncertain
discrete variable geometric
Aleatory uncertain
discrete variable hypergeometric
Aleatory uncertain
variable - discrete
histogram

6.4. VARIABLES

1969
Optional

discrete state set

Set-valued discrete
state variables

Description
The variables specification in a Dakota input file specifies the parameter set to be iterated by a particular
method.
In the case of
An optimization study:
These variables are adjusted in order to locate an optimal design.
Parameter studies/sensitivity analysis/design of experiments:
These parameters are perturbed to explore the parameter space.
Uncertainty analysis:
The variables are associated with distribution/interval characterizations which are used to compute
corresponding distribution/interval characterizations for response functions.
To accommodate these different studies, Dakota supports different:
Variable types
design
aleatory uncertain
epistemic uncertain
state
Variable domains
continuous
discrete

discrete range
discrete integer set
discrete string set
discrete real set

Use the variables page to browse the available variables by type and domain.
Variable Types
Design Variables
Design variables are those variables which are modified for the purposes of computing an optimal
design.
The most common type of design variables encountered in engineering applications are of the continuous type. These variables may assume any real value within their bounds.
All but a handful of the optimization algorithms in Dakota support continuous design variables exclusively.

1970

CHAPTER 6. KEYWORDS AREA

Aleatory Uncertain Variables

Aleatory uncertainty is also known as inherent variability, irreducible uncertainty, or randomness.
Aleatory uncertainty is predominantly characterized using probability theory. This is the only option
implemented in Dakota.
Epistemic Uncertain Variables
Epistemic uncertainty is uncertainty due to lack of knowledge.
In Dakota, epistemic uncertainty is characterized by interval analysis or the Dempster-Shafer theory
of evidence.
Note that epistemic uncertainty can also be modeled with probability density functions (as done with
aleatory uncertainty). Dakota does not support this capability.
State Variables
State variables consist of other variables which are to be mapped through the simulation interface,
in that they are not to be used for design and they are not modeled as being uncertain.
State variables provide a convenient mechanism for managing additional model parameterizations
such as mesh density, simulation convergence tolerances, and time step controls.
Only parameter studies and design of experiments methods will iterate on state variables.
The initial value is used as the only value for the state variable for all other methods, unless
active state is invoked.
See more details on the state variables page.
Variable Domains
Continuous variables are defined by bounds. Discrete variables can be defined in one of three ways, which are
discussed on the page discrete variables.
Ordering of Variables
The ordering of variables is important, and a consistent ordering is employed throughout the Dakota software.
The ordering is shown in dakota.input.summary and can be summarized as:
1. design
(a) continuous
(b) discrete integer
(c) discrete string
(d) discrete real
2. aleatory uncertain
(a) continuous
(b) discrete integer
(c) discrete string
(d) discrete real
3. epistemic uncertain
(a) continuous

6.4. VARIABLES

1971

(b) discrete integer

(c) discrete string
(d) discrete real
4. state
(a) continuous
(b) discrete integer
(c) discrete string
(d) discrete real
Ordering of variable types below this granularity (e.g., from normal to histogram bin within aleatory uncertain
- continuous ) is defined somewhat arbitrarily, but is enforced consistently throughout the code.
Active Variables
The reason variable types exist is that methods have the capability to treat variable types differently. All
methods have default behavior that determines which variable types are active and will be assigned values by
the method. For example, optimization methods will only vary the design variables - by default.
The default behavior should be described on each method page, or on topics pages that relate to classes of
methods. In addition, the default behavior can be modified using the active keyword.

Examples
Several examples follow. In the first example, two continuous design variables are specified:
variables,
continuous_design = 2
initial_point
0.9
1.1
upper_bounds
5.8
2.9
lower_bounds
0.5
-2.9
descriptors
radius location

In the next example, defaults are employed. In this case, initial point will default to a vector of 0.
values, upper bounds will default to vector values of DBL MAX (the maximum number representable in double
precision for a particular platform, as defined in the platforms float.h C header file), lower bounds will
default to a vector of -DBL MAX values, and descriptors will default to a vector of cdv i strings, where
i ranges from one to two:
variables,
continuous_design = 2

In the following example, the syntax for a normal-lognormal distribution is shown. One normal and one
lognormal uncertain variable are completely specified by their means and standard deviations. In addition, the
dependence structure between the two variables is specified using the uncertain correlation matrix.
variables,
normal_uncertain
= 1
means
= 1.0
std_deviations
= 1.0
descriptors
= TF1n
lognormal_uncertain = 1
means
= 2.0
std_deviations
= 0.5
descriptors
= TF2ln
uncertain_correlation_matrix =

1.0 0.2
0.2 1.0

1972

CHAPTER 6. KEYWORDS AREA

An example of the syntax for a state variables specification follows:

variables,
continuous_state = 1
initial_state
4.0
lower_bounds
0.0
upper_bounds
8.0
descriptors
CS1
discrete_state_range = 1
initial_state
104
lower_bounds
100
upper_bounds
110
descriptors
DS1

And in a more advanced example, a variables specification containing a set identifier, continuous and discrete
design variables, normal and uniform uncertain variables, and continuous and discrete state variables is shown:
variables,
id_variables = V1
continuous_design = 2
initial_point
0.9
1.1
upper_bounds
5.8
2.9
lower_bounds
0.5
-2.9
descriptors
radius location
discrete_design_range = 1
initial_point
2
upper_bounds
1
lower_bounds
3
descriptors
material
normal_uncertain = 2
means
= 248.89, 593.33
std_deviations =
12.4,
29.7
descriptors
= TF1n
TF2n
uniform_uncertain = 2
lower_bounds = 199.3, 474.63
upper_bounds = 298.5, 712.
descriptors = TF1u
TF2u
continuous_state = 2
initial_state = 1.e-4 1.e-6
descriptors
= EPSIT1 EPSIT2
discrete_state_set_int = 1
initial_state = 100
set_values
= 100 212 375
descriptors
= load_case

6.4.1

id variables

Keywords Area
variables
id variables
Name the variables block; helpful when there are multiple

Topics
This keyword is related to the topics:
block pointer

6.4. VARIABLES

1973

Specification
Alias: none
Argument(s): STRING
Default: use of last variables parsed

Description
The optional set identifier specification uses the keyword id variables to input a unique string for use in
identifying a particular variables set. A model can then identify the use of this variables set by specifying the
same string in its variables pointer specification.
If the id variables specification is omitted, a particular variables set will be used by a model only if that
model omits specifying a variables pointer and if the variables set was the last set parsed (or is the only set
parsed). In common practice, if only one variables set exists, then id variables can be safely omitted from
the variables specification and variables pointer can be omitted from the model specification(s), since
there is no potential for ambiguity in this case.

Examples
For example, a model whose specification contains variables pointer = V1 will use a variables specification containing the set identifier id variables = V1.

See Also
These keywords may also be of interest:
variables pointer

6.4.2

active

Keywords Area
variables
active
Set the active variables view a method will see

Specification
Alias: none
Argument(s): none
Default: Infer from response or method specification
Required/Description of
Optional
Group

Dakota Keyword
all

Required(Choose
One)

Group 1

Dakota Keyword
Description
Option for the
active keyword

1974

CHAPTER 6. KEYWORDS AREA

design
uncertain
aleatory
epistemic
state

Option for the

active keyword
Option for the
active keyword
Option for the
active keyword
Option for the
active keyword
Option for the
active keyword

Description
There are certain situations where the user may want to explicitly control the subset of variables that is considered
active for a certain Dakota method. This is done by specifying the keyword active in the variables specification
block, followed by one of the following: all, design, uncertain, aleatory, epistemic, or state.
Specifying one of these subsets of variables will allow the Dakota method to operate on the specified variable
types and override the default active subset.
If the user does not specify any explicit override of the active view of the variables, Dakota first considers the
response function specification.
If the user specifies objective functions or calibration terms in the response specification block, then we
can infer that the active variables should be the design variables (since design variables are used within
optimization and least squares methods).
If the user instead specifies the generic response type of response functions, then Dakota cannot
infer the active variable subset from the response specification and will instead infer it from the method
selection.
1. If the method is a parameter study, or any of the methods available under dace, psuade, or fsu methods,
the active view is set to all variables.
2. For uncertainty quantification methods, if the method is sampling, then the view is set to aleatory
if only aleatory variables are present, epistemic if only epistemic variables are present, or uncertain
(covering both aleatory and epistemic) if both are present.
3. If the uncertainty method involves interval estimation or evidence calculations, the view is set to
epistemic.
4. For other uncertainty quantification methods not mentioned in the previous sentences (e.g., reliability
methods or stochastic expansion methods), the default view is set to aleatory.
5. Finally, for verification studies using the Richardson extrapolation method, the active view is set to
state.
6. Note that in surrogate-based optimization, where the surrogate is built on points defined by the method
defined by the dace method pointer, the sampling used to generate the points is performed only
over the design variables as a default unless otherwise specified (e.g. state variables will not be
sampled for surrogate construction).
As alluded to in the previous section, the iterative method selected for use in Dakota determines what subset,
or view, of the variables data is active in the iteration. The general case of having a mixture of various different
types of variables is supported within all of the Dakota methods even though certain methods will only modify
certain types of variables (e.g., optimizers and least squares methods only modify design variables, and uncertainty
quantification methods typically only utilize uncertain variables). This implies that variables which are not under

6.4. VARIABLES

1975

the direct control of a particular iterator will be mapped through the interface in an unmodified state. This allows
for a variety of parameterizations within the model in addition to those which are being used by a particular
iterator, which can provide the convenience of consolidating the control over various modeling parameters in a
single file (the Dakota input file). An important related point is that the variable set that is active with a particular
iterator is the same variable set for which derivatives are typically computed.

Examples
For example, the default behavior for a nondeterministic sampling method is to sample the uncertain variables.
However, if the user specifed active all in the variables specification block, the sampling would be performed
over all variables (e.g. design and state variables in addition to the uncertain variables). This may be desired in
situations such as surrogate-based optimization under uncertainty, where a surrogate may be constructed to span
both design and uncertain variables. This is an example where we expand the active subset beyond the default, but
in other situations, we may wish to restrict from the default. An example of this would be performing design of
experiments in the presence of multiple variable types (for which all types are active by default), but only wanting
to sample over the design variables for purposes of constructing a surrogate model for optimization.

Theory
The optional status of the different variable type specifications allows the user to specify only those variables
which are present (rather than explicitly specifying that the number of a particular type of variables is zero).
However, at least one type of variables that are active for the iterator in use must have nonzero size or an input
error message will result.
all
Keywords Area
variables
active
all
Option for the active keyword

Specification
Alias: none
Argument(s): none

Description
See the active keyword
design
Keywords Area
variables
active

1976
design
Option for the active keyword

Specification
Alias: none
Argument(s): none

Description
See the active keyword
uncertain
Keywords Area
variables
active
uncertain
Option for the active keyword

Specification
Alias: none
Argument(s): none

Description
See the active keyword
aleatory
Keywords Area
variables
active
aleatory
Option for the active keyword

Specification
Alias: none
Argument(s): none

Description
See the active keyword

CHAPTER 6. KEYWORDS AREA

6.4. VARIABLES
epistemic
Keywords Area
variables
active
epistemic
Option for the active keyword

Specification
Alias: none
Argument(s): none

Description
See the active keyword
state
Keywords Area
variables
active
state
Option for the active keyword

Specification
Alias: none
Argument(s): none

Description
See the active keyword

6.4.3

mixed

Keywords Area
variables
mixed
Maintain continuous/discrete variable distinction

1977

1978

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: relaxed (branch and bound), mixed (all other methods)

Description
The variables domain specifies how the discrete variables are treated. If the user specifies mixed in the variable
specification block, the continuous and discrete variables are treated separately. If the user specifies relaxed in
the variable specification block, the discrete variables are relaxed and treated as continuous variables. This may
be useful in optimization problems involving both continuous and discrete variables when a user would like to use
an optimization method that is designed for continuous variable optimization. All Dakota methods have a default
value of mixed for the domain type except for the branch-and-bound method which has a default domain type of
relaxed. Note that the branch-and-bound method is under development at this time. Finally, note that the domain
selection applies to all variable types: design, aleatory uncertain, epistemic uncertain, and state.
With respect to domain type, if the user does not specify an explicit override of mixed or relaxed, Dakota
infers the domain type from the method. As mentioned above, all methods currently use a mixed domain as a
default, except the branch-and-bound method which is under development.

See Also
These keywords may also be of interest:
relaxed

6.4.4

relaxed

Keywords Area
variables
relaxed
Allow treatment of discrete variables as continuous

Specification
Alias: none
Argument(s): none

Description
The variables domain specifies how the discrete variables are treated. If the user specifies mixed in the variable
specification block, the continuous and discrete variables are treated separately. If the user specifies relaxed in
the variable specification block, the discrete variables are relaxed and treated as continuous variables. This may
be useful in optimization problems involving both continuous and discrete variables when a user would like to use
an optimization method that is designed for continuous variable optimization. All Dakota methods have a default
value of mixed for the domain type except for the branch-and-bound method which has a default domain type of
relaxed. Note that the branch-and-bound method is under development at this time. Finally, note that the domain
selection applies to all variable types: design, aleatory uncertain, epistemic uncertain, and state.

6.4. VARIABLES

1979

With respect to domain type, if the user does not specify an explicit override of mixed or relaxed, Dakota
infers the domain type from the method. As mentioned above, all methods currently use a mixed domain as a
default, except the branch-and-bound method which is under development.

See Also
These keywords may also be of interest:
mixed

6.4.5

continuous design

Keywords Area
variables
continuous design
Continuous design variables; each defined by a real interval

Topics
This keyword is related to the topics:
continuous variables
design variables

Specification
Alias: none
Argument(s): INTEGER
Default: no continuous design variables
Required/Optional
Optional

Description of
Group

Dakota Keyword
initial point

Optional

lower bounds

Optional

upper bounds

Optional

scale types

Optional

scales

Optional

descriptors

Description
Continuous variables that are changed during the search for the optimal design.

Dakota Keyword
Description
Initial values
Specify minimum
values
Specify maximium
values
Specify scaling for
the variables
Specify scaling for
the variable.
Labels for the
variables

1980

CHAPTER 6. KEYWORDS AREA

initial point
Keywords Area
variables
continuous design
initial point
Initial values

Specification
Alias: cdv initial point
Argument(s): REALLIST
Default: 0.0

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
lower bounds
Keywords Area
variables
continuous design
lower bounds
Specify minimum values

Specification
Alias: cdv lower bounds
Argument(s): REALLIST
Default: -infinity

Description
Specify minimum values
upper bounds
Keywords Area
variables
continuous design
upper bounds
Specify maximium values

6.4. VARIABLES

1981

Specification
Alias: cdv upper bounds
Argument(s): REALLIST
Default: infinity

Description
Specify maximium values
scale types
Keywords Area
variables
continuous design
scale types
Specify scaling for the variables

Specification
Alias: cdv scale types
Argument(s): STRINGLIST
Default: vector values = none

Description
For continuous variables, the scale types specification includes strings specifying the scaling type for each
component of the continuous design variables vector in methods that support scaling, when scaling is enabled.
Each entry in scale types may be selected from none, value, auto, or log, to select no,
characteristic value, automatic, or logarithmic scaling, respectively. If a single string is specified it will apply to
all components of the continuous design variables vector. Each entry in scales may be a user-specified nonzero
real characteristic value to be used in scaling each variable component. These values are ignored for scaling type
none, required for value, and optional for auto and log. If a single real value is specified it will
apply to all components of the continuous design variables vector.

Examples
Two continuous design variables, one scaled by a value, the other log scaled,
continuous_design = 2
initial_point
-1.2
1.0
lower_bounds
-2.0
0.001
upper_bounds
2.0
2.0
descriptors
x1
"x2"
scale_types =
value log
scales =
4.0
0.1

1982

CHAPTER 6. KEYWORDS AREA

scales
Keywords Area
variables
continuous design
scales
Specify scaling for the variable.

Specification
Alias: cdv scales
Argument(s): REALLIST
Default: vector values = 1 . (no scaling)

Description
For continuous variables, the scale types specification includes strings specifying the scaling type for each
component of the continuous design variables vector in methods that support scaling, when scaling is enabled.
Each entry in scale types may be selected from none, value, auto, or log, to select no,
characteristic value, automatic, or logarithmic scaling, respectively. If a single string is specified it will apply to
all components of the continuous design variables vector. Each entry in scales may be a user-specified nonzero
real characteristic value to be used in scaling each variable component. These values are ignored for scaling type
none, required for value, and optional for auto and log. If a single real value is specified it will
apply to all components of the continuous design variables vector.

Examples
Two continuous design variables, both scaled by the characteristic value 4.0
continuous_design = 2
initial_point
-1.2
1.0
lower_bounds
-200
0.001
upper_bounds
200
2.0
descriptors
x1
"x2"
scale_types = value none
scales = 10.0

descriptors
Keywords Area
variables
continuous design
descriptors
Labels for the variables

6.4. VARIABLES

1983

Specification
Alias: cdv descriptors
Argument(s): STRINGLIST
Default: cdv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.6

discrete design range

Keywords Area
variables
discrete design range
Discrete design variables; each defined by an integer interval

Topics
This keyword is related to the topics:
discrete variables
design variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete design variables
Required/Optional
Optional

Description of
Group

Dakota Keyword
initial point

Optional

lower bounds

Optional

upper bounds

Optional

descriptors

Dakota Keyword
Description
Initial values
Specify minimum
values
Specify maximium
values
Labels for the
variables

Description
These variables take on a range of integer values from the specified lower bound to the specified upper bound.
The details of how to specify this discrete variable are located on the discrete variables page.

1984

CHAPTER 6. KEYWORDS AREA

initial point
Keywords Area
variables
discrete design range
initial point
Initial values

Specification
Alias: ddv initial point
Argument(s): INTEGERLIST
Default: 0

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
lower bounds
Keywords Area
variables
discrete design range
lower bounds
Specify minimum values

Specification
Alias: ddv lower bounds
Argument(s): INTEGERLIST
Default: INT MIN

Description
Specify minimum values
upper bounds
Keywords Area
variables
discrete design range
upper bounds
Specify maximium values

6.4. VARIABLES

1985

Specification
Alias: ddv upper bounds
Argument(s): INTEGERLIST
Default: INT MAX

Description
Specify maximium values
descriptors
Keywords Area
variables
discrete design range
descriptors
Labels for the variables

Specification
Alias: ddv descriptors
Argument(s): STRINGLIST
Default: ddriv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.7

discrete design set

Keywords Area
variables
discrete design set
Set-valued discrete design variables

Topics
This keyword is related to the topics:
discrete variables
design variables

Specification
Alias: none
Argument(s): none

1986

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
integer

Dakota Keyword
Description
Integer-valued
discrete design
variables

Optional

string

String-valued
discrete design set
variables

Optional

real

Real-valued
discrete design
variables

Description
Discrete design variables whose values come from a set of admissible elements. Each variable specified must be
of type integer, string, or real.
integer
Keywords Area
variables
discrete design set
integer
Integer-valued discrete design variables

Topics
This keyword is related to the topics:
discrete variables
design variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete design set integer variables
Required/Description of
Optional
Group

Dakota Keyword

Dakota Keyword
Description

6.4. VARIABLES

1987
Optional

elements per variable

Number of
admissible
elements for each
set variable

Required

elements

The permissible
values for each
discrete variable

Optional

categorical

Whether the
set-valued
variables are
categorical or
relaxable

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
A design variable whose values come from a specified set of admissible integers. The details of how to specify
this discrete variable are located on the discrete variables page.

Examples
Four integer variables whose values will be selected from the following sets during the search for an optimal
design. y1 {0, 1}, y2 {0, 1}, y3 {0, 5} and y4 {10, 15, 20, 23}.
discrete_design_set
integer 4
descriptors
y1
elements_per_variable 2
elements
0 1

y2
2
0 1

y3
2
0 5

y4
4
10 15 20 23

elements per variable

Keywords Area
variables
discrete design set
integer
elements per variable
Number of admissible elements for each set variable

1988

CHAPTER 6. KEYWORDS AREA

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete design set
integer
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): INTEGERLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
categorical
Keywords Area
variables
discrete design set
integer
categorical
Whether the set-valued variables are categorical or relaxable

Specification
Alias: none
Argument(s): STRINGLIST

6.4. VARIABLES

1989
Required/Optional
Optional

Description of
Group

Dakota Keyword
adjacency matrix

Dakota Keyword
Description
1-0 matrix defining
which categorical
variable levels are
related.

Description
A list of strings of length equal to the number of set (integer, string, or real) variables indicating whether they are
strictly categorical, meaning may only take on values from the provided set, or relaxable, meaning may take on
any integer or real value between the lowest and highest specified element. Valid categorical strings include yes,
no, true, and false, or any abbreviation in [yYnNtTfF][.]

Examples
Discrete design set variable, rotor blades, can take on only integer values, 2, 4, or 7 by default. Since categorical
is specified to be false, the integrality can be relaxed and rotor blades can take on any value between 2 and 7,
e.g., 3, 6, or 5.5.
discrete_design_set
integer 1
elements 2 4 7
descriptor rotor_blades
categorical no

adjacency matrix
Keywords Area
variables
discrete design set
integer
categorical
adjacency matrix
1-0 matrix defining which categorical variable levels are related.

Specification
Alias: none
Argument(s): INTEGERLIST

1990

CHAPTER 6. KEYWORDS AREA

Description
The adjacency matrix keyword is associated with discrete design set variables that are specified to
be categorical. Each such variable is associated with one k k symmetric matrix, where k is the number of values
(or levels) of the variable. Entry i, j of a matrix should be 1 if level i and level j are related by some subjective
criteria or if i = j; it should be 0 otherwise. The matrices for all variables of the same type (string, real, or
integer) are entered sequentially as a list of integers as shown in the examples below.
Default Behavior
The adjacency matrix keyword is only relevant for discrete design set real and discretedesign set integer variables if one or more of them have been specified to be categorical. It is always
relevant for discrete design set string variables. If the user does not define an adjacency matrix, the
default is method dependent. Currently, the only method that makes use of the adjacency matrix is mesh adaptivesearch, which uses a tri-diagonal adjacency matrix by default.
Expected Output
The expected output is method dependent.
Usage Tips
If an adjacency matrix is defined for one type of (categorical) discrete design set variable, if must be
defined for all variables of that type, even for those not defined to be categorical. Those for the non-categorical
set variables will be ignored.

Examples
The following example shows a variables specification where some real and some integer discrete designset variables are categorical.
variables
continuous_design = 3
initial_point -1.0
1.5
2.0
lower_bounds -10.0 -10.0 -10.0
upper_bounds
10.0
10.0 10.0
descriptors
x1
x2 x3
discrete_design_range = 2
initial_point 2
2
lower_bounds
1
1
upper_bounds
4
9
descriptors
y1 y2
discrete_design_set
real = 2
elements_per_variable = 4 5
elements = 1.2 2.3 3.4 4.5 1.2 3.3 4.4 5.5 7.7
descriptors y3
y4
categorical no
yes
adjacency_matrix 1 1 0 0 # Begin entry of 4x4 matrix for y3
1 1 1 0
0 1 1 1
0 0 1 1
1 0 1 0 1 # Begin entry of 5x5 matrix for y4
0 1 0 1 0
1 0 1 0 1
0 1 0 1 0
1 0 1 0 1
integer = 2
elements_per_variable = 2 3
elements = 4 7 8 9 12
descriptors z1 z2
categorical yes yes

6.4. VARIABLES

1991

Note that for the real case, the user wants to define an adjacency matrix for the categorical variable, so adjacency matrices for both variables must be specified. The matrix for the first one will be ignored. Note that
no adjacency matrix is specified for either integer categorical variable. The default will be used in both cases.
Currently the only method taking advantage of adjacency matrices is mesh adaptive search, which uses a
tri-diagonal adjacency matrix by default. Thus, the matrices used would be
z1: 1
1
z2: 1
1
0

1
1
1 0
1 1
1 1

The following example shows a variables specification for string variables. Note that string variables are
always considered to be categorical. If an adjacency matrix is not specified, a method-dependent default matrix
will be used.
variables,
continuous_design = 2
initial_point 0.5 0.5
lower_bounds
0.
0.
upper_bounds
1.
1.
descriptors = x y
discrete_design_set string = 1
elements = aniso1 aniso2 iso1 iso2 iso3
descriptors = ancomp
adjacency_matrix 1 1 0 0 0
1 1 0 0 0
0 0 1 1 1
0 0 1 1 1
0 0 1 1 1

See Also
These keywords may also be of interest:
mesh adaptive search
initial point
Keywords Area
variables
discrete design set
integer
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST
Default: middle set value, or rounded down

1992

CHAPTER 6. KEYWORDS AREA

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
discrete design set
integer
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
string
Keywords Area
variables
discrete design set
string
String-valued discrete design set variables

Topics
This keyword is related to the topics:
discrete variables
design variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete design set string variables

6.4. VARIABLES

1993
Required/Optional
Optional

Description of
Group

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

Required

elements

The permissible
values for each
discrete variable

Optional

adjacency matrix

1-0 matrix defining

which categorical
variable levels are
related.

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
Discrete design variables whose values come from a specified set of admissible strings. The details of how
to specify this discrete variable are located on the discrete variables page. Each string element value must be
quoted and may contain alphanumeric, dash, underscore, and colon. White space, quote characters, and backslash/metacharacters are not permitted.

Examples
Two string variables whose values will be selected from the set of provided elements. The first variable, linear
solver, takes on values from a set of three possible elements and the second variable, mesh file, from a set of
two possible elements.
discrete_design_set
string 2
descriptors
linear_solver mesh_file
elements_per_variable 3
2
elements
cg gmres direct
mesh64.exo mesh128.exo

elements per variable

Keywords Area
variables
discrete design set
string
elements per variable
Number of admissible elements for each set variable

1994

CHAPTER 6. KEYWORDS AREA

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete design set
string
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): STRINGLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
adjacency matrix
Keywords Area
variables
discrete design set
string
adjacency matrix
1-0 matrix defining which categorical variable levels are related.

Specification
Alias: none
Argument(s): INTEGERLIST

6.4. VARIABLES

1995

Description
The adjacency matrix keyword is associated with discrete design set variables that are specified to
be categorical. Each such variable is associated with one k k symmetric matrix, where k is the number of values
(or levels) of the variable. Entry i, j of a matrix should be 1 if level i and level j are related by some subjective
criteria or if i = j; it should be 0 otherwise. The matrices for all variables of the same type (string, real, or
integer) are entered sequentially as a list of integers as shown in the examples below.
Default Behavior
The adjacency matrix keyword is only relevant for discrete design set real and discretedesign set integer variables if one or more of them have been specified to be categorical. It is always
relevant for discrete design set string variables. If the user does not define an adjacency matrix, the
default is method dependent. Currently, the only method that makes use of the adjacency matrix is mesh adaptivesearch, which uses a tri-diagonal adjacency matrix by default.
Expected Output
The expected output is method dependent.
Usage Tips
If an adjacency matrix is defined for one type of (categorical) discrete design set variable, if must be
defined for all variables of that type, even for those not defined to be categorical. Those for the non-categorical
set variables will be ignored.

Examples
The following example shows a variables specification where some real and some integer discrete designset variables are categorical.
variables
continuous_design = 3
initial_point -1.0
1.5
2.0
lower_bounds -10.0 -10.0 -10.0
upper_bounds
10.0
10.0 10.0
descriptors
x1
x2 x3
discrete_design_range = 2
initial_point 2
2
lower_bounds
1
1
upper_bounds
4
9
descriptors
y1 y2
discrete_design_set
real = 2
elements_per_variable = 4 5
elements = 1.2 2.3 3.4 4.5 1.2 3.3 4.4 5.5 7.7
descriptors y3
y4
categorical no
yes
adjacency_matrix 1 1 0 0 # Begin entry of 4x4 matrix for y3
1 1 1 0
0 1 1 1
0 0 1 1
1 0 1 0 1 # Begin entry of 5x5 matrix for y4
0 1 0 1 0
1 0 1 0 1
0 1 0 1 0
1 0 1 0 1
integer = 2
elements_per_variable = 2 3
elements = 4 7 8 9 12
descriptors z1 z2
categorical yes yes

1996

CHAPTER 6. KEYWORDS AREA

Note that for the real case, the user wants to define an adjacency matrix for the categorical variable, so adjacency matrices for both variables must be specified. The matrix for the first one will be ignored. Note that
no adjacency matrix is specified for either integer categorical variable. The default will be used in both cases.
Currently the only method taking advantage of adjacency matrices is mesh adaptive search, which uses a
tri-diagonal adjacency matrix by default. Thus, the matrices used would be
z1: 1
1
z2: 1
1
0

1
1
1 0
1 1
1 1

The following example shows a variables specification for string variables. Note that string variables are
always considered to be categorical. If an adjacency matrix is not specified, a method-dependent default matrix
will be used.
variables,
continuous_design = 2
initial_point 0.5 0.5
lower_bounds
0.
0.
upper_bounds
1.
1.
descriptors = x y
discrete_design_set string = 1
elements = aniso1 aniso2 iso1 iso2 iso3
descriptors = ancomp
adjacency_matrix 1 1 0 0 0
1 1 0 0 0
0 0 1 1 1
0 0 1 1 1
0 0 1 1 1

See Also
These keywords may also be of interest:
mesh adaptive search
initial point
Keywords Area
variables
discrete design set
string
initial point
Initial values

Specification
Alias: none
Argument(s): STRINGLIST
Default: middle set value, or rounded down

6.4. VARIABLES

1997

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
discrete design set
string
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
real
Keywords Area
variables
discrete design set
real
Real-valued discrete design variables

Topics
This keyword is related to the topics:
discrete variables
design variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete design set real variables

1998

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

Required

elements

The permissible
values for each
discrete variable

Optional

categorical

Whether the
set-valued
variables are
categorical or
relaxable

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
A design variable whose values come from a specified set of admissible reals. The details of how to specify this
discrete variable are located on the discrete variables page.

Examples
Two continuous, restricted variables whose values will be selected from the following sets during the search for
an optimal design. y1 {0.25, 1.25, 2.25, 3.25, 4.25}, y2 {0, 5}
discrete_design_set
real 2
descriptors
y1
elements_per_variable 5
elemetns
0.25 1.25 2.25 3.25 4.25

elements per variable

Keywords Area
variables
discrete design set
real
elements per variable
Number of admissible elements for each set variable

y2
2
0 5

6.4. VARIABLES

1999

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete design set
real
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): REALLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
categorical
Keywords Area
variables
discrete design set
real
categorical
Whether the set-valued variables are categorical or relaxable

Specification
Alias: none
Argument(s): STRINGLIST

2000

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
adjacency matrix

Dakota Keyword
Description
1-0 matrix defining
which categorical
variable levels are
related.

Description
A list of strings of length equal to the number of set (integer, string, or real) variables indicating whether they are
strictly categorical, meaning may only take on values from the provided set, or relaxable, meaning may take on
any integer or real value between the lowest and highest specified element. Valid categorical strings include yes,
no, true, and false, or any abbreviation in [yYnNtTfF][.]

Examples
Discrete design set variable, rotor blades, can take on only integer values, 2, 4, or 7 by default. Since categorical
is specified to be false, the integrality can be relaxed and rotor blades can take on any value between 2 and 7,
e.g., 3, 6, or 5.5.
discrete_design_set
integer 1
elements 2 4 7
descriptor rotor_blades
categorical no

adjacency matrix
Keywords Area
variables
discrete design set
real
categorical
adjacency matrix
1-0 matrix defining which categorical variable levels are related.

Specification
Alias: none
Argument(s): INTEGERLIST

6.4. VARIABLES

2001

Description
The adjacency matrix keyword is associated with discrete design set variables that are specified to
be categorical. Each such variable is associated with one k k symmetric matrix, where k is the number of values
(or levels) of the variable. Entry i, j of a matrix should be 1 if level i and level j are related by some subjective
criteria or if i = j; it should be 0 otherwise. The matrices for all variables of the same type (string, real, or
integer) are entered sequentially as a list of integers as shown in the examples below.
Default Behavior
The adjacency matrix keyword is only relevant for discrete design set real and discretedesign set integer variables if one or more of them have been specified to be categorical. It is always
relevant for discrete design set string variables. If the user does not define an adjacency matrix, the
default is method dependent. Currently, the only method that makes use of the adjacency matrix is mesh adaptivesearch, which uses a tri-diagonal adjacency matrix by default.
Expected Output
The expected output is method dependent.
Usage Tips
If an adjacency matrix is defined for one type of (categorical) discrete design set variable, if must be
defined for all variables of that type, even for those not defined to be categorical. Those for the non-categorical
set variables will be ignored.

Examples
The following example shows a variables specification where some real and some integer discrete designset variables are categorical.
variables
continuous_design = 3
initial_point -1.0
1.5
2.0
lower_bounds -10.0 -10.0 -10.0
upper_bounds
10.0
10.0 10.0
descriptors
x1
x2 x3
discrete_design_range = 2
initial_point 2
2
lower_bounds
1
1
upper_bounds
4
9
descriptors
y1 y2
discrete_design_set
real = 2
elements_per_variable = 4 5
elements = 1.2 2.3 3.4 4.5 1.2 3.3 4.4 5.5 7.7
descriptors y3
y4
categorical no
yes
adjacency_matrix 1 1 0 0 # Begin entry of 4x4 matrix for y3
1 1 1 0
0 1 1 1
0 0 1 1
1 0 1 0 1 # Begin entry of 5x5 matrix for y4
0 1 0 1 0
1 0 1 0 1
0 1 0 1 0
1 0 1 0 1
integer = 2
elements_per_variable = 2 3
elements = 4 7 8 9 12
descriptors z1 z2
categorical yes yes

2002

CHAPTER 6. KEYWORDS AREA

Note that for the real case, the user wants to define an adjacency matrix for the categorical variable, so adjacency matrices for both variables must be specified. The matrix for the first one will be ignored. Note that
no adjacency matrix is specified for either integer categorical variable. The default will be used in both cases.
Currently the only method taking advantage of adjacency matrices is mesh adaptive search, which uses a
tri-diagonal adjacency matrix by default. Thus, the matrices used would be
z1: 1
1
z2: 1
1
0

1
1
1 0
1 1
1 1

The following example shows a variables specification for string variables. Note that string variables are
always considered to be categorical. If an adjacency matrix is not specified, a method-dependent default matrix
will be used.
variables,
continuous_design = 2
initial_point 0.5 0.5
lower_bounds
0.
0.
upper_bounds
1.
1.
descriptors = x y
discrete_design_set string = 1
elements = aniso1 aniso2 iso1 iso2 iso3
descriptors = ancomp
adjacency_matrix 1 1 0 0 0
1 1 0 0 0
0 0 1 1 1
0 0 1 1 1
0 0 1 1 1

See Also
These keywords may also be of interest:
mesh adaptive search
initial point
Keywords Area
variables
discrete design set
real
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST
Default: middle set value, or rounded down

6.4. VARIABLES

2003

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
discrete design set
real
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.8

normal uncertain

Keywords Area
variables
normal uncertain
Aleatory uncertain variable - normal (Gaussian)

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no normal uncertain variables

2004

CHAPTER 6. KEYWORDS AREA

Required/Optional
Required

Description of
Group

Dakota Keyword
means

Required

std deviations

Optional

lower bounds

Optional

upper bounds

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
First parameter of
the distribution
Second parameter
of the distribution
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
Within the normal uncertain optional group specification, the number of normal uncertain variables, the means,
and standard deviations are required specifications, and the distribution lower and upper bounds and variable
descriptors are optional specifications. The normal distribution is widely used to model uncertain variables such
as population characteristics. It is also used to model the mean of a sample: as the sample size becomes very large,
the Central Limit Theorem states that the distribution of the mean becomes approximately normal, regardless of
the distribution of the original variables.
The density function for the normal distribution is:
f (x) =

1
1
e 2
2N

xN
N

where N and N are the mean and standard deviation of the normal distribution, respectively.
Note that if you specify bounds for a normal distribution, the sampling occurs from the underlying distribution
with the given mean and standard deviation, but samples are not taken outside the bounds (see bounded normal
distribution type in[89]). This can result in the mean and the standard deviation of the sample data being different
from the mean and standard deviation of the underlying distribution. For example, if you are sampling from a
normal distribution with a mean of 5 and a standard deviation of 3, but you specify bounds of 1 and 7, the resulting
mean of the samples will be around 4.3 and the resulting standard deviation will be around 1.6. This is because
you have bounded the original distribution significantly, and asymetrically, since 7 is closer to the original mean
than 1.

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [ 3, + 3]
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
means
Keywords Area
variables

6.4. VARIABLES
normal uncertain
means
First parameter of the distribution

Specification
Alias: nuv means
Argument(s): REALLIST

Description
Means
std deviations
Keywords Area
variables
normal uncertain
std deviations
Second parameter of the distribution

Specification
Alias: nuv std deviations
Argument(s): REALLIST

Description
Standard deviation
lower bounds
Keywords Area
variables
normal uncertain
lower bounds
Specify minimum values

Specification
Alias: nuv lower bounds
Argument(s): REALLIST
Default: -infinity

2005

2006

CHAPTER 6. KEYWORDS AREA

Description
Specify minimum values
upper bounds
Keywords Area
variables
normal uncertain
upper bounds
Specify maximium values

Specification
Alias: nuv upper bounds
Argument(s): REALLIST
Default: infinity

Description
Specify maximium values
initial point
Keywords Area
variables
normal uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

6.4. VARIABLES

2007

descriptors
Keywords Area
variables
normal uncertain
descriptors
Labels for the variables

Specification
Alias: nuv descriptors
Argument(s): STRINGLIST
Default: nuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.9

lognormal uncertain

Keywords Area
variables
lognormal uncertain
Aleatory uncertain variable - lognormal

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no lognormal uncertain variables
Required/Description of
Optional
Group

Dakota Keyword

Dakota Keyword
Description

2008

CHAPTER 6. KEYWORDS AREA

Required(Choose
One)

lambdas

Group 1

means

Optional

lower bounds

Optional

upper bounds

Optional

initial point

Optional

descriptors

First parameter of
the lognormal
distribution (option
3)
First parameter of
the lognormal
distribution
(options 1 & 2)
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
If the logarithm of an uncertain variable X has a normal distribution, that is log X N (, ), then X is distributed
with a lognormal distribution. The lognormal is often used to model:
1. time to perform some task
2. variables which are the product of a large number of other quantities, by the Central Limit Theorem
3. quantities which cannot have negative values.
Within the lognormal uncertain optional group specification, the number of lognormal uncertain variables,
the means, and either standard deviations or error factors must be specified, and the distribution lower and upper
bounds and variable descriptors are optional specifications. These distribution bounds can be used to truncate the
tails of lognormal distributions, which as for bounded normal, can result in the mean and the standard deviation of
the sample data being different from the mean and standard deviation of the underlying distribution (see bounded
lognormal and bounded lognormal-n distribution types in[89]).
For the lognormal variables, one may specify either the mean and standard deviation of the actual lognormal distribution (option 1), the mean and error factor  of the actual lognormal distribution (option 2), or the
mean (lambda) and standard deviation (zeta) of the underlying normal distribution (option 3).
The conversion equations from lognormal mean and either lognormal error factor  or lognormal standard
deviation to the mean and standard deviation of the underlying normal distribution are as follows:
=

ln()
1.645

2 = ln(

2
+ 1)
2

2
2
Conversions from and back to and  or are as follows:
= ln()

= e+

2
2

6.4. VARIABLES

2009
2

2 = e2+ (e 1)
 = e1.645
The density function for the lognormal distribution is:
f (x) =

1 lnx 2
1
e 2 ( )
2x

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [0, + 3].
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
lambdas
Keywords Area
variables
lognormal uncertain
lambdas
First parameter of the lognormal distribution (option 3)

Specification
Alias: lnuv lambdas
Argument(s): REALLIST
Required/Optional
Required

Description of
Group

Dakota Keyword
zetas

Dakota Keyword
Description
Second parameter
of the lognormal
distribution (option
3)

Description
For the lognormal variables, one may specify the mean (lambda) and standard deviation (zeta) of the
underlying normal distribution.
zetas
Keywords Area
variables
lognormal uncertain
lambdas
zetas
Second parameter of the lognormal distribution (option 3)

2010

CHAPTER 6. KEYWORDS AREA

Specification
Alias: lnuv zetas
Argument(s): REALLIST

Description
For the lognormal variables, one may specify the mean (lambda) and standard deviation (zeta) of the
underlying normal distribution.
means
Keywords Area
variables
lognormal uncertain
means
First parameter of the lognormal distribution (options 1 & 2)

Specification
Alias: lnuv means
Argument(s): REALLIST
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
std deviations

error factors

Dakota Keyword
Description
Second parameter
of the lognormal
distribution (option
1)
Second parameter
of the lognormal
distribution (option
2)

Description
For the lognormal variables, one may specify either the mean and standard deviation of the actual lognormal
distribution, the mean and error factor  of the actual lognormal distribution.
This corresponds to the mean of the lognormal random variable
std deviations
Keywords Area
variables
lognormal uncertain
means
std deviations
Second parameter of the lognormal distribution (option 1)

6.4. VARIABLES

2011

Specification
Alias: lnuv std deviations
Argument(s): REALLIST

Description
For the lognormal variables, one may specify either the mean and standard deviation of the actual lognormal
distribution.
This corresponds to the standard deviation of the lognormal random variable.
error factors
Keywords Area
variables
lognormal uncertain
means
error factors
Second parameter of the lognormal distribution (option 2)

Specification
Alias: lnuv error factors
Argument(s): REALLIST

Description
For the lognormal variables, one may specify the mean and error factor  of the actual lognormal distribution.
This specifies the error function of the lognormal random variable.
lower bounds
Keywords Area
variables
lognormal uncertain
lower bounds
Specify minimum values

Specification
Alias: lnuv lower bounds
Argument(s): REALLIST
Default: 0

2012

CHAPTER 6. KEYWORDS AREA

Description
Specify minimum values
upper bounds
Keywords Area
variables
lognormal uncertain
upper bounds
Specify maximium values

Specification
Alias: lnuv upper bounds
Argument(s): REALLIST
Default: infinity

Description
Specify maximium values
initial point
Keywords Area
variables
lognormal uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

6.4. VARIABLES

2013

descriptors
Keywords Area
variables
lognormal uncertain
descriptors
Labels for the variables

Specification
Alias: lnuv descriptors
Argument(s): STRINGLIST
Default: lnuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.10

uniform uncertain

Keywords Area
variables
uniform uncertain
Aleatory uncertain variable - uniform

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no uniform uncertain variables
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

2014

CHAPTER 6. KEYWORDS AREA

Required

lower bounds

Required

upper bounds

Optional

initial point

Optional

descriptors

Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
Within the uniform uncertain optional group specification, the number of uniform uncertain variables and the distribution lower and upper bounds are required specifications, and variable descriptors is an optional specification.
The uniform distribution has the density function:
f (x) =

1
UU LU

where UU and LU are the upper and lower bounds of the uniform distribution, respectively. The mean of the
2
U)
U
uniform distribution is UU +L
and the variance is (UU L
.
2
12

Theory
Note that this distribution is a special case of the more general beta distribution.
lower bounds
Keywords Area
variables
uniform uncertain
lower bounds
Specify minimum values

Specification
Alias: uuv lower bounds
Argument(s): REALLIST

Description
Specify minimum values

6.4. VARIABLES

2015

upper bounds
Keywords Area
variables
uniform uncertain
upper bounds
Specify maximium values

Specification
Alias: uuv upper bounds
Argument(s): REALLIST

Description
Specify maximium values
initial point
Keywords Area
variables
uniform uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
uniform uncertain
descriptors
Labels for the variables

2016

CHAPTER 6. KEYWORDS AREA

Specification
Alias: uuv descriptors
Argument(s): STRINGLIST
Default: uuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.11

loguniform uncertain

Keywords Area
variables
loguniform uncertain
Aleatory uncertain variable - loguniform

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no loguniform uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
lower bounds

Required

upper bounds

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

6.4. VARIABLES

2017

Description
If the logarithm of an uncertain variable X has a uniform distribution, that is log X U (LLU , ULU ), then X is
distributed with a loguniform distribution. The distribution lower bound is LLU and upper bound is LLU The
loguniform distribution has the density function:
f (x) =

1
x(lnULU lnLLU )

Theory
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables.
These variables are initialized to their means for these studies.
lower bounds
Keywords Area
variables
loguniform uncertain
lower bounds
Specify minimum values

Specification
Alias: luuv lower bounds
Argument(s): REALLIST

Description
Specify minimum values
upper bounds
Keywords Area
variables
loguniform uncertain
upper bounds
Specify maximium values

Specification
Alias: luuv upper bounds
Argument(s): REALLIST

2018

CHAPTER 6. KEYWORDS AREA

Description
Specify maximium values
initial point
Keywords Area
variables
loguniform uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
loguniform uncertain
descriptors
Labels for the variables

Specification
Alias: luuv descriptors
Argument(s): STRINGLIST
Default: luuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4. VARIABLES

6.4.12

2019

triangular uncertain

Keywords Area
variables
triangular uncertain
Aleatory uncertain variable - triangular

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no triangular uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
modes

Required

lower bounds

Required

upper bounds

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
Distribution
parameter
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
The triangular distribution is often used when one does not have much data or information, but does have an
estimate of the most likely value and the lower and upper bounds. Within the triangular uncertain optional group
specification, the number of triangular uncertain variables, the modes, and the distribution lower and upper bounds
are required specifications, and variable descriptors is an optional specification.
The density function for the triangular distribution is:
f (x) =

2(x LT )
(UT LT )(MT LT )

f (x) =

2(UT x)
(UT LT )(UT MT )

if LT x MT , and

if MT x UT , and 0 elsewhere. In these equations, LT is the lower bound, UT is the upper bound, and MT is
the mode of the triangular distribution.

2020
modes
Keywords Area
variables
triangular uncertain
modes
Distribution parameter

Specification
Alias: tuv modes
Argument(s): REALLIST

Description
Specify the modes
lower bounds
Keywords Area
variables
triangular uncertain
lower bounds
Specify minimum values

Specification
Alias: tuv lower bounds
Argument(s): REALLIST

Description
Specify minimum values
upper bounds
Keywords Area
variables
triangular uncertain
upper bounds
Specify maximium values

CHAPTER 6. KEYWORDS AREA

6.4. VARIABLES

2021

Specification
Alias: tuv upper bounds
Argument(s): REALLIST

Description
Specify maximium values
initial point
Keywords Area
variables
triangular uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
triangular uncertain
descriptors
Labels for the variables

Specification
Alias: tuv descriptors
Argument(s): STRINGLIST
Default: tuv {i}

2022

CHAPTER 6. KEYWORDS AREA

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.13

exponential uncertain

Keywords Area
variables
exponential uncertain
Aleatory uncertain variable - exponential

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no exponential uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
betas

Optional

initial point

Optional

descriptors

Description
The exponential distribution is often used for modeling failure rates.
The density function for the exponential distribution is given by:
f (x) =

1 x
e

2
where E = and E
= 2.
Note that this distribution is a special case of the more general gamma distribution.

Dakota Keyword
Description
Parameter of the
exponential
distribution
Initial values
Labels for the
variables

6.4. VARIABLES

2023

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [0, + 3].
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
betas
Keywords Area
variables
exponential uncertain
betas
Parameter of the exponential distribution

Specification
Alias: euv betas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the exponential random variables. Length must
match the other parameters and the number of exponential random variables.
initial point
Keywords Area
variables
exponential uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

2024

CHAPTER 6. KEYWORDS AREA

descriptors
Keywords Area
variables
exponential uncertain
descriptors
Labels for the variables

Specification
Alias: euv descriptors
Argument(s): STRINGLIST
Default: euv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.14

beta uncertain

Keywords Area
variables
beta uncertain
Aleatory uncertain variable - beta

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no beta uncertain variables
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.4. VARIABLES

2025
Required

alphas

Required

betas

Required

lower bounds

Required

upper bounds

Optional

initial point

Optional

descriptors

First parameter of
the beta
distribution
Second parameter
of the beta
distribution
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
Within the beta uncertain optional group specification, the number of beta uncertain variables, the alpha and beta
parameters, and the distribution upper and lower bounds are required specifications, and the variable descriptors is
an optional specification. The beta distribution can be helpful when the actual distribution of an uncertain variable
is unknown, but the user has a good idea of the bounds, the mean, and the standard deviation of the uncertain
variable. The density function for the beta distribution is
( + ) (x LB )1 (UB x)1
()()
(UB LB )+1

f (x) =

where () is the gamma function and B(, ) = ()()

(+) is the beta function. To calculate the mean and
standard deviation from the alpha, beta, upper bound, and lower bound parameters of the beta distribution, the
following expressions may be used.
B = LB +
2
B
=

(UB LB )
+

(UB LB )2
( + )2 ( + + 1)

Solving these for and gives:

= (B LB )

2
(B LB )(UB B ) B
2
B (UB LB )

= (UB B )

2
(B LB )(UB B ) B
2 (U L )
B
B
B

Note that the uniform distribution is a special case of this distribution for parameters = = 1.

Theory
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables.
These variables are initialized to their means for these studies.

2026

CHAPTER 6. KEYWORDS AREA

alphas
Keywords Area
variables
beta uncertain
alphas
First parameter of the beta distribution

Specification
Alias: buv alphas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the beta random variables. Length must match the
other parameters and the number of beta random variables.
betas
Keywords Area
variables
beta uncertain
betas
Second parameter of the beta distribution

Specification
Alias: buv betas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the beta random variables. Length must match the
other parameters and the number of beta random variables.
lower bounds
Keywords Area
variables
beta uncertain
lower bounds
Specify minimum values

6.4. VARIABLES

2027

Specification
Alias: buv lower bounds
Argument(s): REALLIST

Description
Specify minimum values
upper bounds
Keywords Area
variables
beta uncertain
upper bounds
Specify maximium values

Specification
Alias: buv upper bounds
Argument(s): REALLIST

Description
Specify maximium values
initial point
Keywords Area
variables
beta uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

2028

CHAPTER 6. KEYWORDS AREA

descriptors
Keywords Area
variables
beta uncertain
descriptors
Labels for the variables

Specification
Alias: buv descriptors
Argument(s): STRINGLIST
Default: buv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.15

gamma uncertain

Keywords Area
variables
gamma uncertain
Aleatory uncertain variable - gamma

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no gamma uncertain variables
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.4. VARIABLES

2029
Required

alphas

Required

betas

Optional

initial point

Optional

descriptors

First parameter of
the gamma
distribution
Second parameter
of the gamma
distribution
Initial values
Labels for the
variables

Description
The gamma distribution is sometimes used to model time to complete a task, such as a repair or service task. It is
a very flexible distribution with its shape governed by alpha and beta.
The density function for the gamma distribution is given by:
x

x1 e
f (x) =
()

2
= 2 . Note that the exponential distribution is a special case of this distribution for
where GA = and GA
parameter = 1.

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [0, + 3].
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
alphas
Keywords Area
variables
gamma uncertain
alphas
First parameter of the gamma distribution

Specification
Alias: gauv alphas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the gamma random variables. Length must match
the other parameters and the number of gamma random variables.

2030

CHAPTER 6. KEYWORDS AREA

betas
Keywords Area
variables
gamma uncertain
betas
Second parameter of the gamma distribution

Specification
Alias: gauv betas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the gamma random variables. Length must match
the other parameters and the number of gamma random variables.
initial point
Keywords Area
variables
gamma uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
gamma uncertain
descriptors
Labels for the variables

6.4. VARIABLES

2031

Specification
Alias: gauv descriptors
Argument(s): STRINGLIST
Default: gauv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.16

gumbel uncertain

Keywords Area
variables
gumbel uncertain
Aleatory uncertain variable - gumbel

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no gumbel uncertain variables
Required/Optional
Required

Description of
Group

Dakota Keyword
alphas

Required

betas

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
First parameter of
the gumbel
distribution
Second parameter
of the gumbel
distribution
Initial values
Labels for the
variables

2032

CHAPTER 6. KEYWORDS AREA

Description
The Gumbel distribution is also referred to as the Type I Largest Extreme Value distribution. The distribution of
maxima in sample sets from a population with a normal distribution will asymptotically converge to this distribution. It is commonly used to model demand variables such as wind loads and flood levels.
The density function for the Gumbel distribution is given by:
f (x) = e(x) exp(e(x) )
where GU = +

0.5772

and GU =

.
6

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [ 3, + 3]
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
alphas
Keywords Area
variables
gumbel uncertain
alphas
First parameter of the gumbel distribution

Specification
Alias: guuv alphas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the gumbel random variables. Length must match
the other parameters and the number of gumbel random variables.
betas
Keywords Area
variables
gumbel uncertain
betas
Second parameter of the gumbel distribution

6.4. VARIABLES

2033

Specification
Alias: guuv betas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the gumbel random variables. Length must match
the other parameters and the number of gumbel random variables.
initial point
Keywords Area
variables
gumbel uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
gumbel uncertain
descriptors
Labels for the variables

Specification
Alias: guuv descriptors
Argument(s): STRINGLIST
Default: guuv {i}

2034

CHAPTER 6. KEYWORDS AREA

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.17

frechet uncertain

Keywords Area
variables
frechet uncertain
Aleatory uncertain variable - Frechet

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no frechet uncertain variables
Required/Optional
Required

Description of
Group

Dakota Keyword
alphas

Required

betas

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
First parameter of
the Frechet
distribution
Second parameter
of the Frechet
distribution
Initial values
Labels for the
variables

Description
The Frechet distribution is also referred to as the Type II Largest Extreme Value distribution. The distribution
of maxima in sample sets from a population with a lognormal distribution will asymptotically converge to this
distribution. It is commonly used to model non-negative demand variables.
The density function for the frechet distribution is:
f (x) =

+1 ( )
( )
e x
x

where F = (1 1 ) and F2 = 2 [(1 2 ) 2 (1 1 )]

6.4. VARIABLES

2035

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [0, + 3].
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
alphas
Keywords Area
variables
frechet uncertain
alphas
First parameter of the Frechet distribution

Specification
Alias: fuv alphas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the Frechet random variables. Length must match
the other parameters and the number of Frechet random variables.
betas
Keywords Area
variables
frechet uncertain
betas
Second parameter of the Frechet distribution

Specification
Alias: fuv betas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the Frechet random variables. Length must match
the other parameters and the number of Frechet random variables.

2036

CHAPTER 6. KEYWORDS AREA

initial point
Keywords Area
variables
frechet uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
frechet uncertain
descriptors
Labels for the variables

Specification
Alias: fuv descriptors
Argument(s): STRINGLIST
Default: fuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.18

weibull uncertain

Keywords Area
variables
weibull uncertain
Aleatory uncertain variable - Weibull

6.4. VARIABLES

2037

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no weibull uncertain variables
Required/Optional
Required

Description of
Group

Dakota Keyword
alphas

Required

betas

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
First parameter of
the Weibull
distribution
Second parameter
of the Weibull
distribution
Initial values
Labels for the
variables

Description
The Weibull distribution is also referred to as the Type III Smallest Extreme Value distribution. The Weibull
distribution is commonly used in reliability studies to predict the lifetime of a device. It is also used to model
capacity variables such as material strength.
The density function for the Weibull distribution is given by:
f (x) =

where W = (1 + 1 ) and W =

2
(1+
)
1
2 (1+
)

alphas
Keywords Area
variables
weibull uncertain
alphas
First parameter of the Weibull distribution

 1
x
x
e ( )

1W

2038

CHAPTER 6. KEYWORDS AREA

Specification
Alias: wuv alphas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the Weibull random variables.
Length must match the other parameters and the number of Weibull random variables.
betas
Keywords Area
variables
weibull uncertain
betas
Second parameter of the Weibull distribution

Specification
Alias: wuv betas
Argument(s): REALLIST

Description
Specifies the list of parameters to define the distributions of the Weibull random variables. Length must match
the other parameters and the number of Weibull random variables.
initial point
Keywords Area
variables
weibull uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

6.4. VARIABLES

2039

descriptors
Keywords Area
variables
weibull uncertain
descriptors
Labels for the variables

Specification
Alias: wuv descriptors
Argument(s): STRINGLIST
Default: wuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.19

histogram bin uncertain

Keywords Area
variables
histogram bin uncertain
Aleatory uncertain variable - continuous histogram

Topics
This keyword is related to the topics:
continuous variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no histogram bin uncertain variables
Required/Description of
Optional
Group

Dakota Keyword

Dakota Keyword
Description

2040

CHAPTER 6. KEYWORDS AREA

Optional

pairs per variable

Number of pairs
defining each
histogram bin
variable

Required

abscissas

Real abscissas for

a bin histogram

ordinates

Ordinates
specifying a
skyline
probability density
function

counts

Frequency or
relative probability
of each bin

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Required(Choose
One)

Group 1

Description
Histogram uncertain variables are typically used to model a set of empirical data. The bin histogram (contrast:
histogram point uncertain) is a continuous aleatory distribution characterized by bins of non-zero width where
the uncertain variable may lie, together with the relative frequencies of each bin. Hence it can be used to specify
a marginal probability density function arising from data.
The histogram bin uncertain keyword specifies the number of variables to be characterized as continuous histograms. The required sub-keywords are: abscissas (ranges of values the variable can take on) and
either ordinates or counts (characterizing each variables frequency information). When using histogram bin variables, each variable must be defined by at least one bin (with two bounding value pairs). When more than one
histogram bin variable is active, pairs per variable can be used to specify unequal apportionment of provided bin
pairs among the variables.
The abscissas specification defines abscissa values (x coordinates) for the probability density function
of each histogram variable. When paired with counts, the specifications provide sets of (x,c) pairs for each
histogram variable where c defines a count (i.e., a frequency or relative probability) associated with a bin. If using
bins of unequal width and specification of probability densities is more natural, then the counts specification
can be replaced with an ordinates specification (y coordinates) in order to support interpretation of the input
as (x,y) pairs defining the profile of a skyline probability density function.
Conversion between the two specifications is straightforward: a count/frequency is a cumulative probability
quantity defined from the product of the ordinate density value and the x bin width. Thus, in the cases of bins of
equal width, ordinate and count specifications are equivalent. In addition, ordinates and counts may be relative
values; it is not necessary to scale them as all user inputs will be normalized.
To fully specify a bin-based histogram with n bins (potentially of unequal width), n+1 (x,c) or (x,y) pairs
must be specified with the following features:
x is the parameter value for the left boundary of a histogram bin and c is the corresponding count for that

6.4. VARIABLES

2041

bin. Alternatively, y defines the ordinate density value for this bin within a skyline probability density
function. The right boundary of the bin is defined by the left boundary of the next pair.
the final pair specifies the right end of the last bin and must have a c or y value of zero.
the x values must be strictly increasing.
all c or y values must be positive, except for the last which must be zero.
a minimum of two pairs must be specified for each bin-based histogram variable.

Examples
The pairs per variable specification provides for the proper association of multiple sets of (x,c) or (x,y)
pairs with individual histogram variables. For example, in this input snippet
histogram_bin_uncertain = 2
pairs_per_variable = 3
abscissas
= 5 8 10
counts
= 17 21 0
descriptors
= hbu_1

4
.1 .2 .3 .4
12 24 12 0
hbu_2

pairs per variable associates the first 3 (x,c) pairs from abscissas and counts {(5,17),(8,21),(10,0)}
with one bin-based histogram variable, where one bin is defined between 5 and 8 with a count of 17 and another
bin is defined between 8 and 10 with a count of 21. The following set of 4 (x,c) pairs {(.1,12),(.2,24),(.3,12),(.4,0)}
defines a second bin-based histogram variable containing three equal-width bins with counts 12, 24, and 12 (middle bin is twice as probable as the other two).

See Also
These keywords may also be of interest:
histogram point uncertain

FAQ
Difference between bin and point histograms: A (continuous) bin histogram specifies bins of non-zero width,
whereas a (discrete) point histogram specifies individual point values, which can be thought of as bins with zero
width. In the terminology of LHS[89], the bin pairs specification defines a continuous linear distribution and
the point pairs specification defines a discrete histogram distribution (although the points are real-valued, the
number of possible values is finite).
pairs per variable
Keywords Area
variables
histogram bin uncertain
pairs per variable
Number of pairs defining each histogram bin variable

2042

CHAPTER 6. KEYWORDS AREA

Specification
Alias: num pairs
Argument(s): INTEGERLIST
Default: equal distribution

Description
By default, the list of abscissas and counts or ordinates will be evenly divided among the histogrambin uncertain variables. pairs per variable is a list of integers that specify the number of pairs to
apportion to each variable.
abscissas
Keywords Area
variables
histogram bin uncertain
abscissas
Real abscissas for a bin histogram

Specification
Alias: huv bin abscissas
Argument(s): REALLIST

Description
A list of real abscissa (x coordinate) values characterizing the probability density function for each of the
histogram bin uncertain variables. These are paired with either counts or ordinates. See histogram binuncertain for details and examples.
ordinates
Keywords Area
variables
histogram bin uncertain
ordinates
Ordinates specifying a skyline probability density function

Specification
Alias: huv bin ordinates
Argument(s): REALLIST

6.4. VARIABLES

2043

Description
The ordinates list of real values defines the profile of a skyline probability density function by pairing with
the specified abscissas. See histogram bin uncertain for details.
counts
Keywords Area
variables
histogram bin uncertain
counts
Frequency or relative probability of each bin

Specification
Alias: huv bin counts
Argument(s): REALLIST

Description
The counts list of real values gives the frequency or relative probability for each bin in a histogram bin uncertain specification. These are paired with the specified abscissas. See histogram bin uncertain for details.

initial point
Keywords Area
variables
histogram bin uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

2044

CHAPTER 6. KEYWORDS AREA

descriptors
Keywords Area
variables
histogram bin uncertain
descriptors
Labels for the variables

Specification
Alias: huv bin descriptors
Argument(s): STRINGLIST
Default: hbuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.20

poisson uncertain

Keywords Area
variables
poisson uncertain
Aleatory uncertain discrete variable - Poisson

Topics
This keyword is related to the topics:
discrete variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no poisson uncertain variables
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.4. VARIABLES

2045
Required

lambdas

Optional

initial point

Optional

descriptors

The parameter for

the Poisson
distribution, the
expected number
of events in the
time interval of
interest
Initial values
Labels for the
variables

Description
The Poisson distribution is used to predict the number of discrete events that happen in a single time interval. The
random events occur uniformly and independently. The expected number of occurences in a single time interval
is , which must be a positive real number. For example, if events occur on average 4 times per year and we
are interested in the distribution of events over six months, would be 2. However, if we were interested in the
distribution of events occuring over 5 years, would be 20.
The density function for the poisson distribution is given by:
f (x) =

e
x!

where
is the expected number of events occuring in a single time interval -x is the number of events that occur
in this time period -f(x) is the probability that x events occur in this time period

Theory
When used with design of experiments and multidimensional parameter studies, distribution bounds are inferred.
These bounds are [0, + 3].
For vector and centered parameter studies, an inferred initial starting point is needed for the uncertain variables. These variables are initialized to their means for these studies.
lambdas
Keywords Area
variables
poisson uncertain
lambdas
The parameter for the Poisson distribution, the expected number of events in the time interval of interest

Specification
Alias: none
Argument(s): REALLIST

2046

CHAPTER 6. KEYWORDS AREA

Description
The density function for the poisson distribution is given by:
f (x) =

e
x!

where is the frequency of events happening, and x is the number of events that occur.
initial point
Keywords Area
variables
poisson uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
poisson uncertain
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: puv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4. VARIABLES

6.4.21

2047

binomial uncertain

Keywords Area
variables
binomial uncertain
Aleatory uncertain discrete variable - binomial

Topics
This keyword is related to the topics:
discrete variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no binomial uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
probability per trial

Required

num trials

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
A distribution
parameter for the
binomial
distribution
A distribution
parameter
Initial values
Labels for the
variables

Description
The binomial distribution describes probabilities associated with a series of independent Bernoulli trials. A
Bernoulli trial is an event with two mutually exclusive outcomes, such as 0 or 1, yes or no, success or fail.
The probability of success remains the same (the trials are independent).
The density function for the binomial distribution is given by:


n
f (x) =
px (1 p)(nx)
x
where p is the probability of failure per trial, n is the number of trials and x is the number of successes.

Theory
The binomial distribution is typically used to predict the number of failures or defective items in a total of n
independent tests or trials, where each trial has the probability p of failing or being defective.

2048

CHAPTER 6. KEYWORDS AREA

probability per trial

Keywords Area
variables
binomial uncertain
probability per trial
A distribution parameter for the binomial distribution

Specification
Alias: prob per trial
Argument(s): REALLIST

Description
The binomial distribution is typically used to predict the number of failures (or defective items or some type of
event) in a total of n independent tests or trials, where each trial has the probability p of failing or being defective.
Each particular test can be considered as a Bernoulli trial.
num trials
Keywords Area
variables
binomial uncertain
num trials
A distribution parameter

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The binomial distribution is typically used to predict the number of failures (or defective items or some type of
event) in a total of n independent tests or trials, where each trial has the probability p of failing or being defective.
Each particular test can be considered as a Bernoulli trial.
initial point
Keywords Area
variables
binomial uncertain
initial point
Initial values

6.4. VARIABLES

2049

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
binomial uncertain
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: biuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.22

negative binomial uncertain

Keywords Area
variables
negative binomial uncertain
Aleatory uncertain discrete variable - negative binomial

Topics
This keyword is related to the topics:
discrete variables
aleatory uncertain variables

2050

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: no negative binomial uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
probability per trial

Required

num trials

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
A negative
binomial
distribution
parameter
A negative
binomial
distribution
parameter
Initial values
Labels for the
variables

Description
The density function for the negative binomial distribution is given by:


n+x1
f (x) =
pn (1 p)x
x
where
p is the probability of success per trial
n is the number of successful trials
X is the number of failures

Theory
The negative binomial distribution is typically used to predict the number of failures observed when repeating a
test until a total of n successes have occurred, where each test has a probability p of success.
probability per trial
Keywords Area
variables
negative binomial uncertain
probability per trial
A negative binomial distribution parameter

6.4. VARIABLES

2051

Specification
Alias: prob per trial
Argument(s): REALLIST

Description
The negative binomial distribution is typically used to predict the number of failures observed when repeating a
test until a total of n successes have occurred, where each test has a probability p of success.
The density function for the negative binomial distribution is given by:


n+x1
f (x) =
pn (1 p)x
x
where
p is the probability of success per trial
n is the number of successful trials
X is the number of failures
num trials
Keywords Area
variables
negative binomial uncertain
num trials
A negative binomial distribution parameter

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The negative binomial distribution is typically used to predict the number of failures observed when repeating a
test until a total of n successes have occurred, where each test has a probability p of success.
The density function for the negative binomial distribution is given by:


n+x1
f (x) =
pn (1 p)x
x
where
p is the probability of success per trial
n is the number of successful trials
X is the number of failures

2052

CHAPTER 6. KEYWORDS AREA

initial point
Keywords Area
variables
negative binomial uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
negative binomial uncertain
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: nbuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.23

geometric uncertain

Keywords Area
variables
geometric uncertain
Aleatory uncertain discrete variable - geometric

6.4. VARIABLES

2053

Topics
This keyword is related to the topics:
discrete variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no geometric uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
probability per trial

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
Geometric
distribution
parameter
Initial values
Labels for the
variables

Description
The geometric distribution represents the number of successful trials that might occur before a failure is observed.
The density function for the geometric distribution is given by:
f (x) = p(1 p)x
where p is the probability of failure per trial.
probability per trial
Keywords Area
variables
geometric uncertain
probability per trial
Geometric distribution parameter

Specification
Alias: prob per trial
Argument(s): REALLIST

2054

CHAPTER 6. KEYWORDS AREA

Description
The geometric distribution represents the number of successful trials that occur before a failure is observed.
The density function for the geometric distribution is given by:
f (x) = p(1 p)x
where p is the probability of failure per trial and x is the number of successful trials.
initial point
Keywords Area
variables
geometric uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
geometric uncertain
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: geuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4. VARIABLES

6.4.24

2055

hypergeometric uncertain

Keywords Area
variables
hypergeometric uncertain
Aleatory uncertain discrete variable - hypergeometric

Topics
This keyword is related to the topics:
discrete variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no hypergeometric uncertain variables
Required/Description of
Optional
Group
Required

Dakota Keyword
total population

Required

selected population

Required

num drawn

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
Parameter for the
hypergeometric
probability
distribution
Distribution
parameter for the
hypergeometric
distribution
Distribution
parameter for the
hypergeometric
distribution
Initial values
Labels for the
variables

Description
The hypergeometric probability density is used when sampling without replacement from a total population of
elements where
The resulting element of each sample can be separated into one of two non-overlapping sets
The probability of success changes with each sample.

2056

CHAPTER 6. KEYWORDS AREA

The density function for the hypergeometric distribution is given by:




m
N m
x
nx


f (x) =
N
n
where:
N is the total population
m is the number of items in the selected population (e.g. the number of white balls in the full urn of N
items)
n is the size of the sample drawn (e.g. number of balls drawn)
x is the number of sucess (e.g. drawing a white ball)

a
b

is a binomial coeffecient

Theory
The hypergeometric is often described using an urn model. For example, say we have a total population containing
N balls, and we know that m of the balls are white and the remaining balls are green. If we draw n balls from the
urn without replacement, the hypergeometric distribution describes the probability of drawing x white balls.
total population
Keywords Area
variables
hypergeometric uncertain
total population
Parameter for the hypergeometric probability distribution

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The density function for the hypergeometric distribution is given by:



m
N m
x
nx


f (x) =
N
n
where

6.4. VARIABLES

2057

N is the total population (e.g. the total number of balls in the urn)
m is the number of items in the selected population (e.g. the number of white balls in the full urn of N
items)
n is the size of the sample (e.g. number of balls drawn)
x is the number of sucess (e.g. drawing a white ball)

a
b

is a binomial coeffecient

selected population
Keywords Area
variables
hypergeometric uncertain
selected population
Distribution parameter for the hypergeometric distribution

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The density function for the hypergeometric distribution is given by:

f (x) =

m
x



N m
nx


N
n

where
N is the total population (e.g. the total number of balls in the urn)
m is the number of items in the selected population (e.g. the number of white balls in the full urn of N
items)
n is the size of the sample (e.g. number of balls drawn)
x is the number of sucess (e.g. drawing a white ball)

a
b

is a binomial coeffecient

2058

CHAPTER 6. KEYWORDS AREA

num drawn
Keywords Area
variables
hypergeometric uncertain
num drawn
Distribution parameter for the hypergeometric distribution

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The density function for the hypergeometric distribution is given by:



m
N m
x
nx


f (x) =
N
n
where
N is the total population (e.g. the total number of balls in the urn)
m is the number of items in the selected population (e.g. the number of white balls in the full urn of N
items)
n is the size of the sample (e.g. number of balls drawn)
x is the number of sucess (e.g. drawing a white ball)

a
b

is a binomial coeffecient

initial point
Keywords Area
variables
hypergeometric uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

6.4. VARIABLES

2059

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
hypergeometric uncertain
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: hguv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.25

histogram point uncertain

Keywords Area
variables
histogram point uncertain
Aleatory uncertain variable - discrete histogram

Topics
This keyword is related to the topics:
discrete variables
aleatory uncertain variables

Specification
Alias: none
Argument(s): none
Default: no histogram point uncertain variables

2060

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
integer

Dakota Keyword
Description
Integer valued
point histogram
variable

Optional

string

String (categorical)
valued point
histogram variable

Optional

real

Real valued point

histogram variable

Description
Histogram uncertain variables are typically used to model a set of empirical data. When the variables take on only
discrete values or categories, a discrete, or point histogram is used to describe their probability mass function (one
could think of this as a histogram bin uncertain variable with bins of zero width). Dakota supports integer-,
string-, and real-valued point histograms.
Point histograms are similar to discrete design set and discrete state set, but as they are uncertain variables,
include the relative probabilities of observing the different values within the set.
The histogram point uncertain keyword is followed by one or more of integer, string, or
real, each of which specify the number of variables to be characterized as discrete histograms of that sub-type.
Each discrete histogram variable is specified by one or more abscissa/count pairs. The abscissas, are the
possible values the variable can take on (x coordinates of type integer, string, or real), and must be specified
in increasing order. These are paired with counts c which provide the frequency of the given value or string,
relative to other possible values/strings.
Thus, to fully specify a point-based histogram with n points, n (x,c) pairs must be specified with the following
features:
x is the point value (integer, string, or real) and c is the corresponding count for that value.
the x values must be strictly increasing (lexicographically for strings).
all c values must be positive.
a minimum of one pair must be specified for each point-based histogram.

Examples
The pairs per variable specification provides for the proper association of multiple sets of (x,c) or (x,y)
pairs with individual histogram variables. For example, in the following specification,
histogram_point_uncertain
integer
= 2
pairs_per_variable = 2
abscissas
= 3 4
counts
= 1 1

3
100 200 300
1
2
1

pairs per variable associates the (x,c) pairs {(3,1),(4,1)} with one point-based histogram variable
(where the values 3 and 4 are equally probable) and associates the (x,c) pairs {(100,1),(200,2),(300,1)} with a
second point-based histogram variable (where the value 200 is twice as probable as either 100 or 300).

6.4. VARIABLES

2061

See Also
These keywords may also be of interest:
histogram bin uncertain

FAQ
Difference between bin and point histograms: A (continuous) bin histogram specifies bins of non-zero width,
whereas a (discrete) point histogram specifies individual point values, which can be thought of as bins with zero
width. In the terminology of LHS[89], the bin pairs specification defines a continuous linear distribution and
the point pairs specification defines a discrete histogram distribution (although the points are real-valued, the
number of possible values is finite).
integer
Keywords Area
variables
histogram point uncertain
integer
Integer valued point histogram variable

Specification
Alias: none
Argument(s): INTEGER
Required/Optional
Optional

Description of
Group

Dakota Keyword
pairs per variable

Dakota Keyword
Description
Number of pairs
defining each
histogram point
integer variable

Required

abscissas

Integer abscissas
for a point
histogram

Required

counts

Counts for
integer-valued
point histogram

2062

CHAPTER 6. KEYWORDS AREA

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
This probability mass function is integer-valued; the abscissa values must all be integers. The n abscissa values are
paired with n counts which indicate the relative frequency (mass) of each integer relative to the other specified
integers.

Examples
histogram_point_uncertain
integer = 2
pairs_per_variable = 2
abscissas
= 3 4
counts
= 1 1

3
100 200 300
1
2
1

There are two variables, the first one has two possible integer values which are equally probable. The second
one has three options, and 200 is twice as probable as either 100 or 300.
pairs per variable
Keywords Area
variables
histogram point uncertain
integer
pairs per variable
Number of pairs defining each histogram point integer variable

Specification
Alias: num pairs
Argument(s): INTEGERLIST
Default: equal distribution

Description
By default, the list of abscissas and counts will be evenly divided among the histogram point integer
variables. The number of pairs per variable specifies the apportionment of abscissa/count pairs among
the histogram point integer variables. It must specify one integer >=1 per variable that indicates how many of the
(abscissa, count) = (x,c) pairs to associate with that variable.

6.4. VARIABLES

2063

abscissas
Keywords Area
variables
histogram point uncertain
integer
abscissas
Integer abscissas for a point histogram

Specification
Alias: none
Argument(s): INTEGERLIST

Description
A list of integer abscissa (x coordinate) values characterizing the probability density function for each of the
integer histogram point uncertain variables. These must be listed in increasing order for each variable,
and are paired with counts. See histogram point uncertain for details and examples.
counts
Keywords Area
variables
histogram point uncertain
integer
counts
Counts for integer-valued point histogram

Specification
Alias: none
Argument(s): REALLIST

Description
Count or frequency for each of abscissas. See histogram point uncertain for details and examples.

2064

CHAPTER 6. KEYWORDS AREA

initial point
Keywords Area
variables
histogram point uncertain
integer
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
histogram point uncertain
integer
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: hpiv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4. VARIABLES

2065

string
Keywords Area
variables
histogram point uncertain
string
String (categorical) valued point histogram variable

Specification
Alias: none
Argument(s): INTEGER
Required/Optional
Optional

Description of
Group

Dakota Keyword
pairs per variable

Dakota Keyword
Description
Number of pairs
defining each
histogram point
string variable

Required

abscissas

String abscissas for

a point histogram

Required

counts

Counts for
string-valued point
histogram

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
This probability mass function is string-valued; the abscissa values must all be strings. The n abscissa values are
paired with n counts which indicate the relative frequency (mass) of each string relative to the other specified
strings.

Examples
histogram_point_uncertain
string = 2
pairs_per_variable = 2
abscissas
= no yes
counts
= 1
1
descriptors
= vote

3
function1 function2 function3
1
2
1
which_function

Here there are two variables, the first one (vote) has two possible string values yes and no which are
equally probable. The second one has three options for which function, and function2 is twice as probable as
function1 or function3.

2066

CHAPTER 6. KEYWORDS AREA

pairs per variable

Keywords Area
variables
histogram point uncertain
string
pairs per variable
Number of pairs defining each histogram point string variable

Specification
Alias: num pairs
Argument(s): INTEGERLIST
Default: equal distribution

Description
By default, the list of abscissas and counts will be evenly divided among the histogram point string variables. The number of pairs per variable specifies the apportionment of abscissa/count pairs among the
histogram point string variables. It must specify one integer >=1 per variable that indicates how many of the
(abscissa, count) = (x,c) pairs to associate with that variable.
abscissas
Keywords Area
variables
histogram point uncertain
string
abscissas
String abscissas for a point histogram

Specification
Alias: none
Argument(s): STRINGLIST

Description
A list of string abscissa (x coordinate) values characterizing the probability density function for each of the
string histogram point uncertain variables. These must be listed in (lexicographically) increasing order
for each variable, and are paired with counts. See histogram point uncertain for details and examples.

6.4. VARIABLES

2067

counts
Keywords Area
variables
histogram point uncertain
string
counts
Counts for string-valued point histogram

Specification
Alias: none
Argument(s): REALLIST

Description
Count or frequency for each of abscissas. See histogram point uncertain for details and examples.
initial point
Keywords Area
variables
histogram point uncertain
string
initial point
Initial values

Specification
Alias: none
Argument(s): STRINGLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

2068

CHAPTER 6. KEYWORDS AREA

descriptors
Keywords Area
variables
histogram point uncertain
string
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: hpsv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
real
Keywords Area
variables
histogram point uncertain
real
Real valued point histogram variable

Specification
Alias: none
Argument(s): INTEGER
Required/Optional
Optional

Description of
Group

Dakota Keyword
pairs per variable

Dakota Keyword
Description
Number of pairs
defining each
histogram point
real variable

6.4. VARIABLES

2069
Required

abscissas

Real abscissas for

a point histogram

Required

counts

Counts for
real-valued point
histogram

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
This probability mass function is real-valued; the abscissa values must all be integers. The n abscissa values are
paired with n counts which indicate the relative frequency (mass) of each real relative to the other specified
reals.

Examples
histogram_point_uncertain
real = 2
pairs_per_variable = 2
abscissas
= 3.1415 4.5389
counts
= 1
1

3
100 200.112345 300
1
2
1

There are two variables, the first one has two possible real values which are equally probable. The second one
has three possible real value options, and 200.112345 is twice as probable as either 100 or 300.
pairs per variable
Keywords Area
variables
histogram point uncertain
real
pairs per variable
Number of pairs defining each histogram point real variable

Specification
Alias: num pairs
Argument(s): INTEGERLIST
Default: equal distribution

2070

CHAPTER 6. KEYWORDS AREA

Description
By default, the list of abscissas and counts will be evenly divided among the histogram point real variables.
The number of pairs per variable specifies the apportionment of abscissa/count pairs among the histogram
point real variables. It must specify one integer >=1 per variable that indicates how many of the (abscissa, count)
= (x,c) pairs to associate with that variable.
abscissas
Keywords Area
variables
histogram point uncertain
real
abscissas
Real abscissas for a point histogram

Specification
Alias: none
Argument(s): REALLIST

Description
A list of real abscissa (x coordinate) values characterizing the probability density function for each of the real
histogram point uncertain variables. These must be listed in increasing order for each variable, and are
paired with counts. See histogram point uncertain for details and examples.
counts
Keywords Area
variables
histogram point uncertain
real
counts
Counts for real-valued point histogram

Specification
Alias: none
Argument(s): REALLIST

Description
Count or frequency for each of abscissas. See histogram point uncertain for details and examples.

6.4. VARIABLES

2071

initial point
Keywords Area
variables
histogram point uncertain
real
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
histogram point uncertain
real
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: hpruv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

2072

6.4.26

CHAPTER 6. KEYWORDS AREA

uncertain correlation matrix

Keywords Area
variables
uncertain correlation matrix
Correlation among aleatory uncertain variables

Specification
Alias: none
Argument(s): REALLIST
Default: identity matrix (uncorrelated)

Description
Aleatory uncertain variables may have correlations specified through use of an uncertain correlationmatrix specification. This specification is generalized in the sense that its specific meaning depends on the
nondeterministic method in use.
When the method is a nondeterministic sampling method (i.e., sampling), then the correlation matrix specifies
rank correlations [52].
When the method is a reliability (i.e., local reliability or global reliability) or stochastic
expansion (i.e., polynomial chaos or stoch collocation) method, then the correlation matrix specifies
correlation coefficients (normalized covariance)[42].
In either of these cases, specifying the identity matrix results in uncorrelated uncertain variables (the default).
The matrix input should be symmetric and have all n2 entries where n is the total number of aleatory uncertain
variables.
Ordering of the aleatory uncertain variables is:
1. normal
2. lognormal
3. uniform
4. loguniform
5. triangular
6. exponential
7. beta
8. gamma
9. gumbel
10. frechet
11. weibull
12. histogram bin
13. poisson

6.4. VARIABLES

2073

14. binomial
15. negative binomial
16. geometric
17. hypergeometric
18. histogram point
When additional variable types are activated, they assume uniform distributions, and the ordering is as listed
on variables.

Examples
Consider the following random variables, distributions and correlations:
X1 , normal, uncorrelated with others
X2 , normal, correlated with X3 , X4 and X5
X3 , weibull , correlated with X5
X4 , exponential, correlated with X3 , X4 and X5
X5 , normal, correlated with X5 These correlations are captured by the following commands (order of the
variables is respected).
uncertain_correlation_matrix
# ordering normal, exponential, weibull
# \f$X_1\f$ \f$X_2\f$ \f$X_5\f$ \f$X_4$\f \f$X_3\f$
1.00 0.00 0.00 0.00 0.00
0.00 1.00 0.50 0.24 0.78
0.00 0.50 1.00 0.00 0.20
0.00 0.24 0.00 1.00 0.49
0.00 0.78 0.20 0.49 1.0

6.4.27

continuous interval uncertain

Keywords Area
variables
continuous interval uncertain
Epistemic uncertain variable - values from one or more continuous intervals

Topics
This keyword is related to the topics:
continuous variables
epistemic uncertain variables

Specification
Alias: interval uncertain
Argument(s): INTEGER
Default: no continuous interval uncertain variables

2074

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
num intervals

Optional

interval probabilities

Required

lower bounds

Required

upper bounds

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
Specify the
number of intervals
for each variable
Assign probability
mass to each
interval
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
Continuous interval uncertain variables are epistemic types. They can specify a single interval per variable which
may be used in interval analysis, where the goal is to determine the interval bounds on the output corresponding to
the interval bounds on the input. All values between the bounds are permissible. More detailed continuous interval
representations can specify a set of belief structures based on intervals that may be contiguous, overlapping, or
disjoint. This is used in specifying the inputs necessary for an epistemic uncertainty analysis using Dempster-Shafer theory of evidence.
Other epistemic types include:
discrete interval uncertain
discrete uncertain set integer
discrete uncertain set string
discrete uncertain set real

Examples
The following specification is for an interval analysis:
continuous_interval_uncertain = 2
lower_bounds = 2.0 4.0
upper_bounds = 2.5 5.0

The following specification is for a Dempster-Shafer analysis:

continuous_interval_uncertain =
num_intervals = 3 2
interval_probs = 0.25 0.5 0.25
lower_bounds = 2.0 4.0 4.5 1.0
upper_bounds = 2.5 5.0 6.0 5.0

2
0.4 0.6
3.0
5.0

Here there are 2 interval uncertain variables. The first one is defined by three intervals, and the second by
two intervals. The three intervals for the first variable have basic probability assignments of 0.2, 0.5, and 0.3,
respectively, while the basic probability assignments for the two intervals for the second variable are 0.4 and 0.6.

6.4. VARIABLES

2075

The basic probability assignments for each interval variable must sum to one. The interval bounds for the first
variable are [2, 2.5], [4, 5], and [4.5, 6], and the interval bounds for the second variable are [1.0, 5.0] and [3.0,
5.0]. Note that the intervals can be overlapping or disjoint. The BPA for the first variable indicates that it is twice
as likely that the value occurs on the interval [4,5] than either [2,2.5] or [4.5,6].

Theory
The continuous interval uncertain variable is NOT a probability distribution. Although it may seem similar to a
histogram, the interpretation of this uncertain variable is different. It is used in epistemic uncertainty analysis,
where one is trying to model uncertainty due to lack of knowledge. The continuous interval uncertain variable is
used in both interval analysis and in Dempster-Shafer theory of evidence.
interval analysis -only one interval is allowed for each continuous interval uncertain variable
-the interval is defined by lower and upper bounds -the value of the random variable lies somewhere in this
interval -output is the minimum and maximum function value conditional on the specified interval
Dempster-Shafer theory of evidence -multiple intervals can be assigned to each continuous intervaluncertain variable -a Basic Probability Assignment (BPA) is associated with each interval. The BPA
represents a probability that the value of the uncertain variable is located within that interval. -each interval
is defined by lower and upper bounds -outputs are called belief and plausibility. Belief represents the
smallest possible probability that is consistent with the evidence, while plausibility represents the largest
possible probability that is consistent with the evidence. Evidence is the intervals together with their BPA.
num intervals
Keywords Area
variables
continuous interval uncertain
num intervals
Specify the number of intervals for each variable

Specification
Alias: iuv num intervals
Argument(s): INTEGERLIST
Default: Equal apportionment of intervals among variables

Description
In Dakota, epistemic uncertainty analysis is performed using either interval estimation or Dempster-Shafer theory
of evidence. In these approaches, one does not assign a probability distribution to each uncertain input variable.
Rather, one divides each uncertain input variable into one or more intervals. The input parameters are only known
to occur within intervals; nothing more is assumed. num intervals specifies the number of such intervals
associated with each interval uncertain parameter.

2076

CHAPTER 6. KEYWORDS AREA

interval probabilities
Keywords Area
variables
continuous interval uncertain
interval probabilities
Assign probability mass to each interval

Specification
Alias: interval probs iuv interval probs
Argument(s): REALLIST
Default: Equal probability assignments for each interval (1/num intervals[i])

Description
The basic probability assignments for each interval variable must sum to one. For example, if an interval variable
is defined with three intervals, the probabilities for these intervals could be 0.2, 0.5, and 0.3 which sum to one,
but could not be 0.5,0.5, and 0.5 which do not sum to one.
lower bounds
Keywords Area
variables
continuous interval uncertain
lower bounds
Specify minimum values

Specification
Alias: none
Argument(s): REALLIST

Description
Specify minimum values
upper bounds
Keywords Area
variables
continuous interval uncertain
upper bounds
Specify maximium values

6.4. VARIABLES

2077

Specification
Alias: none
Argument(s): REALLIST

Description
Specify maximium values
initial point
Keywords Area
variables
continuous interval uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
continuous interval uncertain
descriptors
Labels for the variables

Specification
Alias: iuv descriptors
Argument(s): STRINGLIST
Default: ciuv {i}

2078

CHAPTER 6. KEYWORDS AREA

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.28

discrete interval uncertain

Keywords Area
variables
discrete interval uncertain
Epistemic uncertain variable - values from one or more discrete intervals

Topics
This keyword is related to the topics:
discrete variables
epistemic uncertain variables

Specification
Alias: discrete uncertain range
Argument(s): INTEGER
Default: No discrete interval uncertain variables
Required/Description of
Optional
Group
Optional

Dakota Keyword
num intervals

Optional

interval probabilities

Required

lower bounds

Required

upper bounds

Optional

initial point

Optional

descriptors

Dakota Keyword
Description
Specify the
number of intervals
for each variable
Assign probability
mass to each
interval
Specify minimum
values
Specify maximium
values
Initial values
Labels for the
variables

Description
Discrete interval uncertain variables are epistemic types. They can specify a single interval per variable which
may be used in interval analysis, where the goal is to determine the interval bounds on the output corresponding to
the interval bounds on the input. Permissible values are any integer within the bound. More detailed continuous

6.4. VARIABLES

2079

interval representations can specify a set of belief structures based on intervals that may be contiguous, overlapping, or disjoint. This is used in specifying the inputs necessary for an epistemic uncertainty analysis using
Dempster-Shafer theory of evidence.
Other epistemic types include:
continuous interval uncertain
discrete uncertain set integer
discrete uncertain set string
discrete uncertain set real

Examples
Let d1 be 2, 3 or 4 with probability 0.2, 4 or 5 with probability 0.5 and 6 with probability 0.3. Let d2 be 4, 5
or 6 with probability 0.4 and 6, 7 or 8 with probability 0.6. The following specification is for a Dempster-Shafer
analysis:
discrete_interval_uncertain = 2
num_intervals = 3 2
interval_probs = 0.2 0.5 0.3 0.4 0.6
lower_bounds = 2 4 6 4 6
upper_bounds = 4 5 6 6 8

Theory
Dempster-Shafer theory of evidence -multiple intervals can be assigned to each discrete intervaluncertain variable -a Basic Probability Assignment (BPA) is associated with each interval. The BPA
represents a probability that the value of the uncertain variable is located within that interval. -each interval
is defined by lower and upper bounds -outputs are called belief and plausibility. Belief represents the
smallest possible probability that is consistent with the evidence, while plausibility represents the largest
possible probability that is consistent with the evidence. Evidence is the intervals together with their BPA.
num intervals
Keywords Area
variables
discrete interval uncertain
num intervals
Specify the number of intervals for each variable

Specification
Alias: none
Argument(s): INTEGERLIST
Default: Equal apportionment of intervals among variables

2080

CHAPTER 6. KEYWORDS AREA

Description
In Dakota, epistemic uncertainty analysis is performed using either interval estimation or Dempster-Shafer theory
of evidence. In these approaches, one does not assign a probability distribution to each uncertain input variable.
Rather, one divides each uncertain input variable into one or more intervals. The input parameters are only known
to occur within intervals; nothing more is assumed. num intervals specifies the number of such intervals
associated with each interval uncertain parameter.
interval probabilities
Keywords Area
variables
discrete interval uncertain
interval probabilities
Assign probability mass to each interval

Specification
Alias: interval probs range probabilities range probs
Argument(s): REALLIST
Default: Equal probability assignments for each interval (1/num intervals[i])

Description
The basic probability assignments for each interval variable must sum to one. For example, if an interval variable
is defined with three intervals, the probabilities for these intervals could be 0.2, 0.5, and 0.3 which sum to one,
but could not be 0.5,0.5, and 0.5 which do not sum to one.
lower bounds
Keywords Area
variables
discrete interval uncertain
lower bounds
Specify minimum values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Specify minimum values

6.4. VARIABLES

2081

upper bounds
Keywords Area
variables
discrete interval uncertain
upper bounds
Specify maximium values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
Specify maximium values
initial point
Keywords Area
variables
discrete interval uncertain
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
discrete interval uncertain
descriptors
Labels for the variables

2082

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: diuv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.29

discrete uncertain set

Keywords Area
variables
discrete uncertain set
Set-valued discrete uncertain variables

Topics
This keyword is related to the topics:
discrete variables
epistemic uncertain variables

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
integer

string

Dakota Keyword
Description
Discrete, epistemic
uncertain variable integers within a
set
Discrete, epistemic
uncertain variable strings within a set

6.4. VARIABLES

2083
Optional

real

Discrete, epistemic
uncertain variable real numbers
within a set

Description
Discrete uncertain variables whose values come from a set of admissible elements. Each variable specified must
be of type integer, string, or real.
integer
Keywords Area
variables
discrete uncertain set
integer
Discrete, epistemic uncertain variable - integers within a set

Topics
This keyword is related to the topics:
discrete variables
epistemic uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete uncertain set integer variables
Required/Description of
Optional
Group
Optional

Required

Dakota Keyword
elements per variable

elements

Dakota Keyword
Description
Number of
admissible
elements for each
set variable
The permissible
values for each
discrete variable

2084

CHAPTER 6. KEYWORDS AREA

Optional

set probabilities

Optional

categorical

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

This keyword
defines the
probabilities for
the various
elements of
discrete sets.
Whether the
set-valued
variables are
categorical or
relaxable

Description
Discrete set variables may be used to specify categorical choices which are epistemic. For example, if we have
three possible forms for a physics model (model 1, 2, or 3) and there is epistemic uncertainty about which one is
correct, a discrete uncertain set may be used to represent this type of uncertainty.
This variable is defined by a set of integers, in which the discrete value may take any value within the integer
set (for example, the set may be defined as 1, 2, and 4)
Other epistemic types include:
continuous interval uncertain
discrete interval uncertain
discrete uncertain set string
discrete uncertain set real

Examples
Let d1 be 2 or 13 and d2 be 4, 5 or 26. The following specification is for an interval analysis:
discrete_uncertain_set
integer
num_set_values 2
3
set_values
2 13 4 5 26
descriptors
di1 di2

Theory
The discrete uncertain set-integer variable is NOT a discrete random variable. It can be contrasted
to a the histogram-defined random variables: histogram bin uncertain and histogram point uncertain. It is used
in epistemic uncertainty analysis, where one is trying to model uncertainty due to lack of knowledge.
The discrete uncertain set integer variable is used in both interval analysis and in Dempster-Shafer theory of
evidence.

6.4. VARIABLES

2085

interval analysis -the values are integers, equally weighted -the true value of the random variable is one of
the integers in this set -output is the minimum and maximum function value conditional on the specified
inputs
Dempster-Shafer theory of evidence -the values are integers, but they can be assigned different weights
-outputs are called belief and plausibility. Belief represents the smallest possible probability that is
consistent with the evidence, while plausibility represents the largest possible probability that is consistent
with the evidence. Evidence is the values together with their weights.
elements per variable
Keywords Area
variables
discrete uncertain set
integer
elements per variable
Number of admissible elements for each set variable

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete uncertain set
integer
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): INTEGERLIST

2086

CHAPTER 6. KEYWORDS AREA

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
set probabilities
Keywords Area
variables
discrete uncertain set
integer
set probabilities
This keyword defines the probabilities for the various elements of discrete sets.

Specification
Alias: set probs
Argument(s): REALLIST
Default: Equal probability assignments for each set member (1/num set values[i])

Description
There are three types of discrete uncertain set variables: integer, string, or real sets. With each of
these types, one defines the number of elements of the set per that variable, the values of those elements, and the
associated probabilities. For example, if one has an integer discrete uncertain set variable with 3 elements {3,4,8},
then one could define the probabilities associated with those set elements as (for example) 0.2, 0.5, and 0.3. The
set probabilities for a particular variable should sum to one over all the elements in that set.
categorical
Keywords Area
variables
discrete uncertain set
integer
categorical
Whether the set-valued variables are categorical or relaxable

Specification
Alias: none
Argument(s): STRINGLIST

6.4. VARIABLES

2087

Description
A list of strings of length equal to the number of set (integer, string, or real) variables indicating whether they are
strictly categorical, meaning may only take on values from the provided set, or relaxable, meaning may take on
any integer or real value between the lowest and highest specified element. Valid categorical strings include yes,
no, true, and false, or any abbreviation in [yYnNtTfF][.]

Examples
Discrete design set variable, rotor blades, can take on only integer values, 2, 4, or 7 by default. Since categorical
is specified to be false, the integrality can be relaxed and rotor blades can take on any value between 2 and 7,
e.g., 3, 6, or 5.5.
discrete_design_set
integer 1
elements 2 4 7
descriptor rotor_blades
categorical no

initial point
Keywords Area
variables
discrete uncertain set
integer
initial point
Initial values

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
discrete uncertain set
integer
descriptors
Labels for the variables

2088

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: dusiv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
string
Keywords Area
variables
discrete uncertain set
string
Discrete, epistemic uncertain variable - strings within a set

Topics
This keyword is related to the topics:
discrete variables
epistemic uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete uncertain set string variables
Required/Description of
Optional
Group
Optional

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

6.4. VARIABLES

2089
Required

elements

The permissible
values for each
discrete variable

Optional

set probabilities

Optional

initial point

This keyword
defines the
probabilities for
the various
elements of
discrete sets.
Initial values

Optional

descriptors

Labels for the

variables

Description
Discrete set variables may be used to specify categorical choices which are epistemic. For example, if we have
three possible forms for a physics model (model 1, 2, or 3) and there is epistemic uncertainty about which one is
correct, a discrete uncertain set may be used to represent this type of uncertainty.
This variable is defined by a set of strings, in which the discrete value may take any value within the string set
(for example, the set may be defined as coarse, medium, and fine)
Other epistemic types include:
continuous interval uncertain
discrete interval uncertain
discrete uncertain set integer
discrete uncertain set real

Examples
discrete_uncertain_set
string
num_set_values 2
set_values
red blue
descriptors
ds1

3
coarse medium fine
ds2

elements per variable

Keywords Area
variables
discrete uncertain set
string
elements per variable
Number of admissible elements for each set variable

2090

CHAPTER 6. KEYWORDS AREA

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete uncertain set
string
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): STRINGLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
set probabilities
Keywords Area
variables
discrete uncertain set
string
set probabilities
This keyword defines the probabilities for the various elements of discrete sets.

6.4. VARIABLES

2091

Specification
Alias: set probs
Argument(s): REALLIST
Default: Equal probability assignments for each set member (1/num set values[i])

Description
There are three types of discrete uncertain set variables: integer, string, or real sets. With each of
these types, one defines the number of elements of the set per that variable, the values of those elements, and the
associated probabilities. For example, if one has an integer discrete uncertain set variable with 3 elements {3,4,8},
then one could define the probabilities associated with those set elements as (for example) 0.2, 0.5, and 0.3. The
set probabilities for a particular variable should sum to one over all the elements in that set.
initial point
Keywords Area
variables
discrete uncertain set
string
initial point
Initial values

Specification
Alias: none
Argument(s): STRINGLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).
descriptors
Keywords Area
variables
discrete uncertain set
string
descriptors
Labels for the variables

2092

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: dussv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
real
Keywords Area
variables
discrete uncertain set
real
Discrete, epistemic uncertain variable - real numbers within a set

Topics
This keyword is related to the topics:
discrete variables
epistemic uncertain variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete uncertain set real variables
Required/Description of
Optional
Group
Optional

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

6.4. VARIABLES

2093
Required

elements

The permissible
values for each
discrete variable

Optional

set probabilities

Optional

categorical

This keyword
defines the
probabilities for
the various
elements of
discrete sets.
Whether the
set-valued
variables are
categorical or
relaxable

Optional

initial point

Initial values

Optional

descriptors

Labels for the

variables

Description
Discrete set variables may be used to specify categorical choices which are epistemic. For example, if we have
three possible forms for a physics model (model 1, 2, or 3) and there is epistemic uncertainty about which one is
correct, a discrete uncertain set may be used to represent this type of uncertainty.
This variable is defined by a set of reals, in which the discrete variable may take any value defined within the
real set (for example, a parameter may have two allowable real values, 3.285 or 4.79).
Other epistemic types include:
continuous interval uncertain
discrete interval uncertain
discrete uncertain set integer
discrete uncertain set string

Examples
Let d1 be 2.1 or 1.3 and d2 be 0.4, 5 or 2.6. The following specification is for an interval analysis:
discrete_uncertain_set
integer
num_set_values 2
set_values
2.1 1.3
descriptors
dr1

3
0.4 5
dr2

2.6

Theory
The discrete uncertain set-integer variable is NOT a discrete random variable. It can be contrasted
to a the histogram-defined random variables: histogram bin uncertain and histogram point uncertain. It is used
in epistemic uncertainty analysis, where one is trying to model uncertainty due to lack of knowledge.

2094

CHAPTER 6. KEYWORDS AREA

The discrete uncertain set integer variable is used in both interval analysis and in Dempster-Shafer theory of
evidence.
interval analysis -the values are integers, equally weighted -the true value of the random variable is one of
the integers in this set -output is the minimum and maximum function value conditional on the specified
inputs
Dempster-Shafer theory of evidence -the values are integers, but they can be assigned different weights
-outputs are called belief and plausibility. Belief represents the smallest possible probability that is
consistent with the evidence, while plausibility represents the largest possible probability that is consistent
with the evidence. Evidence is the values together with their weights.
elements per variable
Keywords Area
variables
discrete uncertain set
real
elements per variable
Number of admissible elements for each set variable

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete uncertain set
real
elements
The permissible values for each discrete variable

6.4. VARIABLES

2095

Specification
Alias: set values
Argument(s): REALLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
set probabilities
Keywords Area
variables
discrete uncertain set
real
set probabilities
This keyword defines the probabilities for the various elements of discrete sets.

Specification
Alias: set probs
Argument(s): REALLIST
Default: Equal probability assignments for each set member (1/num set values[i])

Description
There are three types of discrete uncertain set variables: integer, string, or real sets. With each of
these types, one defines the number of elements of the set per that variable, the values of those elements, and the
associated probabilities. For example, if one has an integer discrete uncertain set variable with 3 elements {3,4,8},
then one could define the probabilities associated with those set elements as (for example) 0.2, 0.5, and 0.3. The
set probabilities for a particular variable should sum to one over all the elements in that set.
categorical
Keywords Area
variables
discrete uncertain set
real
categorical
Whether the set-valued variables are categorical or relaxable

2096

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST

Description
A list of strings of length equal to the number of set (integer, string, or real) variables indicating whether they are
strictly categorical, meaning may only take on values from the provided set, or relaxable, meaning may take on
any integer or real value between the lowest and highest specified element. Valid categorical strings include yes,
no, true, and false, or any abbreviation in [yYnNtTfF][.]

Examples
Discrete design set variable, rotor blades, can take on only integer values, 2, 4, or 7 by default. Since categorical
is specified to be false, the integrality can be relaxed and rotor blades can take on any value between 2 and 7,
e.g., 3, 6, or 5.5.
discrete_design_set
integer 1
elements 2 4 7
descriptor rotor_blades
categorical no

initial point
Keywords Area
variables
discrete uncertain set
real
initial point
Initial values

Specification
Alias: none
Argument(s): REALLIST

Description
The initial point specifications provide the point in design space (variable values) from which an iterator
is started. These default to the midpoint of bounds (continuous design variables) or the middle value (discrete
design variables).

6.4. VARIABLES

2097

descriptors
Keywords Area
variables
discrete uncertain set
real
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: dusrv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.30

continuous state

Keywords Area
variables
continuous state
Continuous state variables

Topics
This keyword is related to the topics:
state variables
continuous variables

Specification
Alias: none
Argument(s): INTEGER
Default: No continuous state variables
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

2098

CHAPTER 6. KEYWORDS AREA

Optional

initial state

Optional

lower bounds

Optional

upper bounds

Optional

descriptors

Initial values for

the state variables
Specify minimum
values
Specify maximium
values
Labels for the
variables

Description
Continuous state variables are defined by bounds.
Default behavior for most methods is that only the initial state values are used.
See the state variables page for details on the behavior of state variables.
initial state
Keywords Area
variables
continuous state
initial state
Initial values for the state variables

Specification
Alias: csv initial state
Argument(s): REALLIST
Default: 0.0

Description
The initial state specifications provide the initial values for the state variables.
This is an optional keyword. If it is not specified, the initial state will be inferred from the other keywords that
define the state variable.
Defaults are:
Continuous state variables - use the midpoint of the bounds
Set variables - use the value with the index closest to the middle of the set
Range variables - use the midpoint of the range

6.4. VARIABLES
lower bounds
Keywords Area
variables
continuous state
lower bounds
Specify minimum values

Specification
Alias: csv lower bounds
Argument(s): REALLIST
Default: -infinity

Description
Specify minimum values
upper bounds
Keywords Area
variables
continuous state
upper bounds
Specify maximium values

Specification
Alias: csv upper bounds
Argument(s): REALLIST
Default: infinity

Description
Specify maximium values
descriptors
Keywords Area
variables
continuous state
descriptors
Labels for the variables

2099

2100

CHAPTER 6. KEYWORDS AREA

Specification
Alias: csv descriptors
Argument(s): STRINGLIST
Default: csv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.31

discrete state range

Keywords Area
variables
discrete state range
Discrete state variables; each defined by an integer interval

Topics
This keyword is related to the topics:
discrete variables
state variables

Specification
Alias: none
Argument(s): INTEGER
Default: No discrete state variables
Required/Optional
Optional

Description of
Group

Dakota Keyword
initial state

Optional

lower bounds

Optional

upper bounds

Optional

descriptors

Dakota Keyword
Description
Initial values for
the state variables
Specify minimum
values
Specify maximium
values
Labels for the
variables

Description
Discrete state variables defined by bounds.
The details of how to specify this discrete variable are located on the discrete variables page.
See the state variables page for details on the behavior of state variables.

6.4. VARIABLES

2101

initial state
Keywords Area
variables
discrete state range
initial state
Initial values for the state variables

Specification
Alias: dsv initial state
Argument(s): INTEGERLIST
Default: 0

Description
The initial state specifications provide the initial values for the state variables.
This is an optional keyword. If it is not specified, the initial state will be inferred from the other keywords that
define the state variable.
Defaults are:
Continuous state variables - use the midpoint of the bounds
Set variables - use the value with the index closest to the middle of the set
Range variables - use the midpoint of the range
lower bounds
Keywords Area
variables
discrete state range
lower bounds
Specify minimum values

Specification
Alias: dsv lower bounds
Argument(s): INTEGERLIST
Default: INT MIN

Description
Specify minimum values

2102

CHAPTER 6. KEYWORDS AREA

upper bounds
Keywords Area
variables
discrete state range
upper bounds
Specify maximium values

Specification
Alias: dsv upper bounds
Argument(s): INTEGERLIST
Default: INT MAX

Description
Specify maximium values
descriptors
Keywords Area
variables
discrete state range
descriptors
Labels for the variables

Specification
Alias: dsv descriptors
Argument(s): STRINGLIST
Default: dsriv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.4.32

discrete state set

Keywords Area
variables
discrete state set
Set-valued discrete state variables

6.4. VARIABLES

2103

Topics
This keyword is related to the topics:
discrete variables
state variables

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
integer

Optional

string

Optional

real

Dakota Keyword
Description
Discrete state
variables, each
defined by a set of
permissible
integers
String-valued
discrete state set
variables
Discrete state
variables, each
defined by a set of
permissible real
numbers

Description
Discrete state variables whose values come from a set of admissible elements. Each variable specified must be of
type integer, string, or real.
integer
Keywords Area
variables
discrete state set
integer
Discrete state variables, each defined by a set of permissible integers

Topics
This keyword is related to the topics:
discrete variables
state variables

2104

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete state set integer variables
Required/Description of
Optional
Group
Optional

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

Required

elements

The permissible
values for each
discrete variable

Optional

categorical

Whether the
set-valued
variables are
categorical or
relaxable

Optional

initial state

Optional

descriptors

Initial values for

the state variables
Labels for the
variables

Description
Discrete state variables defined by a set of permissible integers.
The details of how to specify this discrete variable are located on the discrete variables page.
See the state variables page for details on the behavior of state variables.
elements per variable
Keywords Area
variables
discrete state set
integer
elements per variable
Number of admissible elements for each set variable

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

6.4. VARIABLES

2105

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete state set
integer
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): INTEGERLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
categorical
Keywords Area
variables
discrete state set
integer
categorical
Whether the set-valued variables are categorical or relaxable

Specification
Alias: none
Argument(s): STRINGLIST

Description
A list of strings of length equal to the number of set (integer, string, or real) variables indicating whether they are
strictly categorical, meaning may only take on values from the provided set, or relaxable, meaning may take on
any integer or real value between the lowest and highest specified element. Valid categorical strings include yes,
no, true, and false, or any abbreviation in [yYnNtTfF][.]

2106

CHAPTER 6. KEYWORDS AREA

Examples
Discrete design set variable, rotor blades, can take on only integer values, 2, 4, or 7 by default. Since categorical
is specified to be false, the integrality can be relaxed and rotor blades can take on any value between 2 and 7,
e.g., 3, 6, or 5.5.
discrete_design_set
integer 1
elements 2 4 7
descriptor rotor_blades
categorical no

initial state
Keywords Area
variables
discrete state set
integer
initial state
Initial values for the state variables

Specification
Alias: none
Argument(s): INTEGERLIST
Default: middle set value, or rounded down

Description
The initial state specifications provide the initial values for the state variables.
This is an optional keyword. If it is not specified, the initial state will be inferred from the other keywords that
define the state variable.
Defaults are:
Continuous state variables - use the midpoint of the bounds
Set variables - use the value with the index closest to the middle of the set
Range variables - use the midpoint of the range
descriptors
Keywords Area
variables
discrete state set
integer
descriptors
Labels for the variables

6.4. VARIABLES

2107

Specification
Alias: none
Argument(s): STRINGLIST
Default: dssiv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
string
Keywords Area
variables
discrete state set
string
String-valued discrete state set variables

Topics
This keyword is related to the topics:
discrete variables
state variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete state set string variables
Required/Description of
Optional
Group
Optional

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

2108

CHAPTER 6. KEYWORDS AREA

Required

elements

The permissible
values for each
discrete variable

Optional

initial state

Optional

descriptors

Initial values for

the state variables
Labels for the
variables

Description
Discrete state variables whose values come from a specified set of admissible strings. The details of how to
specify this discrete variable are located on the discrete variables page. See the state variables page for details on
the behavior of state variables. Each string element value must be quoted and may contain alphanumeric, dash,
underscore, and colon. White space, quote characters, and backslash/metacharacters are not permitted.
elements per variable
Keywords Area
variables
discrete state set
string
elements per variable
Number of admissible elements for each set variable

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete state set
string

6.4. VARIABLES

2109

elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): STRINGLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
initial state
Keywords Area
variables
discrete state set
string
initial state
Initial values for the state variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: middle set value, or rounded down

Description
The initial state specifications provide the initial values for the state variables.
This is an optional keyword. If it is not specified, the initial state will be inferred from the other keywords that
define the state variable.
Defaults are:
Continuous state variables - use the midpoint of the bounds
Set variables - use the value with the index closest to the middle of the set
Range variables - use the midpoint of the range

2110

CHAPTER 6. KEYWORDS AREA

descriptors
Keywords Area
variables
discrete state set
string
descriptors
Labels for the variables

Specification
Alias: none
Argument(s): STRINGLIST
Default: dsssv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.
real
Keywords Area
variables
discrete state set
real
Discrete state variables, each defined by a set of permissible real numbers

Topics
This keyword is related to the topics:
discrete variables
state variables

Specification
Alias: none
Argument(s): INTEGER
Default: no discrete state set real variables

6.4. VARIABLES

2111
Required/Optional
Optional

Description of
Group

Dakota Keyword
elements per variable

Dakota Keyword
Description
Number of
admissible
elements for each
set variable

Required

elements

The permissible
values for each
discrete variable

Optional

categorical

Whether the
set-valued
variables are
categorical or
relaxable

Optional

initial state

Optional

descriptors

Initial values for

the state variables
Labels for the
variables

Description
Discrete state variables defined by a set of permissible real numbers.
The details of how to specify this discrete variable are located on the discrete variables page.
See the state variables page for details on the behavior of state variables.
elements per variable
Keywords Area
variables
discrete state set
real
elements per variable
Number of admissible elements for each set variable

Specification
Alias: num set values
Argument(s): INTEGERLIST
Default: equal distribution

2112

CHAPTER 6. KEYWORDS AREA

Description
Discrete set variables (including design, uncertain, and state) take on only a fixed set of values. For each type
(integer, string, or real), this keyword specifies how many admissible values are provided for each variable. If
not specified, equal apportionment of elements among variables is assumed, and the number of elements must be
evenly divisible by the number of variables.
elements
Keywords Area
variables
discrete state set
real
elements
The permissible values for each discrete variable

Specification
Alias: set values
Argument(s): REALLIST

Description
Specify the permissible values for discrete set variables (of type integer, string, or real). See the description on
the discrete variables page.
categorical
Keywords Area
variables
discrete state set
real
categorical
Whether the set-valued variables are categorical or relaxable

Specification
Alias: none
Argument(s): STRINGLIST

Description
A list of strings of length equal to the number of set (integer, string, or real) variables indicating whether they are
strictly categorical, meaning may only take on values from the provided set, or relaxable, meaning may take on
any integer or real value between the lowest and highest specified element. Valid categorical strings include yes,
no, true, and false, or any abbreviation in [yYnNtTfF][.]

6.4. VARIABLES

2113

Examples
Discrete design set variable, rotor blades, can take on only integer values, 2, 4, or 7 by default. Since categorical
is specified to be false, the integrality can be relaxed and rotor blades can take on any value between 2 and 7,
e.g., 3, 6, or 5.5.
discrete_design_set
integer 1
elements 2 4 7
descriptor rotor_blades
categorical no

initial state
Keywords Area
variables
discrete state set
real
initial state
Initial values for the state variables

Specification
Alias: none
Argument(s): REALLIST
Default: middle set value, or rounded down

Description
The initial state specifications provide the initial values for the state variables.
This is an optional keyword. If it is not specified, the initial state will be inferred from the other keywords that
define the state variable.
Defaults are:
Continuous state variables - use the midpoint of the bounds
Set variables - use the value with the index closest to the middle of the set
Range variables - use the midpoint of the range
descriptors
Keywords Area
variables
discrete state set
real
descriptors
Labels for the variables

2114

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): STRINGLIST
Default: dssrv {i}

Description
The optional variables labels specification descriptors is a list of strings which identify the variables. These
are used in console and tabular output.
The default descriptor strings use a root string plus a numeric identifier.

6.5

interface

Keywords Area
interface
Specifies how function evaluations will be performed in order to map the variables into the responses.

Topics
This keyword is related to the topics:
block

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
id interface

Optional

algebraic mappings

Optional

analysis drivers

Dakota Keyword
Description
Name the interface
block; helpful
when there are
multiple
Use AMPL to
define algebraic
input-output
mappings
Define how Dakota
should run a
function evaluation

6.5. INTERFACE

2115
Optional

asynchronous

Optional

evaluation servers

Optional

evaluation scheduling

Optional

processors per evaluation

Optional

analysis servers

Optional

analysis scheduling

Specify analysis
driver concurrency,
when Dakota is run
in serial
Specify the
number of
evaluation servers
when Dakota is run
in parallel
Specify the
scheduling of
concurrent
evaluations when
Dakota is run in
parallel
Specify the
number of
processors per
evaluation server
when Dakota is run
in parallel
Specify the
number of analysis
servers when
Dakota is run in
parallel
Specify the
scheduling of
concurrent
analyses when
Dakota is run in
parallel

Description
The interface section in a Dakota input file specifies how function evaluations will be performed in order to map
the variables into the responses.
In this context, a function evaluation is the series of operations that takes the variables and computes the
responses. This can be comprised of one or many codes, scripts, and glue, which are generically referred to as
analysis drivers.
The optional asynchronous flag specifies use of asynchronous protocols (i.e., background system calls,
nonblocking forks, POSIX threads) when evaluations or analyses are invoked. The evaluation concurrency
and analysis concurrency specifications serve a dual purpose:
when running Dakota on a single processor in asynchronous mode, the default concurrency of evaluations and analyses is all concurrency that is available. The evaluation concurrency and analysisconcurrency specifications can be used to limit this concurrency in order to avoid machine overload or
usage policy violation.
when running Dakota on multiple processors in message passing mode, the default concurrency of evaluations and analyses on each of the servers is one (i.e., the parallelism is exclusively that of the message

2116

CHAPTER 6. KEYWORDS AREA

passing). With the evaluation concurrency and analysis concurrency specifications, a hybrid parallelism can be selected through combination of message passing parallelism with asynchronous
parallelism on each server.

If Dakotas automatic parallel configuration is undesirable for some reason, the user can specify overrides that enforce a desired number of partitions, a size for the partitions, and/or a desired scheduling configuration at the evaluation and analysis parallelism levels. The optional evaluation servers and analysis servers specifications support user overrides of the automatic parallel configuration for the number of evaluation servers and
the number of analysis servers, and the optional processors per evaluation specification supports user
overrides for the size of processor allocations for evaluation servers (Note: see direct for the processors peranalysis specification supported for direct interfaces). Similarly, the optional evaluation scheduling
and analysis scheduling specifications can be used to override the automatic parallel configuration at the
evaluation and analysis parallelism levels to use either a dedicated master or a peer partition. In addition,
the evaluation parallelism level supports an override for the scheduling algorithm used within a peer partition;
this can be either dynamic or static scheduling (default configuration of a peer partition employs a dynamic
scheduler when it can be supported; i.e., when the peer 1 local scheduling can be asynchronous). The ParallelLibrary class and the Parallel Computing chapter of the Users Manual[4] provide additional details on parallel
configurations.
When performing asynchronous local evaluations, the local evaluation scheduling keyword controls how new evaluation jobs are dispatched when one completes. If the local evaluation scheduling
is specified as dynamic (the default), each completed evaluation will be replaced by the next in the local evaluation queue. If local evaluation scheduling is specified as static, each completed evaluation will be
replaced by an evaluation number that is congruent modulo the evaluation concurrency. This is helpful
for relative node scheduling as described in Dakota/examples/parallelism. For example, assuming only
asynchronous local concurrency (no MPI), if the local concurrency is 6 and job 2 completes, it will be replaced
with job 8. For the case of hybrid parallelism, static local scheduling results in evaluation replacements that are
modulo the total capacity, defined as the product of the evaluation concurrency and the number of evaluation
servers. Both of these cases can result in idle processors if runtimes are non-uniform, so the default dynamic
scheduling is preferred when relative node scheduling is not required.

Theory
Function evaluations are performed using either interfaces to simulation codes, algebraic mappings, or a combination of the two.
When employing mappings with simulation codes, the interface invokes the simulation using either forks,
direct function invocations, or computational grid invocations.
In the fork case, Dakota will treat the simulation as a black-box and communication between Dakota and
the simulation occurs through parameter and result files. This is the most common case.
In the direct function case, the simulation is internal to Dakota and communication occurs through the
function parameter list. The direct case can involve linked simulation codes or test functions which are
compiled into the Dakota executable. The test functions allow for rapid testing of algorithms without
process creation overhead or engineering simulation expense.
The grid case is experimental and under development, but is intended to support simulations which are
external to Dakota and geographically distributed.
When employing algebraic mappings, the AMPL solver library[29] is used to evaluate a directed acyclic graph
(DAG) specification from a separate stub.nl file. Separate stub.col and stub.row files are also required to declare
the string identifiers of the subset of inputs and outputs, respectively, that will be used in the algebraic mappings.

6.5. INTERFACE

6.5.1

2117

id interface

Keywords Area
interface
id interface
Name the interface block; helpful when there are multiple

Topics
This keyword is related to the topics:
block identifier

Specification
Alias: none
Argument(s): STRING
Default: use of last interface parsed

Description
The optional set identifier specification uses the keyword id interface to input a string for use in identifying
a particular interface specification. A model can then identify the use of this interface by specifying the same
string in its interface pointer specification.
If the id interface specification is omitted, a particular interface specification will be used by a model
only if that model omits specifying a interface pointer and if the interface set was the last set parsed (or
is the only set parsed). In common practice, if only one interface set exists, then id interface can be safely
omitted from the interface specification and interface pointer can be omitted from the model specification(s), since there is no potential for ambiguity in this case.

Examples
For example, a model whose specification contains interface pointer = I1 will use an interface specification with id interface = I1.

6.5.2

algebraic mappings

Keywords Area
interface
algebraic mappings
Use AMPL to define algebraic input-output mappings

Specification
Alias: none
Argument(s): STRING
Default: no algebraic mappings

2118

CHAPTER 6. KEYWORDS AREA

Description
If desired, one can define algebraic input-output mappings using the AMPL code[26] and save these mappings in
3 files: stub.nl, stub.col, and stub.row, where stub is a particular root name describing a particular
problem. These files names can be communicated to Dakota using the algebraic mappings input. This
string may either specify the stub.nl filename, or alternatively, just the stub itself.
Dakota then uses stub.col and stub.row to extract the input and output identifier strings and employs
the AMPL solver library[29] to process the DAG specification in stub.nl. The variable and objective function
names declared within AMPL should be a subset of the variable descriptors and response descriptors used by
Dakota (see variables and descriptors). Ordering is not important, as Dakota will reorder data as needed.

6.5.3

analysis drivers

Keywords Area
interface
analysis drivers
Define how Dakota should run a function evaluation

Specification
Alias: none
Argument(s): STRINGLIST
Required/Optional
Optional

Description of
Group

Dakota Keyword
analysis components

Optional

input filter

Optional

output filter

system
Required(Choose
One)

Group 1

Dakota Keyword
Description
Provide additional
identifiers to
analysis drivers.
Run a
pre-processing
script before the
analysis drivers
Run a
post-processing
script after the
analysis drivers
(Not
recommended)
Launch analysis
drivers with a
system call

6.5. INTERFACE

2119
fork

direct

matlab

python

scilab

grid
Optional

failure capture

Optional

deactivate

Launch analysis
drivers using fork
command
Run analysis
drivers that are
linked-to or
compiled-with
Dakota
Run Matlab with a
direct interface requires special
Dakota build
Run Python with a
direct interface requires special
Dakota build
Run Scilab with a
direct interface requires special
Dakota build
Experimental
capability
Determine how
Dakota responds to
analysis driver
failure
Deactivate Dakota
features to simplify
interface
development,
increase execution
speed, or reduce
memory and disk
requirements

Description
The required 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).
Types of Interfaces
Dakota has two recommended ways of running analysis drivers:
as an external processes (fork), or
using internal code to couple to the analysis driver (direct)
Other options are available for advanced users, and are not as well documented, supported, or tested:
external processes (system)
internal coupling (python, matlab, scilab, grid)

2120

CHAPTER 6. KEYWORDS AREA

Use Cases
The internally coupled codes have few options because many of the details are already handled with the
coupling. Their behavior is described in the direct keyword.
For external processes using the fork keyword,
A function evaluation may comprise:
1. A single analysis driver: Function evaluation, including all pre- and post-processing is contained entirely
within a single script/executable.
2. A single analysis driver with filters: Function evaluation is explicitly split into pre-processing (performed
by the input filter), analysis, and post-processing (by the output filter).
3. A single analysis driver with environment variables: Function evaluation is contained within one analysis
driver, but it requires environment variables to be set before running.
4. Multiple analysis drivers: Drivers are run sequentially or concurrently (See the 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 DAKOTA PARAMETERS FILE and DAKOTA RESULTS FILE which can be used in the driver script.
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
Users Manual; for details on the filters and environment variables, see the subsection on Syntax for Filter and
Driver Strings.

Examples
Examples:
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

FAQ
Where will Dakota look for the analysis driver? 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).
Where should the driver be located? When the driver is a script it is most commonly placed in the same
directory as the Dakota input file. When using a 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.

6.5. INTERFACE

2121

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.
What if Dakota fails to run my analysis driver? 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.
analysis components
Keywords Area
interface
analysis drivers
analysis components
Provide additional identifiers to analysis drivers.

Specification
Alias: none
Argument(s): STRINGLIST
Default: no additional identifiers

Description
The optional analysis components specification allows the user to provide additional identifiers (e.g., mesh
file names) for use by the analysis drivers. This is particularly useful when the same analysis driver is to be
reused multiple times for slightly different analyses. The specific content within the strings is open-ended and
can involve whatever syntax is convenient for a particular analysis driver. The number of analysis components nc
should be an integer multiple of the number of drivers nd , and the first nc /nd component strings will be passed
to the first driver, etc.
input filter
Keywords Area
interface
analysis drivers
input filter
Run a pre-processing script before the analysis drivers

Specification
Alias: none
Argument(s): STRING
Default: no input filter

2122

CHAPTER 6. KEYWORDS AREA

Description
The optional input filter and output filter specifications provide the names of separate pre- and postprocessing programs or scripts which assist in mapping Dakota parameters files into analysis input files and
mapping analysis output files into Dakota results files, respectively.
If there is only a single analysis driver, then it is usually most convenient to combine pre- and post-processing
requirements into a single analysis driver script and omit the separate input and output filters. However, in the
case of multiple analysis drivers, the input and output filters provide a convenient location for non-repeated preand post-processing requirements. That is, input and output filters are only executed once per function evaluation, regardless of the number of analysis drivers, which makes them convenient locations for data processing
operations that are shared among the analysis drivers.
output filter
Keywords Area
interface
analysis drivers
output filter
Run a post-processing script after the analysis drivers

Specification
Alias: none
Argument(s): STRING
Default: no output filter

Description
The optional input filter and output filter specifications provide the names of separate pre- and postprocessing programs or scripts which assist in mapping Dakota parameters files into analysis input files and
mapping analysis output files into Dakota results files, respectively.
If there is only a single analysis driver, then it is usually most convenient to combine pre- and post-processing
requirements into a single analysis driver script and omit the separate input and output filters. However, in the
case of multiple analysis drivers, the input and output filters provide a convenient location for non-repeated preand post-processing requirements. That is, input and output filters are only executed once per function evaluation, regardless of the number of analysis drivers, which makes them convenient locations for data processing
operations that are shared among the analysis drivers.
system
Keywords Area
interface
analysis drivers
system
(Not recommended) Launch analysis drivers with a system call

6.5. INTERFACE

2123

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
parameters file

Optional

results file

Optional

allow existing results

Optional

verbatim

Optional

aprepro

Optional

labeled

Optional

file tag

Optional

file save

Optional

work directory

Dakota Keyword
Description
Specify the name
of the parameters
file
Specify the name
of the results file
Change how
Dakota deals with
existing results
files
Specify the
command Dakota
uses to launch
analysis driver(s)
and filters
Write parameters
files in APREPRO
syntax
Requires correct
function value
labels in results file
Tag each
parameters &
results file name
with the function
evaluation number
Keep the
parameters &
results files after
the analysis driver
completes
Perform each
function evaluation
in a separate
working directory

Description
The system call interface is included in Dakota for portability and backward compatibility. Users are strongly
encouraged to use the fork interface if possible, reverting to system only when necessary. To enable the system
call interface, replace the fork keyword with system. All other keywords have identical meanings to those for
the fork interface

2124

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
fork
parameters file
Keywords Area
interface
analysis drivers
system
parameters file
Specify the name of the parameters file

Specification
Alias: none
Argument(s): STRING
Default: Unix temp files

Description
The parameters file is used by Dakota to pass the parameter values to the analysis driver. The name of the file can
be optionally specified using the parameters file keyword.
If this is not specified, the default data transfer files are temporary files with system-generated names (e.g.,
/usr/tmp/aaaa08861).
results file
Keywords Area
interface
analysis drivers
system
results file
Specify the name of the results file

Specification
Alias: none
Argument(s): STRING
Default: Unix temp files

6.5. INTERFACE

2125

Description
The results file must be written by the analysis driver. It is read by Dakota to determine the response values for
each function evaluation.
The name of the file can be optionally specified using the results file keyword.
If this is not specified, the default data transfer files are temporary files with system-generated names (e.g.,
/usr/tmp/aaaa08861).
allow existing results
Keywords Area
interface
analysis drivers
system
allow existing results
Change how Dakota deals with existing results files

Specification
Alias: none
Argument(s): none
Default: results files removed before each evaluation

Description
By default Dakota will remove existing results files before invoking the analysis driver to avoid problems
created by stale files in the current directory. To override this behavior and not delete existing files, specify
allow existing results.
verbatim
Keywords Area
interface
analysis drivers
system
verbatim
Specify the command Dakota uses to launch analysis driver(s) and filters

Specification
Alias: none
Argument(s): none
Default: driver/filter invocation syntax augmented with file names

2126

CHAPTER 6. KEYWORDS AREA

Description
The typical commands that Dakota uses to launch analysis drivers are:
> analysis_driver parameters_file_name results_file_name

Dakota will automatically arrange the executables and file names.

If the analysis driver requires a different syntax, the entire command can be specified as the analysis driver
and the verbatim keyword will tell Dakota to use this as the command.
Note, this will not allow the use of file tag, because the exact command must be specified.
For additional information on invocation syntax, see the Interfaces chapter of the Users Manual[4].

Examples
In the following example, the analysis driver command is run without any edits from Dakota.
interface
analysis_driver = "matlab -nodesktop -nojvm -r MatlabDriver_hardcoded_filenames; exit "
fork
parameters_file params.in
results_file results.out
verbatim # this tells Dakota to fork the command exactly as written, instead of appending I/O filenames

The -r flag identifies the commands that will be run by matlab. The Matlab script has the parameters file and
results file names hardcoded, so no additional arguments are required.
aprepro
Keywords Area
interface
analysis drivers
system
aprepro
Write parameters files in APREPRO syntax

Topics
This keyword is related to the topics:
file formats

Specification
Alias: dprepro
Argument(s): none
Default: standard parameters file format

6.5. INTERFACE

2127

Description
The format of data in the parameters files can be modified for direct usage with the APREPRO pre-processing
tool [75] using the aprepro specification
Without this keyword, the parameters file are written in DPrePro format. DPrePro is a utility included with
Dakota, described in the Users Manual[4].
labeled
Keywords Area
interface
analysis drivers
system
labeled
Requires correct function value labels in results file

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: Function value labels optional

Description
The labeled keyword directs Dakota to enforce a stricter results file format and enables more detailed error
reporting.
When the labeled keyword is used, function values in results files must be accompanied by their corresponding descriptors. If the user did not supply response descriptors in her Dakota input file, then Dakota
auto-generated descriptors are expected.
Distinct error messages are emitted for function values that are out-of-order, repeated, or missing. Labels that
appear without a function value and unexpected data are also reported as errors. Dakota attempts to report all
errors in a results file, not just the first it encounters. After reporting results file errors, Dakota aborts.
Labels for analytic gradients and Hessians currently are not supported.
Although the labeled keyword is optional, its use is recommended to help catch and identify problems with
results files. The Users Manual contains further information about the results file format.
Default Behavior
By default, Dakota does not require labels for function values, and ignores them if they are present.

2128

CHAPTER 6. KEYWORDS AREA

file tag
Keywords Area
interface
analysis drivers
system
file tag
Tag each parameters & results file name with the function evaluation number

Specification
Alias: none
Argument(s): none
Default: no tagging

Description
If this keyword is used, Dakota will append a period and the function evaluation number to the names of the
parameter and results files.
For example, if the following is included in the interface section of the Dakota input:
parameters_file = params.in
results_file = results.out
file_tag

Then for the 3rd evaluation, Dakota will write params.in.3, and will expect results.out.3 to be written
by the analysis driver.
If this keyword is omitted, the default is no file tagging.
File tagging is most useful when multiple function evaluations are running simultaneously using files in a
shared disk space. The analysis driver will be able to infer the function evaluation number from the file names.
Note that when the file save keyword is used, Dakota renames parameters and results files, giving them tags,
after execution of the analysis driver if they otherwise would be overwritten by the next evaluation.
file save
Keywords Area
interface
analysis drivers
system
file save
Keep the parameters & results files after the analysis driver completes

Specification
Alias: none
Argument(s): none
Default: file cleanup

6.5. INTERFACE

2129

Description
If file save is used, Dakota will not delete the parameters and results files after the function evaluation is
completed.
The default behavior is NOT to save these files.
If file tag is not specified and the saved files would be overwritten by a future evaluation, Dakota renames
them after the analysis driver has run by tagging them with the evaluation number.
File saving is most useful when debugging the data communication between Dakota and the simulation.
work directory
Keywords Area
interface
analysis drivers
system
work directory
Perform each function evaluation in a separate working directory

Specification
Alias: none
Argument(s): none
Default: no work directory
Required/Optional
Optional

Description of
Group

Dakota Keyword
named

Optional

directory tag

Optional

directory save

Dakota Keyword
Description
The base name of
the work directory
created by Dakota
Tag each work
directory with the
function evaluation
number
Preserve the work
directory after
function evaluation
completion

2130

CHAPTER 6. KEYWORDS AREA

Optional

link files

Paths to be linked
into each working
directory

Optional

copy files

Files and
directories to be
copied into each
working directory

Optional

replace

Overwrite existing
files within a work
directory

Description
When performing concurrent evaluations, it is typically necessary to cloister simulation input and output files in
separate directories to avoid conflicts. When the work directory feature is enabled, Dakota will create a
directory for each evaluation, with optional tagging (directory tag) and saving (directory save ), as
with files, and execute the analysis driver from that working directory.
The directory may be named with a string, or left anonymous to use an automatically-generated directory in
the systems temporary file space, e.g., /tmp/dakota work c93vb71z/. The optional link files and copy files keywords specify files or directories which should appear in each working directory.
When using work directory, the analysis drivers may be given by an absolute path, located in (or relative to)
the startup directory alongside the Dakota input file, in the list of template files linked or copied, or on the $PATH
(Path% on Windows).
named
Keywords Area
interface
analysis drivers
system
work directory
named
The base name of the work directory created by Dakota

Specification
Alias: none
Argument(s): STRING
Default: workdir

6.5. INTERFACE

2131

Description
The named keyword is followed by a string, indicating the name of the work directory created by Dakota. If
relative, the work directory will be created relative to the directory from which Dakota is invoked.
If named is not used, the default work directory is a temporary directory with a system-generated name (e.g.,
/tmp/dakota work c93vb71z/).

See Also
These keywords may also be of interest:
directory tag
directory save
directory tag
Keywords Area
interface
analysis drivers
system
work directory
directory tag
Tag each work directory with the function evaluation number

Specification
Alias: dir tag
Argument(s): none
Default: no work directory tagging

Description
If this keyword is used, Dakota will append a period and the function evaluation number to the work directory
names.
If this keyword is omitted, the default is no tagging, and the same work directory will be used for ALL function
evaluations. Tagging is most useful when multiple function evaluations are running simultaneously.
directory save
Keywords Area
interface
analysis drivers
system
work directory
directory save
Preserve the work directory after function evaluation completion

2132

CHAPTER 6. KEYWORDS AREA

Specification
Alias: dir save
Argument(s): none
Default: remove work directory

Description
By default, when a working directory is created by Dakota using the work directory keyword, it is deleted
after the evaluation is completed. The directory save keyword will cause Dakota to leave (not delete) the
directory.
link files
Keywords Area
interface
analysis drivers
system
work directory
link files
Paths to be linked into each working directory

Specification
Alias: none
Argument(s): STRINGLIST
Default: no linked files

Description
Specifies the paths (files or directories) that will be symbolically linked from each working directory. Wildcards
using and ? are permitted. Linking is space-saving and useful for files not modified during the function evaluation. However, not all filesystems support linking, for example, support on Windows varies.

Examples
Specifying
link_files = siminput*.in /path/to/simdir1 simdir2/*

will create copies

workdir/siminput*.in
workdir/simdir1/
workdir/*

# links to each of rundir / siminput*.in

# whole directory simdir1 linked
# each entry in directory simdir2 linked

6.5. INTERFACE

2133

copy files
Keywords Area
interface
analysis drivers
system
work directory
copy files
Files and directories to be copied into each working directory

Specification
Alias: none
Argument(s): STRINGLIST
Default: no copied files

Description
Specifies the files or directories that will be recursively copied into each working directory. Wildcards using and
? are permitted.

Examples
Specifying
copy_files = siminput*.in /path/to/simdir1 simdir2/*

will create copies

workdir/siminput*.in # files rundir/siminput*.in copied
workdir/simdir1/
# whole directory simdir1 recursively copied
workdir/*
# contents of directory simdir2 recursively copied

where rundir is the directory in which Dakota was started.

replace
Keywords Area
interface
analysis drivers
system
work directory
replace
Overwrite existing files within a work directory

2134

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: do not overwrite files

Description
By default, Dakota will not overwrite any existing files in a work directory. The replace keyword changes this
behavior to force overwriting.
fork
Keywords Area
interface
analysis drivers
fork
Launch analysis drivers using fork command

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
parameters file

Optional

results file

Optional

allow existing results

Optional

verbatim

Dakota Keyword
Description
Specify the name
of the parameters
file
Specify the name
of the results file
Change how
Dakota deals with
existing results
files
Specify the
command Dakota
uses to launch
analysis driver(s)
and filters

6.5. INTERFACE

2135
Optional

aprepro

Optional

labeled

Optional

file tag

Optional

file save

Optional

work directory

Write parameters
files in APREPRO
syntax
Requires correct
function value
labels in results file
Tag each
parameters &
results file name
with the function
evaluation number
Keep the
parameters &
results files after
the analysis driver
completes
Perform each
function evaluation
in a separate
working directory

Description
The fork interface is the most common means by which Dakota launches a separate application analysis process.
The fork interface is recommended over system for most analysis drivers that are external to Dakota (i.e.
not using the direct interface).
As explained in the Users Manual, the parameters and results file names are passed on the command line to
the analysis driver(s). If input/output filters are specified, they will be run before/after the analysis drivers. The
verbatim keyword is used to modify the default driver/filter commands.
For additional information on invocation syntax, see the Interfaces chapter of the Users Manual[4].

Examples
interface
analysis_drivers = rosenbrock
fork
parameters_file = params.in
results_file
= results.out
file_tag
file_save

parameters file
Keywords Area
interface
analysis drivers
fork
parameters file

2136

CHAPTER 6. KEYWORDS AREA

Specify the name of the parameters file

Specification
Alias: none
Argument(s): STRING
Default: Unix temp files

Description
The parameters file is used by Dakota to pass the parameter values to the analysis driver. The name of the file can
be optionally specified using the parameters file keyword.
If this is not specified, the default data transfer files are temporary files with system-generated names (e.g.,
/usr/tmp/aaaa08861).
results file
Keywords Area
interface
analysis drivers
fork
results file
Specify the name of the results file

Specification
Alias: none
Argument(s): STRING
Default: Unix temp files

Description
The results file must be written by the analysis driver. It is read by Dakota to determine the response values for
each function evaluation.
The name of the file can be optionally specified using the results file keyword.
If this is not specified, the default data transfer files are temporary files with system-generated names (e.g.,
/usr/tmp/aaaa08861).
allow existing results
Keywords Area
interface
analysis drivers
fork
allow existing results
Change how Dakota deals with existing results files

6.5. INTERFACE

2137

Specification
Alias: none
Argument(s): none
Default: results files removed before each evaluation

Description
By default Dakota will remove existing results files before invoking the analysis driver to avoid problems
created by stale files in the current directory. To override this behavior and not delete existing files, specify
allow existing results.
verbatim
Keywords Area
interface
analysis drivers
fork
verbatim
Specify the command Dakota uses to launch analysis driver(s) and filters

Specification
Alias: none
Argument(s): none
Default: driver/filter invocation syntax augmented with file names

Description
The typical commands that Dakota uses to launch analysis drivers are:
> analysis_driver parameters_file_name results_file_name

Dakota will automatically arrange the executables and file names.

If the analysis driver requires a different syntax, the entire command can be specified as the analysis driver
and the verbatim keyword will tell Dakota to use this as the command.
Note, this will not allow the use of file tag, because the exact command must be specified.
For additional information on invocation syntax, see the Interfaces chapter of the Users Manual[4].

Examples
In the following example, the analysis driver command is run without any edits from Dakota.
interface
analysis_driver = "matlab -nodesktop -nojvm -r MatlabDriver_hardcoded_filenames; exit "
fork
parameters_file params.in
results_file results.out
verbatim # this tells Dakota to fork the command exactly as written, instead of appending I/O filenames

The -r flag identifies the commands that will be run by matlab. The Matlab script has the parameters file and
results file names hardcoded, so no additional arguments are required.

2138

CHAPTER 6. KEYWORDS AREA

aprepro
Keywords Area
interface
analysis drivers
fork
aprepro
Write parameters files in APREPRO syntax

Topics
This keyword is related to the topics:
file formats

Specification
Alias: dprepro
Argument(s): none
Default: standard parameters file format

Description
The format of data in the parameters files can be modified for direct usage with the APREPRO pre-processing
tool [75] using the aprepro specification
Without this keyword, the parameters file are written in DPrePro format. DPrePro is a utility included with
Dakota, described in the Users Manual[4].
labeled
Keywords Area
interface
analysis drivers
fork
labeled
Requires correct function value labels in results file

Topics
This keyword is related to the topics:
file formats

6.5. INTERFACE

2139

Specification
Alias: none
Argument(s): none
Default: Function value labels optional

Description
The labeled keyword directs Dakota to enforce a stricter results file format and enables more detailed error
reporting.
When the labeled keyword is used, function values in results files must be accompanied by their corresponding descriptors. If the user did not supply response descriptors in her Dakota input file, then Dakota
auto-generated descriptors are expected.
Distinct error messages are emitted for function values that are out-of-order, repeated, or missing. Labels that
appear without a function value and unexpected data are also reported as errors. Dakota attempts to report all
errors in a results file, not just the first it encounters. After reporting results file errors, Dakota aborts.
Labels for analytic gradients and Hessians currently are not supported.
Although the labeled keyword is optional, its use is recommended to help catch and identify problems with
results files. The Users Manual contains further information about the results file format.
Default Behavior
By default, Dakota does not require labels for function values, and ignores them if they are present.
file tag
Keywords Area
interface
analysis drivers
fork
file tag
Tag each parameters & results file name with the function evaluation number

Specification
Alias: none
Argument(s): none
Default: no tagging

Description
If this keyword is used, Dakota will append a period and the function evaluation number to the names of the
parameter and results files.
For example, if the following is included in the interface section of the Dakota input:
parameters_file = params.in
results_file = results.out
file_tag

2140

CHAPTER 6. KEYWORDS AREA

Then for the 3rd evaluation, Dakota will write params.in.3, and will expect results.out.3 to be written
by the analysis driver.
If this keyword is omitted, the default is no file tagging.
File tagging is most useful when multiple function evaluations are running simultaneously using files in a
shared disk space. The analysis driver will be able to infer the function evaluation number from the file names.
Note that when the file save keyword is used, Dakota renames parameters and results files, giving them tags,
after execution of the analysis driver if they otherwise would be overwritten by the next evaluation.
file save
Keywords Area
interface
analysis drivers
fork
file save
Keep the parameters & results files after the analysis driver completes

Specification
Alias: none
Argument(s): none
Default: file cleanup

Description
If file save is used, Dakota will not delete the parameters and results files after the function evaluation is
completed.
The default behavior is NOT to save these files.
If file tag is not specified and the saved files would be overwritten by a future evaluation, Dakota renames
them after the analysis driver has run by tagging them with the evaluation number.
File saving is most useful when debugging the data communication between Dakota and the simulation.
work directory
Keywords Area
interface
analysis drivers
fork
work directory
Perform each function evaluation in a separate working directory

Specification
Alias: none
Argument(s): none
Default: no work directory

6.5. INTERFACE

2141
Required/Optional
Optional

Description of
Group

Dakota Keyword
named

Dakota Keyword
Description
The base name of
the work directory
created by Dakota

Optional

directory tag

Optional

directory save

Optional

link files

Paths to be linked
into each working
directory

Optional

copy files

Files and
directories to be
copied into each
working directory

Optional

replace

Overwrite existing
files within a work
directory

Tag each work

directory with the
function evaluation
number
Preserve the work
directory after
function evaluation
completion

Description
When performing concurrent evaluations, it is typically necessary to cloister simulation input and output files in
separate directories to avoid conflicts. When the work directory feature is enabled, Dakota will create a
directory for each evaluation, with optional tagging (directory tag) and saving (directory save ), as
with files, and execute the analysis driver from that working directory.
The directory may be named with a string, or left anonymous to use an automatically-generated directory in
the systems temporary file space, e.g., /tmp/dakota work c93vb71z/. The optional link files and copy files keywords specify files or directories which should appear in each working directory.
When using work directory, the analysis drivers may be given by an absolute path, located in (or relative to)
the startup directory alongside the Dakota input file, in the list of template files linked or copied, or on the $PATH
(Path% on Windows).
named
Keywords Area
interface
analysis drivers
fork

2142

CHAPTER 6. KEYWORDS AREA

work directory
named
The base name of the work directory created by Dakota

Specification
Alias: none
Argument(s): STRING
Default: workdir

Description
The named keyword is followed by a string, indicating the name of the work directory created by Dakota. If
relative, the work directory will be created relative to the directory from which Dakota is invoked.
If named is not used, the default work directory is a temporary directory with a system-generated name (e.g.,
/tmp/dakota work c93vb71z/).

See Also
These keywords may also be of interest:
directory tag
directory save
directory tag
Keywords Area
interface
analysis drivers
fork
work directory
directory tag
Tag each work directory with the function evaluation number

Specification
Alias: dir tag
Argument(s): none
Default: no work directory tagging

Description
If this keyword is used, Dakota will append a period and the function evaluation number to the work directory
names.
If this keyword is omitted, the default is no tagging, and the same work directory will be used for ALL function
evaluations. Tagging is most useful when multiple function evaluations are running simultaneously.

6.5. INTERFACE

2143

directory save
Keywords Area
interface
analysis drivers
fork
work directory
directory save
Preserve the work directory after function evaluation completion

Specification
Alias: dir save
Argument(s): none
Default: remove work directory

Description
By default, when a working directory is created by Dakota using the work directory keyword, it is deleted
after the evaluation is completed. The directory save keyword will cause Dakota to leave (not delete) the
directory.
link files
Keywords Area
interface
analysis drivers
fork
work directory
link files
Paths to be linked into each working directory

Specification
Alias: none
Argument(s): STRINGLIST
Default: no linked files

Description
Specifies the paths (files or directories) that will be symbolically linked from each working directory. Wildcards
using and ? are permitted. Linking is space-saving and useful for files not modified during the function evaluation. However, not all filesystems support linking, for example, support on Windows varies.

2144

CHAPTER 6. KEYWORDS AREA

Examples
Specifying
link_files = siminput*.in /path/to/simdir1 simdir2/*

will create copies

workdir/siminput*.in
workdir/simdir1/
workdir/*

# links to each of rundir / siminput*.in

# whole directory simdir1 linked
# each entry in directory simdir2 linked

copy files
Keywords Area
interface
analysis drivers
fork
work directory
copy files
Files and directories to be copied into each working directory

Specification
Alias: none
Argument(s): STRINGLIST
Default: no copied files

Description
Specifies the files or directories that will be recursively copied into each working directory. Wildcards using and
? are permitted.

Examples
Specifying
copy_files = siminput*.in /path/to/simdir1 simdir2/*

will create copies

workdir/siminput*.in # files rundir/siminput*.in copied
workdir/simdir1/
# whole directory simdir1 recursively copied
workdir/*
# contents of directory simdir2 recursively copied

where rundir is the directory in which Dakota was started.

6.5. INTERFACE

2145

replace
Keywords Area
interface
analysis drivers
fork
work directory
replace
Overwrite existing files within a work directory

Specification
Alias: none
Argument(s): none
Default: do not overwrite files

Description
By default, Dakota will not overwrite any existing files in a work directory. The replace keyword changes this
behavior to force overwriting.
direct
Keywords Area
interface
analysis drivers
direct
Run analysis drivers that are linked-to or compiled-with Dakota

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
processors per analysis

Dakota Keyword
Description
Specify the
number of
processors per
analysis when
Dakota is run in
parallel

2146

CHAPTER 6. KEYWORDS AREA

Description
The primary use of the direct interface is to invoke internal test functions that perform parameter to response
mappings for simple functions as inexpensively as possible. These problems are compiled directly into the Dakota
executable as part of the direct function interface class and are used for algorithm testing.
Dakota also supports direct interfaces to a few select simulation codes. One example is ModelCenter, a
commercial simulation management framework from Phoenix Integration. To utilize this interface, a user must
first define the simulation specifics within a ModelCenter session and then save these definitions to a ModelCenter configuration file. The analysis components specification provides the means to communicate this
configuration file to Dakotas ModelCenter interface.

Examples
The rosenbrock function is available as an executable, which can be launched with fork, and is also compiled with
Dakota. The internal version can be launched with:
interface
analysis_drivers = rosenbrock
direct

processors per analysis

Keywords Area
interface
analysis drivers
direct
processors per analysis
Specify the number of processors per analysis when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER
Default: no override of auto configure

Description
For direct function interfaces, processors per analysis is an additional optional setting within the required group which can be used to specify multiprocessor analysis partitions. As with the evaluation servers, analysis servers, evaluation self scheduling, evaluation static scheduling,
analysis self scheduling, and analysis static scheduling specifications, processors per analysis provides a means for the user to override the automatic parallel configuration (refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4]) for the number of processors used for each
analysis partition. Note that if both analysis servers and processors per analysis are specified
and they are not in agreement, then analysis servers takes precedence.

6.5. INTERFACE

2147

matlab
Keywords Area
interface
analysis drivers
matlab
Run Matlab with a direct interface - requires special Dakota build

Specification
Alias: none
Argument(s): none

Description
Dakota supports library-linked interfaces to Matlab, Scilab, and Python scientific computation software, but they
must be explicitly enabled when compiling Dakota from source. First consult the Users Manual[4] for discussion
and examples.
Contact the Dakota users mailing list for assistance building and using Dakota with these interfaces.
In all these interfaces, the analysis driver is used to specify a Matlab, Scilab, or Python file which
implements the parameter to response mapping.
python
Keywords Area
interface
analysis drivers
python
Run Python with a direct interface - requires special Dakota build

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
numpy

Dakota Keyword
Description
Enable the use of
numpy in Dakotas
Python interface

2148

CHAPTER 6. KEYWORDS AREA

Description
Dakota supports library-linked interfaces to Matlab, Scilab, and Python scientific computation software, but they
must be explicitly enabled when compiling Dakota from source. First consult the Users Manual[4] for discussion
and examples.
Contact the Dakota users mailing list for assistance building and using Dakota with these interfaces.
In all these interfaces, the analysis driver is used to specify a Matlab, Scilab, or Python file which
implements the parameter to response mapping.
numpy
Keywords Area
interface
analysis drivers
python
numpy
Enable the use of numpy in Dakotas Python interface

Specification
Alias: none
Argument(s): none
Default: Python list dataflow

Description
When the numpy keyword is used, Dakota expects responses in the form of a Python dictionary of numpy arrays.
See the example in examples/linked interfaces/Python.
scilab
Keywords Area
interface
analysis drivers
scilab
Run Scilab with a direct interface - requires special Dakota build

Specification
Alias: none
Argument(s): none

6.5. INTERFACE

2149

Description
Dakota supports library-linked interfaces to Matlab, Scilab, and Python scientific computation software, but they
must be explicitly enabled when compiling Dakota from source. First consult the Users Manual[4] for discussion
and examples.
Contact the Dakota users mailing list for assistance building and using Dakota with these interfaces.
In all these interfaces, the analysis driver is used to specify a Matlab, Scilab, or Python file which
implements the parameter to response mapping.
grid
Keywords Area
interface
analysis drivers
grid
Experimental capability

Specification
Alias: none
Argument(s): none

Description
For grid interfaces, no additional specifications are used at this time.
This capability has been used for interfaces with IDEA and JAVASpaces in the past and is currently a placeholder for future work with Condor and/or Globus services. It is not currently operational.
failure capture
Keywords Area
interface
analysis drivers
failure capture
Determine how Dakota responds to analysis driver failure

Specification
Alias: none
Argument(s): none
Default: abort

2150

CHAPTER 6. KEYWORDS AREA

Required/Optional

Description of
Group

Required(Choose
One)

failure mitigation
(Group 1)

Dakota Keyword
abort
retry
recover

continuation

Dakota Keyword
Description
(Default) Abort the
Dakota job
Rerun failed
analyses
Substitute dummy
values for the
responses
Cause Dakota to
step toward the
failed target
simulation from a
nearby successful
source

Description
Dakota can deal with analysis failure in a few ways.
The first step is that Dakota must detect analysis failure. Importantly, Dakota always expects a results file to be
written by the analysis driver, even when a failure has occurred. If the file does not exist when the analysis driver
exits, a Dakota error results, causing Dakota itself to terminate. The analysis driver communicates an analysis
failure to Dakota by writing a results file beginning with the word fail, which is not case sensitive. Everything
after fail is ignored.
Once Dakota detects analysis failure, the failure can be mitigated in four ways:
abort (the default)
retry
recover
continuation
Refer to the Simulation Code Failure Capturing chapter of the Users Manual[4] for additional information.
abort
Keywords Area
interface
analysis drivers
failure capture
abort
(Default) Abort the Dakota job

Specification
Alias: none
Argument(s): none

6.5. INTERFACE

2151

Description
abort will stop the Dakota job, as well as any other running analysis drivers.
retry
Keywords Area
interface
analysis drivers
failure capture
retry
Rerun failed analyses

Specification
Alias: none
Argument(s): INTEGER

Description
The retry selection supports an integer input for specifying a limit on retries
recover
Keywords Area
interface
analysis drivers
failure capture
recover
Substitute dummy values for the responses

Specification
Alias: none
Argument(s): REALLIST

Description
The recover selection supports a list of reals for specifying the dummy function values (only zeroth order
information is supported) to use for the failed function evaluation.

2152

CHAPTER 6. KEYWORDS AREA

continuation
Keywords Area
interface
analysis drivers
failure capture
continuation
Cause Dakota to step toward the failed target simulation from a nearby successful source

Specification
Alias: none
Argument(s): none

Description
When failure capture continuation is enabled and an evaluation fails, then Dakota will attempt to
march incrementally from a previous good evaluation (the source) toward the failing one (the target). Further
details about the algorithm employed by Dakota are supplied in the Users Manual [4].
deactivate
Keywords Area
interface
analysis drivers
deactivate
Deactivate Dakota features to simplify interface development, increase execution speed, or reduce memory
and disk requirements

Specification
Alias: none
Argument(s): none
Default: Active set vector control, function evaluation cache, and restart file features are active
Required/Description of
Dakota Keyword
Dakota Keyword
Optional
Group
Description
Optional
active set vector
Deactivate the
Active Set Vector
Optional
evaluation cache
Do not retain
function evaluation
history in memory

6.5. INTERFACE

2153
Optional

strict cache equality

Optional

restart file

Do not require
strict cache
equality when
finding duplicates
Deactivate writing
to the restart file

Description
The optional deactivate specification block includes three features which a user may deactivate in order to
simplify interface development, increase execution speed, and/or reduce memory and disk requirements:
Active set vector (ASV) control: deactivation of this feature using a deactivate active set vector
specification allows the user to turn off any variability in ASV values so that active set logic can be omitted
in the users simulation interface. This option trades some efficiency for simplicity in interface development.
The default behavior is to request the minimum amount of data required by an algorithm at any given time,
which implies that the ASV values may vary from one function evaluation to the next. Since the users
interface must return the data set requested by the ASV values, this interface must contain additional logic
to account for any variations in ASV content. Deactivating this ASV control causes Dakota to always
request a full data set (the full function, gradient, and Hessian data that is available from the interface
as specified in the responses specification) on each function evaluation. For example, if ASV control has
been deactivated and the responses section specifies four response functions, analytic gradients, and no
Hessians, then the ASV on every function evaluation will be { 3 3 3 3 }, regardless of what subset of this
data is currently needed. While wasteful of computations in many instances, this simplifies the interface
and allows the user to return the same data set on every evaluation. Conversely, if ASV control is active
(the default behavior), then the ASV requests in this example might vary from { 1 1 1 1 } to { 2 0 0 2 },
etc., according to the specific data needed on a particular function evaluation. This will require the users
interface to read the ASV requests and perform the appropriate logic in conditionally returning only the data
requested. In general, the default ASV behavior is recommended for the sake of computational efficiency,
unless interface development time is a critical concern. Note that in both cases, the data returned to Dakota
from the users interface must match the ASV passed in, or else a response recovery error will result.
However, when the ASV control is deactivated, the ASV values are invariant and need not be checked on
every evaluation. Note: Deactivating the ASV control can have a positive effect on load balancing for
parallel Dakota executions. Thus, there is significant overlap in this ASV control option with speculative
gradients. There is also overlap with the mode override approach used with certain optimizers to combine
individual value, gradient, and Hessian requests.
Function evaluation cache: deactivation of this feature using a deactivate evaluation cache specification allows the user to avoid retention of the complete function evaluation history in memory. This can
be important for reducing memory requirements in large-scale applications (i.e., applications with a large
number of variables or response functions) and for eliminating the overhead of searching for duplicates
within the function evaluation cache prior to each new function evaluation (e.g., for improving speed in
problems with 1000s of inexpensive function evaluations or for eliminating overhead when performing
timing studies). However, the downside is that unnecessary computations may be performed since duplication in function evaluation requests may not be detected. For this reason, this option is not recommended
when function evaluations are costly. Note: duplication detection within Dakota can be deactivated, but
duplication detection features within specific optimizers may still be active.
Strict Cache Equality: By default, Dakotas evaluation cache and restart capabilities are based on strict
binary equality. This provides a performance advantage, as it permits a hash-based data structure to be used

2154

CHAPTER 6. KEYWORDS AREA

to search the evaluation cache. However, deactiving strict equality may prevent cache misses, which can
occur when attempting to use a restart file on a machine different from the one on which it was generated.

Restart file: deactivation of this feature using a deactivate restart file specification allows the
user to eliminate the output of each new function evaluation to the binary restart file. This can increase speed
and reduce disk storage requirements, but at the expense of a loss in the ability to recover and continue a
run that terminates prematurely (e.g., due to a system crash or network problem). This option is not recommended when function evaluations are costly or prone to failure. Please note that using the deactivate
restart file specification will result in a zero length restart file with the default name dakota.rst.
These three features may be deactivated independently and concurrently.
active set vector
Keywords Area
interface
analysis drivers
deactivate
active set vector
Deactivate the Active Set Vector

Specification
Alias: none
Argument(s): none

Description
Described on parent page
evaluation cache
Keywords Area
interface
analysis drivers
deactivate
evaluation cache
Do not retain function evaluation history in memory

Specification
Alias: none
Argument(s): none

6.5. INTERFACE

2155

Description
Described on parent page
strict cache equality
Keywords Area
interface
analysis drivers
deactivate
strict cache equality
Do not require strict cache equality when finding duplicates

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
cache tolerance

Description
Described on parent page
cache tolerance
Keywords Area
interface
analysis drivers
deactivate
strict cache equality
cache tolerance
Specify tolerance when identifying duplicate function evaluations

Specification
Alias: none
Argument(s): REAL

Dakota Keyword
Description
Specify tolerance
when identifying
duplicate function
evaluations

2156

CHAPTER 6. KEYWORDS AREA

Description
Described on parent page
restart file
Keywords Area
interface
analysis drivers
deactivate
restart file
Deactivate writing to the restart file

Specification
Alias: none
Argument(s): none

Description
Described on parent page

6.5.4

asynchronous

Keywords Area
interface
asynchronous
Specify analysis driver concurrency, when Dakota is run in serial

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none
Default: synchronous interface usage
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

6.5. INTERFACE

2157
Optional

evaluation concurrency

Optional

local evaluation scheduling

Optional

analysis concurrency

Determine how
many concurrent
evaluations Dakota
will schedule
Control how local
asynchronous jobs
are scheduled
Limit the number
of analysis drivers
within an
evaluation that
Dakota will
schedule

Description
The optional asynchronous keyword specifies use of asynchronous protocols (i.e., background system calls,
nonblocking forks, POSIX threads) when evaluations or analyses are invoked. The evaluation concurrency
and analysis concurrency specifications serve a dual purpose:
when running Dakota on a single processor in asynchronous mode, the default concurrency of evaluations and analyses is all concurrency that is available. The evaluation concurrency and analysisconcurrency specifications can be used to limit this concurrency in order to avoid machine overload or
usage policy violation.
when running Dakota on multiple processors in message passing mode, the default concurrency of evaluations and analyses on each of the servers is one (i.e., the parallelism is exclusively that of the message
passing). With the evaluation concurrency and analysis concurrency specifications, a hybrid parallelism can be selected through combination of message passing parallelism with asynchronous
parallelism on each server.
evaluation concurrency
Keywords Area
interface
asynchronous
evaluation concurrency
Determine how many concurrent evaluations Dakota will schedule

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER
Default: local: unlimited concurrency, hybrid: no concurrency

2158

CHAPTER 6. KEYWORDS AREA

Description
When asynchronous execution is enabled, the default behavior is to launch all available evaluations simultaneously. The evaluation concurrency keywrod can be used to limit the number of concurrent evaluations.

local evaluation scheduling

Keywords Area
interface
asynchronous
local evaluation scheduling
Control how local asynchronous jobs are scheduled

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none
Default: dynamic
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
dynamic

static

Dakota Keyword
Description
Dynamic local
scheduling
(sequential)
Static local
scheduling (tiled)

Description
When performing asynchronous local evaluations, the local evaluation scheduling keyword controls how new
evaluation jobs are dispatched when one completes.
The two options are:
dynamic
static
If the local evaluation scheduling is specified as dynamic (the default), each completed evaluation will be replaced
by the next in the local evaluation queue.
If local evaluation scheduling is specified as static, each completed evaluation will be replaced by an evaluation number that is congruent modulo the evaluation concurrency. This is helpful for relative node scheduling
as described in Dakota/examples/parallelism. For example, assuming only asynchronous local concurrency (no
MPI), if the local concurrency is 6 and job 2 completes, it will be replaced with job 8.

6.5. INTERFACE

2159

For the case of hybrid parallelism, static local scheduling results in evaluation replacements that are modulo
the total capacity, defined as the product of the evaluation concurrency and the number of evaluation servers.
Both of these cases can result in idle processors if runtimes are non-uniform, so the default dynamic scheduling
is preferred when relative node scheduling is not required.
dynamic
Keywords Area
interface
asynchronous
local evaluation scheduling
dynamic
Dynamic local scheduling (sequential)

Specification
Alias: none
Argument(s): none

Description
If the local evaluation scheduling is specified as dynamic (the default), each completed evaluation will be replaced
by the next in the local evaluation queue.
static
Keywords Area
interface
asynchronous
local evaluation scheduling
static
Static local scheduling (tiled)

Specification
Alias: none
Argument(s): none

2160

CHAPTER 6. KEYWORDS AREA

Description
If local evaluation scheduling is specified as static, each completed evaluation will be replaced by an evaluation
number that is congruent modulo the evaluation concurrency. This is helpful for relative node scheduling as
described in Dakota/examples/parallelism. For example, assuming only asynchronous local concurrency (no MPI), if the local concurrency is 6 and job 2 completes, it will be replaced with job 8.
For the case of hybrid parallelism, static local scheduling results in evaluation replacements that are modulo
the total capacity, defined as the product of the evaluation concurrency and the number of evaluation servers.
Both of these cases can result in idle processors if runtimes are non-uniform, so the default dynamic scheduling
is preferred when relative node scheduling is not required.
analysis concurrency
Keywords Area
interface
asynchronous
analysis concurrency
Limit the number of analysis drivers within an evaluation that Dakota will schedule

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER
Default: local: unlimited concurrency, hybrid: no concurrency

Description
When asynchronous execution is enabled and each evaluation involves multiple analysis drivers, then the
default behavior is to launch all drivers simultaneously. The analysis concurrency keyword can be used
to limit the number of concurrently run drivers.

6.5.5

evaluation servers

Keywords Area
interface
evaluation servers
Specify the number of evaluation servers when Dakota is run in parallel

6.5. INTERFACE

2161

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER
Default: no override of auto configure

Description
The optional evaluation servers specification supports user override of the automatic parallel configuration for the number of evaluation servers. That is, if the automatic configuration is undesirable for some reason,
the user can enforce a desired number of partitions at the evaluation parallelism level. Refer to ParallelLibrary
and the Parallel Computing chapter of the Users Manual [4] for additional information.

6.5.6

evaluation scheduling

Keywords Area
interface
evaluation scheduling
Specify the scheduling of concurrent evaluations when Dakota is run in parallel

Specification
Alias: none
Argument(s): none
Default: automatic (see discussion)
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
master

peer

Dakota Keyword
Description
Specify a
dedicated master
partition for
parallel evaluation
scheduling
Specify a peer
partition for
parallel evaluation
scheduling

Description
When Dakota is run in parallel, the partition type and scheduling for the evaluation servers are determined automatically. If these settings are undesirable, they may be overridden by the user using the evaluation scheduling keyword.
The partition type and scheduling are

2162

CHAPTER 6. KEYWORDS AREA

master
Keywords Area
interface
evaluation scheduling
master
Specify a dedicated master partition for parallel evaluation scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a dedicated master partition. In a dedicated master partition, one processor (the master) dynamically schedules work on the evaluation
servers. This reduces the number of processors available to create servers by 1.
peer
Keywords Area
interface
evaluation scheduling
peer
Specify a peer partition for parallel evaluation scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

6.5. INTERFACE

2163
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
dynamic

static

Dakota Keyword
Description
Specify dynamic
scheduling in a
peer partition when
Dakota is run in
parallel.
Specify static
scheduling in a
peer partition when
Dakota is run in
parallel.

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a peer partition. In a peer
partition, all processors are available to be assigned to evaluation servers. The scheduling,static or dynamic,
must also be specified.
dynamic
Keywords Area
interface
evaluation scheduling
peer
dynamic
Specify dynamic scheduling in a peer partition when Dakota is run in parallel.

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none
Default: dynamic (see discussion)

Description
In dynamic scheduling, evaluations are assigned to servers as earlier evaluations complete. Dynamic scheduling
is advantageous when evaluations are of uneven duration.

2164

CHAPTER 6. KEYWORDS AREA

static
Keywords Area
interface
evaluation scheduling
peer
static
Specify static scheduling in a peer partition when Dakota is run in parallel.

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
In static scheduling, all available evaluations are assigned to servers in a predetermined fashion. Each completed evaluation is replaced with one congruent modulo the evaluation concurrency. For example, with 6 servers,
eval number 2 will be replaced by eval number 8.

6.5.7

processors per evaluation

Keywords Area
interface
processors per evaluation
Specify the number of processors per evaluation server when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER

6.5. INTERFACE

2165

Description
The optional processors per evaluation specification supports user override of the automatic parallel
configuration for the number of processors in each evaluation server. That is, if the automatic configuration is
undesirable for some reason, the user can enforce a desired server size at the evaluation parallelism level. Refer
to ParallelLibrary and the Parallel Computing chapter of the Users Manual [4] for additional information.

6.5.8

analysis servers

Keywords Area
interface
analysis servers
Specify the number of analysis servers when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): INTEGER
Default: no override of auto configure

Description
The optional analysis servers specification supports user override of the automatic parallel configuration
for the number of analysis servers. That is, if the automatic configuration is undesirable for some reason, the
user can enforce a desired number of partitions at the analysis parallelism level. Refer to ParallelLibrary and the
Parallel Computing chapter of the Users Manual [4] for additional information.

6.5.9

analysis scheduling

Keywords Area
interface
analysis scheduling
Specify the scheduling of concurrent analyses when Dakota is run in parallel

Topics
This keyword is related to the topics:
concurrency and parallelism

2166

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: no override of auto configure
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
master

peer

Dakota Keyword
Description
Specify a
dedicated master
partition for
parallel analysis
scheduling
Specify a peer
partition for
parallel analysis
scheduling

Description
When Dakota is run in parallel, the partition type for the analysis servers is determined automatically. If this
setting is undesirable, it may be overridden by the user using the analysis scheduling keyword.
The partition type and scheduling are
master
Keywords Area
interface
analysis scheduling
master
Specify a dedicated master partition for parallel analysis scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a dedicated master partition.
In a dedicated master partition, one processor (the master) dynamically schedules work on the analysis servers.
This reduces the number of processors available to create servers by 1.

6.6. RESPONSES

2167

peer
Keywords Area
interface
analysis scheduling
peer
Specify a peer partition for parallel analysis scheduling

Topics
This keyword is related to the topics:
concurrency and parallelism

Specification
Alias: none
Argument(s): none

Description
This option overrides the Dakota parallel automatic configuration, forcing the use of a peer partition. In a peer partition, all processors are available to be assigned to analysis servers. Note that unlike the case of evaluationscheduling, it is not possible to specify static or dynamic.

6.6

responses

Keywords Area
responses
Description of the model output data returned to Dakota upon evaluation of an interface.

Topics
This keyword is related to the topics:
block

Specification
Alias: none
Argument(s): none
Required/Optional

Description of
Group

Dakota Keyword

Dakota Keyword
Description

2168

CHAPTER 6. KEYWORDS AREA

Optional

id responses

Name the response

block, helpful
when there are
multiple

Optional

descriptors

Labels for the

responses
Response type
suitable for
optimization
Response type
suitable for
calibration or least
squares
Generic response
type
Gradients will not
be used
Analysis driver
will return
gradients
Gradients are
needed and will be
obtained from a
mix of numerical
and analytic
sources
Gradients are
needed and will be
approximated by
finite differences
Hessians will not
be used
Hessians are
needed and will be
approximated by
finite differences
Hessians are
needed and will be
approximated by
secant updates
(BFGS or SR1)
from a series of
gradient
evaluations

Required(Choose
One)

objective functions
Group 1
calibration terms

response functions
no gradients
Required(Choose
One)

gradient type
(Group 2)

analytic gradients

mixed gradients

numerical gradients

no hessians
Required(Choose
One)

Hessian type
(Group 3)

numerical hessians

quasi hessians

6.6. RESPONSES

2169
analytic hessians

mixed hessians

Hessians are
needed and are
available directly
from the analysis
driver
Hessians are
needed and will be
obtained from a
mix of numerical,
analytic, and
quasi sources

Description
The responses specification in a Dakota input file indicates the types of data that can be returned by an interface
when invoked during Dakotas execution. The specification includes three groups and two optional keywords.
Group 1 is related to the type and number of responses expected by Dakota
The specification must be one of three types:
1. objective and constraint functions
2. calibration (least squares) terms and constraint functions
3. a generic response functions specification.
These correspond to optimization, least squares, and uncertainty quantification methods, respectively. The
response type chosen from Group 1 should be consistent with the iterative technique called for in the method
specification. Certain general-purpose iterative techniques, such as parameter studies and design of experiments
methods, can be used with any of these data sets.
Each type of response has additional required and optional keywords.
Group 2 is related to the availability of first derivatives (gradient vectors) for the response functions.
The gradient specification also links back to the iterative method used. Gradients commonly are needed when
the iterative study involves gradient-based optimization, local reliability analysis for uncertainty quantification, or
local sensitivity analysis. They can optionally be used to build some types of surrogate models.
Group 3 is related to the availability of second derivatives (Hessian matrices) for the response functions.
Hessian availability for the response functions is similar to the gradient availability specifications, with the
addition of support for quasi-Hessians. The Hessian specification also links back to the iterative method in
use; Hessians commonly would be used in gradient-based optimization by full Newton methods or in reliability
analysis with second-order limit state approximations or second-order probability integrations.

Examples
Several examples follow. The first example shows an optimization data set containing an objective function and
two nonlinear inequality constraints. These three functions have analytic gradient availability and no Hessian
availability.
responses
objective_functions = 1
nonlinear_inequality_constraints = 2
analytic_gradients
no_hessians

2170

CHAPTER 6. KEYWORDS AREA

The next example shows a typical specification for a calibration data set. The six residual functions will
have numerical gradients computed using the dakota finite differencing routine with central differences of 0.1%
(plus/minus delta relative to current variables value = .001value).
responses
calibration_terms = 6
numerical_gradients
method_source dakota
interval_type central
fd_gradient_step_size = .001
no_hessians

The last example shows a generic specification that could be used with a nondeterministic sampling iterator.
The three response functions have no gradient or Hessian availability; therefore, only function values will be used
by the iterator.
responses
response_functions = 3
no_gradients
no_hessians

Parameter study and design of experiments iterators are not restricted in terms of the response data sets which
may be catalogued; they may be used with any of the function specification examples shown above.

Theory
Responses specify the total data set that is available for use by the method over the course of iteration. This is
distinguished from the data subset described by an active set vector (see Dakota File Data Formats in the Users
Manual [Adams et al., 2010]) indicating the particular subset of the response data needed for a particular function
evaluation. Thus, the responses specification is a broad description of the data to be used during a study whereas
the active set vector indicates the subset currently needed.

6.6.1

id responses

Keywords Area
responses
id responses
Name the response block, helpful when there are multiple

Topics
This keyword is related to the topics:
block identifier

Specification
Alias: none
Argument(s): STRING
Default: use of last responses parsed

6.6. RESPONSES

2171

Description
The optional block identifier id responses specifies a string to uniquely identify a particular responses specification (typically used when there are multiple present). A model can then specify or point to this response set by
specifying the same string in its responses pointer specification. For example, a model whose specification
contains responses pointer = R1 will use a responses set with id responses = R1.
If the id responses specification is omitted, a particular responses specification will be used by a model
only if that model omits specifying a responses pointer and if the responses set was the last set parsed
(or is the only set parsed). In common practice, if only one responses set exists, then id responses can
be safely omitted from the responses specification and responses pointer can be omitted from the model
specification(s), since there is no potential for ambiguity in this case.

6.6.2

descriptors

Keywords Area
responses
descriptors
Labels for the responses

Specification
Alias: response descriptors
Argument(s): STRINGLIST
Default: root strings plus numeric identifiers

Description
The optional response labels specification descriptors is a list of strings which will be printed in Dakota
output to identify the values for particular response functions.
Note that the ordering of responses and descriptors in the input currently must match the order of the values
returned to Dakota in a results file. See the example below.
The default descriptor strings use a root string plus a numeric identifier. This root string is
"obj fn" for objective functions
"least sq term" for least squares terms
"response fn" for generic response functions
"nln ineq con" for nonlinear inequality constraints
"nln eq con" for nonlinear equality constraints

Examples
Note that the descriptors currently must match the order of the values in the results file; they are not used to
validate the returned data. For example, if the responses block contains:
\c descriptors x1 x2 x3

and the results file contains

2172

CHAPTER 6. KEYWORDS AREA

4 x1
5 x3
6 x2

Then Dakota will understand the returned data to be:

x1 = 4
x2 = 5
x3 = 6

6.6.3

objective functions

Keywords Area
responses
objective functions
Response type suitable for optimization

Specification
Alias: num objective functions
Argument(s): INTEGER
Required/Optional
Optional

Description of
Group

Dakota Keyword
sense

Optional

primary scale types

Optional

primary scales

Optional

weights

Optional

nonlinear inequality constraints

Dakota Keyword
Description
Whether to
minimize or
maximize each
objective function
Choose a scaling
type for each
response
Supply a
characteristic value
to scale each
reponse
Specify weights
for each objective
function
Group to specify
nonlinear
inequality
constraints

6.6. RESPONSES

2173
Optional

nonlinear equalityconstraints

Optional

scalar objectives

Optional

field objectives

Group to specify
nonlinear equality
constraints
Number of scalar
objective functions
Number of field
objective functions

Description
The objective functions keyword specifies the number of objective functions returned to Dakota. The
number of objective functions must be 1 or greater.
Constraints
The keywords nonlinear inequality constraints, and nonlinear equality constraints
specify the number of nonlinear inequality constraints, and nonlinear equality constraints, respectively. When interfacing to external applications, the responses must be returned to Dakota in this order: objective functions,
nonlinear inequality constraints, then nonlinear equality constraints.
Any linear constraints present in an application need only be input to an optimizer at start up and do not need
to be part of the data returned on every function evaluation. These are therefore specified in the method block.
Bounds on the design variables are specified in the variables block.
Optional Keywords
The optional keywords relate to scaling the objective functions (for better numerical results), formulating the
problem as minimization or maximization, and dealing with multiple objective functions. If scaling is used, it is
applied before multi-objective weighted sums are formed.

See Also
These keywords may also be of interest:
calibration terms
response functions
method
variables
sense
Keywords Area
responses
objective functions
sense
Whether to minimize or maximize each objective function

Specification
Alias: none
Argument(s): STRINGLIST
Default: vector values = minimize

2174

CHAPTER 6. KEYWORDS AREA

Description
The sense keyword is used to declare whether each objective function should be minimized or maximized. The
argument options are:
"minimization"
"maximization" These can be abbreviated to "min" and "max".
The number of strings should either be equal to the number of objective functions, or one. If a single string is
specified it will apply to each objective function.
primary scale types
Keywords Area
responses
objective functions
primary scale types
Choose a scaling type for each response

Specification
Alias: objective function scale types
Argument(s): STRINGLIST
Default: no scaling

Description
The primary scale types keyword specifies one of number of primary functions strings indicating the scaling type for each response value in methods that support scaling, when scaling is enabled.
See the scaling keyword in the method section for details on how to use this keyword. Note that primary
response functions (objective, calibration, or response functions) cannot be automaticaly scaled due to lack of
bounds, so valid scale types are none value and log.
primary scales
Keywords Area
responses
objective functions
primary scales
Supply a characteristic value to scale each reponse

Specification
Alias: objective function scales
Argument(s): REALLIST
Default: 1.0 (no scaling)

6.6. RESPONSES

2175

Description
Each entry in primary scales is a user-specified nonzero characteristic value to scale each response.
The argument may be of length 1 or the number of primary response functions. See the scaling keyword
in the method section for details on how to use this keyword.
weights
Keywords Area
responses
objective functions
weights
Specify weights for each objective function

Specification
Alias: multi objective weights
Argument(s): REALLIST
Default: equal weights

Description
If the number of objective functions is greater than 1, then a weights specification provides a simple weightedsum approach to combining multiple objectives into a single objective:
f=

n
X

wi fi

i=1

If weights are not specified, then each response is given equal weighting:
f=

n
X
fi
i=1

where, in both of these cases, a minimization sense will retain a positive weighting for a minimizer and a
maximization sense will apply a negative weighting.
nonlinear inequality constraints
Keywords Area
responses
objective functions
nonlinear inequality constraints
Group to specify nonlinear inequality constraints

Specification
Alias: num nonlinear inequality constraints
Argument(s): INTEGER
Default: 0

2176

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
lower bounds

Optional

upper bounds

Optional

scale types

Optional

scales

Dakota Keyword
Description
Specify minimum
values
Specify maximium
values
Choose how each
constraint is scaled
Characteristic
values for scaling

Description
The lower bounds and upper bounds specifications provide the lower and upper bounds for 2-sided nonlinear inequalities of the form
gl g(x) gu
The defaults for the inequality constraint bounds are selected so that one-sided inequalities of the form
g(x) 0.0
result when there are no user constraint bounds specifications (this provides backwards compatibility with previous Dakota versions).
In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize
are treated as -infinity. This feature is commonly used to drop one of the bounds in order to specify a 1-sided
constraint (just as the default lower bounds drop out since -DBL MAX < -bigRealBoundSize). The same
approach is used for nonexistent linear inequality bounds and for nonexistent design variable bounds.
The scale types and scales keywords are related to scaling of g (x). See the scaling keyword in the
method section for details.
lower bounds
Keywords Area
responses
objective functions
nonlinear inequality constraints
lower bounds
Specify minimum values

Specification
Alias: nonlinear inequality lower bounds
Argument(s): REALLIST
Default: vector values = -infinity

Description
Specify minimum values

6.6. RESPONSES
upper bounds
Keywords Area
responses
objective functions
nonlinear inequality constraints
upper bounds
Specify maximium values

Specification
Alias: nonlinear inequality upper bounds
Argument(s): REALLIST
Default: vector values = 0 .

Description
Specify maximium values
scale types
Keywords Area
responses
objective functions
nonlinear inequality constraints
scale types
Choose how each constraint is scaled

Specification
Alias: nonlinear inequality scale types
Argument(s): STRINGLIST
Default: no scaling

Description
See the scaling keyword in the method section for details on how to use this keyword.

2177

2178

CHAPTER 6. KEYWORDS AREA

scales
Keywords Area
responses
objective functions
nonlinear inequality constraints
scales
Characteristic values for scaling

Specification
Alias: nonlinear inequality scales
Argument(s): REALLIST
Default: 1.0 (no scaling)

Description
See the scaling keyword in the method section for details on how to use this keyword.
nonlinear equality constraints
Keywords Area
responses
objective functions
nonlinear equality constraints
Group to specify nonlinear equality constraints

Specification
Alias: num nonlinear equality constraints
Argument(s): INTEGER
Default: 0
Required/Optional
Optional

Optional

Description of
Group

Dakota Keyword
targets

scale types

Dakota Keyword
Description
Target values for
the nonlinear
equality constraint
Choose how each
constraint is scaled

6.6. RESPONSES

2179
Optional

scales

Characteristic
values for scaling

Description
The targets specification provides the targets for nonlinear equalities of the form
g(x) = gt
and the defaults for the equality targets enforce a value of 0. for each constraint
g(x) = 0.0
The scale types and scales keywords are related to scaling of g (x). See the scaling keyword in the
method section for details.
targets
Keywords Area
responses
objective functions
nonlinear equality constraints
targets
Target values for the nonlinear equality constraint

Specification
Alias: nonlinear equality targets
Argument(s): REALLIST
Default: vector values = 0 .

Description
The targets specification provides the targets for nonlinear equalities of the form
g(x) = gt
and the defaults for the equality targets enforce a value of 0.0 for each constraint:
g(x) = 0.0

scale types
Keywords Area
responses
objective functions
nonlinear equality constraints
scale types
Choose how each constraint is scaled

2180

CHAPTER 6. KEYWORDS AREA

Specification
Alias: nonlinear equality scale types
Argument(s): STRINGLIST
Default: no scaling

Description
See the scaling keyword in the method section for details on how to use this keyword.
scales
Keywords Area
responses
objective functions
nonlinear equality constraints
scales
Characteristic values for scaling

Specification
Alias: nonlinear equality scales
Argument(s): REALLIST
Default: 1.0 (no scaling)

Description
See the scaling keyword in the method section for details on how to use this keyword.
scalar objectives
Keywords Area
responses
objective functions
scalar objectives
Number of scalar objective functions

Specification
Alias: num scalar objectives
Argument(s): INTEGER

6.6. RESPONSES

2181

Description
This keyword describes the number of scalar objective functions. It is meant to be used in conjunction with
field objectives, which describes the number of field objectives functions. The total number of objective
functions, both scalar and field, is given by objective functions. If only scalar objective functions are
specified, it is not necessary to specify the number of scalar terms explicitly: one can simply say objective functions = 5 and get 5 scalar objectives. However, if there are three scalar objectives and 2 field objectives,
then objective functions = 5 but scalar objectives = 3 and field objectives = 2.
Objective functions are responses that are used with optimization methods in Dakota. Currently, each term
in a field objective is added to the total objective function presented to the optimizer. For example, if you have
one field objective with 100 terms (e.g. a time-temperature trace with 100 time points and 100 corresponding
temperature points), the 100 temperature values will be added to create the overall objective.

See Also
These keywords may also be of interest:
field objectives
field objectives
Keywords Area
responses
objective functions
field objectives
Number of field objective functions

Specification
Alias: num field objectives
Argument(s): INTEGER
Required/Optional
Required

Description of
Group

Dakota Keyword
lengths

Optional

num coordinates per field

Optional

read field coordinates

Dakota Keyword
Description
Lengths of field
responses
Number of
independent
coordinates for
field responses
Add context to
data: flag to
indicate that field
coordinates should
be read

2182

CHAPTER 6. KEYWORDS AREA

Description
This keyword describes the number of field objective functions. A field function is a set of related response
values collected over a range of independent coordinate values which may or may not be specified by the user.
For example, voltage over time would be a field function, where voltage is the field objective and time
is the independent coordinate. Similarly, temperature over time and space would be a field response, where the
independent coordinates would be both time and spatial coordinates such as (x,y) or (x,y,z), depending on the
application. The main difference between scalar objectives and field objectives is that for field data, we plan to
implement methods that take advantage of the correlation or relationship between the field values.
Note that if there is one field objective, and it has length 100 (meaning 100 values), then the users
simulation code must return 100 values. Also, if there are both scalar and field objectives, the user should specify
the number of scalar objectives as scalar objectives. If there are only field objectives, it still is necessary
to specify both objective functions = NN and field objectives = NN, where NN is the number of
field objectives.
Objective functions are responses that are used with optimization methods in Dakota. Currently, each term
in a field objective is added to the total objective function presented to the optimizer. For example, if you have
one field objective with 100 terms (e.g. a time-temperature trace with 100 time points and 100 corresponding
temperature points), the 100 temperature values will be added to create the overall objective.

See Also
These keywords may also be of interest:
scalar objectives
lengths
Keywords Area
responses
objective functions
field objectives
lengths
Lengths of field responses

Specification
Alias: none
Argument(s): INTEGERLIST

Description
This keyword describes the lengths of each field response. It is an integer vector of length field responses.
For example, if the field responses = 2, an example would be lengths = 50 200, indicating that the first
field response has 50 field elements but the second one has 200. The coordinate values (e.g. the independent
variables) corresponding to these field responses are read in files labeled response descriptor.coords.

6.6. RESPONSES

2183

See Also
These keywords may also be of interest:
field responses
num coordinates per field
Keywords Area
responses
objective functions
field objectives
num coordinates per field
Number of independent coordinates for field responses

Specification
Alias: none
Argument(s): INTEGERLIST

Description
This keyword describes the number of independent coordinates for each field response. It is an integer vector
of length field responses. For example, if the field responses = 2, an example would be num coordinates per field = 2 1 means that the first field response has two sets of independent coordinates
(perhaps x, y locations), but the second response only has one (for example, time where the field response is
only dependent upon time). The actual coordinate values (e.g. the independent variables) corresponding to these
field responses are defined in a file call response descriptor.coords, where response descriptor is the name of the
individual field.

See Also
These keywords may also be of interest:
field responses
read field coordinates
Keywords Area
responses
objective functions
field objectives
read field coordinates
Add context to data: flag to indicate that field coordinates should be read

2184

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
Field coordinates specify independent variables (e.g. spatial or temporal coordinates) upon which the field depends. For example, the voltage level above might be a function of time, so time is the field coordinate. If the
user has field coordinates to read, they need to specify read field coordinates. The field coordinates
will then be read from a file named response descriptor.coords, where response descriptor is the user-provided
descriptor for the field response. The number of columns in the coords file should be equal to the number of field
coordinates.

6.6.4

calibration terms

Keywords Area
responses
calibration terms
Response type suitable for calibration or least squares

Specification
Alias: least squares terms num least squares terms
Argument(s): INTEGER
Required/Description of
Optional
Group
Optional
Optional
Optional

Dakota Keyword
scalar calibration terms
field calibration terms
primary scale types

Optional

primary scales

Optional

weights

Dakota Keyword
Description
Number of scalar
calibration terms
Number of field
calibration terms
Choose a scaling
type for each
response
Supply a
characteristic value
to scale each
reponse
Apply different
weights to each
response

6.6. RESPONSES

2185
Optional(Choose
One)

calibration data

Supply calibration
data in the case of
field data or mixed
data (both scalar
and field data).

calibration data file

Specify a text file

containing
calibration data for
scalar responses

Optional

nonlinear inequality constraints

Optional

nonlinear equalityconstraints

Group to specify
nonlinear
inequality
constraints
Group to specify
nonlinear equality
constraints

Group 1

Description
Responses for a calibration study are specified using calibration terms and optional keywords for weighting/scaling, data, and constraints. In general when calibrating, Dakota automatically tunes parameters to minimize discrepancies or residuals between the model and the data:
Ri = yiM odel () yiData .
There are two use cases:
If calibration data file is NOT specified, then each of the calibration terms returned to Dakota through the
interface is a residual Ri to be driven toward zero.
If calibration data file IS specified, then each of the calibration terms returned to Dakota must be a response
yiM odel (), which Dakota will difference with the data in the specified data file.
Constraints
The keywords nonlinear inequality constraints, and nonlinear equality constraints
specify the number of nonlinear inequality constraints, and nonlinear equality constraints, respectively. When
interfacing to external applications, the responses must be returned to Dakota in this order: calibration terms,
nonlinear inequality constraints, then nonlinear equality constraints.
Any linear constraints present in an application need only be input to an optimizer at start up and do not need
to be part of the data returned on every function evaluation. These are therefore specified in the method block.
Optional Keywords
The optional keywords relate to scaling responses (for better numerical results), dealing with multiple residuals, and importing data.
See the scaling keyword in the method section for more details on scaling. If scaling is specified, then it is
applied to each residual prior to squaring:
f=

n
X
i=1

wi (

yiM odel yiData 2

)
si

2186

CHAPTER 6. KEYWORDS AREA

In the case where experimental data uncertainties are supplied, then the weights are automatically defined to
be the inverse of the experimental variance:
f=

n
X
1 yiM odel yiData 2
(
)
2
si
i=1 i

Theory
Dakota calibration terms are typically used to solve problems of parameter estimation, system identification, and
model calibration/inversion. Local least squares calibration problems are most efficiently solved using specialpurpose least squares solvers such as Gauss-Newton or Levenberg-Marquardt; however, they may also be solved
using any general-purpose optimization algorithm in Dakota. While Dakota can solve these problems with either
least squares or optimization algorithms, the response data sets to be returned from the simulator are different
when using objective functions versus calibration terms.
Least squares calibration involves a set of residual functions, whereas optimization involves a single objective
function (sum of the squares of the residuals), i.e.,
f=

n
X
i=1

Ri2 =

n
X

yiM odel () yiData

2

i=1

where f is the objective function and the set of Ri are the residual functions, most commonly defined as the
difference between a model response and data. Therefore, function values and derivative data in the least squares
case involve the values and derivatives of the residual functions, whereas the optimization case involves values and
derivatives of the sum of squares objective function. This means that in the least squares calibration case, the user
must return each of n residuals separately as a separate calibration term. Switching between the two approaches
sometimes requires different simulation interfaces capable of returning the different granularity of response data
required, although Dakota supports automatic recasting of residuals into a sum of squares for presentation to
an optimization method. Typically, the user must compute the difference between the model results and the
observations when computing the residuals. However, the user has the option of specifying the observational data
(e.g. from physical experiments or other sources) in a file.

See Also
These keywords may also be of interest:
objective functions
response functions
scalar calibration terms
Keywords Area
responses
calibration terms
scalar calibration terms
Number of scalar calibration terms

6.6. RESPONSES

2187

Specification
Alias: none
Argument(s): INTEGER

Description
This keyword describes the number of scalar calibration terms. It is meant to be used in conjunction with fieldcalibration terms, which describes the number of field calibration terms. The total number of calibration
terms, both scalar and field, is given by calibration terms. If only scalar calibration terms are specified, it
is not necessary to specify the number of scalar terms explicitly: one can simply say calibration terms =
5 and get 5 scalar terms. However, if there are three scalar terms and 2 field terms, then calibration terms
= 5 but scalar calibration terms = 3 and field calibration terms = 2.
Calibration terms are responses that are used with calibration methods in Dakota, such as least squares optimizers. Currently, each scalar term is added to the total sum-of-squares error function presented to the optimizer.
However, each individual field value is added as well. For example, if you have one field calibration term with
length 100 (e.g. a time - temperature trace with 100 time points and 100 temperature points), the 100 temperature
values will be added to create the overall sum-of-squares error function used in calibration.

See Also
These keywords may also be of interest:
field calibration terms
field calibration terms
Keywords Area
responses
calibration terms
field calibration terms
Number of field calibration terms

Specification
Alias: none
Argument(s): INTEGER
Required/Optional
Required
Optional

Description of
Group

Dakota Keyword
lengths
num coordinates per field

Dakota Keyword
Description
Lengths of field
responses
Number of
independent
coordinates for
field responses

2188

CHAPTER 6. KEYWORDS AREA

Optional

read field coordinates

Add context to
data: flag to
indicate that field
coordinates should
be read

Description
This keyword describes the number of field calibration terms. A set of field calibration terms is a set of related
response values collected over a range of independent coordinate values which may or may not be specified by
the user. For example, voltage over time would be a field function, where voltage is the field objective
and time is the independent coordinate. Similarly, temperature over time and space would be a field response,
where the independent coordinates would be both time and spatial coordinates such as (x,y) or (x,y,z), depending
on the application. The main difference between scalar calibration terms and field calibration terms is that for
field data, we plan to implement methods that take advantage of the correlation or relationship between the field
values. For example, with calibration, if we want to calibrate parameters that result in a good model fit to a timetemperature curve, we may have to do some interpolation between the experimental data and the simulation data.
That capability requires knowledge of the independent coordinates.
Note that if there is one field calibration terms, and it has length 100 (meaning 100 values), then
the users simulation code must return 100 values. Also, if there are both scalar and field calibration, the user
should specify the number of scalar terms as scalar calibration terms. If there are only field calibration
terms, it still is necessary to specify both field calibration terms = NN and calibration terms =
NN, where NN is the number of field calibration terms.
Calibration terms are responses that are used with calibration methods in Dakota, such as least squares optimizers. Currently, each scalar term is added to the total sum-of-squares error function presented to the optimizer.
However, each individual field value is added as well. For example, if you have one field calibration term with
length 100 (e.g. a time-temperature trace with 100 time points and 100 temperature points), the 100 temperature
values will be added to create the overall sum-of-squares error function used in calibration. We have an initial
capability to interpolate the field data from the users simulation to the experimental data. For example, if the user
has thermocouple readings at 20 time points, it will be an experimental field response with 20 time points and
20 temperature values. Dakota takes the 100 simulation time-temperature values (from the example above) and
interpolates those to the 20 experimental points, to create 20 residual terms (simulation minus experimental data
points) that will be used in calibration.

See Also
These keywords may also be of interest:
scalar calibration terms
lengths
Keywords Area
responses
calibration terms
field calibration terms
lengths
Lengths of field responses

6.6. RESPONSES

2189

Specification
Alias: none
Argument(s): INTEGERLIST

Description
This keyword describes the lengths of each field response. It is an integer vector of length field responses.
For example, if the field responses = 2, an example would be lengths = 50 200, indicating that the first
field response has 50 field elements but the second one has 200. The coordinate values (e.g. the independent
variables) corresponding to these field responses are read in files labeled response descriptor.coords.

See Also
These keywords may also be of interest:
field responses
num coordinates per field
Keywords Area
responses
calibration terms
field calibration terms
num coordinates per field
Number of independent coordinates for field responses

Specification
Alias: none
Argument(s): INTEGERLIST

Description
This keyword describes the number of independent coordinates for each field response. It is an integer vector
of length field responses. For example, if the field responses = 2, an example would be num coordinates per field = 2 1 means that the first field response has two sets of independent coordinates
(perhaps x, y locations), but the second response only has one (for example, time where the field response is
only dependent upon time). The actual coordinate values (e.g. the independent variables) corresponding to these
field responses are defined in a file call response descriptor.coords, where response descriptor is the name of the
individual field.

See Also
These keywords may also be of interest:
field responses

2190

CHAPTER 6. KEYWORDS AREA

read field coordinates

Keywords Area
responses
calibration terms
field calibration terms
read field coordinates
Add context to data: flag to indicate that field coordinates should be read

Specification
Alias: none
Argument(s): none

Description
Field coordinates specify independent variables (e.g. spatial or temporal coordinates) upon which the field depends. For example, the voltage level above might be a function of time, so time is the field coordinate. If the
user has field coordinates to read, they need to specify read field coordinates. The field coordinates
will then be read from a file named response descriptor.coords, where response descriptor is the user-provided
descriptor for the field response. The number of columns in the coords file should be equal to the number of field
coordinates.
primary scale types
Keywords Area
responses
calibration terms
primary scale types
Choose a scaling type for each response

Specification
Alias: calibration term scale types least squares term scale types
Argument(s): STRINGLIST
Default: no scaling

Description
The primary scale types keyword specifies one of number of primary functions strings indicating the scaling type for each response value in methods that support scaling, when scaling is enabled.
See the scaling keyword in the method section for details on how to use this keyword. Note that primary
response functions (objective, calibration, or response functions) cannot be automaticaly scaled due to lack of
bounds, so valid scale types are none value and log.

6.6. RESPONSES

2191

primary scales
Keywords Area
responses
calibration terms
primary scales
Supply a characteristic value to scale each reponse

Specification
Alias: calibration term scales least squares term scales
Argument(s): REALLIST
Default: 1.0 (no scaling)

Description
Each entry in primary scales is a user-specified nonzero characteristic value to scale each response.
The argument may be of length 1 or the number of primary response functions. See the scaling keyword
in the method section for details on how to use this keyword.
weights
Keywords Area
responses
calibration terms
weights
Apply different weights to each response

Specification
Alias: calibration weights least squares weights
Argument(s): REALLIST
Default: equal weights

Description
The weights specification provides a means to specify a relative emphasis among the vector of squared residuals
through multiplication of these squared residuals by a vector of weights:
f=

n
X
i=1

wi Ri2 =

n
X
i=1

wi (yiM yiO )2

2192

CHAPTER 6. KEYWORDS AREA

calibration data
Keywords Area
responses
calibration terms
calibration data
Supply calibration data in the case of field data or mixed data (both scalar and field data).

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
num experiments

Dakota Keyword
Description
Add context to
data: number of
different
experiments
Add context to
data: number of
configuration
variables.
Add context to
experiment data
description by
specifying the type
of experimental
error.

Optional

num config variables

Optional

variance type

Optional

scalar data file

Specify a scalar
data file to
complement field
data files (mixed
case)

Optional

interpolate

Flag to indicate
interpolation of
simulation values.

Description
calibration data specifies a keyword block that indicates that Dakota should read in various types of experimental data. This block is primarily to support the reading of field calibration data.
The user will specify the number of experiments, num experiments. If this is not specified, it is assumed
there is only one experiment.
For each experiment, there are four main types of data related to fields:

6.6. RESPONSES

2193

values.
These are the values of the experiment field (e.g. temperature values, voltage levels, etc.) These MUST be specified in a file named response descriptor.NUM.dat, where NUM is replaced by the number of
the experiment (1, 2, ...) and response descriptor is replaced by the actual response descriptor the
user has specified. For example, if response descriptor = voltage, then the voltage field values for
experiment 1 should be in a file labeled voltage.1.dat. The field values should be in a column (e.g. one field
value per row).
field coordinates.
Field coordinates specify independent variables (e.g. spatial or temporal coordinates) upon which the field
depends. For example, the voltage level above might be a function of time, so time is the field coordinate.
For the calibration data, the field coordinates are read from a file named response descriptor.NUM.coords,
similar to the pattern for field values. The number of columns in the coords file should be equal to the
number of field coordinates.
variance terms.
The user needs to specify variance type, which defines the type of experimental measurement error.
This is a string list, with one variance type specified for each scalar and each field. The available types
are none (no variance is specified), scalar (one scalar value is specified which is applicable to all of the
measurements in the field), diagonal (a column vector is provided which contains the number of elements
of the experimental data field. Each element of the vector contains the experimental measurement variance
corresponding to that particular field measurement. For example, for the fifth term in the field, the fifth
term in the diagonal vector would have the variance of that measurement), and matrix. In the matrix case,
a full covariance matrix is provided, which contains the pairwise correlations between each element in the
field. For each field, if the variance type is not none, a data file must be provided with the name
response descriptor.NUM.sigma, which contains the appropriate variance data for that field.
configuration variables.
Configuration variables specify the conditions corresponding to different experiments. This is used when
there is more than one experiment. If num config variables is positive, the configuration variables
for each experiment should be placed in a file named experiment.NUM.config, where the number of items
in that config file are the num config variables. Currently, configuration variables are not being
used. However, the intent is that they will be used as state variables for the simulation (for example) and
not as variables that would be calibrated.
The above description is relevant for field data (with files for field values, field coordinates, field variances). If
the user also has scalar experimental data, it may be entered in the same way (e.g. one file for a scalar experimental
value named scalar response descriptor.NUM.dat, etc.) However, the user can choose to enter the scalar data in
the format that we offer for pure scalar data, where we have just one file, with the number of rows of that file equal
to the number of experiments. In that case, the scalar data is in the file given by the name scalar data file,
and the format of that file is the same as discussed in calibration data file.
One important feature of field data is the capability to interpolate between points in the field. For example, we
may have simulation data at a set of responses y at time points t: ( ts1 , ys1 ), ( ts2 , ys2 ), etc. In this example, t is the
independent coordinate for the simulation, and the simulation time and response points are denoted with subscripts
s1, s2, s3,. If the user has experimental data that is taken at different time points: ( te1 , ye1 ), ( te2 , ye2 ), ..., it is
necessary to interpolate the simulation data to provide estimates of the simulation response at the experimental
time points to construct the residual terms (model - experiment) at the experimental time points. Dakota can
perform this interpolation now. The user must specify the keyword interpolate, and also provide the field
coordinates as well as field values for the experiment data. If the interpolate keyword is not specified, Dakota
will assume that the simulation field data and the experiment field data is taken at the same set of independent

2194

CHAPTER 6. KEYWORDS AREA

coordinate values and simply construct the difference between these field terms to create the set of residuals
for the sum-of-squares calculation. When interpolate is specified, the simulation coordinates are assumed
fixed and the same for each simulation. These simulation coordinates are provided in response descriptor.coords.
However, the experiment coordinates for each experiment can be different, and are provided in the files numbered
by experiment with the file names given by response descriptor.NUM.coords, as indicated above.
num experiments
Keywords Area
responses
calibration terms
calibration data
num experiments
Add context to data: number of different experiments

Specification
Alias: none
Argument(s): INTEGER
Default: 1

Description
The number of different experiments. Dakota will expand the total number of residual terms based on the number
of calibration terms and the number of experiments. For example, if the number of calibration terms are five
scalars, and there are three experiments, the total number of residuals in the least squares formulation will be 15.
See calibration data or calibration data file.
num config variables
Keywords Area
responses
calibration terms
calibration data
num config variables
Add context to data: number of configuration variables.

Specification
Alias: none
Argument(s): INTEGER
Default: 0

6.6. RESPONSES

2195

Description
This is an optional description. If there are multiple experiments, there can be different configuration variables
(e.g. experimental settings, boundary conditions, etc.) per experiment. See calibration data or calibration datafile. Note: as of Dakota 6.2, configuration variables are not used. However, the intent is to treat them as state
variables which will be passed to the simulation, and not treated as parameters which are calibrated.
variance type
Keywords Area
responses
calibration terms
calibration data
variance type
Add context to experiment data description by specifying the type of experimental error.

Specification
Alias: none
Argument(s): STRINGLIST
Default: none

Description
There are four options for specifying the experimental error (e.g. the measurement error in the data you provide
for calibration purposes): none, scalar, diagonal, or matrix.
If the user specifies none, Dakota will calculate a variance (sigma-squared) term. This will be a constant
variance term across all of the data). If the user specifies scalar, they can provide a scalar variance per calibration
term. Note that for scalar calibration terms, only none or scalar are options for the measurement variance.
However, for field calibration terms, there are two additional options. diagonal allows the user to provide a
vector of measurement variances (one for each term in the calibration field). This vector corresponds to the
diagonal of the full covariance matrix of measurement errors. If the user specifies matrix, they can provide a
full covariance matrix (not just the diagonal terms), where each element(i,j) of the covariance matrix represents
the covariance of the measurement error between the i-th and j-th field values.
scalar data file
Keywords Area
responses
calibration terms
calibration data
scalar data file
Specify a scalar data file to complement field data files (mixed case)

2196

Specification
Alias: none
Argument(s): STRING

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2197
Required/Optional

Description of
Group

Optional(Choose
One)

tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format
for experiment data

custom annotated

Selects
custom-annotated
tabular file format
for experiment data

freeform

Selects free-form
tabular file format
for experiment data

Description
When calibrating both scalar and field calibration terms, to associated experimental data, the scalar data may be
provided in the file named by scalar data file. This file follows the same format as: calibration data file.
Default Behavior
If scalar data file is omitted, all calibration data, including for scalar responses, will be read from the
generic field calibration data format.
annotated
Keywords Area
responses
calibration terms
calibration data
scalar data file
annotated
Selects annotated tabular file format for experiment data

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

2198

CHAPTER 6. KEYWORDS AREA

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. For experiment data files, each subsequent row contains an experiment ID, followed by data for configuration
variables, observations, and/or observation errors, depending on context.
Default Behavior
By default, Dakota imports tabular experiment data files in annotated format. The annotated keyword can
be used to explicitly specify this.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

Examples
Import an annotated experimental data file containing a header row, leading exp id column, and experiment data
in a calibration study
responses
...
scalar_data_file shock_experiment.dat
annotated

Example data file with two measured quantities, three experiments:

%exp_id
velocity
stress
1
18.23
83.21
2
34.14
93.24
3
22.41
88.92

custom annotated
Keywords Area
responses
calibration terms
calibration data
scalar data file
custom annotated
Selects custom-annotated tabular file format for experiment data

Topics
This keyword is related to the topics:
file formats

6.6. RESPONSES

Specification
Alias: none
Argument(s): none
Default: annotated format

2199

2200

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Optional

Dakota Keyword
header

exp id

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file
Enable experiment
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file containing experiment data, including configuration variables, observatiions, and/or observation errors, depending on context. For experiment import, customannotated allows user options for whether header row and exp id column appear in the tabular file, thus
bridging freeform and (fully) annotated.
Default Behavior
By default, Dakota imports tabular experiment data files in annotated format. The custom annotated
keyword, followed by options can be used to select other formats.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

Examples
Import an experimental data file containing a header row, no leading exp id column, and experiment data in a
calibration study
responses
...
scalar_data_file shock_experiment.dat
custom_annotated header

Example data file with two measured quantities, three experiments:

%

velocity
18.23
34.14
22.41

stress
83.21
93.24
88.92

header
Keywords Area
responses
calibration terms

6.6. RESPONSES
calibration data
scalar data file
custom annotated
header
Enable header row in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
exp id
Keywords Area
responses
calibration terms
calibration data
scalar data file
custom annotated
exp id
Enable experiment ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no exp id column

Description
See description of parent custom annotated

2201

2202

CHAPTER 6. KEYWORDS AREA

freeform
Keywords Area
responses
calibration terms
calibration data
scalar data file
freeform
Selects free-form tabular file format for experiment data

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. For
experiment data files, each row contains data for configuration variables, observatiions, and/or observation errors,
depending on context.
Default Behavior
By default, Dakota imports tabular experiment data files in annotated format. Specify freeform to instead
select this format.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

Examples
Import a free-form experimental data file containing raw experiment data in a calibration study
responses
...
scalar_data_file shock_experiment.dat
freeform

Example data file with two measured quantities, three experiments:

18.23
34.14
22.41

83.21
93.24
88.92

6.6. RESPONSES

2203

interpolate
Keywords Area
responses
calibration terms
calibration data
interpolate
Flag to indicate interpolation of simulation values.

Specification
Alias: none
Argument(s): none

Description
If interpolate is specified, Dakota will interpolate between the simulation data and the experiment data to
calculate the residuals for calibration methods. Specifically, the simulation data is interpolated onto the experimental data points. So, if the simulation data is a field of length 100 with one independent coordinate, and the
experiment data is of length 5 with one independent coordinate, the interpolation is done between the 100 (t,f)
simulation points (where t is the independent coordinate and f is the simulation field value) onto the five (t e, f e)
points to obtain the residual differences between the simulation and experiment. See calibration data.
calibration data file
Keywords Area
responses
calibration terms
calibration data file
Specify a text file containing calibration data for scalar responses

Specification
Alias: least squares data file
Argument(s): STRING
Default: none
Required/Optional
Optional(Choose
One)

Description of
Group
tabular format
(Group 1)

Dakota Keyword
annotated

Dakota Keyword
Description
Selects annotated
tabular file format
for experiment data

2204

CHAPTER 6. KEYWORDS AREA

custom annotated

Selects
custom-annotated
tabular file format
for experiment data

freeform

Selects free-form
tabular file format
for experiment data

Optional

num experiments

Optional

num config variables

Optional

variance type

Add context to
data: number of
different
experiments
Add context to
data: number of
configuration
variables.
Add context to
experiment data
description by
specifying the type
of experimental
error.

Description
Enables text file import of experimental observations for use in calibration, for scalar responses only. Dakota will
calibrate model variables to best match tese data. Key options include:
format: whether the data file is in annotated, custom annotated, or freeform format
content: where num experiments, num config variables, and variance type indicate which
columns appear in the data.
While some components may be omitted, the most complete version of a an annotated calibration data file could
include columns corresponding to:
exp_id | configuration xvars | y data observations | y data variances

Each row in the file corresponds to an experiment or replicate observation of an experiment to be compared to
the model output.
Usage Tips
The calibration data file used when ONLY scalar calibration terms are present. If there are
field calibration terms, instead use calibration data. For mixed scalar and field calibration terms,
on may use the calibration data specification, together with its sub-specification scalar data file, which uses the format described here.
Simple Case
In the simplest case, no data content descriptors are specified, so the data file must contain only the y Data
observations which represent a single experimental observation. In this case, the data file should have Nterms
columns and 1 row, where Nterms is the value of calibration terms.

6.6. RESPONSES

2205

For each function evaluation, Dakota will run the analysis driver, which must return Nterms model responses.
Then the residuals are computed as:
Ri = yiM odel yiData .
These residuals can be weighted using weights.
With experimental variances
If information is known about the measurement error and the uncertainty in the measurement, that can be
specified by sending the measurement error variance to Dakota. In this case, the keyword variance type is
added, followed by a string of variance types of length one or of length Nterms , where Nterms is the value of
calibration terms. The variance type for each response can be none or scalar. NOTE: you must specify
the same variance type for all scalar terms. That is, they will all be none or all be scalar.
For each response that has a scalar variance type, each row of the datafile will now have Nterms of y
data values followed by Nterms columns that specify the measurement error (in units of variance, not standard
deviation of the measurement error) for y variances.
Dakota will run the analysis driver, which must return Nterms responses. Then the residuals are computed as:
Ri =

yiM odel yiData

vari

for i = 1 . . . Nterms .
Fully general case
In the most general case, the content of the data file is described by the arguments of three parameters. The
parameters are optional, and defaults are described below.
num experiments ( Nexp )
Default: Nexp = 1
This indicates that the data represents multiple experiments, where each experiment might be conducted
with different values of configuration variables. An experiment can also be thought of as a replicate, where
the experiments are run at the same values of the configuration variables.
num config variables ( Ncf g )
This is not yet supported, but will specify the values of experimental conditions at which data were collected.
variance type (none or scalar)
This indicates if the data file contains variances for measurement error of the experimental data. The default
is none.
If the user does not specify variance type, or if the variance type = none, only the actual observations are specified in the calibration data file. If the user specifies variance type = scalar, then
the calibration data file must contain two times calibration terms. The first calibration terms columns are the experimental data, and the second calibration terms columns are the experimental
measurement error variance. For example, if the user has three calibration terms, and specifies variancetype = scalar, then the calibration data must contain six columns. The first three columns will contain the data,
and the second three columns will contain the experimental error (in units of variance) for the data in the first three
columns. These variances are used to weight the residuals in the sum-of-squares objective.
A more advanced use of the calibration data file might specify num experiments NE indicating
that there are multiple experiments. When multiple experiments are present, Dakota will expand the number of
residuals for the repeat measurement data and difference with the data accordingly. For example, if the user has
five experiments in the example above with three calibration terms, the calibration data file would need
to contain five rows (one for each experiment), and each row should contain three experimental data values that

2206

CHAPTER 6. KEYWORDS AREA

will be differenced with respect to the appropriate model response. In this example, NE = 5. To summarize,
Dakota will calculate the sum of the squared residuals as:
f=

NE
X

Ri2

i=1

where the residuals now are calculated as:

Ri = yiM odel () yiData .

annotated
Keywords Area
responses
calibration terms
calibration data file
annotated
Selects annotated tabular file format for experiment data

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
An annotated tabular file is a whitespace-separated text file with one leading header row of comments/column labels. For experiment data files, each subsequent row contains an experiment ID, followed by data for configuration
variables, observations, and/or observation errors, depending on context.
Default Behavior
By default, Dakota imports tabular experiment data files in annotated format. The annotated keyword can
be used to explicitly specify this.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

6.6. RESPONSES

2207

Examples
Import an annotated experimental data file containing a header row, leading exp id column, and experiment data
in a calibration study
responses
...
scalar_data_file shock_experiment.dat
annotated

Example data file with two measured quantities, three experiments:

%exp_id
velocity
stress
1
18.23
83.21
2
34.14
93.24
3
22.41
88.92

custom annotated
Keywords Area
responses
calibration terms
calibration data file
custom annotated
Selects custom-annotated tabular file format for experiment data

Topics
This keyword is related to the topics:
file formats

Specification
Alias: none
Argument(s): none
Default: annotated format
Required/Optional
Optional

Description of
Group

Dakota Keyword
header

Dakota Keyword
Description
Enable header row
in
custom-annotated
tabular file

2208

CHAPTER 6. KEYWORDS AREA

Optional

exp id

Enable experiment
ID column in
custom-annotated
tabular file

Description
A custom-annotated tabular file is a whitespace-separated text file containing experiment data, including configuration variables, observatiions, and/or observation errors, depending on context. For experiment import, customannotated allows user options for whether header row and exp id column appear in the tabular file, thus
bridging freeform and (fully) annotated.
Default Behavior
By default, Dakota imports tabular experiment data files in annotated format. The custom annotated
keyword, followed by options can be used to select other formats.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

Examples
Import an experimental data file containing a header row, no leading exp id column, and experiment data in a
calibration study
responses
...
scalar_data_file shock_experiment.dat
custom_annotated header

Example data file with two measured quantities, three experiments:

%

velocity
18.23
34.14
22.41

stress
83.21
93.24
88.92

header
Keywords Area
responses
calibration terms
calibration data file
custom annotated
header
Enable header row in custom-annotated tabular file

6.6. RESPONSES

Specification
Alias: none
Argument(s): none
Default: no header

Description
See description of parent custom annotated
exp id
Keywords Area
responses
calibration terms
calibration data file
custom annotated
exp id
Enable experiment ID column in custom-annotated tabular file

Specification
Alias: none
Argument(s): none
Default: no exp id column

Description
See description of parent custom annotated
freeform
Keywords Area
responses
calibration terms
calibration data file
freeform
Selects free-form tabular file format for experiment data

Topics
This keyword is related to the topics:
file formats

2209

2210

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none
Default: annotated format

Description
A freeform tabular file is whitespace-separated text file with no leading header row and no leading columns. For
experiment data files, each row contains data for configuration variables, observatiions, and/or observation errors,
depending on context.
Default Behavior
By default, Dakota imports tabular experiment data files in annotated format. Specify freeform to instead
select this format.
Usage Tips
Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to
annotated format, though freeform remains an option.
When importing tabular data, a warning will be generated if a specific number of data are expected, but
extra is found and an error generated when there is insufficient data.

Examples
Import a free-form experimental data file containing raw experiment data in a calibration study
responses
...
scalar_data_file shock_experiment.dat
freeform

Example data file with two measured quantities, three experiments:

18.23
34.14
22.41

83.21
93.24
88.92

num experiments
Keywords Area
responses
calibration terms
calibration data file
num experiments
Add context to data: number of different experiments

Specification
Alias: none
Argument(s): INTEGER
Default: 1

6.6. RESPONSES

2211

Description
The number of different experiments. Dakota will expand the total number of residual terms based on the number
of calibration terms and the number of experiments. For example, if the number of calibration terms are five
scalars, and there are three experiments, the total number of residuals in the least squares formulation will be 15.
See calibration data or calibration data file.
num config variables
Keywords Area
responses
calibration terms
calibration data file
num config variables
Add context to data: number of configuration variables.

Specification
Alias: none
Argument(s): INTEGER
Default: 0

Description
This is an optional description. If there are multiple experiments, there can be different configuration variables
(e.g. experimental settings, boundary conditions, etc.) per experiment. See calibration data or calibration datafile. Note: as of Dakota 6.2, configuration variables are not used. However, the intent is to treat them as state
variables which will be passed to the simulation, and not treated as parameters which are calibrated.
variance type
Keywords Area
responses
calibration terms
calibration data file
variance type
Add context to experiment data description by specifying the type of experimental error.

Specification
Alias: none
Argument(s): STRINGLIST
Default: none

2212

CHAPTER 6. KEYWORDS AREA

Description
There are four options for specifying the experimental error (e.g. the measurement error in the data you provide
for calibration purposes): none, scalar, diagonal, or matrix.
If the user specifies none, Dakota will calculate a variance (sigma-squared) term. This will be a constant
variance term across all of the data). If the user specifies scalar, they can provide a scalar variance per calibration
term. Note that for scalar calibration terms, only none or scalar are options for the measurement variance.
However, for field calibration terms, there are two additional options. diagonal allows the user to provide a
vector of measurement variances (one for each term in the calibration field). This vector corresponds to the
diagonal of the full covariance matrix of measurement errors. If the user specifies matrix, they can provide a
full covariance matrix (not just the diagonal terms), where each element(i,j) of the covariance matrix represents
the covariance of the measurement error between the i-th and j-th field values.
nonlinear inequality constraints
Keywords Area
responses
calibration terms
nonlinear inequality constraints
Group to specify nonlinear inequality constraints

Specification
Alias: num nonlinear inequality constraints
Argument(s): INTEGER
Default: 0
Required/Description of
Optional
Group
Optional

Dakota Keyword
lower bounds

Optional

upper bounds

Optional

scale types

Optional

scales

Dakota Keyword
Description
Specify minimum
values
Specify maximium
values
Choose how each
constraint is scaled
Characteristic
values for scaling

Description
The lower bounds and upper bounds specifications provide the lower and upper bounds for 2-sided nonlinear inequalities of the form
gl g(x) gu
The defaults for the inequality constraint bounds are selected so that one-sided inequalities of the form
g(x) 0.0
result when there are no user constraint bounds specifications (this provides backwards compatibility with previous Dakota versions).

6.6. RESPONSES

2213

In a user bounds specification, any upper bound values greater than +bigRealBoundSize (1.e+30, as
defined in Minimizer) are treated as +infinity and any lower bound values less than -bigRealBoundSize
are treated as -infinity. This feature is commonly used to drop one of the bounds in order to specify a 1-sided
constraint (just as the default lower bounds drop out since -DBL MAX < -bigRealBoundSize). The same
approach is used for nonexistent linear inequality bounds and for nonexistent design variable bounds.
The scale types and scales keywords are related to scaling of g (x). See the scaling keyword in the
method section for details.
lower bounds
Keywords Area
responses
calibration terms
nonlinear inequality constraints
lower bounds
Specify minimum values

Specification
Alias: nonlinear inequality lower bounds
Argument(s): REALLIST
Default: vector values = -infinity

Description
Specify minimum values
upper bounds
Keywords Area
responses
calibration terms
nonlinear inequality constraints
upper bounds
Specify maximium values

Specification
Alias: nonlinear inequality upper bounds
Argument(s): REALLIST
Default: vector values = 0 .

2214

CHAPTER 6. KEYWORDS AREA

Description
Specify maximium values
scale types
Keywords Area
responses
calibration terms
nonlinear inequality constraints
scale types
Choose how each constraint is scaled

Specification
Alias: nonlinear inequality scale types
Argument(s): STRINGLIST
Default: no scaling

Description
See the scaling keyword in the method section for details on how to use this keyword.
scales
Keywords Area
responses
calibration terms
nonlinear inequality constraints
scales
Characteristic values for scaling

Specification
Alias: nonlinear inequality scales
Argument(s): REALLIST
Default: 1.0 (no scaling)

Description
See the scaling keyword in the method section for details on how to use this keyword.

6.6. RESPONSES

2215

nonlinear equality constraints

Keywords Area
responses
calibration terms
nonlinear equality constraints
Group to specify nonlinear equality constraints

Specification
Alias: num nonlinear equality constraints
Argument(s): INTEGER
Default: 0
Required/Optional
Optional

Description of
Group

Dakota Keyword
targets

Optional

scale types

Optional

scales

Dakota Keyword
Description
Target values for
the nonlinear
equality constraint
Choose how each
constraint is scaled
Characteristic
values for scaling

Description
The targets specification provides the targets for nonlinear equalities of the form
g(x) = gt
and the defaults for the equality targets enforce a value of 0. for each constraint
g(x) = 0.0
The scale types and scales keywords are related to scaling of g (x). See the scaling keyword in the
method section for details.
targets
Keywords Area
responses
calibration terms
nonlinear equality constraints
targets
Target values for the nonlinear equality constraint

2216

CHAPTER 6. KEYWORDS AREA

Specification
Alias: nonlinear equality targets
Argument(s): REALLIST
Default: vector values = 0 .

Description
The targets specification provides the targets for nonlinear equalities of the form
g(x) = gt
and the defaults for the equality targets enforce a value of 0.0 for each constraint:
g(x) = 0.0

scale types
Keywords Area
responses
calibration terms
nonlinear equality constraints
scale types
Choose how each constraint is scaled

Specification
Alias: nonlinear equality scale types
Argument(s): STRINGLIST
Default: no scaling

Description
See the scaling keyword in the method section for details on how to use this keyword.
scales
Keywords Area
responses
calibration terms
nonlinear equality constraints
scales
Characteristic values for scaling

6.6. RESPONSES

2217

Specification
Alias: nonlinear equality scales
Argument(s): REALLIST
Default: 1.0 (no scaling)

Description
See the scaling keyword in the method section for details on how to use this keyword.

6.6.5

response functions

Keywords Area
responses
response functions
Generic response type

Specification
Alias: num response functions
Argument(s): INTEGER
Required/Optional
Optional
Optional

Description of
Group

Dakota Keyword
scalar responses
field responses

Dakota Keyword
Description
Number of scalar
response functions
Number of field
responses
functions

Description
A generic response data set is specified using response functions. Each of these functions is simply a
response quantity of interest with no special interpretation taken by the method in use.
Whereas objective, constraint, and residual functions have special meanings for optimization and least squares
algorithms, the generic response function data set need not have a specific interpretation and the user is free to
define whatever functional form is convenient.

Theory
This type of data set is used by uncertainty quantification methods, in which the effect of parameter uncertainty
on response functions is quantified, and can also be used in parameter study and design of experiments methods
(although these methods are not restricted to this data set), in which the effect of parameter variations on response
functions is evaluated.

2218

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
objective functions
calibration terms
scalar responses
Keywords Area
responses
response functions
scalar responses
Number of scalar response functions

Specification
Alias: num scalar responses
Argument(s): INTEGER

Description
This keyword describes the number of scalar response functions. It is meant to be used in conjunction with
field responses, which describes the number of field response functions. The total number of response
functions, both scalar and field, is given by response functions. If only scalar responses functions are
specified, it is not necessary to specify the number of scalar terms explicitly: one can simply say response functions = 5 and get 5 scalar responses. However, if there are three scalar responses and 2 field responses,
then response functions = 5 but scalar responses = 3 and field responses = 2.
This type of data set is used by uncertainty quantification methods, in which the effect of parameter uncertainty
on response functions is quantified, and can also be used in parameter study and design of experiments methods
(although these methods are not restricted to this data set), in which the effect of parameter variations on response
functions is evaluated.

See Also
These keywords may also be of interest:
field responses
field responses
Keywords Area
responses
response functions
field responses
Number of field responses functions

6.6. RESPONSES

2219

Specification
Alias: num field responses
Argument(s): INTEGER
Required/Optional
Required

Description of
Group

Dakota Keyword
lengths

Optional

num coordinates per field

Optional

read field coordinates

Dakota Keyword
Description
Lengths of field
responses
Number of
independent
coordinates for
field responses
Add context to
data: flag to
indicate that field
coordinates should
be read

Description
This keyword describes the number of field response functions. A field function is a set of related response
values collected over a range of independent coordinate values which may or may not be specified by the user.
For example, voltage over time would be a field function, where voltage is the field objective and time
is the independent coordinate. Similarly, temperature over time and space would be a field response, where the
independent coordinates would be both time and spatial coordinates such as (x,y) or (x,y,z), depending on the
application. The main difference between scalar responses and field responses is that for field data, we plan to
implement methods that take advantage of the correlation or relationship between the field values.
Note that if there is one field response, and it has length 100 (meaning 100 values), then the users
simulation code must return 100 values. Also, if there are both scalar and field responses, the user should specify
the number of scalar responses as scalar responses. If there are only field responses, it still is necessary to
specify both response functions = NN and field responses = NN, where NN is the number of field
responses.
This type of data set is used by uncertainty quantification methods, in which the effect of parameter uncertainty
on response functions is quantified, and can also be used in parameter study and design of experiments methods
(although these methods are not restricted to this data set), in which the effect of parameter variations on response
functions is evaluated. Currently, field response functions will be translated back to scalar responses. So, a field
of length 100 will be treated as 100 separate scalar responses. However, in future versions of Dakota, we plan to
implement methods which can exploit the nature of field data.

See Also
These keywords may also be of interest:
scalar responses
lengths
Keywords Area
responses
response functions

2220

CHAPTER 6. KEYWORDS AREA

field responses
lengths
Lengths of field responses

Specification
Alias: none
Argument(s): INTEGERLIST

Description
This keyword describes the lengths of each field response. It is an integer vector of length field responses.
For example, if the field responses = 2, an example would be lengths = 50 200, indicating that the first
field response has 50 field elements but the second one has 200. The coordinate values (e.g. the independent
variables) corresponding to these field responses are read in files labeled response descriptor.coords.

See Also
These keywords may also be of interest:
field responses
num coordinates per field
Keywords Area
responses
response functions
field responses
num coordinates per field
Number of independent coordinates for field responses

Specification
Alias: none
Argument(s): INTEGERLIST

Description
This keyword describes the number of independent coordinates for each field response. It is an integer vector
of length field responses. For example, if the field responses = 2, an example would be num coordinates per field = 2 1 means that the first field response has two sets of independent coordinates
(perhaps x, y locations), but the second response only has one (for example, time where the field response is
only dependent upon time). The actual coordinate values (e.g. the independent variables) corresponding to these
field responses are defined in a file call response descriptor.coords, where response descriptor is the name of the
individual field.

6.6. RESPONSES

2221

See Also
These keywords may also be of interest:
field responses
read field coordinates
Keywords Area
responses
response functions
field responses
read field coordinates
Add context to data: flag to indicate that field coordinates should be read

Specification
Alias: none
Argument(s): none

Description
Field coordinates specify independent variables (e.g. spatial or temporal coordinates) upon which the field depends. For example, the voltage level above might be a function of time, so time is the field coordinate. If the
user has field coordinates to read, they need to specify read field coordinates. The field coordinates
will then be read from a file named response descriptor.coords, where response descriptor is the user-provided
descriptor for the field response. The number of columns in the coords file should be equal to the number of field
coordinates.

6.6.6

no gradients

Keywords Area
responses
no gradients
Gradients will not be used

Specification
Alias: none
Argument(s): none

Description
The no gradients specification means that gradient information is not needed in the study. Therefore, it will
neither be retrieved from the simulation nor computed with finite differences. The no gradients keyword is a
complete specification for this case.

2222

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
numerical gradients
analytic gradients
mixed gradients

6.6.7

analytic gradients

Keywords Area
responses
analytic gradients
Analysis driver will return gradients

Specification
Alias: none
Argument(s): none

Description
The analytic gradients specification means that gradient information is available directly from the simulation (finite differencing is not required). The simulation must return the gradient data in the Dakota format
(enclosed in single brackets; see Dakota File Data Formats in the Users Manual[4]) for the case of file transfer of
data. The analytic gradients keyword is a complete specification for this case.

See Also
These keywords may also be of interest:
numerical gradients
no gradients
mixed gradients

6.6.8

mixed gradients

Keywords Area
responses
mixed gradients
Gradients are needed and will be obtained from a mix of numerical and analytic sources

Specification
Alias: none
Argument(s): none

6.6. RESPONSES

2223
Required/Optional
Required

Description of
Group

Dakota Keyword
id numerical gradients

Required

id analytic gradients

Optional

method source

Optional(Choose
One)

Group 1

dakota

vendor
Optional

Optional(Choose
One)

interval type

Group 2

forward
central

Optional

fd step size

Dakota Keyword
Description
Identify which
numerical gradient
corresponds to
which response
Identify which
analytical gradient
corresponds to
which response
Specify which
finite difference
routine is used
(Default) Use
internal Dakota
finite differences
algorithm
Use non-Dakota fd
algorithm
Specify how to
compute gradients
and hessians
Use forward
differences
Use central
differences
Step size used
when computing
gradients and
Hessians

Description
The mixed gradients specification means that some gradient information is available directly from the simulation (analytic) whereas the rest will have to be finite differenced (numerical). This specification allows the user
to make use of as much analytic gradient information as is available and then finite difference for the rest.
The method source, interval type, and fd gradient step size specifications pertain to those
functions listed by the id numerical gradients list.

Examples
For example, the objective function may be a simple analytic function of the design variables (e.g., weight)
whereas the constraints are nonlinear implicit functions of complex analyses (e.g., maximum stress).

See Also
These keywords may also be of interest:
numerical gradients
no gradients

2224

CHAPTER 6. KEYWORDS AREA

analytic gradients
id numerical gradients
Keywords Area
responses
mixed gradients
id numerical gradients
Identify which numerical gradient corresponds to which response

Topics
This keyword is related to the topics:
objective function pointer

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The id analytic gradients list specifies by number the functions which have analytic gradients, and the
id numerical gradients list specifies by number the functions which must use numerical gradients. Each
function identifier, from 1 through the total number of functions, must appear once and only once within the union
of the id analytic gradients and id numerical gradients lists.

See Also
These keywords may also be of interest:
id analytic gradients
id analytic gradients
Keywords Area
responses
mixed gradients
id analytic gradients
Identify which analytical gradient corresponds to which response

Topics
This keyword is related to the topics:
objective function pointer

6.6. RESPONSES

2225

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The id analytic gradients list specifies by number the functions which have analytic gradients, and the
id numerical gradients list specifies by number the functions which must use numerical gradients. Each
function identifier, from 1 through the total number of functions, must appear once and only once within the union
of the id analytic gradients and id numerical gradients lists.

See Also
These keywords may also be of interest:
id numerical gradients
method source
Keywords Area
responses
mixed gradients
method source
Specify which finite difference routine is used

Specification
Alias: none
Argument(s): none
Default: dakota

Description
The method source setting specifies the source of the finite differencing routine that will be used to compute
the numerical gradients:
dakota (default)
vendor
dakota denotes Dakotas internal finite differencing algorithm and vendor denotes the finite differencing algorithm supplied by the iterator package in use (DOT, CONMIN, NPSOL, NL2SOL, NLSSOL, and OPT++ each
have their own internal finite differencing routines). The dakota routine is the default since it can execute in parallel and exploit the concurrency in finite difference evaluations (see Exploiting Parallelism in the Users Manual
[4]).
However, the vendor setting can be desirable in some cases since certain libraries will modify their algorithm
when the finite differencing is performed internally. Since the selection of the dakota routine hides the use of
finite differencing from the optimizers (the optimizers are configured to accept user-supplied gradients, which

2226

CHAPTER 6. KEYWORDS AREA

some algorithms assume to be of analytic accuracy), the potential exists for the vendor setting to trigger the
use of an algorithm more optimized for the higher expense and/or lower accuracy of finite-differencing. For
example, NPSOL uses gradients in its line search when in user-supplied gradient mode (since it assumes they are
inexpensive), but uses a value-based line search procedure when internally finite differencing. The use of a valuebased line search will often reduce total expense in serial operations. However, in parallel operations, the use of
gradients in the NPSOL line search (user-supplied gradient mode) provides excellent load balancing without need
to resort to speculative optimization approaches.
In summary, then, the dakota routine is preferred for parallel optimization, and the vendor routine may be
preferred for serial optimization in special cases.
dakota
Keywords Area
responses
mixed gradients
dakota
(Default) Use internal Dakota finite differences algorithm

Specification
Alias: none
Argument(s): none
Default: relative
Required/Optional
Optional

Optional(Choose
One)

Description of
Group

Dakota Keyword
ignore bounds

relative
Group 1
absolute
bounds

Dakota Keyword
Description
Do not respect
bounds when
computing
gradients or
Hessians
Scale step size by
the parameter
value
Do not scale
step-size
Scale step-size by
the domain of the
parameter

Description
The dakota routine is the default since it can execute in parallel and exploit the concurrency in finite difference
evaluations (see Exploiting Parallelism in the Users Manual [4]).
When the method source is dakota, the user may also specify the type of scaling desired when determining the finite difference step size. The choices are absolute, bounds, and relative. For absolute,
the step size will be applied as is. For bounds, it will be scaled by the range of each parameter. For relative,
it will be scaled by the parameter value.

6.6. RESPONSES

2227

ignore bounds
Keywords Area
responses
mixed gradients
dakota
ignore bounds
Do not respect bounds when computing gradients or Hessians

Specification
Alias: none
Argument(s): none
Default: bounds respected

Description
When Dakota computes gradients or Hessians by finite differences and the variables in question have bounds,
it by default chooses finite-differencing steps that keep the variables within their specified bounds. Older versions of Dakota generally ignored bounds when computing finite differences. To restore the older behavior, one
can add keyword ignore bounds to the response specification when method source dakota (or just
dakota) is also specified.
In forward difference or backward difference computations, honoring bounds is straightforward.
To honor bounds when approximating f /xi , i.e., component i of the gradient of f , by central differences,
Dakota chooses two steps h1 and h2 with h1 6= h2 , such that x + h1 ei and x + h2 ei both satisfy the bounds, and
then computes
f h22 (f1 f0 ) h21 (f2 f0 )
,
=
xi
h1 h2 (h2 h1 )
with f0 = f (x), f1 = f (x + h1 ei ), and f2 = f (x + h2 ei ).
relative
Keywords Area
responses
mixed gradients
dakota
relative
Scale step size by the parameter value

Specification
Alias: none
Argument(s): none

2228

Description
Scale step size by the parameter value
absolute
Keywords Area
responses
mixed gradients
dakota
absolute
Do not scale step-size

Specification
Alias: none
Argument(s): none
Default: relative

Description
Do not scale step-size
bounds
Keywords Area
responses
mixed gradients
dakota
bounds
Scale step-size by the domain of the parameter

Specification
Alias: none
Argument(s): none

Description
Scale step-size by the domain of the parameter

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2229

vendor
Keywords Area
responses
mixed gradients
vendor
Use non-Dakota fd algorithm

Specification
Alias: none
Argument(s): none

Description
See parent page for usage notes.
interval type
Keywords Area
responses
mixed gradients
interval type
Specify how to compute gradients and hessians

Specification
Alias: none
Argument(s): none
Default: forward

Description
The interval type setting is used to select between forward and central differences in the numerical
gradient calculations. The dakota, DOT vendor, and OPT++ vendor routines have both forward and central
differences available, the CONMIN and NL2SOL vendor routines support forward differences only, and the NPSOL and NLSSOL vendor routines start with forward differences and automatically switch to central differences
as the iteration progresses (the user has no control over this). The following forward difference expression
f (x + hei ) f (x)
f (x)
=
h
and the following central difference expression
f (x)
=

f (x + hei ) f (x hei )
2h

are used to estimate the ith component of the gradient vector.

2230
forward
Keywords Area
responses
mixed gradients
forward
Use forward differences

Specification
Alias: none
Argument(s): none
Default: forward

Description
See parent page for usage notes.
central
Keywords Area
responses
mixed gradients
central
Use central differences

Specification
Alias: none
Argument(s): none

Description
See parent page for usage notes.
fd step size
Keywords Area
responses
mixed gradients
fd step size
Step size used when computing gradients and Hessians

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2231

Specification
Alias: fd gradient step size
Argument(s): REALLIST
Default: 0.001

Description
fd gradient step size specifies the relative finite difference step size to be used in the computations. Either
a single value may be entered for use with all parameters, or a list of step sizes may be entered, one for each
parameter.
The latter option of a list of step sizes is only valid for use with the Dakota finite differencing routine. For
Dakota with an interval scaling type of absolute, the differencing interval will be fd gradient step size.
For Dakota with and interval scaling type of bounds, the differencing intervals are computed by multiplying fd gradient step size with the range of the parameter. For Dakota (with an interval scaling type of
relative), DOT, CONMIN, and OPT++, the differencing intervals are computed by multiplying the fd gradient step size with the current parameter value. In this case, a minimum absolute differencing interval is needed when the current parameter value is close to zero. This prevents finite difference intervals for
the parameter which are too small to distinguish differences in the response quantities being computed. Dakota,
DOT, CONMIN, and OPT++ all use .01fd gradient step size as their minimum absolute differencing interval. With a fd gradient step size = .001, for example, Dakota, DOT, CONMIN, and OPT++
will use intervals of .001current value with a minimum interval of 1.e-5. NPSOL and NLSSOL use a different formula for their finite difference intervals: fd gradient step size(1+|current parameter
value|). This definition has the advantage of eliminating the need for a minimum absolute differencing interval
since the interval no longer goes to zero as the current parameter value goes to zero.

6.6.9

numerical gradients

Keywords Area
responses
numerical gradients
Gradients are needed and will be approximated by finite differences

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
method source

Dakota Keyword
Description
Specify which
finite difference
routine is used

2232

CHAPTER 6. KEYWORDS AREA

Optional(Choose
One)

Group 1

dakota

vendor
Optional

Optional(Choose
One)

interval type

Group 2

forward
central

Optional

fd step size

(Default) Use
internal Dakota
finite differences
algorithm
Use non-Dakota fd
algorithm
Specify how to
compute gradients
and hessians
Use forward
differences
Use central
differences
Step size used
when computing
gradients and
Hessians

Description
The numerical gradients specification means that gradient information is needed and will be computed
with finite differences using either the native or one of the vendor finite differencing routines.

See Also
These keywords may also be of interest:
no gradients
analytic gradients
mixed gradients
method source
Keywords Area
responses
numerical gradients
method source
Specify which finite difference routine is used

Specification
Alias: none
Argument(s): none
Default: dakota

6.6. RESPONSES

2233

Description
The method source setting specifies the source of the finite differencing routine that will be used to compute
the numerical gradients:
dakota (default)
vendor
dakota denotes Dakotas internal finite differencing algorithm and vendor denotes the finite differencing algorithm supplied by the iterator package in use (DOT, CONMIN, NPSOL, NL2SOL, NLSSOL, and OPT++ each
have their own internal finite differencing routines). The dakota routine is the default since it can execute in parallel and exploit the concurrency in finite difference evaluations (see Exploiting Parallelism in the Users Manual
[4]).
However, the vendor setting can be desirable in some cases since certain libraries will modify their algorithm
when the finite differencing is performed internally. Since the selection of the dakota routine hides the use of
finite differencing from the optimizers (the optimizers are configured to accept user-supplied gradients, which
some algorithms assume to be of analytic accuracy), the potential exists for the vendor setting to trigger the
use of an algorithm more optimized for the higher expense and/or lower accuracy of finite-differencing. For
example, NPSOL uses gradients in its line search when in user-supplied gradient mode (since it assumes they are
inexpensive), but uses a value-based line search procedure when internally finite differencing. The use of a valuebased line search will often reduce total expense in serial operations. However, in parallel operations, the use of
gradients in the NPSOL line search (user-supplied gradient mode) provides excellent load balancing without need
to resort to speculative optimization approaches.
In summary, then, the dakota routine is preferred for parallel optimization, and the vendor routine may be
preferred for serial optimization in special cases.

dakota
Keywords Area
responses
numerical gradients
dakota
(Default) Use internal Dakota finite differences algorithm

Specification
Alias: none
Argument(s): none
Default: relative

2234

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Optional(Choose
One)

Description of
Group

Dakota Keyword
ignore bounds

relative
Group 1
absolute
bounds

Dakota Keyword
Description
Do not respect
bounds when
computing
gradients or
Hessians
Scale step size by
the parameter
value
Do not scale
step-size
Scale step-size by
the domain of the
parameter

Description
The dakota routine is the default since it can execute in parallel and exploit the concurrency in finite difference
evaluations (see Exploiting Parallelism in the Users Manual [4]).
When the method source is dakota, the user may also specify the type of scaling desired when determining the finite difference step size. The choices are absolute, bounds, and relative. For absolute,
the step size will be applied as is. For bounds, it will be scaled by the range of each parameter. For relative,
it will be scaled by the parameter value.
ignore bounds
Keywords Area
responses
numerical gradients
dakota
ignore bounds
Do not respect bounds when computing gradients or Hessians

Specification
Alias: none
Argument(s): none
Default: bounds respected

Description
When Dakota computes gradients or Hessians by finite differences and the variables in question have bounds,
it by default chooses finite-differencing steps that keep the variables within their specified bounds. Older versions of Dakota generally ignored bounds when computing finite differences. To restore the older behavior, one
can add keyword ignore bounds to the response specification when method source dakota (or just
dakota) is also specified.

6.6. RESPONSES

2235

In forward difference or backward difference computations, honoring bounds is straightforward.

To honor bounds when approximating f /xi , i.e., component i of the gradient of f , by central differences,
Dakota chooses two steps h1 and h2 with h1 6= h2 , such that x + h1 ei and x + h2 ei both satisfy the bounds, and
then computes
f h22 (f1 f0 ) h21 (f2 f0 )
,
=
xi
h1 h2 (h2 h1 )
with f0 = f (x), f1 = f (x + h1 ei ), and f2 = f (x + h2 ei ).
relative
Keywords Area
responses
numerical gradients
dakota
relative
Scale step size by the parameter value

Specification
Alias: none
Argument(s): none

Description
Scale step size by the parameter value
absolute
Keywords Area
responses
numerical gradients
dakota
absolute
Do not scale step-size

Specification
Alias: none
Argument(s): none
Default: relative

Description
Do not scale step-size

2236
bounds
Keywords Area
responses
numerical gradients
dakota
bounds
Scale step-size by the domain of the parameter

Specification
Alias: none
Argument(s): none

Description
Scale step-size by the domain of the parameter
vendor
Keywords Area
responses
numerical gradients
vendor
Use non-Dakota fd algorithm

Specification
Alias: none
Argument(s): none

Description
See parent page for usage notes.
interval type
Keywords Area
responses
numerical gradients
interval type
Specify how to compute gradients and hessians

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2237

Specification
Alias: none
Argument(s): none
Default: forward

Description
The interval type setting is used to select between forward and central differences in the numerical
gradient calculations. The dakota, DOT vendor, and OPT++ vendor routines have both forward and central
differences available, the CONMIN and NL2SOL vendor routines support forward differences only, and the NPSOL and NLSSOL vendor routines start with forward differences and automatically switch to central differences
as the iteration progresses (the user has no control over this). The following forward difference expression
f (x + hei ) f (x)
f (x)
=
h
and the following central difference expression
f (x + hei ) f (x hei )
f (x)
=
2h
are used to estimate the ith component of the gradient vector.
forward
Keywords Area
responses
numerical gradients
forward
Use forward differences

Specification
Alias: none
Argument(s): none
Default: forward

Description
See parent page for usage notes.
central
Keywords Area
responses
numerical gradients
central
Use central differences

2238

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
See parent page for usage notes.
fd step size
Keywords Area
responses
numerical gradients
fd step size
Step size used when computing gradients and Hessians

Specification
Alias: fd gradient step size
Argument(s): REALLIST
Default: 0.001

Description
fd gradient step size specifies the relative finite difference step size to be used in the computations. Either
a single value may be entered for use with all parameters, or a list of step sizes may be entered, one for each
parameter.
The latter option of a list of step sizes is only valid for use with the Dakota finite differencing routine. For
Dakota with an interval scaling type of absolute, the differencing interval will be fd gradient step size.
For Dakota with and interval scaling type of bounds, the differencing intervals are computed by multiplying fd gradient step size with the range of the parameter. For Dakota (with an interval scaling type of
relative), DOT, CONMIN, and OPT++, the differencing intervals are computed by multiplying the fd gradient step size with the current parameter value. In this case, a minimum absolute differencing interval is needed when the current parameter value is close to zero. This prevents finite difference intervals for
the parameter which are too small to distinguish differences in the response quantities being computed. Dakota,
DOT, CONMIN, and OPT++ all use .01fd gradient step size as their minimum absolute differencing interval. With a fd gradient step size = .001, for example, Dakota, DOT, CONMIN, and OPT++
will use intervals of .001current value with a minimum interval of 1.e-5. NPSOL and NLSSOL use a different formula for their finite difference intervals: fd gradient step size(1+|current parameter
value|). This definition has the advantage of eliminating the need for a minimum absolute differencing interval
since the interval no longer goes to zero as the current parameter value goes to zero.

6.6. RESPONSES

6.6.10

2239

no hessians

Keywords Area
responses
no hessians
Hessians will not be used

Specification
Alias: none
Argument(s): none

Description
The no hessians specification means that the method does not require Dakota to manage the computation of
any Hessian information. Therefore, it will neither be retrieved from the simulation nor computed by Dakota. The
no hessians keyword is a complete specification for this case. Note that, in some cases, Hessian information
may still be being approximated internal to an algorithm (e.g., within a quasi-Newton optimizer such as optppq newton); however, Dakota has no direct involvement in this process and the responses specification need not
include it.

See Also
These keywords may also be of interest:
numerical hessians
quasi hessians
analytic hessians
mixed hessians

6.6.11

numerical hessians

Keywords Area
responses
numerical hessians
Hessians are needed and will be approximated by finite differences

Specification
Alias: none
Argument(s): none

2240

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
fd step size

Optional(Choose
One)

relative
Group 1
absolute
bounds

Optional(Choose
One)

difference
interval (Group 2)

forward
central

Dakota Keyword
Description
Step size used
when computing
gradients and
Hessians
Scale step size by
the parameter
value
Do not scale
step-size
Scale step-size by
the domain of the
parameter
Use forward
differences
Use central
differences

Description
The numerical hessians specification means that Hessian information is needed and will be computed with
finite differences using either first-order gradient differencing (for the cases of analytic gradients or for
the functions identified by id analytic gradients in the case of mixed gradients) or first- or secondorder function value differencing (all other gradient specifications). In the former case, the following expression
f (x + hei ) f (x)
2 f (x)i
=
h
estimates the ith Hessian column, and in the latter case, the following expressions
f (x + hi ei + hj ej ) f (x + hi ei ) f (x hj ej ) + f (x)
2 f (x)i,j
=
hi hj
and
f (x + hei + hej ) f (x + hei hej ) f (x hei + hej ) + f (x hei hej )
2 f (x)i,j
=
4h2
provide first- and second-order estimates of the ij th Hessian term. Prior to Dakota 5.0, Dakota always used
second-order estimates. In Dakota 5.0 and newer, the default is to use first-order estimates (which honor bounds
on the variables and require only about a quarter as many function evaluations as do the second-order estimates),
but specifying central after numerical hessians causes Dakota to use the old second-order estimates,
which do not honor bounds. In optimization algorithms that use Hessians, there is little reason to use second-order
differences in computing Hessian approximations.

See Also
These keywords may also be of interest:
no hessians
quasi hessians

6.6. RESPONSES

2241

analytic hessians
mixed hessians
fd step size
Keywords Area
responses
numerical hessians
fd step size
Step size used when computing gradients and Hessians

Specification
Alias: fd hessian step size
Argument(s): REALLIST
Default: 0.001 (forward), 0.002 (central)

Description
fd gradient step size specifies the relative finite difference step size to be used in the computations. Either
a single value may be entered for use with all parameters, or a list of step sizes may be entered, one for each
parameter.
The latter option of a list of step sizes is only valid for use with the Dakota finite differencing routine. For
Dakota with an interval scaling type of absolute, the differencing interval will be fd gradient step size.
For Dakota with and interval scaling type of bounds, the differencing intervals are computed by multiplying fd gradient step size with the range of the parameter. For Dakota (with an interval scaling type of
relative), DOT, CONMIN, and OPT++, the differencing intervals are computed by multiplying the fd gradient step size with the current parameter value. In this case, a minimum absolute differencing interval is needed when the current parameter value is close to zero. This prevents finite difference intervals for
the parameter which are too small to distinguish differences in the response quantities being computed. Dakota,
DOT, CONMIN, and OPT++ all use .01fd gradient step size as their minimum absolute differencing interval. With a fd gradient step size = .001, for example, Dakota, DOT, CONMIN, and OPT++
will use intervals of .001current value with a minimum interval of 1.e-5. NPSOL and NLSSOL use a different formula for their finite difference intervals: fd gradient step size(1+|current parameter
value|). This definition has the advantage of eliminating the need for a minimum absolute differencing interval
since the interval no longer goes to zero as the current parameter value goes to zero.
relative
Keywords Area
responses
numerical hessians
relative
Scale step size by the parameter value

2242

Specification
Alias: none
Argument(s): none

Description
Scale step size by the parameter value
absolute
Keywords Area
responses
numerical hessians
absolute
Do not scale step-size

Specification
Alias: none
Argument(s): none
Default: relative

Description
Do not scale step-size
bounds
Keywords Area
responses
numerical hessians
bounds
Scale step-size by the domain of the parameter

Specification
Alias: none
Argument(s): none

Description
Scale step-size by the domain of the parameter

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2243

forward
Keywords Area
responses
numerical hessians
forward
Use forward differences

Specification
Alias: none
Argument(s): none
Default: forward

Description
See parent page for usage notes.
central
Keywords Area
responses
numerical hessians
central
Use central differences

Specification
Alias: none
Argument(s): none

Description
See parent page for usage notes.

6.6.12

quasi hessians

Keywords Area
responses
quasi hessians
Hessians are needed and will be approximated by secant updates (BFGS or SR1) from a series of gradient
evaluations

2244

Specification
Alias: none
Argument(s): none

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2245
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
bfgs

sr1

Dakota Keyword
Description
Use BFGS method
to compute
quasi-hessians
Use the Symmetric
Rank 1 update
method to compute
quasi-Hessians

Description
The quasi hessians specification means that Hessian information is needed and will be approximated using
secant updates (sometimes called quasi-Newton updates, though any algorithm that approximates Newtons
method is a quasi-Newton method).
Compared to finite difference numerical Hessians, secant approximations do not expend additional function
evaluations in estimating all of the second-order information for every point of interest. Rather, they accumulate
approximate curvature information over time using the existing gradient evaluations.
The supported secant approximations include the Broyden-Fletcher-Goldfarb-Shanno (BFGS) update (specified with the keyword bfgs) and the Symmetric Rank 1 (SR1) update (specified with the keyword sr1).

See Also
These keywords may also be of interest:
no hessians
numerical hessians
analytic hessians
mixed hessians
bfgs
Keywords Area
responses
quasi hessians
bfgs
Use BFGS method to compute quasi-hessians

Specification
Alias: none
Argument(s): none

2246

CHAPTER 6. KEYWORDS AREA

Required/Optional
Optional

Description of
Group

Dakota Keyword
damped

Dakota Keyword
Description
Numerical
safeguarding for
BFGS updates

Description
Broyden-Fletcher-Goldfarb-Shanno (BFGS) update will be used to compute quasi-Hessians.
Bk+1 = Bk

yk ykT
Bk sk sTk Bk
+
sTk Bk sk
ykT sk

where Bk is the k th approximation to the Hessian, sk = xk+1 xk is the step and yk = fk+1 fk is the
corresponding yield in the gradients.
Notes
Initial scaling of

T
yk
yk
Ts I
yk
k

is used for B0 prior to the first update.

Numerical safeguarding is used to protect against numerically small denominators within the updates.
This safeguarding skips the update if |ykT sk | < 106 sTk Bk sk
Additional safeguarding can be added using the damped option, which utilizes an alternative damped BFGS update when the curvature condition ykT sk > 0 is nearly violated.
damped
Keywords Area
responses
quasi hessians
bfgs
damped
Numerical safeguarding for BFGS updates

Specification
Alias: none
Argument(s): none
Default: undamped BFGS

Description
See parent page.

6.6. RESPONSES

2247

sr1
Keywords Area
responses
quasi hessians
sr1
Use the Symmetric Rank 1 update method to compute quasi-Hessians

Specification
Alias: none
Argument(s): none

Description
The Symmetric Rank 1 (SR1) update (specified with the keyword sr1) will be used to compute quasi-Hessians.
Bk+1 = Bk +

(yk Bk sk )(yk Bk sk )T
(yk Bk sk )T sk

where Bk is the k th approximation to the Hessian, sk = xk+1 xk is the step and yk = fk+1 fk is the
corresponding yield in the gradients.
Notes
Initial scaling of

T
yk
yk
Ts I
yk
k

is used for B0 prior to the first update.

Numerical safeguarding is used to protect against numerically small denominators within the updates.
This safeguarding skips the update if |(yk Bk sk )T sk | < 106 ||sk ||2 ||yk Bk sk ||2

6.6.13

analytic hessians

Keywords Area
responses
analytic hessians
Hessians are needed and are available directly from the analysis driver

Specification
Alias: none
Argument(s): none

Description
The analytic hessians specification means that Hessian information is available directly from the simulation. The simulation must return the Hessian data in the Dakota format (enclosed in double brackets; see Dakota
File Data Formats in Users Manual [4]) for the case of file transfer of data. The analytic hessians keyword
is a complete specification for this case.

2248

CHAPTER 6. KEYWORDS AREA

See Also
These keywords may also be of interest:
no hessians
numerical hessians
quasi hessians
mixed hessians

6.6.14

mixed hessians

Keywords Area
responses
mixed hessians
Hessians are needed and will be obtained from a mix of numerical, analytic, and quasi sources

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Optional(Choose
One)

Description of
Group

Dakota Keyword
id numerical hessians

relative
Group 1
absolute
bounds

Optional(Choose
One)

difference
interval (Group 2)

forward
central

Optional

id quasi hessians

Dakota Keyword
Description
Identify which
numerical-Hessian
corresponds to
which response
Scale step size by
the parameter
value
Do not scale
step-size
Scale step-size by
the domain of the
parameter
Use forward
differences
Use central
differences
Identify which
quasi-Hessian
corresponds to
which response

6.6. RESPONSES

2249
Optional

id analytic hessians

Identify which
analytical Hessian
corresponds to
which response

Description
Hessian availability must be specified with either no hessians, numerical hessians, quasi hessians,
analytic hessians, or mixed hessians.
The mixed hessians specification means that some Hessian information is available directly from the
simulation (analytic) whereas the rest will have to be estimated by finite differences (numerical) or approximated
by secant updating. As for mixed gradients, this specification allows the user to make use of as much analytic
information as is available and then estimate/approximate the rest.
The id analytic hessians list specifies by number the functions which have analytic Hessians, and
the id numerical hessians and id quasi hessians lists specify by number the functions which must
use numerical Hessians and secant Hessian updates, respectively. Each function identifier, from 1 through the
total number of functions, must appear once and only once within the union of the id analytic hessians,
id numerical hessians, and id quasi hessians lists.
The fd hessian step size and bfgs, damped bfgs, or sr1 secant update selections are as described previously in responses and pertain to those functions listed by the id numerical hessians and
id quasi hessians lists.

See Also
These keywords may also be of interest:
no hessians
numerical hessians
quasi hessians
analytic hessians
id numerical hessians
Keywords Area
responses
mixed hessians
id numerical hessians
Identify which numerical-Hessian corresponds to which response

Topics
This keyword is related to the topics:
objective function pointer

2250

Specification
Alias: none
Argument(s): INTEGERLIST

CHAPTER 6. KEYWORDS AREA

6.6. RESPONSES

2251
Required/Optional
Optional

Description of
Group

Dakota Keyword
fd step size

Dakota Keyword
Description
Step size used
when computing
gradients and
Hessians

Description
The id analytic hessians list specifies by number the functions which have analytic Hessians, and the
id numerical hessians and id quasi hessians lists specify by number the functions which must use
numerical Hessians and secant Hessian updates, respectively. Each function identifier, from 1 through the total
number of functions, must appear once and only once within the union of the id analytic hessians, id numerical hessians, and id quasi hessians lists.

See Also
These keywords may also be of interest:
id analytic hessians
id quasi hessians
fd step size
Keywords Area
responses
mixed hessians
id numerical hessians
fd step size
Step size used when computing gradients and Hessians

Specification
Alias: fd hessian step size
Argument(s): REALLIST
Default: 0.001 (forward), 0.002 (central)

Description
fd gradient step size specifies the relative finite difference step size to be used in the computations. Either
a single value may be entered for use with all parameters, or a list of step sizes may be entered, one for each
parameter.
The latter option of a list of step sizes is only valid for use with the Dakota finite differencing routine. For
Dakota with an interval scaling type of absolute, the differencing interval will be fd gradient step size.
For Dakota with and interval scaling type of bounds, the differencing intervals are computed by multiplying fd gradient step size with the range of the parameter. For Dakota (with an interval scaling type of

2252

CHAPTER 6. KEYWORDS AREA

relative), DOT, CONMIN, and OPT++, the differencing intervals are computed by multiplying the fd gradient step size with the current parameter value. In this case, a minimum absolute differencing interval is needed when the current parameter value is close to zero. This prevents finite difference intervals for
the parameter which are too small to distinguish differences in the response quantities being computed. Dakota,
DOT, CONMIN, and OPT++ all use .01fd gradient step size as their minimum absolute differencing interval. With a fd gradient step size = .001, for example, Dakota, DOT, CONMIN, and OPT++
will use intervals of .001current value with a minimum interval of 1.e-5. NPSOL and NLSSOL use a different formula for their finite difference intervals: fd gradient step size(1+|current parameter
value|). This definition has the advantage of eliminating the need for a minimum absolute differencing interval
since the interval no longer goes to zero as the current parameter value goes to zero.
relative
Keywords Area
responses
mixed hessians
relative
Scale step size by the parameter value

Specification
Alias: none
Argument(s): none

Description
Scale step size by the parameter value
absolute
Keywords Area
responses
mixed hessians
absolute
Do not scale step-size

Specification
Alias: none
Argument(s): none
Default: relative

Description
Do not scale step-size

6.6. RESPONSES
bounds
Keywords Area
responses
mixed hessians
bounds
Scale step-size by the domain of the parameter

Specification
Alias: none
Argument(s): none

Description
Scale step-size by the domain of the parameter
forward
Keywords Area
responses
mixed hessians
forward
Use forward differences

Specification
Alias: none
Argument(s): none
Default: forward

Description
See parent page for usage notes.
central
Keywords Area
responses
mixed hessians
central
Use central differences

2253

2254

CHAPTER 6. KEYWORDS AREA

Specification
Alias: none
Argument(s): none

Description
See parent page for usage notes.
id quasi hessians
Keywords Area
responses
mixed hessians
id quasi hessians
Identify which quasi-Hessian corresponds to which response

Topics
This keyword is related to the topics:
objective function pointer

Specification
Alias: none
Argument(s): INTEGERLIST
Required/Optional
Required(Choose
One)

Description of
Group
Group 1

Dakota Keyword
bfgs

sr1

Dakota Keyword
Description
Use BFGS method
to compute
quasi-hessians
Use the Symmetric
Rank 1 update
method to compute
quasi-Hessians

Description
The id analytic hessians list specifies by number the functions which have analytic Hessians, and the
id numerical hessians and id quasi hessians lists specify by number the functions which must use
numerical Hessians and secant Hessian updates, respectively. Each function identifier, from 1 through the total
number of functions, must appear once and only once within the union of the id analytic hessians, id numerical hessians, and id quasi hessians lists.

6.6. RESPONSES

2255

See Also
These keywords may also be of interest:
id numerical hessians
id analytic hessians
bfgs
Keywords Area
responses
mixed hessians
id quasi hessians
bfgs
Use BFGS method to compute quasi-hessians

Specification
Alias: none
Argument(s): none
Required/Optional
Optional

Description of
Group

Dakota Keyword
damped

Dakota Keyword
Description
Numerical
safeguarding for
BFGS updates

Description
Broyden-Fletcher-Goldfarb-Shanno (BFGS) update will be used to compute quasi-Hessians.
Bk+1 = Bk

Bk sk sTk Bk
yk ykT
+
sTk Bk sk
ykT sk

where Bk is the k th approximation to the Hessian, sk = xk+1 xk is the step and yk = fk+1 fk is the
corresponding yield in the gradients.
Notes
Initial scaling of

T
yk
yk
Ts I
yk
k

is used for B0 prior to the first update.

Numerical safeguarding is used to protect against numerically small denominators within the updates.
This safeguarding skips the update if |ykT sk | < 106 sTk Bk sk
Additional safeguarding can be added using the damped option, which utilizes an alternative damped BFGS update when the curvature condition ykT sk > 0 is nearly violated.

2256

CHAPTER 6. KEYWORDS AREA

damped
Keywords Area
responses
mixed hessians
id quasi hessians
bfgs
damped
Numerical safeguarding for BFGS updates

Specification
Alias: none
Argument(s): none
Default: undamped BFGS

Description
See parent page.
sr1
Keywords Area
responses
mixed hessians
id quasi hessians
sr1
Use the Symmetric Rank 1 update method to compute quasi-Hessians

Specification
Alias: none
Argument(s): none

Description
The Symmetric Rank 1 (SR1) update (specified with the keyword sr1) will be used to compute quasi-Hessians.
Bk+1 = Bk +

(yk Bk sk )(yk Bk sk )T
(yk Bk sk )T sk

where Bk is the k th approximation to the Hessian, sk = xk+1 xk is the step and yk = fk+1 fk is the
corresponding yield in the gradients.
Notes

6.6. RESPONSES
Initial scaling of

2257
T
yk
yk
Ts I
yk
k

is used for B0 prior to the first update.

Numerical safeguarding is used to protect against numerically small denominators within the updates.
This safeguarding skips the update if |(yk Bk sk )T sk | < 106 ||sk ||2 ||yk Bk sk ||2
id analytic hessians
Keywords Area
responses
mixed hessians
id analytic hessians
Identify which analytical Hessian corresponds to which response

Topics
This keyword is related to the topics:
objective function pointer

Specification
Alias: none
Argument(s): INTEGERLIST

Description
The id analytic hessians list specifies by number the functions which have analytic Hessians, and the
id numerical hessians and id quasi hessians lists specify by number the functions which must use
numerical Hessians and secant Hessian updates, respectively. Each function identifier, from 1 through the total
number of functions, must appear once and only once within the union of the id analytic hessians, id numerical hessians, and id quasi hessians lists.

See Also
These keywords may also be of interest:
id numerical hessians
id quasi hessians

2258

CHAPTER 6. KEYWORDS AREA

Bibliography
[1] Computational investigations of low-discrepancy sequences. ACM Transactions on Mathematical Software,
23(2):266294, 1997. 1661, 1776, 1777
[2] M.A. Abramson, C. Audet, G. Couture, J.E. Dennis, Jr., S. Le Digabel, and C. Tribes. The NOMAD project.
Software available at http://www.gerad.ca/nomad. 666
[3] B. M. Adams, L. E. Bauman, W. J. Bohnhoff, K. R. Dalbey, J. P. Eddy, M. S. Ebeida, M. S. Eldred, P. D.
Hough, K. T. Hu, J. D. Jakeman, Ahmad Rushdi, L. P. Swiler, J. A. Stephens, D. M. Vigil, and T. M.
Wildey. Dakota, a multilevel parallel object-oriented framework for design optimization, parameter estimation, uncertainty quantification, and sensitivity analysis: Version 6.2 developers manual. Technical Report
SAND2014-5014, Sandia National Laboratories, Albuquerque, NM, Updated May 2015. Available online
from http://dakota.sandia.gov/documentation.html. 7
[4] B. M. Adams, L. E. Bauman, W. J. Bohnhoff, K. R. Dalbey, J. P. Eddy, M. S. Ebeida, M. S. Eldred, P. D.
Hough, K. T. Hu, J. D. Jakeman, Ahmad Rushdi, L. P. Swiler, J. A. Stephens, D. M. Vigil, and T. M.
Wildey. Dakota, a multilevel parallel object-oriented framework for design optimization, parameter estimation, uncertainty quantification, and sensitivity analysis: Version 6.2 users manual. Technical Report
SAND2014-4633, Sandia National Laboratories, Albuquerque, NM, Updated May 2015. Available online
from http://dakota.sandia.gov/documentation.html. 7, 13, 14, 27, 82, 124, 134, 135, 136,
139, 215, 216, 218, 219, 224, 225, 227, 233, 234, 236, 245, 256, 257, 258, 361, 449, 940, 1063, 1698, 1701,
1793, 1959, 1961, 2114, 2124, 2125, 2133, 2135, 2136, 2144, 2145, 2146, 2147, 2148, 2150, 2159, 2163,
2220, 2223, 2224, 2231, 2232, 2245
[5] B. M. Adams, L. E. Bauman, W. J. Bohnhoff, K. R. Dalbey, J. P. Eddy, M. S. Ebeida, M. S. Eldred, P. D.
Hough, K. T. Hu, J. D. Jakeman, Ahmad Rushdi, L. P. Swiler, J. A. Stephens, D. M. Vigil, and T. M.
Wildey. Dakota, a multilevel parallel object-oriented framework for design optimization, parameter estimation, uncertainty quantification, and sensitivity analysis: Version 6.2 reference manual. Technical Report
SAND2014-5015, Sandia National Laboratories, Albuquerque, NM, Updated May 2015. Available online
from http://dakota.sandia.gov/documentation.html. 125, 128
[6] B. M. Adams, L. E. Bauman, W. J. Bohnhoff, K. R. Dalbey, J. P. Eddy, M. S. Ebeida, M. S. Eldred, P. D.
Hough, K. T. Hu, J. D. Jakeman, Ahmad Rushdi, L. P. Swiler, J. A. Stephens, D. M. Vigil, and T. M.
Wildey. Dakota, a multilevel parallel object-oriented framework for design optimization, parameter estimation, uncertainty quantification, and sensitivity analysis: Version 6.2 theory manual. Technical Report
SAND2014-4253, Sandia National Laboratories, Albuquerque, NM, Updated May 2015. Available online
from http://dakota.sandia.gov/documentation.html. 940, 1063, 1505, 1534
[7] G. Anderson and P. Anderson. The UNIX C Shell Field Guide. Prentice-Hall, Englewood Cliffs, NJ, 1986.
10
[8] J. S. Arora. Introduction to Optimum Design. McGraw-Hill, New York, 1989. 134
2259

2260

BIBLIOGRAPHY

[9] C. Audet, S. Le Digabel, and C. Tribes. NOMAD user guide. Technical Report G-2009-37, Les cahiers du
GERAD, 2009. 666
[10] J.-P. Berrut and L. N. Trefethen. Barycentric lagrange interpolation. SIAM Review, 46(3):501517, 2004.
130
[11] B. J. Bichon, M. S. Eldred, L. P. Swiler, S. Mahadevan, and J. M. McFarland. Multimodal reliability
assessment for complex engineering applications using efficient global optimization. In Proceedings of the
48th AIAA/ASME/ASCE/AHS/ASC Structures, Structural Dynamics, and Materials Conference (9th AIAA
Non-Deterministic Approaches Conference), number AIAA-2007-1946, Honolulu, HI, April 2007. 1735
[12] B. J. Bichon, M. S. Eldred, L. P. Swiler, S. Mahadevan, and J. M. McFarland. Efficient global reliability
analysis for nonlinear implicit performance functions. AIAA Journal, 46(10):24592468, 2008. 1735
[13] K. Breitung. Asymptotic approximation for multinormal integrals. J. Eng. Mech., ASCE, 110(3):357366,
1984. 1700
[14] R. H. Byrd, R. B. Schnabel, and G. A. Schultz. Parallel quasi-newton methods for unconstrained optimization. Mathematical Programming, 42:273306, 1988. 279, 296, 313, 330, 347, 369, 386, 403, 422, 454,
473, 493, 525, 549, 573, 597, 621, 880
[15] K. J. Chang, R. T. Haftka, G. L. Giles, and P.-J. Kao. Sensitivity-based scaling for approximating structural
response. J. Aircraft, 30:283288, 1993. 1924, 1948
[16] A. R. Conn, N. I. M. Gould, and P. L. Toint. Trust-Region Methods. MPS-SIAM Series on Optimization,
SIAM-MPS, Philadelphia, 2000. 260, 261, 262
[17] A. Der Kiureghian and P. L. Liu. Structural reliability under incomplete information. J. Eng. Mech., ASCE,
112(EM-1):85104, 1986. 129
[18] Q. Du, V. Faber, and M. Gunzburger. Centroidal voronoi tessellations: Applications and algorithms. SIAM
Review, 41:637676, 1999. 1654
[19] J. E. Eddy and K. Lewis. Effective generation of pareto sets using genetic programming. In Proceedings of
ASME Design Engineering Technical Conference, 2001. 149
[20] A. S. El-Bakry, R. A. Tapia, T. Tsuchiya, and Y. Zhang. On the formulation and theory of the newton interiorpoint method for nonlinear programming. Journal of Optimization Theory and Applications, 89:507541,
1996. 544, 568, 592, 616
[21] M. S. Eldred, H. Agarwal, V. M. Perez, S. F. Wojtkiewicz, Jr., and J. E. Renaud. Investigation of reliability
method formulations in DAKOTA/UQ. Structure & Infrastructure Engineering: Maintenance, Management,
Life-Cycle Design & Performance, 3(3):199213, 2007. 126, 127
[22] M. S. Eldred and B. J. Bichon. Second-order reliability formulations in DAKOTA/UQ. In Proceedings of
the 47th AIAA/ASME/ASCE/AHS/ASC Structures, Structural Dynamics and Materials Conference, number
AIAA-2006-1828, Newport, RI, May 14 2006. 1700
[23] M. S. Eldred and D. M. Dunlavy. Formulations for surrogate-based optimization with data fit, multifidelity,
and reduced-order models. In Proceedings of the 11th AIAA/ISSMO Multidisciplinary Analysis and Optimization Conference, number AIAA-2006-7117, Portsmouth, VA, September 68 2006. 245, 256, 257,
258
[24] M. S. Eldred, A. A. Giunta, and S. S. Collis. Second-order corrections for surrogate-based optimization with
model hierarchies. In Proceedings of the 10th AIAA/ISSMO Multidisciplinary Analysis and Optimization
Conference, Albany, NY,, Aug. 30Sept. 1, 2004. AIAA Paper 2004-4457. 1700, 1924, 1925, 1947, 1948

BIBLIOGRAPHY

2261

[25] G. M. Fadel, M. F. Riley, and J.-F. M. Barthelemy. Two point exponential approximation method for structural optimization. Structural Optimization, 2(2):117124, 1990. 1940
[26] R. Fourer, D. M. Gay, and B. W. Kernighan. AMPL: A Modeling Language for Mathematical Programming,
2nd ed. Duxbury Press/Brooks/Cole Publishing Co., Pacific Grove, CA, 2003. For small examples, e.g.,
at most 300 variables, a student version of AMPL suffices; see http://www.ampl.com/DOWNLOADS.
2116
[27] J. H. Friedman. Multivariate adaptive regression splines. Annals of Statistics, 19(1):1141, March 1991.
1856
[28] J. Gablonsky. Direct version 2.0 userguide technical report. Technical Report CRSC-TR01-08, North Carolina State University, Center for Research in Scientific Computation, Raleigh, NC, 2001. 892
[29] D. M. Gay. Hooking your solver to AMPL. Technical Report Technical Report 97-4-06, Bell Laboratories, Murray Hill, NJ, 1997. Available online as http://www.ampl.com/REFS/HOOKING/
index.html and http://www.ampl.com/REFS/hooking2.pdf and http://www.ampl.
com/REFS/hooking2.ps.gz. 2114, 2116
[30] D. M. Gay. Specifying and reading program input with NIDR. Technical Report SAND2008-2261P, Sandia
National Laboratories, 2008. Available as http://dakota.sandia.gov/papers/nidr08.pdf.
21
[31] R. Ghanem and J. R. Red-Horse. Propagation of probabilistic uncertainty in complex physical systems using
a stochastic finite element technique. Physica D, 133:137144, 1999. 126, 127, 130
[32] R. G. Ghanem and P. D. Spanos. Stochastic Finite Elements: A Spectral Approach. Springer-Verlag, New
York, 1991. 126, 127, 130
[33] P. E. Gill, W. Murray, M. A. Saunders, and M. H. Wright. Users guide for NPSOL (Version 4.0): A Fortran
package for nonlinear programming. Technical Report TR SOL-86-2, System Optimization Laboratory,
Stanford University, Stanford, CA, 1986. 150, 450, 469, 488
[34] P. E. Gill, W. Murray, and M. H. Wright. Practical Optimization. Academic Press, San Diego, CA, 1981.
20, 134
[35] A. A. Giunta. Use of data sampling, surrogate models, and numerical optimization in engineering design.
In Proc. 40th AIAA Aerospace Science Meeting and Exhibit, number AIAA-2002-0538, Reno, NV, January
2002. 1925, 1949
[36] A. A. Giunta, L. P. Swiler, S. L Brown, M. S. Eldred, M. D. Richards, and E. C. Cyr. The surfpack software library for surrogate modeling of sparse, irregularly spaced multidimensional data. In Proceedings of
the 11th AIAA/ISSMO Multidisciplinary Analysis and Optimization Conference, number AIAA-2006-7049,
Portsmouth, VA, 2006. 1833
[37] G. A. Gray and T. G. Kolda. Algorithm 856: APPSPACK 4.0: Asynchronous parallel pattern search for
derivative-free optimization. ACM Transactions on Mathematical Software, 32(3):485507, September
2006. 149, 643
[38] M. Gunburger and J. Burkardt. Uniformity measures for point samples in hypercubes, 2004. Available on
John Burkardts web site: http://www.csit.fsu.edu/burkardt/. 1646, 1656, 1779
[39] Heikki Haario, Marko Laine, Antonietta Mira, and Eero Saksman. Dram: Efficient adaptive mcmc. Statistics
and Computing, 16:339354, 2006. 1495, 1522

2262

BIBLIOGRAPHY

[40] R. T. Haftka. Combining global and local approximations. AIAA Journal, 29(9):15231525, 1991. 1924,
1947
[41] R. T. Haftka and Z. Gurdal. Elements of Structural Optimization. Kluwer, Boston, 1992. 134
[42] A. Haldar and S. Mahadevan. Probability, Reliability, and Statistical Methods in Engineering Design. Wiley,
New York, 2000. 126, 1697, 2070
[43] J. H. Halton. On the efficiency of certain quasi-random sequences of points in evaluating multi-dimensional
integrals. Numerische Mathematik, 2:8490, 1960. 1661, 1776, 1777
[44] J. H. Halton and G. B. Smith. Algorithm 247: Radical-inverse quasi-random point sequence. Communications of the ACM, 7:701702, 1964. 1661, 1776, 1777
[45] W. E. Hart, A. A. Giunta, A. G. Salinger, and B. G. van Bloemen Waanders. An overview of the adaptive
pattern search algorithm and its application to engineering optimization problems. In Proceedings of the
McMaster Optimization Conference: Theory and Applications, Hamilton, Ontario, Canada, 2001. 774, 780
[46] J. C. Helton and F. J. Davis. Sampling-based methods for uncertainty and sensitivity analysis. Technical
Report SAND99-2240, Sandia National Laboratories, Albuquerque, NM, 2000. 126, 128
[47] J. C. Helton and W. L. Oberkampf. Special issue of reliability engineering and system safety: Issue on
alternative representations of epistemic uncertainty, JulSep 2004. 132
[48] D. Higdon, J. Gattiker, B. Williams, and M. Rightley. Computer model calibration using high-dimensional
output. Journal of the American Statistical Association, 103(482):570583, 2008. 1514
[49] N. J. Higham. The numerical stability of barycentric lagrange interpolation. IMA Journal of Numerical
Analysis, 24(4):547556, 2004. 130
[50] M. Hohenbichler and R. Rackwitz. Improvement of second-order reliability estimates by importance sampling. J. Eng. Mech., ASCE, 114(12):21952199, 1988. 1700
[51] H.P. Hong. Simple approximations for improving second-order reliability estimates. J. Eng. Mech., ASCE,
125(5):592595, 1999. 1700
[52] R. L. Iman and W. J. Conover. A distribution-free approach to inducing rank correlation among input
variables. Communications in Statistics: Simulation and Computation, B11(3):311334, 1982. 2070
[53] R. L. Iman and M. J Shortencarier. A Fortran 77 program and users guide for the generation of latin
hypercube samples for use with computer models. Technical Report NUREG/CR-3624, SAND83-2365,
Sandia National Laboratories, Albuquerque, NM, 1984. 126, 128
[54] D. Jones, M. Schonlau, and W. Welch. Efficient global optimization of expensive black-box functions.
Journal of Global Optimization, 13:455492, 1998. 912
[55] M. C. Kennedy and A. OHagan. Bayesian calibration of computer models. Journal of the Royal Statistical
Society, 63:425464, 2001. 1514
[56] W. A. Klimke. Uncertainty Modeling using Fuzzy Arithmetic and Sparse Grids. PhD thesis, Universitat
Stuttgart, Stuttgart, Germany, 2005. 130
[57] R. M. Lewis and S. N. Nash. A multigrid approach to the optimization of systems governed by differential
equations. In Proceedings of the 8th AIAA/USAF/NASA/ISSMO Symposium on Multidisciplinary Analysis
and Optimization, number AIAA-2000-4890, Long Beach, CA, Sep 2000. 1924, 1947, 1948

BIBLIOGRAPHY

2263

[58] J. M. McFarland. Uncertainty Analysis for Computer Simulations through Validation and Calibration. PhD thesis, Vanderbilt University, Nashville, Tennesssee, 2008. available for download at
http://etd.library.vanderbilt.edu/ETD-db/available/etd-03282008-125137/. 916, 1342, 1360, 1401, 1420,
1452, 1546, 1594, 1739, 1836
[59] M. D. McKay, R. J. Beckman, and W. J. Conover. A comparison of three methods for selecting values of
input variables in the analysis of output from a computer code. Technometrics, 21(2):239245, 1979. 126,
128
[60] J. C. Meza, R. A. Oliva, P. D. Hough, and P. J. Williams. OPT++: an object oriented toolkit for nonlinear
optimization. ACM Transactions on Mathematical Software, 33(2), 2007. 150
[61] J. More and D. Thuente. Line search algorithms with guaranteed sufficient decrease. ACM Transactions on
Mathematical Software, 20(3):286307, 1994. 540, 541, 542, 564, 565, 567, 588, 589, 590, 591, 612, 613,
614, 615
[62] M. D. Morris. Factorial sampling plans for preliminary computational experiments.
33(2):161174, 1991. 1667

Technometrics,

[63] R. H. Myers and D. C. Montgomery. Response Surface Methodology: Process and Product Optimization
Using Designed Experiments. John Wiley & Sons, Inc., New York, 1995. 1890
[64] A. Nealen. A short-as-possible introduction to the least squares, weighted least squares, and moving least
squares methods for scattered data approximation and interpolation. Technical report, Discrete Geometric
Modeling Group, Technishe Universitaet, Berlin, Germany, 2004. 1863
[65] J. Nocedal and Wright S. J. Numerical Optimization. Springer Series in Operations Research. Springer,
New York, 1999. 134
[66] W. .L. Oberkampf and J. C. Helton. Evidence theory for engineering applications. Technical Report
SAND2003-3559P, Sandia National Laboratories, Albuquerque, NM, 2003. 132
[67] M. J. L. Orr. Introduction to radial basis function networks. Technical report, University of Edinburgh,
Edinburgh, Scotland, 1996. 1880
[68] V. M. Perez, J. E. Renaud, and L. T. Watson. An interior-point sequential approximation optimization
methodology. Structural and Multidisciplinary Optimization, 27(5):360370, July 2004. 264, 265
[69] T. D. Plantenga. HOPSPACK 2.0 user manual. Technical Report SAND2009-6265, Sandia National Laboratories, 2009. 149
[70] E. Prudencio and S. H. Cheung. Parallel adaptive multilevel sampling algorithms for the bayesian analysis of
mathematical models. International Journal for Uncertainty Quantification, 2:215237, 2012. 1498, 1526
[71] D. G. Robinson and C. Atcitty. Comparison of quasi- and pseudo-monte carlo sampling for reliability and
uncertainty analysis. In Proceedings of the AIAA Probabilistic Methods Conference, number AIAA99-1589,
St. Louis, MO, 1999. 1783
[72] M. Rosenblatt. Remarks on a multivariate transformation. Annals of Mathematical Statistics, 23(3):470472,
1952. 129
[73] A. Saltelli, S. Tarantola, F. Campolongo, and M. Ratto. Sensitivity Analysis in Practice: A Guide to Assessing
Scientific Models. John Wiley & Sons, 2004. 1010, 1083, 1142, 1647, 1658, 1667, 1780

2264

BIBLIOGRAPHY

[74] K. Schittkowski. NLPQLP: A fortran implementation of a sequential quadratic programming algorithm with
distributed and non-monotone line search users guide. Technical report, Department of Mathematics,
University of Bayreuth, Bayreuth, Germany, 2004. 150
[75] G. D. Sjaardema. APREPRO: An algebraic preprocessor for parameterizing finite element analyses. Technical Report SAND92-2291, Sandia National Laboratories, Albuquerque, NM, 1992. 2125, 2136
[76] R. Srinivasan. Importance Sampling. Springer-Verlag, 2002. 1175
[77] A. Stroud. Approximate Calculation of Multiple Integrals. Prentice Hall, 1971. 954
[78] L. P. Swiler and N. J. West. Importance sampling: Promises and limitations. In Proceedings of the 12th
AIAA Non-Deterministic Approaches Conference, number AIAA-2010-2850, 2010. 1175
[79] G. Tang, L. P. Swiler, and M. S Eldred. Using stochastic expansion methods in evidence theory for mixed
aleatory-epistemic uncertainty quantification. In Proceedings of the 51st AIAA/ASME/ASCE/AHS/ASC
Structures, Structural Dynamics, and Materials Conference (12th AIAA Non-Deterministic Approaches conference), Orlando, FL, April 12-15, 2010. AIAA Paper 2010-XXXX. 126, 127
[80] R. A. Tapia and M. Argaez. Global convergence of a primal-dual interior-point newton method for nonlinear
programming using a modified augmented lagrangian function. (In Preparation). 544, 568, 593, 617
[81] C. H. Tong. The PSUADE software library. Web site, 2005.
uncertainty_quantification/#psuade. 151

http://www.llnl.gov/CASC/

[82] R. J. Vanderbei and D. F. Shanno. An interior-point algorithm for nonconvex nonlinear programming.
Computational Optimization and Applications, 13:231259, 1999. 545, 569, 593, 617
[83] G. N. Vanderplaats. CONMIN a FORTRAN program for constrained function minimization. Technical
Report TM X-62282, NASA, 1973. See also Addendum to Technical Memorandum, 1978. 147, 417
[84] G. N. Vanderplaats. Numerical Optimization Techniques for Engineering Design: With Applications.
McGraw-Hill, New York, 1984. 134
[85] Vanderplaats Research and Development, Inc., Colorado Springs, CO. DOT Users Manual, Version 4.20,
1995. 148, 361
[86] J. A. Vrugt, C. J. F. ter Braak, C. G. H. Diks, B. A. Robinson, J. M. Hyman, and D. Higdon. Accelerating markov chain monte carlo simulation by self-adaptive differential evolution with randomized subspace
sampling. International Journal of Nonlinear Scientific Numerical Simulation, 10(3), 2009. 1445, 1587,
1588
[87] V. G. Weirs, J. R. Kamm, L. P. Swiler, M. Ratto, S. Tarantola, B. M. Adams, W. J. Rider, and M. S Eldred.
Sensitivity analysis techniques applied to a system of hyperbolic conservation laws. Reliability Engineering
and System Safety, 107:157170, 2012. 1010, 1083, 1142, 1647, 1658, 1780
[88] S. J. Wright. Primal-Dual Interior-Point Methods. SIAM, 1997. 546, 570, 594, 618
[89] G. D. Wyss and K. H. Jorgensen. A users guide to LHS: Sandias Latin hypercube sampling software.
Technical Report SAND98-0210, Sandia National Laboratories, Albuquerque, NM, 1998. 2002, 2006,
2039, 2059
[90] D. Xiu. Numerical integration formulas of degree two. Applied Numerical Mathematics, 58:15151520,
2008. 954

BIBLIOGRAPHY

2265

[91] S. Xu and R. V. Grandhi. Effective two-point function approximation for design optimization. AIAA J.,
36(12):22692275, 1998. 1700, 1940
[92] D. C. Zimmerman. Genetic algorithms for navigating expensive and complex design spaces, September
1996. Final Report for Sandia National Laboratories contract AO-7736 CA 02. 1870