.. _model-nested:

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


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


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

   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                                     | `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-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.)