.. _method-multilevel_sampling-qoi_aggregation:

"""""""""""""""
qoi_aggregation
"""""""""""""""


Aggregation strategy for the QoIs statistics for problems with multiple responses in the MLMC algorithm


.. toctree::
   :hidden:
   :maxdepth: 1

   method-multilevel_sampling-qoi_aggregation-sum
   method-multilevel_sampling-qoi_aggregation-max


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* sum


**Child Keywords:**

+-------------------------+--------------------+--------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                    |
|                         | Group              |                    |                                               |
+=========================+====================+====================+===============================================+
| Required (Choose One)   | Qoi Aggregation    | `sum`__            | Aggregate the variances over all QoIs to      |
|                         |                    |                    | generate a target for each level in a MLMC    |
|                         |                    |                    | algorithm.                                    |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `max`__            | Compute sample allocation for each response   |
|                         |                    |                    | and use maximum over responses for each level |
|                         |                    |                    | in a MLMC algorithm                           |
+-------------------------+--------------------+--------------------+-----------------------------------------------+

.. __: method-multilevel_sampling-qoi_aggregation-sum.html
__ method-multilevel_sampling-qoi_aggregation-max.html



**Description**


In the multilevel method a variance of the ``allocation_target`` is computed for each of the responses and their levels :math:`Y^i_\ell, i = 1,..., R, \ell = 0,..., L` . Setting ``qoi_aggregation`` describes the rule on how to aggregate those variances over multiple response functions. Supported options are ``sum`` (default) and ``max``. For ``sum``, the variances are aggregated and a single sample allocation is computed. For ``max``, an individual sample allocation for each response using the respective variances over levels is computed and the maximum over all responses for each level is taken (worst case scenario allocation).

*Default Behavior*
"sum"



**Examples**


The following method block

.. code-block::

    method,
     model_pointer = 'HIERARCH'
            multilevel_sampling
       pilot_samples = 20 seed = 1237
       convergence_tolerance = .01
       allocation_target = mean
          qoi_aggregation = sum


uses the sum rule to aggregate the variance over the qois.


