Dakota Reference Manual: Dakota Input Specification

| Dakota Reference Manual Version 6.15 Explore and Predict with Confidence

- Main Page
- Related Pages

All Pages
Dakota Input Specification

Dakota input is specified in a text file, e.g., `dakota_uq.in` containing blocks of keywords that control program behavior. This section describes the format and admissible elements of an input file.

# Dakota Keywords

Valid Dakota input keywords are dictated by `dakota.xml`, included in source and binary distributions of Dakota. This specification file is used with the NIDR[29] parser to validate user input and is therefore the definitive source for input syntax, capability options, and optional and required capability sub-parameters for any given Dakota version. A more readable variant of the specification `dakota.input.summary` is also distributed.

While complete, 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.

# Input Spec Overview

Refer to the dakota.input.summary file, in Input Spec Summary, for all current valid input keywords.

- 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[29] (Gay, 2008).

## 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 `dakota.input.summary` used in building the executable, which is installed alongside the executable, will often resolve the errors.

- 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 Dakota parser provides error messages that help the user isolate errors in input files. Running `dakota` `-input` `dakota_study.in` `-check` will validate the input file without running the study.

## 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 `N*value` instead of repeating the value N times.

For example

      lower_bounds  -2.0  -2.0  -2.0
      upper_bounds   2.0   2.0   2.0

could also be written

      lower_bounds  3*-2.0
      upper_bounds  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+2*S ... 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. 80. 90.
                      30. 40. 50. 60. 70.
        counts      = 10 20 30 20 10
                      10 20 30 20 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

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