.. _method-multilevel_polynomial_chaos:

"""""""""""""""""""""""""""
multilevel_polynomial_chaos
"""""""""""""""""""""""""""


Multilevel uncertainty quantification using polynomial chaos expansions


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

   method-multilevel_polynomial_chaos-max_iterations
   method-multilevel_polynomial_chaos-allocation_control
   method-multilevel_polynomial_chaos-convergence_tolerance
   method-multilevel_polynomial_chaos-metric_scale
   method-multilevel_polynomial_chaos-discrepancy_emulation
   method-multilevel_polynomial_chaos-expansion_order_sequence
   method-multilevel_polynomial_chaos-orthogonal_least_interpolation
   method-multilevel_polynomial_chaos-askey
   method-multilevel_polynomial_chaos-wiener
   method-multilevel_polynomial_chaos-normalized
   method-multilevel_polynomial_chaos-export_expansion_file
   method-multilevel_polynomial_chaos-samples_on_emulator
   method-multilevel_polynomial_chaos-sample_type
   method-multilevel_polynomial_chaos-rng
   method-multilevel_polynomial_chaos-probability_refinement
   method-multilevel_polynomial_chaos-final_moments
   method-multilevel_polynomial_chaos-response_levels
   method-multilevel_polynomial_chaos-probability_levels
   method-multilevel_polynomial_chaos-reliability_levels
   method-multilevel_polynomial_chaos-gen_reliability_levels
   method-multilevel_polynomial_chaos-distribution
   method-multilevel_polynomial_chaos-variance_based_decomp
   method-multilevel_polynomial_chaos-diagonal_covariance
   method-multilevel_polynomial_chaos-full_covariance
   method-multilevel_polynomial_chaos-import_approx_points_file
   method-multilevel_polynomial_chaos-export_approx_points_file
   method-multilevel_polynomial_chaos-seed_sequence
   method-multilevel_polynomial_chaos-fixed_seed
   method-multilevel_polynomial_chaos-model_pointer


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+------------------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                     | Dakota Keyword Description                    |
|                         | Group              |                                    |                                               |
+=========================+====================+====================================+===============================================+
| Optional                                     | `max_iterations`__                 | Number of iterations allowed for optimizers   |
|                                              |                                    | and adaptive UQ methods                       |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `allocation_control`__             | Sample allocation approach for multilevel     |
|                                              |                                    | expansions                                    |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `convergence_tolerance`__          | Stopping criterion based on objective         |
|                                              |                                    | function or statistics convergence            |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `metric_scale`__                   | define scaling of statistical metrics when    |
|                                              |                                    | adapting UQ surrogates                        |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `discrepancy_emulation`__          | Formulation for emulation of model            |
|                                              |                                    | discrepancies.                                |
+-------------------------+--------------------+------------------------------------+-----------------------------------------------+
| Required (Choose One)   | Coefficient        | `expansion_order_sequence`__       | Sequence of expansion orders used in a        |
|                         | Computation        |                                    | multi-stage expansion                         |
|                         | Approach           +------------------------------------+-----------------------------------------------+
|                         |                    | `orthogonal_least_interpolation`__ | Build a polynomial chaos expansion from       |
|                         |                    |                                    | simulation samples using orthogonal least     |
|                         |                    |                                    | interpolation.                                |
+-------------------------+--------------------+------------------------------------+-----------------------------------------------+
| Optional (Choose One)   | Basis Polynomial   | `askey`__                          | Select the standardized random variables (and |
|                         | Family             |                                    | associated basis polynomials) from the Askey  |
|                         |                    |                                    | family that best match the user-specified     |
|                         |                    |                                    | random variables.                             |
|                         |                    +------------------------------------+-----------------------------------------------+
|                         |                    | `wiener`__                         | Use standard normal random variables (along   |
|                         |                    |                                    | with Hermite orthogonal basis polynomials)    |
|                         |                    |                                    | when transforming to a standardized           |
|                         |                    |                                    | probability space.                            |
+-------------------------+--------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `normalized`__                     | The normalized specification requests output  |
|                                              |                                    | of PCE coefficients that correspond to        |
|                                              |                                    | normalized orthogonal basis polynomials       |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `export_expansion_file`__          | Export the coefficients and multi-index of a  |
|                                              |                                    | Polynomial Chaos Expansion (PCE) to a file    |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `samples_on_emulator`__            | Number of samples at which to evaluate an     |
|                                              |                                    | emulator (surrogate)                          |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `sample_type`__                    | Selection of sampling strategy                |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `rng`__                            | Selection of a random number generator        |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `probability_refinement`__         | Allow refinement of probability and           |
|                                              |                                    | generalized reliability results using         |
|                                              |                                    | importance sampling                           |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `final_moments`__                  | Output moments of the specified type and      |
|                                              |                                    | include them within the set of final          |
|                                              |                                    | statistics.                                   |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `response_levels`__                | Values at which to estimate desired           |
|                                              |                                    | statistics for each response                  |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `probability_levels`__             | Specify probability levels at which to        |
|                                              |                                    | estimate the corresponding response value     |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `reliability_levels`__             | Specify reliability levels at which the       |
|                                              |                                    | response values will be estimated             |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `gen_reliability_levels`__         | Specify generalized relability levels at      |
|                                              |                                    | which to estimate the corresponding response  |
|                                              |                                    | value                                         |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `distribution`__                   | Selection of cumulative or complementary      |
|                                              |                                    | cumulative functions                          |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `variance_based_decomp`__          | Activates global sensitivity analysis based   |
|                                              |                                    | on decomposition of response variance into    |
|                                              |                                    | main, interaction, and total effects          |
+-------------------------+--------------------+------------------------------------+-----------------------------------------------+
| Optional (Choose One)   | Covariance Type    | `diagonal_covariance`__            | Display only the diagonal terms of the        |
|                         |                    |                                    | covariance matrix                             |
|                         |                    +------------------------------------+-----------------------------------------------+
|                         |                    | `full_covariance`__                | Display the full covariance matrix            |
+-------------------------+--------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `import_approx_points_file`__      | Filename for points at which to evaluate the  |
|                                              |                                    | PCE/SC surrogate                              |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| Optional                                     | `export_approx_points_file`__      | Output file for surrogate model value         |
|                                              |                                    | evaluations                                   |
+----------------------------------------------+------------------------------------+-----------------------------------------------+
| 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                                     | `model_pointer`__                  | Identifier for model block to be used by a    |
|                                              |                                    | method                                        |
+----------------------------------------------+------------------------------------+-----------------------------------------------+

