.. _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-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`__ | Uses a sequential quadratic programming | | | Solver | | method for underlying optimization | | | +------------------------------+---------------------------------------------+ | | | `nip`__ | Uses a nonlinear interior point method for | | | | | underlying optimization | +-------------------------+--------------------+------------------------------+---------------------------------------------+ | 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-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.