.. _method-mesh_adaptive_search:

""""""""""""""""""""
mesh_adaptive_search
""""""""""""""""""""


Finds optimal variable values using adaptive mesh-based search


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

   method-mesh_adaptive_search-initial_delta
   method-mesh_adaptive_search-variable_tolerance
   method-mesh_adaptive_search-function_precision
   method-mesh_adaptive_search-seed
   method-mesh_adaptive_search-history_file
   method-mesh_adaptive_search-display_format
   method-mesh_adaptive_search-variable_neighborhood_search
   method-mesh_adaptive_search-neighbor_order
   method-mesh_adaptive_search-display_all_evaluations
   method-mesh_adaptive_search-use_surrogate
   method-mesh_adaptive_search-max_iterations
   method-mesh_adaptive_search-max_function_evaluations
   method-mesh_adaptive_search-scaling
   method-mesh_adaptive_search-model_pointer


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+----------------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                   | Dakota Keyword Description                    |
|                         | Group              |                                  |                                               |
+=========================+====================+==================================+===============================================+
| Optional                                     | `initial_delta`__                | Initial step size for derivative-free         |
|                                              |                                  | optimizers                                    |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `variable_tolerance`__           | Step length-based stopping criteria for       |
|                                              |                                  | derivative-free optimizers                    |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `function_precision`__           | Specify the maximum precision of the analysis |
|                                              |                                  | code responses                                |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `seed`__                         | Seed of the random number generator           |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `history_file`__                 | Name of file where mesh adaptive search       |
|                                              |                                  | records all evaluation points.                |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `display_format`__               | Information to be reported from mesh adaptive |
|                                              |                                  | search's internal records.                    |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `variable_neighborhood_search`__ | Percentage of evaluations to do to escape     |
|                                              |                                  | local minima.                                 |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `neighbor_order`__               | Number of dimensions in which to perturb      |
|                                              |                                  | categorical variables.                        |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `display_all_evaluations`__      | Shows mesh adaptive search's internally held  |
|                                              |                                  | list of all evaluations                       |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `use_surrogate`__                | Surrogate model usage mode for mesh adaptive  |
|                                              |                                  | search                                        |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `max_iterations`__               | Number of iterations allowed for optimizers   |
|                                              |                                  | and adaptive UQ methods                       |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `max_function_evaluations`__     | Number of function evaluations allowed for    |
|                                              |                                  | optimizers                                    |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `scaling`__                      | Turn on scaling for variables, responses, and |
|                                              |                                  | constraints                                   |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `model_pointer`__                | Identifier for model block to be used by a    |
|                                              |                                  | method                                        |
+----------------------------------------------+----------------------------------+-----------------------------------------------+

.. __: method-mesh_adaptive_search-initial_delta.html
__ method-mesh_adaptive_search-variable_tolerance.html
__ method-mesh_adaptive_search-function_precision.html
__ method-mesh_adaptive_search-seed.html
__ method-mesh_adaptive_search-history_file.html
__ method-mesh_adaptive_search-display_format.html
__ method-mesh_adaptive_search-variable_neighborhood_search.html
__ method-mesh_adaptive_search-neighbor_order.html
__ method-mesh_adaptive_search-display_all_evaluations.html
__ method-mesh_adaptive_search-use_surrogate.html
__ method-mesh_adaptive_search-max_iterations.html
__ method-mesh_adaptive_search-max_function_evaluations.html
__ method-mesh_adaptive_search-scaling.html
__ method-mesh_adaptive_search-model_pointer.html



**Description**


The mesh adaptive direct search algorithm :cite:p:`AuLeTr09a`
is a derivative-free generalized pattern
search in which the set of points evaluated becomes increasingly
dense, leading to good convergence properties.  It can handle
unconstrained problems as well as those with bound constraints and
general nonlinear constraints. Furthermore, it can handle continuous,
discrete, and categorical variables.

*Default Behavior*

By default, ``mesh_adaptive_search`` operates on design variables.  The
types of variables can be expanded through the use of the ``active``
keyword in the :dakkw:`variables` block in the Dakota input file.
Categorical variables, however, must be limited to design variables.

*Expected Outputs*

The best objective function value achieved and associated parameter
and constraint values can be found at the end of the Dakota output.
The method's internally summarized iteration history will appear in
the screen output by default, with the option to control the method's
output through Dakota's output level.  It also generates a history
file containing a list of all function evaluations done.

*Expected HDF5 Output*

If Dakota was built with HDF5 support and run with the
:dakkw:`environment-results_output-hdf5` keyword, this method
writes the following results to HDF5:


- :ref:`hdf5_results-best_params`
- :ref:`hdf5_results-best_obj_fncs` (when :dakkw:`responses-objective_functions`) are specified)
- :ref:`hdf5_results-best_constraints`
- :ref:`hdf5_results-calibration` (when :dakkw:`responses-calibration_terms` are specified)

*Additional Discussion*

The mesh adaptive direct search method is made available in Dakota
through the NOMAD software :cite:p:`Nomad`,
available to the public under the
GNU LGPL from http://www.gerad.ca/nomad.



**Examples**


The following is an example of a Dakota input file that makes use of
``mesh_adaptive_search`` to optimize the textbook function.


.. code-block::

    method,
            mesh_adaptive_search
            seed = 1234
    
    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'
    
    interface,
           direct
              analysis_driver = 'text_book'
    
    responses,
            objective_functions = 1
            no_gradients
            no_hessians


The best function value and associated parameters are found at the end
of the Dakota output.


.. code-block::

    <<<<< Function evaluation summary: 674 total (674 new, 0 duplicate)
    <<<<< Best parameters          =
                          1.0000000000e+00 x1
                          1.0000000000e+00 x2
                          1.0000000000e+00 x3
    <<<<< Best objective function  =
                          1.0735377280e-52
    <<<<< Best evaluation ID: 658


A NOMAD-generated iteration summary is also printed to the screen.


.. code-block::

    MADS run {
    
     BBE OBJ
    
        1 17.0625000000
        2 1.0625000000
       13 0.0625000000
       24 0.0002441406
       41 0.0000314713
       43 0.0000028610
       54 0.0000000037
       83 0.0000000000
      105 0.0000000000
      112 0.0000000000
      114 0.0000000000
      135 0.0000000000
      142 0.0000000000
      153 0.0000000000
      159 0.0000000000
      171 0.0000000000
      193 0.0000000000
      200 0.0000000000
      207 0.0000000000
      223 0.0000000000
      229 0.0000000000
      250 0.0000000000
      266 0.0000000000
      282 0.0000000000
      288 0.0000000000
      314 0.0000000000
      320 0.0000000000
      321 0.0000000000
      327 0.0000000000
      354 0.0000000000
      361 0.0000000000
      372 0.0000000000
      373 0.0000000000
      389 0.0000000000
      400 0.0000000000
      417 0.0000000000
      444 0.0000000000
      459 0.0000000000
      461 0.0000000000
      488 0.0000000000
      492 0.0000000000
      494 0.0000000000
      501 0.0000000000
      518 0.0000000000
      530 0.0000000000
      537 0.0000000000
      564 0.0000000000
      566 0.0000000000
      583 0.0000000000
      590 0.0000000000
      592 0.0000000000
      604 0.0000000000
      606 0.0000000000
      629 0.0000000000
      636 0.0000000000
      658 0.0000000000
      674 0.0000000000
    
    } end of run (mesh size reached NOMAD precision)
    
    blackbox evaluations                     : 674
    best feasible solution                   : ( 1 1 1 ) h=0 f=1.073537728e-52




