.. _responses:

"""""""""
responses
"""""""""


Description of the model output data returned to Dakota upon evaluation of an interface.



**Topics**


block


.. toctree::
   :hidden:
   :maxdepth: 1

   responses-id_responses
   responses-descriptors
   responses-objective_functions
   responses-calibration_terms
   responses-response_functions
   responses-no_gradients
   responses-analytic_gradients
   responses-mixed_gradients
   responses-numerical_gradients
   responses-no_hessians
   responses-numerical_hessians
   responses-quasi_hessians
   responses-analytic_hessians
   responses-mixed_hessians
   responses-metadata


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword          | Dakota Keyword Description                    |
|                         | Group              |                         |                                               |
+=========================+====================+=========================+===============================================+
| Optional                                     | `id_responses`__        | Name the responses block; helpful when there  |
|                                              |                         | are multiple                                  |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `descriptors`__         | Labels for the responses                      |
+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required (Choose One)   | Response Type      | `objective_functions`__ | Response type suitable for optimization       |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `calibration_terms`__   | Response type suitable for calibration or     |
|                         |                    |                         | least squares                                 |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `response_functions`__  | Generic response type                         |
+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required (Choose One)   | Gradient Type      | `no_gradients`__        | Gradients will not be used                    |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `analytic_gradients`__  | Analysis driver will return gradients         |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `mixed_gradients`__     | Gradients are needed and will be obtained     |
|                         |                    |                         | from a mix of numerical and analytic sources  |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `numerical_gradients`__ | Gradients are needed and will be approximated |
|                         |                    |                         | by finite differences                         |
+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required (Choose One)   | Hessian Type       | `no_hessians`__         | Hessians will not be used                     |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `numerical_hessians`__  | Hessians are needed and will be approximated  |
|                         |                    |                         | by finite differences                         |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `quasi_hessians`__      | Hessians are needed and will be approximated  |
|                         |                    |                         | by secant updates (BFGS or SR1) from a series |
|                         |                    |                         | of gradient evaluations                       |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `analytic_hessians`__   | Hessians are needed and are available         |
|                         |                    |                         | directly from the analysis driver             |
|                         |                    +-------------------------+-----------------------------------------------+
|                         |                    | `mixed_hessians`__      | Hessians are needed and will be obtained from |
|                         |                    |                         | a mix of numerical, analytic, and "quasi"     |
|                         |                    |                         | sources                                       |
+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `metadata`__            | (Experimental) Labels for floating point      |
|                                              |                         | response metadata                             |
+----------------------------------------------+-------------------------+-----------------------------------------------+

.. __: responses-id_responses.html
__ responses-descriptors.html
__ responses-objective_functions.html
__ responses-calibration_terms.html
__ responses-response_functions.html
__ responses-no_gradients.html
__ responses-analytic_gradients.html
__ responses-mixed_gradients.html
__ responses-numerical_gradients.html
__ responses-no_hessians.html
__ responses-numerical_hessians.html
__ responses-quasi_hessians.html
__ responses-analytic_hessians.html
__ responses-mixed_hessians.html
__ responses-metadata.html



**Description**


The ``responses`` specification in a Dakota input file indicates the
types of data that can be returned by an interface when invoked during
Dakota's execution. The specification includes three groups and two
optional keywords.

**The response type group** indicates the type and number of
responses expected by Dakota.  It must be one of three types:


- Optimization: objective and constraint functions
- Calibration: calibration (least squares) terms and constraint functions
- Uncertainty Quantifiation: generic response functions

The response type specified 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 response
types.

*The gradient type group* indicates 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.

*The Hessian type group* specifies 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.


.. code-block::

    responses
      objective_functions = 1
        nonlinear_inequality_constraints = 2
      analytic_gradients
      no_hessians


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 =
.001*value).


.. code-block::

    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.


.. code-block::

    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.


