.. _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.


