Blurb::
Identify which method leads the Dakota study

Description::

An optional \c 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 \ref method-id_method. If \c top_method_pointer is not used, then
it will be inferred as decribed below (no \c top_method_pointer within
an environment specification is treated the same as no environment
specification).

<b> Default Behavior </b>

The \c top_method_pointer keyword is typically used in Dakota studies
consisting of more than one \ref 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 \ref method) or may specify a single method without
recursion. Either case will ultimately result in identification of one
or more model specifications using \c model_pointer, which again may
or may not involve further recursion (see \ref model-nested and \ref
model-surrogate for recursion cases). Each of the model specifications
identify the variables and responses specifications (using \ref
model-variables_pointer and \ref 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 \ref
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.

Topics::	block_pointer
Examples::
Specify that the optimization method is the outermost method in an
optimization under uncertainty study
\verbatim
environment
  top_method_pointer 'OPTIMIZATION_METHOD'
method
  id_method 'UQ_METHOD'
...
method
  id_method 'OPTIMIZATION_METHOD'
...
\endverbatim
Theory::
Faq::
See_Also::	method-id_method
