.. _model-nested:

""""""
nested
""""""


A model whose responses are computed through the use of a sub-iterator


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

   model-nested-id_model
   model-nested-variables_pointer
   model-nested-responses_pointer
   model-nested-hierarchical_tagging
   model-nested-optional_interface_pointer
   model-nested-sub_method_pointer


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+--------------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                 | Dakota Keyword Description                    |
|                         | Group              |                                |                                               |
+=========================+====================+================================+===============================================+
| Optional                                     | `id_model`__                   | Give the model block an identifying name, in  |
|                                              |                                | case of multiple model blocks                 |
+----------------------------------------------+--------------------------------+-----------------------------------------------+
| Optional                                     | `variables_pointer`__          | Specify which variables block will be         |
|                                              |                                | included with this model block                |
+----------------------------------------------+--------------------------------+-----------------------------------------------+
| Optional                                     | `responses_pointer`__          | Specify which reponses block will be used by  |
|                                              |                                | this model block                              |
+----------------------------------------------+--------------------------------+-----------------------------------------------+
| Optional                                     | `hierarchical_tagging`__       | Enables hierarchical evaluation tagging       |
+----------------------------------------------+--------------------------------+-----------------------------------------------+
| Optional                                     | `optional_interface_pointer`__ | Pointer to interface that provides non-nested |
|                                              |                                | responses                                     |
+----------------------------------------------+--------------------------------+-----------------------------------------------+
| Required                                     | `sub_method_pointer`__         | The ``sub_method_pointer`` specifies the      |
|                                              |                                | method block for the sub-iterator             |
+----------------------------------------------+--------------------------------+-----------------------------------------------+

.. __: model-nested-id_model.html
__ model-nested-variables_pointer.html
__ model-nested-responses_pointer.html
__ model-nested-hierarchical_tagging.html
__ model-nested-optional_interface_pointer.html
__ model-nested-sub_method_pointer.html



**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 \b ``optional_interface_pointer`` points
to the interface specification and
``optional_interface_responses_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``. (See the discussions for the
``sub_method_pointer`` and ``optional_interface_pointer`` keywords.)


