.. _method-multilevel_multifidelity_sampling: """"""""""""""""""""""""""""""""" multilevel_multifidelity_sampling """"""""""""""""""""""""""""""""" Multilevel-Multifidelity sampling methods for UQ .. toctree:: :hidden: :maxdepth: 1 method-multilevel_multifidelity_sampling-model_pointer method-multilevel_multifidelity_sampling-rng method-multilevel_multifidelity_sampling-max_function_evaluations method-multilevel_multifidelity_sampling-max_iterations method-multilevel_multifidelity_sampling-convergence_tolerance method-multilevel_multifidelity_sampling-sample_type method-multilevel_multifidelity_sampling-solution_mode method-multilevel_multifidelity_sampling-pilot_samples method-multilevel_multifidelity_sampling-seed_sequence method-multilevel_multifidelity_sampling-fixed_seed method-multilevel_multifidelity_sampling-id_method method-multilevel_multifidelity_sampling-output method-multilevel_multifidelity_sampling-final_solutions method-multilevel_multifidelity_sampling-export_sample_sequence **Specification** - *Alias:* multilevel_multifidelity_mc mlmfmc - *Arguments:* None - *JSON argument key:* None **Child Keywords:** +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Required/Optional | Description of Group | JSON Group Key | Dakota Keyword | Dakota Keyword Description | +=========================+========================+====================+================================+============================================================+ | Optional | | | `model_pointer`__ | Identifier for model block to be used by a method | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `rng`__ | Selection of a random number generator | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `max_function_evaluations`__ | Stopping criterion based on maximum function evaluations | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `max_iterations`__ | Number of iterations allowed for optimizers and adaptive | | | | | | UQ methods | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `convergence_tolerance`__ | Stopping criterion based on relative error reduction | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `sample_type`__ | Selection of sampling strategy | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `solution_mode`__ | Solution mode for multilevel/multifidelity methods | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `pilot_samples`__ | Initial set of samples for multilevel/multifidelity | | | | | | sampling methods. | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | 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 | | | `id_method`__ | Name the method block; helpful when there are multiple | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `output`__ | Control how much method information is written to the | | | | | | screen and output file | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `final_solutions`__ | Number of designs returned as the best solutions | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `export_sample_sequence`__ | Enable export of multilevel/multifidelity sample sequences | | | | | | to individual files | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ .. __: method-multilevel_multifidelity_sampling-model_pointer.html __ method-multilevel_multifidelity_sampling-rng.html __ method-multilevel_multifidelity_sampling-max_function_evaluations.html __ method-multilevel_multifidelity_sampling-max_iterations.html __ method-multilevel_multifidelity_sampling-convergence_tolerance.html __ method-multilevel_multifidelity_sampling-sample_type.html __ method-multilevel_multifidelity_sampling-solution_mode.html __ method-multilevel_multifidelity_sampling-pilot_samples.html __ method-multilevel_multifidelity_sampling-seed_sequence.html __ method-multilevel_multifidelity_sampling-fixed_seed.html __ method-multilevel_multifidelity_sampling-id_method.html __ method-multilevel_multifidelity_sampling-output.html __ method-multilevel_multifidelity_sampling-final_solutions.html __ method-multilevel_multifidelity_sampling-export_sample_sequence.html **Description** An adaptive sampling method that utilizes both multilevel and multifidelity relationships within an ensemble surrogate model in order to improve efficiency through variance reduction. In the case of a multilevel relationship, multilevel Monte Carlo methods are used to compute an optimal sample allocation per level, and in the case of a multifidelity relationship, control variate Monte Carlo methods are used to compute an optimal sample allocation per fidelity. These two approaches can also be combined, resulting in the multilevel-multifidelity sampling approach below. *Multilevel Control Variate Monte Carlo* If both multilevel and multifidelity structure are included within an ensemble model specification, then an inner control variate can be applied across two model fidelities for each level within an outer multilevel approach. On each level, a control variate is active for the discrepancy :math:`Y_{\ell}` based on .. math:: Y_{\ell}^\star = Y_{\ell} + \alpha_\ell \left( \hat{Y}^{\mathrm{LF}}_\ell - \mathbb{E}\left[ Y^{\mathrm{LF}}_\ell \right] \right), where :math:`Y^{\mathrm{LF}}_\ell = \gamma_\ell Q^{\mathrm{LF}}_\ell - Q^{\mathrm{HF}}_\ell` . The optimal parameter :math:`\gamma_\ell` is computed from the correlation properties between model forms and discretization levels (see the theory manual for further details) and the optimal allocation :math:`N_\ell` (per level) is finally obtained from it. *Default Behavior* The ``multilevel_multifidelity_sampling`` method employs Monte Carlo sample sets be default, but this default can be overridden to use Latin hypercube sample sets using ``sample_type`` ``lhs``. *Expected Output* The ``multilevel_multifidelity_sampling`` 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 ``multilevel_multifidelity_sampling`` method must be used in combination with an ensemble model specification. The highest and lowest fidelity model must provide multiple discretization levels, for which it is necessary to identify the variable string descriptor that controls the resolution levels using ``solution_level_control`` as well as the associated array of relative costs using ``solution_level_cost``. **Examples** The following method block .. tab:: Freeform .. code-block:: dakota method model_pointer = 'HIERARCH' multilevel_multifidelity_sampling pilot_samples = 20 seed = 1237 convergence_tolerance = .01 .. tab:: JSON .. code-block:: json { "method": [ { "multilevel_multifidelity_sampling": { "model_pointer": "HIERARCH", "pilot_samples": [20], "seed_sequence": [1237], "convergence_tolerance": { "value": 0.01 } } } ] } specifies a multilevel-multifidelity Monte Carlo study in combination with the model identified by the HIERARCH pointer. This model specification provides a two-dimensional hierarchy, comprised of two model forms each with four discretization levels: .. tab:: Freeform :new-set: .. code-block:: dakota model id_model = 'HIERARCH' ensemble_surrogate ordered_model_fidelities = 'LF' 'HF' model id_model = 'LF' simulation solution_level_control = 'N_x' solution_level_cost = 375. 10125. 81000. 648000. model id_model = 'HF' simulation solution_level_control = 'N_x' solution_level_cost = 5.67e+5 4.536e+6 2.1e+7 1.68e+8 .. tab:: JSON .. code-block:: json { "model": [ { "ensemble_surrogate": { "id_model": "HIERARCH", "ensemble": { "ordered_model_fidelities": { "pointers": ["LF", "HF"] } } } }, { "single": { "id_model": "LF", "cost_model": { "solution_level_cost": [375.0, 10125.0, 81000.0, 648000.0] } } }, { "single": { "id_model": "HF", "cost_model": { "solution_level_cost": [567000.0, 4536000.0, 21000000.0, 168000000.0] } } } ] } Refer to ``dakota/test/dakota_uq_heat_eq_mlcvmc``.in in the source distribution for this case as well as additional examples.