.. _inputfile-main:

.. _`topic-block`:

"""""""""""""""""
Dakota Input File
"""""""""""""""""

.. toctree::
   :maxdepth: 1
   
   inputfile/formatting
   inputfile/model
   inputfile/variables
   inputfile/interfaces
   inputfile/responses
   inputfile/inputstodakota
   inputfile/inputspec   

.. note::
   
   If you are looking for video resources on Dakota's input file format, :ref:`click here <inputfile-videos>`.

There are six specification blocks that may appear in Dakota input files. These are identified in the input file using the following
keywords: variables, interface, responses, model, method, and environment. While, these keyword blocks can appear in any
order in a Dakota input file, there is an inherent relationship that ties them together. The simplest form of that relationship is
shown in :numref:`inputfile:figure01`:

.. figure:: img/InputBlocks.png
   :name: inputfile:figure01
   :alt: Relationship between the six blocks, for a simple study.
   :width: 400
   :align: center
   
   Relationship between the six blocks, for a simple study.

It can be summarized as follows: **In each iteration of its algorithm, a method block requests a variables-to-responses mapping from its model, which the model fulfills through an interface.**

.. literalinclude:: samples/rosen_multidim.in
   :language: dakota
   :tab-width: 2
   :caption: Rosenbrock 2-D parameter study example: the Dakota input file.
   :name: tutorial:rosenbrock_multidim

As a concrete example, a simple Dakota input file, rosen_multidim.in, is shown above in :numref:`tutorial:rosenbrock_multidim`, for a two-dimensional
parameter study on Rosenbrock’s function. This input file will be used to describe the basic format and syntax used in all
Dakota input files.

.. note::

   To see the results of this study and more, consult the :ref:`Examples section <examples-gettingstarted-rosenbrock>`.
   
.. note::

   While most Dakota analyses satisfy the relationship where a single method runs a single model, :ref:`advanced cases are possible <adv_meth>`.

The first block of the input file is the **environment block.** This keyword block is used to specify the
general Dakota settings such as Dakota’s graphical output (via the graphics flag) and the tabular data output (via the
tabular data keyword). In advanced cases, it also identifies the top method pointer that will control the Dakota
study. The environment block is optional, and at most one such block can appear in a Dakota input file.

The **method block** of the input file specifies which iterative method Dakota will employ and associated method options. The
keyword multidim parameter study in :numref:`tutorial:rosenbrock_multidim` calls for a multidimensional parameter study, while the keyword
partitions specifies the number of intervals per variable (a method option). In this case, there will be eight intervals (nine
data points) evaluated between the lower and upper bounds of both variables (bounds provided subsequently in the variables
section), for a total of 81 response function evaluations. At least one method block is required, and multiple blocks may appear
in Dakota input files for advanced studies.

The :ref:`model block <models:main>` of the input file specifies the model that Dakota will use. A model provides the logical unit for determining
how a set of variables is mapped through an interface into a set of responses when needed by an iterative method. In the
default case, the model allows one to specify a single set of variables, interface, and responses. The model block is optional in
this simple case. Alternatively, it can be explicitly defined as in :numref:`tutorial:rosenbrock_multidim`, where the keyword single specifies the use of
a single model in the parameter study. If one wishes to perform more sophisticated studies such as surrogate-based analysis
or optimization under uncertainty, the logical organization specified in the model block becomes critical in informing Dakota
on how to manage the different components of such studies, and multiple model blocks are likely needed.

The :ref:`variables block <variables:main>` of the input file specifies the number, type, and characteristics of the parameters that will be varied
by Dakota. The variables can be classified as design variables, uncertain variables, or state variables. Design variables are
typically used in optimization and calibration, uncertain variables are used in UQ and sensitivity studies, and state variables are
usually fixed. In all three cases, variables can be continuous or discrete, with discrete having real, integer, and string subtypes.
The variables section shown in :numref:`tutorial:rosenbrock_multidim`
specifies that there are two continuous design variables. The sub-specifications for continuous design variables provide the
descriptors “x1” and “x2” as well as lower and upper bounds for these variables. The information about the variables is
organized in column format for readability. So, both variables x1 and x2 have a lower bound of -2.0 and an upper bound of
2.0. At least one variables block is required, and multiple blocks may appear in Dakota input files for advanced studies.

The :ref:`interface block <interfaces:main>` of the input file specifies the simulation code that will be used to map variables into responses as well
as details on how Dakota will pass data to and from that code. In this example, the keyword direct is used to indicate
the use of a function linked directly into Dakota, and data is passed directly between the two. The name of the function is
identified by the analysis driver keyword. Alternatively, fork or system executions can be used to invoke instances
of a simulation code that is external to Dakota as explained :ref:`here <couplingtosimulations-main>` and :ref:`here <advint>`.
In this case, data is passed between Dakota and the simulation via text files. At least one interface block is required, and
multiple blocks may appear in Dakota input files for advanced studies.

The :ref:`responses block <responses:main>` of the input file specifies the types of data that the interface will return to Dakota. They are categorized
primarily according to usage. Objective functions are used in optimization, calibration terms in calibration, and response
functions in sensitivity analysis and UQ. For the example shown in :numref:`tutorial:rosenbrock_multidim`, the assignment ``response functions = 1``
indicates that there is only one response function. The responses block can include additional information returned by the
interface. That includes constraints and derivative information. In this example, there are no
constraints associated with Rosenbrock’s function, so the keywords for constraint specifications are omitted. The keywords
no gradients and no hessians indicate that no derivatives will be provided to the method; none are needed for a
parameter study. At least one responses block is required, and multiple blocks may appear in Dakota input files for advanced
studies.

.. _inputfile-videos:

===============
Video Resources
===============

+--------------------------------+-----------------+----------------+
| Title                          | Link            | Resources      |
+================================+=================+================+
| Input File Format              | |Screencast|_   |                |
+--------------------------------+-----------------+----------------+
| Input Syntax / Building Blocks | |Training|_     | `Slides`__ /   |
|                                |                 | `Exercises`__  |
+--------------------------------+-----------------+----------------+

.. __: https://dakota.sandia.gov/sites/default/files/training/DakotaTraining_InputComponents.pdf
__ https://dakota.sandia.gov/sites/default/files/training/input-151215.zip

.. |Screencast| image:: inputfile/img/InputFileScreencastTeaser.png
                  :alt: Watch Screencast 1.2: Input File Format
.. _Screencast: https://www.youtube.com/watch?v=f1l8DIXd9Gs&list=PLouetuxaIMDo-NMFXT-hlHYhOkePLrayY&index=2

.. |Training| image:: inputfile/img/InputFileTrainingTeaser.png
                :alt: Input Syntax / Building Blocks
.. _Training: http://digitalops.sandia.gov/Mediasite/Play/16134f3f4b6842d2b145a9600cbbcbbd1d