.. _method-approximate_control_variate:
"""""""""""""""""""""""""""
approximate_control_variate
"""""""""""""""""""""""""""
Approximate control variate (ACV) sampling methods for UQ
.. toctree::
:hidden:
:maxdepth: 1
method-approximate_control_variate-acv_independent_sampling
method-approximate_control_variate-acv_multifidelity
method-approximate_control_variate-acv_recursive_diff
method-approximate_control_variate-search_model_graphs
method-approximate_control_variate-pilot_samples
method-approximate_control_variate-solution_mode
method-approximate_control_variate-truth_fixed_by_pilot
method-approximate_control_variate-sqp
method-approximate_control_variate-nip
method-approximate_control_variate-global_local
method-approximate_control_variate-competed_local
method-approximate_control_variate-seed_sequence
method-approximate_control_variate-fixed_seed
method-approximate_control_variate-sample_type
method-approximate_control_variate-export_sample_sequence
method-approximate_control_variate-convergence_tolerance
method-approximate_control_variate-max_iterations
method-approximate_control_variate-max_function_evaluations
method-approximate_control_variate-final_statistics
method-approximate_control_variate-rng
method-approximate_control_variate-model_pointer
**Specification**
- *Alias:* acv_sampling
- *Arguments:* None
**Child Keywords:**
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| Required/Optional | Description of | Dakota Keyword | Dakota Keyword Description |
| | Group | | |
+=========================+====================+==============================+===============================================+
| Required (Choose One) | Solution Approach | `acv_independent_sampling`__ | Approximate control variate (ACV) algorithm |
| | | | that employs independent samples per model |
| | +------------------------------+-----------------------------------------------+
| | | `acv_multifidelity`__ | Approximate control variate (ACV) algorithm |
| | | | that mimics MFMC by employing a nested |
| | | | pyramid sample pattern This ACV variant uses |
| | | | sample set definitions that are similar to |
| | | | multifidelity Monte Carlo (MFMC), in that |
| | | | sample sets are nested with each new level |
| | | | adding an increment on top of the previous. |
| | +------------------------------+-----------------------------------------------+
| | | `acv_recursive_diff`__ | Weighted recursive difference option for |
| | | | approximate control variate sampling (ACV-RD) |
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| Optional | `search_model_graphs`__ | Perform a recursion of admissible DAGs for a |
| | | given model ensemble |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `pilot_samples`__ | Initial set of samples for |
| | | multilevel/multifidelity sampling methods. |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `solution_mode`__ | Solution mode for multilevel/multifidelity |
| | | methods |
+----------------------------------------------+------------------------------+-----------------------------------------------+
| Optional | `truth_fixed_by_pilot`__ | Option to suppress any increment to the |
| | | number of truth samples |
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| 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 | `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-approximate_control_variate-acv_independent_sampling.html
__ method-approximate_control_variate-acv_multifidelity.html
__ method-approximate_control_variate-acv_recursive_diff.html
__ method-approximate_control_variate-search_model_graphs.html
__ method-approximate_control_variate-pilot_samples.html
__ method-approximate_control_variate-solution_mode.html
__ method-approximate_control_variate-truth_fixed_by_pilot.html
__ method-approximate_control_variate-sqp.html
__ method-approximate_control_variate-nip.html
__ method-approximate_control_variate-global_local.html
__ method-approximate_control_variate-competed_local.html
__ method-approximate_control_variate-seed_sequence.html
__ method-approximate_control_variate-fixed_seed.html
__ method-approximate_control_variate-sample_type.html
__ method-approximate_control_variate-export_sample_sequence.html
__ method-approximate_control_variate-convergence_tolerance.html
__ method-approximate_control_variate-max_iterations.html
__ method-approximate_control_variate-max_function_evaluations.html
__ method-approximate_control_variate-final_statistics.html
__ method-approximate_control_variate-rng.html
__ method-approximate_control_variate-model_pointer.html
**Description**
An adaptive sampling method that utilizes multifidelity
relationships in order to improve efficiency through variance reduction.
It employs an ensemble model to manage an unordered set of
lower-fidelity approximations to a single truth model.
Compared to multifidelity Monte Carlo (MFMC), ACV relaxes the nested
sampling of a recursive emulator, instead targeting the truth model's
variance with each control variate pair. While the ensemble of
control variates appears identical to MFMC:
.. math:: \hat{Q}_{HF}^{CV} = \hat{Q}_{HF}^{MC} - \sum_{i=1}^M \beta_i (\hat{Q}_{LF_i}^{MC} - \mathbb{E}[Q_{LF_i}])
the sample patterns used for the constituent estimators differ as
depicted in Gorodetsky et al. (2020), Figure 2. Two ACV variants
are currently implemented, ACV-MF and ACV-IS, with ACV-KL to follow.
*Default Behavior*
The ``approximate_control_variate`` 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 ``approximate_control_variate`` 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 ``approximate_control_variate`` method must be used in combination
with an ensemble model specification that defines either a
model form sequence or a discretization level sequence. For a model
form sequence, each model must provide a scalar
``solution_level_cost``. For a discretization level sequence,
``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 = 'NONHIER'
approximate_control_variate
acv_mf nip
pilot_samples = 20 seed = 1237
max_iterations = 10
convergence_tolerance = .001
specifies ACV-MF using the nonlinear interior point (NIP) solver in
combination with the model identified by the NONHIER pointer.
This NONHIER model specification provides a one-dimensional sequence,
here defined by a single truth model and a set of unordered approximation
models, each with a single (or default) discretization level:
.. code-block::
model,
id_model = 'NONHIER'
surrogate ensemble
truth_model = 'HF'
unordered_model_fidelities = 'LF1' 'LF2'
model,
id_model = 'LF1'
interface_pointer = 'LF1_INT'
simulation
solution_level_cost = 1
model,
id_model = 'LF2'
interface_pointer = 'LF2_INT'
simulation
solution_level_cost = 16
model,
id_model = 'HF'
interface_pointer = 'HF_INT'
simulation
solution_level_cost = 256.
Refer to ``dakota/test/dakota_uq_diffusion_acv3_cost4``.in and
``dakota/test/dakota_uq_tunable_acv``.in in the source distribution
for this case as well as additional examples.
Refer to [Gorodetsky et al., JCP (408), 2020] for more
detailed algorithm descriptions, theoretical considerations, and
a helpful sample set diagram.