.. _method-multilevel_blue:
"""""""""""""""
multilevel_blue
"""""""""""""""
The multilevel best linear unbiased estimator (ML BLUE) sampling method for UQ
.. toctree::
:hidden:
:maxdepth: 1
method-multilevel_blue-group_throttle
method-multilevel_blue-pilot_samples
method-multilevel_blue-solution_mode
method-multilevel_blue-sqp
method-multilevel_blue-nip
method-multilevel_blue-global_local
method-multilevel_blue-competed_local
method-multilevel_blue-seed_sequence
method-multilevel_blue-fixed_seed
method-multilevel_blue-sample_type
method-multilevel_blue-export_sample_sequence
method-multilevel_blue-convergence_tolerance
method-multilevel_blue-max_iterations
method-multilevel_blue-max_function_evaluations
method-multilevel_blue-rng
method-multilevel_blue-model_pointer
**Specification**
- *Alias:* None
- *Arguments:* None
**Child Keywords:**
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| Required/Optional | Description of | Dakota Keyword | Dakota Keyword Description |
| | Group | | |
+=========================+====================+==============================+===============================================+
| Optional | `group_throttle`__ | Reduce the number of groups in multilevel |
| | | BLUE using a throttle |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `pilot_samples`__ | Initial set of samples for groups in the |
| | | multilevel BLUE sampling method |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `solution_mode`__ | Solution mode for multilevel/multifidelity |
| | | methods |
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| Optional (Choose One) | Optimization | `sqp`__ | Use a sequential quadratic programming method |
| | Solver | | for solving an optimization sub-problem |
| | +------------------------------+-----------------------------------------------+
| | | `nip`__ | Use a nonlinear interior point method for |
| | | | solving an optimization sub-problem |
| | +------------------------------+-----------------------------------------------+
| | | `global_local`__ | Use a hybrid global-local scheme for solving |
| | | | an optimization sub-problem |
| | +------------------------------+-----------------------------------------------+
| | | `competed_local`__ | Use a competed local solver scheme for |
| | | | solving an optimization sub-problem |
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| 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 | `sample_type`__ | Selection of sampling strategy |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `export_sample_sequence`__ | Enable export of multilevel/multifidelity |
| | | sample sequences to individual files |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `convergence_tolerance`__ | Stopping criterion based on relative error |
| | | reduction |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `max_iterations`__ | Number of iterations allowed for optimizers |
| | | and adaptive UQ methods |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `max_function_evaluations`__ | Stopping criterion based on maximum function |
| | | evaluations |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `rng`__ | Selection of a random number generator |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `model_pointer`__ | Identifier for model block to be used by a |
| | | method |
+----------------------------------------------+------------------------------+-----------------------------------------------+
.. __: method-multilevel_blue-group_throttle.html
__ method-multilevel_blue-pilot_samples.html
__ method-multilevel_blue-solution_mode.html
__ method-multilevel_blue-sqp.html
__ method-multilevel_blue-nip.html
__ method-multilevel_blue-global_local.html
__ method-multilevel_blue-competed_local.html
__ method-multilevel_blue-seed_sequence.html
__ method-multilevel_blue-fixed_seed.html
__ method-multilevel_blue-sample_type.html
__ method-multilevel_blue-export_sample_sequence.html
__ method-multilevel_blue-convergence_tolerance.html
__ method-multilevel_blue-max_iterations.html
__ method-multilevel_blue-max_function_evaluations.html
__ method-multilevel_blue-rng.html
__ method-multilevel_blue-model_pointer.html
**Description**
An adaptive multifidelity sampling method that improves performance
relative to single-fidelity Monte Carlo sampling, either of terms of
greater accuracy (reduced variance in the estimated statistics) for
a prescribed budget or reduced cost for specified accuracy. It employs
an ensemble model to manage a set of lower-fidelity approximations to
a single truth model.
Compared to other estimators (MLMC, MLCV MC, MFMC, ACV, generalized
ACV), ML BLUE is distinguished in that it employs a group-based
approach, where independent samples are allocated for each group and
each group is composed of unordered combinations of models. The number
of groups grows combinatorially with the total number of models, and a
few throttle options are provided to prevent the number of groups from
growing to excess.
As described in :cite:p:`Schaden2020`, the ML BLUE estimator for QoI
expected values is
.. math:: \Psi q^B = y
where
.. math:: \Psi = \sum_{k=1}^K m_k R_k^T C_k^{-1} R_k
.. math:: y = \sum_{k=1}^K R_k^T C_k^{-1} S_k
.. math:: S_k = \sum_{i=1}^{m_k} Y_k^{(i)}
given group sample count :math:`m_k`, group restriction operator
:math:`R_k`, group covariance estimate :math:`C_k`, and group QoI
sum :math:`S_k` for each group :math:`k`. For a linear combination
of the model means :math:`q_{\beta}^B = \beta^T q^B`, the variance
of ML BLUE is :math:`\beta^T \Psi^{-1} \beta`. The numerical solution
for :math:`m` minimizes this variance subject to a prescribed budget
(or minimizes cost for specified accuracy), where the common choice
of :math:`\beta = [1, 0, 0, \dots]^T` targets the HF mean.
**Status**
This method is currently under active development. It exhibits
competitive performance for smaller numbers of models (roughly 5 or
less), whereas larger model ensembles lead to ill-conditioning in the
matrix solutions and inaccurate results. Throttling can delay these
problems in some cases, but more advanced numerical treatments are
needed (work in progress).
*Default Behavior*
The ``multilevel_blue`` method employs a number of important default settings:
* The pilot sampling strategy involves shared samples for initial estimation of group covariances (refer to :dakkw:`method-multilevel_blue-pilot_samples`).
* The number of groups is not throttled by default (refer to :dakkw:`method-multilevel_blue-group_throttle`).
* The default solver is ``global_local``, starting with the DIRECT global solver and proceeding to available local solvers (SQP and NIP) in competition. For larger group counts, a purely local approach can be more scalable.
* Solution mode will be ``online_pilot``, an approach which iterates toward a set of shared samples whose size is consistent with the optimal allocation. Since group-based approaches will try to allocate the entire budget on the first iteration, the use of under-relaxation (see :dakkw:`method-multilevel_blue-solution_mode-online_pilot-relaxation`) can be especially beneficial.
* Monte Carlo sample sets are used by default and are most consistent with the underlying theory, but this default can be overridden to use Latin hypercube sample sets using ``sample_type`` ``lhs``. Allocations remain governed by Monte Carlo variance for all cases.
*Expected Output*
The ``multilevel_blue`` method reports estimates of the first four
moments and a summary of the evaluations performed for each group and
for each model instance. The method does not support any level
mappings (response, probability, reliability, generalized reliability)
at this time.
*Usage Tips*
The ``multilevel_blue`` method must be used in combination with an
ensemble model specification that enumerates a truth model and
approximation models using either a model form ensemble, a set of
resolution levels, or some combination. By default, all model forms
and resolution levels will be enumerated within the model ensemble.
For each model instance, cost data must by provided either using
``solution_level_cost`` or metadata that is returned from simulations
for estimating cost on the fly. For a sequence of discretization
levels, ``solution_level_control`` must identify the variable string
descriptor that controls the resolution levels and the associated
array of relative costs must be provided using
``solution_level_cost``.
**Examples**
The following method block:
.. code-block::
method,
model_pointer = 'HIERARCH'
multilevel_blue
solution_mode online_pilot
relaxation factor_sequence = .5 .75 1.
pilot_samples = 25 #independent
seed = 8674132
max_function_evaluations = 500
specifies ML BLUE using an iterated online pilot in combination with
the default optimization solver strategy (global_local), the default
shared pilot estimation of group covariances, and an ensemble model
identified by the HIERARCH pointer.
This HIERARCH model specification provides a one-dimensional sequence,
here defined by a set of 3 discretization levels:
.. code-block::
model,
id_model = 'HIERARCH'
variables_pointer = 'HF_VARS'
surrogate ensemble
truth_model = 'HF'
model,
id_model = 'HF'
variables_pointer = 'HF_VARS'
interface_pointer = 'HF_INT'
simulation
solution_level_control = 'mesh_size'
solution_level_cost = 1 16 256
Refer to ``dakota/test/dakota_uq_diffusion_mlblue_cost4``.in within
the source distribution for this case as well as additional examples.
**Theory**
Refer to :cite:p:`Schaden2020` for more detailed algorithm
descriptions, theoretical considerations, and illustrative examples.