.. _method-mesh_adaptive_search-use_surrogate:

"""""""""""""
use_surrogate
"""""""""""""


Surrogate model usage mode for mesh adaptive search


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

   method-mesh_adaptive_search-use_surrogate-inform_search
   method-mesh_adaptive_search-use_surrogate-optimize


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* optimize


**Child Keywords:**

+-------------------------+--------------------+--------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                  |
|                         | Group              |                    |                                             |
+=========================+====================+====================+=============================================+
| Required (Choose One)   | Surrogate Purpose  | `inform_search`__  | Surrogate informs evaluation order in mesh  |
|                         |                    |                    | adaptive search                             |
|                         |                    +--------------------+---------------------------------------------+
|                         |                    | `optimize`__       | Surrogate is used in lieu of true model for |
|                         |                    |                    | mesh adaptive search                        |
+-------------------------+--------------------+--------------------+---------------------------------------------+

.. __: method-mesh_adaptive_search-use_surrogate-inform_search.html
__ method-mesh_adaptive_search-use_surrogate-optimize.html



**Description**


The ``use_surrogate`` keyword is used to define how a surrogate model
(if one is provided) is to be used by ``mesh_adaptive_search``.  There
are two approaches available: ``inform_search`` uses the surrogate to
sort list of trial points and subsequently the true function is
evaluated on the most promising points first.  Both true function and
surrogate are used interchangeably within the method.  ``optimize``
forces the use of a surrogate in lieu of the true model and thus the
true function is never invoked except to construct the surrogate.

*Known Issue: When using discrete variables, there have been
sometimes significant differences in surrogate behavior observed
across computing platforms in some cases.  The cause has not yet been
fully diagnosed and is currently under investigation.  In addition,
guidance on appropriate construction and use of surrogates with
discrete variables is under development.  In the meantime, users
should therefore be aware that there is a risk of inaccurate results
when using surrogates with discrete variables.*

*Default Behavior*

By default, ``mesh_adaptive_search`` follows behaviour provided by
``optimize`` option.



**Examples**


The following example shows the syntax used to set ``use_surrogate``.


.. code-block::

    method,
     mesh_adaptive_search
     model_pointer = 'SURROGATE'
     use_surrogate inform_search
    
    model,
     id_model = 'SURROGATE'
     surrogate global
     polynomial quadratic
     dace_method_pointer = 'SAMPLING'
    
    variables,
     continuous_design = 3
       initial_point   -1.0    1.5   2.0
       upper_bounds    10.0   10.0  10.0
       lower_bounds   -10.0  -10.0 -10.0
       descriptors      'x1'  'x2'  'x3'
     discrete_design_range = 2
       initial_point      2     2
       lower_bounds       1     1
       upper_bounds       4     9
       descriptors      'y1'   'y2'
           discrete_design_set
             real = 2
               elements_per_variable = 4 5
               elements = 1.2 2.3 3.4 4.5 1.2 3.3 4.4 5.5 7.7
               descriptors      'y3'   'y4'
             integer = 2
               elements_per_variable = 2 2
               elements = 4 7 8 9
               descriptors      'z1'   'z2'
    
    method,
     id_method = 'SAMPLING'
     model_pointer = 'TRUTH'
     sampling
       samples = 55
    
    model,
     id_model = 'TRUTH'
     single
       interface_pointer = 'TRUE_FN'
    
    interface,
     id_interface = 'TRUE_FN'
           direct
       analysis_driver = 'text_book'
    
    responses,
     objective_functions = 1
     no_gradients
     no_hessians