.. _environment-top_method_pointer:

""""""""""""""""""
top_method_pointer
""""""""""""""""""


Identify which method leads the Dakota study



**Topics**


block_pointer


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



**Specification**

- *Alias:* method_pointer 

- *Arguments:* STRING

- *Default:* see discussion


**Description**


An optional ``top_method_pointer`` specification may be used to point
to a particular method specification that will lead the Dakota
analysis. The associated string must be a method identifier specified
via :dakkw:`method-id_method`. If ``top_method_pointer`` is not used, then
it will be inferred as decribed below (no ``top_method_pointer`` within
an environment specification is treated the same as no environment
specification).

*Default Behavior*

The ``top_method_pointer`` keyword is typically used in Dakota studies
consisting of more than one :dakkw:`method` block to clearly indicate
which is the leading method.  This method provides the starting point
for the iteration. The corresponding method specification may recurse
with additional sub-method pointers in the case of "meta-iteration"
(see :dakkw:`method`) or may specify a single method without
recursion. Either case will ultimately result in identification of one
or more model specifications using ``model_pointer``, which again may
or may not involve further recursion (see :dakkw:`model-nested` and
:dakkw:`model-surrogate` for recursion cases). Each of the model specifications
identify the variables and responses specifications (using
:dakkw:`model-variables_pointer` and :dakkw:`model-responses_pointer`) that are
used to build the model, and depending on the type of model, may also
identify an interface specification (for example, using
:dakkw:`model-single-interface_pointer`). If one of these specifications does
not provide an optional pointer, then that component will be
constructed using the last specification parsed.

When the environment block is omitted, the top level method will be
inferred as follows: When a single method is specified, there is no
ambiguity and the sole method will be the top method.  When multiple
methods are specified, the top level method will be deduced from the
hierarchical relationships implied by method pointers. If this
inference is not well defined (e.g., there are multiple method
specifications without any pointer relationship), then the default
behavior is to employ the last method specification parsed.



**Examples**


Specify that the optimization method is the outermost method in an
optimization under uncertainty study

.. code-block::

    environment
      top_method_pointer 'OPTIMIZATION_METHOD'
    method
      id_method 'UQ_METHOD'
    ...
    method
      id_method 'OPTIMIZATION_METHOD'
    ...