.. _method-multilevel_sampling:

"""""""""""""""""""
multilevel_sampling
"""""""""""""""""""


Multilevel sampling methods for UQ


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

   method-multilevel_sampling-seed_sequence
   method-multilevel_sampling-fixed_seed
   method-multilevel_sampling-pilot_samples
   method-multilevel_sampling-solution_mode
   method-multilevel_sampling-sample_type
   method-multilevel_sampling-export_sample_sequence
   method-multilevel_sampling-allocation_target
   method-multilevel_sampling-qoi_aggregation
   method-multilevel_sampling-convergence_tolerance
   method-multilevel_sampling-convergence_tolerance_type
   method-multilevel_sampling-convergence_tolerance_target
   method-multilevel_sampling-max_iterations
   method-multilevel_sampling-max_function_evaluations
   method-multilevel_sampling-final_statistics
   method-multilevel_sampling-rng
   method-multilevel_sampling-model_pointer


**Specification**

- *Alias:* multilevel_mc mlmc 

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+----------------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                   | Dakota Keyword Description                    |
|                         | Group              |                                  |                                               |
+=========================+====================+==================================+===============================================+
| Optional                                     | `seed_sequence`__                | Sequence of seed values for multi-stage       |
|                                              |                                  | random sampling                               |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `fixed_seed`__                   | Reuses the same seed value for multiple       |
|                                              |                                  | random sampling sets                          |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `pilot_samples`__                | Initial set of samples for multilevel         |
|                                              |                                  | sampling methods.                             |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `solution_mode`__                | Solution mode for multilevel/multifidelity    |
|                                              |                                  | methods                                       |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `sample_type`__                  | Selection of sampling strategy                |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `export_sample_sequence`__       | Enable export of multilevel/multifidelity     |
|                                              |                                  | sample sequences to individual files          |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `allocation_target`__            | Allocation statistics/target for the MLMC     |
|                                              |                                  | sample allocation.                            |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `qoi_aggregation`__              | Aggregation strategy for the QoIs statistics  |
|                                              |                                  | for problems with multiple responses in the   |
|                                              |                                  | MLMC algorithm                                |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `convergence_tolerance`__        | Stopping criterion based on relative error    |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `convergence_tolerance_type`__   | Select absolute or relative convergence       |
|                                              |                                  | tolerance                                     |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `convergence_tolerance_target`__ | Select target for MLMC sample allocation      |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `max_iterations`__               | Stopping criterion based on number of         |
|                                              |                                  | refinement iterations within the multilevel   |
|                                              |                                  | sample allocation                             |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `max_function_evaluations`__     | Stopping criterion based on maximum function  |
|                                              |                                  | evaluations                                   |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `final_statistics`__             | Indicate the type of final statistics to be   |
|                                              |                                  | returned by a UQ method                       |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `rng`__                          | Selection of a random number generator        |
+----------------------------------------------+----------------------------------+-----------------------------------------------+
| Optional                                     | `model_pointer`__                | Identifier for model block to be used by a    |
|                                              |                                  | method                                        |
+----------------------------------------------+----------------------------------+-----------------------------------------------+

.. __: method-multilevel_sampling-seed_sequence.html
__ method-multilevel_sampling-fixed_seed.html
__ method-multilevel_sampling-pilot_samples.html
__ method-multilevel_sampling-solution_mode.html
__ method-multilevel_sampling-sample_type.html
__ method-multilevel_sampling-export_sample_sequence.html
__ method-multilevel_sampling-allocation_target.html
__ method-multilevel_sampling-qoi_aggregation.html
__ method-multilevel_sampling-convergence_tolerance.html
__ method-multilevel_sampling-convergence_tolerance_type.html
__ method-multilevel_sampling-convergence_tolerance_target.html
__ method-multilevel_sampling-max_iterations.html
__ method-multilevel_sampling-max_function_evaluations.html
__ method-multilevel_sampling-final_statistics.html
__ method-multilevel_sampling-rng.html
__ method-multilevel_sampling-model_pointer.html



**Description**


An adaptive sampling method that utilizes multilevel
relationships within an ensemble surrogate model in order to
improve efficiency through variance reduction.

In the case of a multilevel relationship, multilevel Monte Carlo
methods are used to compute an optimal sample allocation per level.

*Multilevel Monte Carlo*

The Monte Carlo estimator for the mean is defined as

.. math::  \mathbb{E}[Q] \equiv \hat{Q}^{MC} = \frac{1}{N} \sum_{i=1}^N Q^{(i)} 

In a multilevel method with :math:`L`  levels, we replace this estimator
with a telescoping sum:

.. math::  \mathbb{E}[Q] \equiv \hat{Q}^{ML}
   = \sum_{l=0}^L \frac{1}{N_l} \sum_{i=1}^{N_l} (Q_l^{(i)} - Q_{l-1}^{(i)})
   \equiv \sum_{l=0}^L \hat{Y}^{MC}_l 

This decomposition forms discrepancies for each level greater than 0,
seeking reduction in the variance of the discrepancy :math:`Y`  relative
to the variance of the original response :math:`Q` .  The number of samples
allocated for each level ( :math:`N_l` ) is based on a total cost minimization
procedure that incorporates the relative cost and observed variance for each
of the :math:`Y_\ell` .

*Default Behavior*

The ``multilevel_sampling`` method employs Monte Carlo sample sets by
default, but this default can be overridden to use Latin hypercube
sample sets using ``sample_type`` ``lhs``.

*Expected Output*

The ``multilevel_sampling`` method reports estimates of the first four
moments and a summary of the evaluations performed for each model
fidelity and discretization level.  The method does not support any
level mappings (response, probability, reliability, generalized
reliability) at this time.

*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-sampling_moments` (moments only, not confidence intervals)

In addition, the execution group has the attribute ``equiv_hf_evals``, which
records the equivalent number of high-fidelity evaluations.

*Usage Tips*

The multilevel sampling method must be used in combination with an
ordered ensemble surrogate model specification, and supports either a sequence of
model forms or a sequence of discretization levels.  For the former,
each model form must provide a scalar ``solution_level_cost`` and for the
latter, it is necessary to identify the variable string descriptor that
controls the resolution levels using ``solution_level_control`` as well
as the associated array of relative costs using ``solution_level_cost``.



**Examples**


The following method block

.. code-block::

    method,
     model_pointer = 'HIERARCH'
     multilevel_sampling
       pilot_samples = 20 seed = 1237
       max_iterations = 10
       convergence_tolerance = .001


specifies a multilevel Monte Carlo study in combination with the model
identified by the HIERARCH pointer.  This model specification provides
a one-dimensional hierarchy, typically defined by a single model
fidelity with multiple discretization levels, but may also be provided
as multiple ordered model fidelities, each with a single (or default)
discretization level.  An example of the former (single model fidelity
with multiple discretization levels) follows:

.. code-block::

    model,
     id_model = 'HIERARCH'
     surrogate ensemble
       ordered_model_fidelities = 'SIM1'
       correction additive zeroth_order
    
    model,
     id_model = 'SIM1'
     simulation
       solution_level_control = 'N_x'
       solution_level_cost = 630. 1260. 2100. 4200.


Refer to ``dakota/test/dakota_uq_*_mlmc``.in in the source distribution
for additional examples.