.. __: method-multilevel_polynomial_chaos-max_iterations.html
__ method-multilevel_polynomial_chaos-allocation_control.html
__ method-multilevel_polynomial_chaos-convergence_tolerance.html
__ method-multilevel_polynomial_chaos-metric_scale.html
__ method-multilevel_polynomial_chaos-discrepancy_emulation.html
__ method-multilevel_polynomial_chaos-expansion_order_sequence.html
__ method-multilevel_polynomial_chaos-orthogonal_least_interpolation.html
__ method-multilevel_polynomial_chaos-askey.html
__ method-multilevel_polynomial_chaos-wiener.html
__ method-multilevel_polynomial_chaos-normalized.html
__ method-multilevel_polynomial_chaos-export_expansion_file.html
__ method-multilevel_polynomial_chaos-samples_on_emulator.html
__ method-multilevel_polynomial_chaos-sample_type.html
__ method-multilevel_polynomial_chaos-rng.html
__ method-multilevel_polynomial_chaos-probability_refinement.html
__ method-multilevel_polynomial_chaos-final_moments.html
__ method-multilevel_polynomial_chaos-response_levels.html
__ method-multilevel_polynomial_chaos-probability_levels.html
__ method-multilevel_polynomial_chaos-reliability_levels.html
__ method-multilevel_polynomial_chaos-gen_reliability_levels.html
__ method-multilevel_polynomial_chaos-distribution.html
__ method-multilevel_polynomial_chaos-variance_based_decomp.html
__ method-multilevel_polynomial_chaos-diagonal_covariance.html
__ method-multilevel_polynomial_chaos-full_covariance.html
__ method-multilevel_polynomial_chaos-import_approx_points_file.html
__ method-multilevel_polynomial_chaos-export_approx_points_file.html
__ method-multilevel_polynomial_chaos-seed_sequence.html
__ method-multilevel_polynomial_chaos-fixed_seed.html
__ method-multilevel_polynomial_chaos-model_pointer.html



**Description**


As described in :dakkw:`method-polynomial_chaos`, the polynomial chaos
expansion (PCE) is a general framework for the approximate representation
of random response functions in terms of series expansions in standardized
random variables:


.. math:: R = \sum_{i=0}^P \alpha_i \Psi_i(\xi) 

where :math:`\alpha_i`  is a deterministic coefficient, :math:`\Psi_i`  is a
multidimensional orthogonal polynomial and :math:`\xi`  is a vector of
standardized random variables.

In the multilevel and multifidelity cases, we decompose this expansion
into several constituent expansions, one per model form or solution
control level.  In a bi-fidelity case with low-fidelity (LF) and
high-fidelity (HF) models, we have:


.. math:: R = \sum_{i=0}^{P^{LF}} \alpha^{LF}_i \Psi_i(\xi)
     + \sum_{i=0}^{P^{HF}}      \delta_i \Psi_i(\xi) 

where :math:`\delta_i`  is a coefficient for the discrepancy expansion.

For the case of regression-based PCE (least squares, compressed sensing,
or orthogonal least interpolation), an optimal sample allocation procedure
can be applied for the resolution of each level within a multilevel sampling
procedure as in :dakkw:`method-multilevel_sampling`.  The core difference
is that a Monte Carlo estimator of the statistics is replaced with a
PCE-based estimator of the statistics, requiring approximation of the
variance of these estimators.

Initial prototypes for multilevel PCE can be explored using
``dakota/share/dakota/test/dakota_uq_diffusion_mlpce``.in, and will be stabilized in
future releases.


*Additional Resources*

Dakota provides access to multilevel PCE methods through the
NonDMultilevelPolynomialChaos class. Refer to the 
:ref:`theory:uq:expansion` section within the theory portion of the Users Guide
for additional information on the Multilevel PCE algorithm.


*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-se_moments` (expansion moments only)
- :ref:`hdf5_results-pdf`
- :ref:`hdf5_results-level_mappings`

In addition, the execution group has the attribute ``equiv_hf_evals``, which
records the equivalent number of high-fidelity evaluations.



**Examples**



.. code-block::

    method,
     multilevel_polynomial_chaos
       model_pointer = 'HIERARCH'
       pilot_samples = 10
       expansion_order_sequence = 2
       collocation_ratio = .9
       seed = 1237
       orthogonal_matching_pursuit
       convergence_tolerance = .01
     output silent
    
    model,
     id_model = 'HIERARCH'
     surrogate ensemble
       ordered_model_fidelities = 'SIM1'
       correction additive zeroth_order
    
    model,
     id_model = 'SIM1'
     simulation
       solution_level_control = 'mesh_size'
       solution_level_cost = 1. 8. 64. 512. 4096.




