.. _method-adaptive_sampling:

"""""""""""""""""
adaptive_sampling
"""""""""""""""""


(Experimental) Adaptively refine a Gaussian process surrogate



**Topics**


uncertainty_quantification


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

   method-adaptive_sampling-initial_samples
   method-adaptive_sampling-seed
   method-adaptive_sampling-samples_on_emulator
   method-adaptive_sampling-fitness_metric
   method-adaptive_sampling-batch_selection
   method-adaptive_sampling-refinement_samples
   method-adaptive_sampling-import_build_points_file
   method-adaptive_sampling-export_approx_points_file
   method-adaptive_sampling-misc_options
   method-adaptive_sampling-max_iterations
   method-adaptive_sampling-response_levels
   method-adaptive_sampling-probability_levels
   method-adaptive_sampling-gen_reliability_levels
   method-adaptive_sampling-distribution
   method-adaptive_sampling-rng
   method-adaptive_sampling-model_pointer


**Specification**

- *Alias:* nond_adaptive_sampling 

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+-------------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                | Dakota Keyword Description                    |
|                         | Group              |                               |                                               |
+=========================+====================+===============================+===============================================+
| Optional                                     | `initial_samples`__           | Initial number of samples for sampling-based  |
|                                              |                               | methods                                       |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `seed`__                      | Seed of the random number generator           |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `samples_on_emulator`__       | Number of samples at which to evaluate an     |
|                                              |                               | emulator (surrogate)                          |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `fitness_metric`__            | (Experimental) Specify the ``fitness_metric`` |
|                                              |                               | used to select the next point                 |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `batch_selection`__           | (Experimental) How to select new points       |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `refinement_samples`__        | Number of samples used to refine a probabilty |
|                                              |                               | estimate or sampling design.                  |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `import_build_points_file`__  | File containing points you wish to use to     |
|                                              |                               | build a surrogate                             |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `export_approx_points_file`__ | Output file for surrogate model value         |
|                                              |                               | evaluations                                   |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `misc_options`__              | (Experimental) Hook for algorithm-specific    |
|                                              |                               | adaptive sampling options                     |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `max_iterations`__            | Number of iterations allowed for optimizers   |
|                                              |                               | and adaptive UQ methods                       |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `response_levels`__           | Values at which to estimate desired           |
|                                              |                               | statistics for each response                  |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `probability_levels`__        | Specify probability levels at which to        |
|                                              |                               | estimate the corresponding response value     |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `gen_reliability_levels`__    | Specify generalized relability levels at      |
|                                              |                               | which to estimate the corresponding response  |
|                                              |                               | value                                         |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `distribution`__              | Selection of cumulative or complementary      |
|                                              |                               | cumulative functions                          |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `rng`__                       | Selection of a random number generator        |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `model_pointer`__             | Identifier for model block to be used by a    |
|                                              |                               | method                                        |
+----------------------------------------------+-------------------------------+-----------------------------------------------+

.. __: method-adaptive_sampling-initial_samples.html
__ method-adaptive_sampling-seed.html
__ method-adaptive_sampling-samples_on_emulator.html
__ method-adaptive_sampling-fitness_metric.html
__ method-adaptive_sampling-batch_selection.html
__ method-adaptive_sampling-refinement_samples.html
__ method-adaptive_sampling-import_build_points_file.html
__ method-adaptive_sampling-export_approx_points_file.html
__ method-adaptive_sampling-misc_options.html
__ method-adaptive_sampling-max_iterations.html
__ method-adaptive_sampling-response_levels.html
__ method-adaptive_sampling-probability_levels.html
__ method-adaptive_sampling-gen_reliability_levels.html
__ method-adaptive_sampling-distribution.html
__ method-adaptive_sampling-rng.html
__ method-adaptive_sampling-model_pointer.html



**Description**


This is an experimental capability that is not ready for production
use at this point.  It was part of an investigation into computational
topology-based approaches to feature identification and surrogate
refinement.

The goal in performing adaptive sampling is to construct a surrogate model that
can be used as an accurate predictor to some expensive simulation, thus it is
to one's advantage to build a surrogate that minimizes the error over the entire
domain of interest using as little data as possible from the expensive
simulation. The adaptive part alludes to the fact that the surrogate will be
refined by focusing samples of the expensive simulation on particular areas of
interest rather than rely on random selection or standard space-filling
techniques.

At a high-level, the adaptive sampling pipeline is a four-step process:


- Evaluate the expensive simulation (referred to as the true model) at initial sample point


  1. Fit a surrogate model

  2. Create a candidate set and score based on information from surrogate

  3. Select a candidate point to evaluate the true model

  4. Loop until done



In terms of the Dakota implementation, the adaptive sampling method
currently uses Latin Hypercube sampling (LHS) to generate the initial
points in Step 1 above. For Step 2, we use a Gaussian process model.

The default behavior is to add one point at a time.
At each iteration (e.g. each loop of Steps 2-4 above), a Latin Hypercube
sample is generated (a new one, different from the initial sample) and
the surrogate model is evaluated at this points.
These are the candidate points that are then evaluated
according to the fitness metric. The number of candidates used
in practice should be high enough to fill most
of the input domain: we recommend at least hundreds of points
for a low-dimensional problem.
All of the candidates (samples on the emulator) are
given a score and then the highest-scoring candidate is selected to be evaluated
on the true model.

The adaptive sampling method also can generate batches of points
to add at a time using the ``batch_selection`` and ``batch_size`` keywords.


