<!-------------------------------------------->


\page input_spec Dakota Input Specification

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

\section input_spec-nidr Dakota Keywords

Valid %Dakota input keywords are dictated by \c dakota.xml, included
in source and binary distributions of %Dakota.  This specification
file is used with the NIDR \cite Gay2008 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
\c dakota.input.summary is also distributed.

While complete, users may find \c 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:
\subpage input_file_examples.  Advanced users can master the many
input specification possibilities by understanding the structure of
the input specification file.

\section input_spec-overview Input Spec Overview 
Refer to the dakota.input.summary file, in \subpage input_spec_summary, 
for all current valid input keywords. 

- The summary describes every keyword including:
  - Whether it is required or optional
  - Whether it takes <tt>ARGUMENTS</tt> (always required)
    Additional notes about <tt>ARGUMENTS</tt> can be found here: \ref input_spec-overview-arguments.
  - Whether it has an <tt>ALIAS</tt>, or synonym
  - Which additional keywords can be specified to change its behavior
- Additional details and descriptions are described in \ref keywords
- For additional details on NIDR specification logic and rules, refer to \cite Gay2008 (Gay, 2008).

\subsection input_spec-mistakes Common Specification Mistakes

Spelling mistakes and omission of required parameters are the most
common errors. Some causes of errors are more obscure:

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

\li 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
\verbatim
# Comment about the following "responses" keyword...
responses,
    objective_functions = 1
    # Comment within keyword "responses"
    analytic_gradients
# Another comment within keyword "responses"
    no_hessians
\endverbatim
you would need to write
\verbatim
# Comment about the following "responses" keyword...
responses,                       \
    objective_functions = 1           \
    # Comment within keyword "responses"      \
    analytic_gradients               \
# Another comment within keyword "responses"      \
    no_hessians
\endverbatim
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 \c dakota \c -input
\c dakota_study.in \c -check will validate the input file without
running the study.


<!-------------------------------------------->

\subsection input_spec-overview-arguments 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 \c N*value instead of
repeating the value N times. 

For example
\verbatim
  lower_bounds  -2.0  -2.0  -2.0
  upper_bounds   2.0   2.0   2.0
\endverbatim
could also be written
\verbatim
  lower_bounds  3*-2.0
  upper_bounds  3* 2.0
\endverbatim
(with optional spaces around the \c * ). 

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 \c test/dakota_uq_textbook_sop_lhs.in ),
\verbatim
  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
\endverbatim
could also be written
\verbatim
  histogram_point = 2
    abscissas   = 50 : 10 : 90
                  30 : 10 : 70
    counts      = 10:10:30 20 10
                  10:10:30 20 10
\endverbatim

Count and sequence abbreviations can be used together. For example
\verbatim
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
\endverbatim
can be abbreviated 
\verbatim
response_levels =
	2*0.0:0.1:1.0
\endverbatim

