.. _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-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`__ | Sampling scheme within the approximate |
| | | | control variate (ACV) algorithm that employs |
| | | | independent samples (IS) across model |
| | | | pairings |
| | +------------------------------+-----------------------------------------------+
| | | `acv_multifidelity`__ | Approximate control variate (ACV) algorithm |
| | | | that employs a nested pyramid sample pattern, |
| | | | similar to MFMC |
| | +------------------------------+-----------------------------------------------+
| | | `acv_recursive_diff`__ | Sampling scheme within the approximate |
| | | | control variate (ACV) algorithm that employs |
| | | | weighted recursive differences (RD) across |
| | | | model pairings |
+-------------------------+--------------------+------------------------------+-----------------------------------------------+
| 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 | `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-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 is not a recursive
emulator based on hierarchical control variate pairings. Rather, the
truth model's variance is targeted using each control variate pairing.
These pairings are codified with a directed acyclic graph (DAG), such
that ACV defines a "peer" DAG where all approximation nodes point to the
root node and the root node identifies the reference "truth" model.
MFMC, on the other hand, employs a "hierarchical" DAG, where each
approximation node points to the next approximation of higher
fidelity, ending with the truth model at the root node.
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 :cite:p:`GORODETSKY2020109257`, Figure 2, with the
:math:`z^1` and :math:`z^2` definitions reflective of the control
variate pairings.
In the generalized ACV case (:cite:p:`Bomarito2022`) available from
the :dakkw:`method-approximate_control_variate-search_model_graphs`
specification, three different ACV sampling schemes are supported:
ACV-MF (multifidelity), ACV-IS (independent sampling), and ACV-RD
(recursive difference), where each scheme supports an enumerative
search over admissible DAGs and model subset selections. Each
of these three schemes is also supported in non-generalized form
for specific DAG definitions, as follows:
* ACV-MF: peer DAG in :dakkw:`method-approximate_control_variate` and hierarchical DAG in :dakkw:`method-multifidelity_sampling`
* ACV-IS: peer DAG in :dakkw:`method-approximate_control_variate`.
* ACV-RD: hierarchical DAG in :dakkw:`method-multilevel_sampling` using the :dakkw:`weighted` option.
Finally, the ACV-KL variant (:cite:p:`GORODETSKY2020109257`) is not
another sampling scheme, but rather a parametrically defined estimator
that enumerates a relatively small subset of admissible DAGs. It is
available under the
:dakkw:`method-approximate_control_variate-search_model_graphs-kl_recursion`
option, using the approaches described in :cite:p:`Bomarito2022`.
*Default Behavior*
The ``approximate_control_variate`` method employs a number of important
default settings:
* The DAG defining control variate pairings defaults to a "peer" DAG where all approximation nodes point to the root node and the root node identifies the reference "truth" model. This means that every approximation participates in a sample set that is shared with the truth model (the root allocation), and each approximation (each of the nodes connecting to the root) then has its own augmentation to this shared set. For ACV-IS and ACV-RD, these augmentations are independent. To explore other admissible DAGs, ``search_model_graphs`` can be used.
* 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 model ensembles, a purely local approach is 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.
* 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 ``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 enumerates a truth model and
a set of model approximations using either a model form sequence, a
discretization level sequence, or a combination of model forms and
discretization levels. For each model form and discretization, each
instance must either provide a ``solution_level_cost`` or return
metadata for estimating cost. 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``. An alternative to prescribing the cost
profile is estimating it on the fly using cost metadata that is
returned from the different simulation instances.
**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 within the source distribution
for this case as well as additional examples.
**Theory**
Refer to :cite:p:`GORODETSKY2020109257` for more
detailed algorithm descriptions, theoretical considerations, and
helpful sample set diagrams.
Refer to :cite:p:`Bomarito2022` for understanding ACV generalizations
for the different control variate pairings that are possible when
codified into a more comprehensive set of potential DAGs.