.. _method-multilevel_sampling: """"""""""""""""""" multilevel_sampling """"""""""""""""""" Multilevel Monte Carlo (MLMC) sampling method for UQ .. toctree:: :hidden: :maxdepth: 1 method-multilevel_sampling-model_pointer method-multilevel_sampling-rng method-multilevel_sampling-max_function_evaluations method-multilevel_sampling-max_iterations method-multilevel_sampling-convergence_tolerance method-multilevel_sampling-sample_type method-multilevel_sampling-solution_mode method-multilevel_sampling-pilot_samples method-multilevel_sampling-seed_sequence method-multilevel_sampling-fixed_seed method-multilevel_sampling-id_method method-multilevel_sampling-output method-multilevel_sampling-final_solutions method-multilevel_sampling-weighted method-multilevel_sampling-export_sample_sequence method-multilevel_sampling-allocation_target method-multilevel_sampling-qoi_aggregation method-multilevel_sampling-convergence_tolerance_target **Specification** - *Alias:* multilevel_mc mlmc - *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`__ | Stopping criterion based on number of refinement | | | | | | iterations within the multilevel sample allocation | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ | Optional | | | `convergence_tolerance`__ | Stopping criterion based on relative error | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ | 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 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 | | | `weighted`__ | Include control variate weights for each of the recursive | | | | | | differences using in multilevel Monte Carlo (MLMC) | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ | Optional | | | `export_sample_sequence`__ | Enable export of multilevel/multifidelity sample sequences | | | | | | to individual files | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ | Optional | | | `allocation_target`__ | Allocation statistics/target for the MLMC sample | | | | | | allocation. | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ | Optional | | | `qoi_aggregation`__ | Aggregation strategy for the QoIs statistics for problems | | | | | | with multiple responses in the MLMC algorithm | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ | Optional | | | `convergence_tolerance_target`__ | Select target for MLMC sample allocation | +-------------------------+------------------------+--------------------+----------------------------------+------------------------------------------------------------+ .. __: method-multilevel_sampling-model_pointer.html __ method-multilevel_sampling-rng.html __ method-multilevel_sampling-max_function_evaluations.html __ method-multilevel_sampling-max_iterations.html __ method-multilevel_sampling-convergence_tolerance.html __ method-multilevel_sampling-sample_type.html __ method-multilevel_sampling-solution_mode.html __ method-multilevel_sampling-pilot_samples.html __ method-multilevel_sampling-seed_sequence.html __ method-multilevel_sampling-fixed_seed.html __ method-multilevel_sampling-id_method.html __ method-multilevel_sampling-output.html __ method-multilevel_sampling-final_solutions.html __ method-multilevel_sampling-weighted.html __ method-multilevel_sampling-export_sample_sequence.html __ method-multilevel_sampling-allocation_target.html __ method-multilevel_sampling-qoi_aggregation.html __ method-multilevel_sampling-convergence_tolerance_target.html **Description** An adaptive sampling method that utilizes multilevel 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. *Multilevel Monte Carlo* The Monte Carlo estimator for the mean is defined as .. math:: \mathbb{E}[Q] \equiv \hat{Q}^{MC} = \frac{1}{N} \sum_{i=1}^N Q^{(i)} In a multilevel method with :math:`L` levels, we replace this estimator with a telescoping sum: .. math:: \mathbb{E}[Q] \equiv \hat{Q}^{ML} = \sum_{l=0}^L \frac{1}{N_l} \sum_{i=1}^{N_l} (Q_l^{(i)} - Q_{l-1}^{(i)}) \equiv \sum_{l=0}^L \hat{Y}^{MC}_l This decomposition forms discrepancies for each level greater than 0, seeking reduction in the variance of the discrepancy :math:`Y` relative to the variance of the original response :math:`Q` . The number of samples allocated for each level ( :math:`N_l` ) is based on a total cost minimization procedure that incorporates the relative cost and observed variance for each of the :math:`Y_\ell` . *Weighting and Model Selection* Similar to MFMC (see :dakkw:`method-multifidelity_sampling`), weighted MLMC is a special case of generalized ACV using the ACV-RD sampling scheme (:cite:p:`Bomarito2022`) in combination with a hierarchical DAG (each approximation node points to the next approximation of higher fidelity, ending with the truth model at the root node). As such, the selection of a weighted MLMC approach is promoted to the generalized ACV solver in order to gain access to both weighting and optional model selection capabilities by activating the :dakkw:`method-multilevel_sampling-weighted` and :dakkw:`method-multilevel_sampling-weighted-search_model_graphs-model_selection` options, respectively. This results in one or more numerical solutions for a fixed hierarchical DAG. *Default Behavior* The ``multilevel_sampling`` method employs a number of important default settings: * By default, MLMC is unweighted and provides a convenient analytic solution for the optimal sample allocations. The option of weighted MLMC is also available as a numerical solution and can be combined with model selection as described above. * 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 ``multilevel_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 sampling method must be used in combination with an ordered ensemble surrogate model specification, and supports either a sequence of model forms or a sequence of discretization levels. For the former, each model form must provide a scalar ``solution_level_cost`` and for the latter, 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``. 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 .. tab:: Freeform .. code-block:: dakota method model_pointer = 'HIERARCH' multilevel_sampling pilot_samples = 20 seed = 1237 max_iterations = 10 convergence_tolerance = .001 model id_model = 'HIERARCH' ensemble_surrogate ordered_model_fidelities = 'SIM1' correction additive zeroth_order model id_model = 'SIM1' simulation solution_level_control = 'N_x' solution_level_cost = 630. 1260. 2100. 4200. .. tab:: JSON .. code-block:: json { "method": [ { "multilevel_sampling": { "model_pointer": "HIERARCH", "pilot_samples": [20], "seed_sequence": [1237], "max_iterations": 10, "convergence_tolerance": { "value": 0.001 } } } ], "model": [ { "ensemble_surrogate": { "id_model": "HIERARCH", "ensemble": { "ordered_model_fidelities": { "pointers": ["SIM1"], "correction": { "correction_type": {"additive": true}, "correction_order": {"zeroth_order": true} } } } } }, { "single": { "id_model": "SIM1", "cost_model": { "solution_level_cost": [630.0, 1260.0, 2100.0, 4200.0] } } } ] } specifies a multilevel Monte Carlo study in combination with the model identified by the HIERARCH pointer. This model specification provides a one-dimensional hierarchy, typically defined by a single model fidelity with multiple discretization levels, but may also be provided as multiple ordered model fidelities, each with a single (or default) discretization level. Refer to ``dakota/test/dakota_uq_*_mlmc``.in in the source distribution for additional examples.