.. _method-multilevel_function_train:

"""""""""""""""""""""""""
multilevel_function_train
"""""""""""""""""""""""""


Multilevel uncertainty quantification using function train expansions


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

   method-multilevel_function_train-max_iterations
   method-multilevel_function_train-allocation_control
   method-multilevel_function_train-convergence_tolerance
   method-multilevel_function_train-metric_scale
   method-multilevel_function_train-discrepancy_emulation
   method-multilevel_function_train-rounding_tolerance
   method-multilevel_function_train-arithmetic_tolerance
   method-multilevel_function_train-regression_type
   method-multilevel_function_train-max_solver_iterations
   method-multilevel_function_train-max_cross_iterations
   method-multilevel_function_train-solver_tolerance
   method-multilevel_function_train-response_scaling
   method-multilevel_function_train-tensor_grid
   method-multilevel_function_train-collocation_points_sequence
   method-multilevel_function_train-collocation_ratio
   method-multilevel_function_train-start_order_sequence
   method-multilevel_function_train-adapt_order
   method-multilevel_function_train-kick_order
   method-multilevel_function_train-max_order
   method-multilevel_function_train-max_cv_order_candidates
   method-multilevel_function_train-start_rank_sequence
   method-multilevel_function_train-adapt_rank
   method-multilevel_function_train-kick_rank
   method-multilevel_function_train-max_rank
   method-multilevel_function_train-max_cv_rank_candidates
   method-multilevel_function_train-samples_on_emulator
   method-multilevel_function_train-sample_type
   method-multilevel_function_train-rng
   method-multilevel_function_train-probability_refinement
   method-multilevel_function_train-final_moments
   method-multilevel_function_train-response_levels
   method-multilevel_function_train-probability_levels
   method-multilevel_function_train-reliability_levels
   method-multilevel_function_train-gen_reliability_levels
   method-multilevel_function_train-distribution
   method-multilevel_function_train-variance_based_decomp
   method-multilevel_function_train-diagonal_covariance
   method-multilevel_function_train-full_covariance
   method-multilevel_function_train-import_approx_points_file
   method-multilevel_function_train-export_approx_points_file
   method-multilevel_function_train-seed_sequence
   method-multilevel_function_train-fixed_seed
   method-multilevel_function_train-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.                                |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `rounding_tolerance`__          | An accuracy tolerance that is used to guide   |
|                                              |                                 | rounding during rank adaptation.              |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `arithmetic_tolerance`__        | A secondary rounding tolerance used for       |
|                                              |                                 | post-processing                               |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `regression_type`__             | Type of solver for forming function train     |
|                                              |                                 | approximations by regression                  |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `max_solver_iterations`__       | Maximum iterations in determining polynomial  |
|                                              |                                 | coefficients                                  |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `max_cross_iterations`__        | Maximum number of iterations for              |
|                                              |                                 | cross-approximation during a rank adaptation. |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `solver_tolerance`__            | Convergence tolerance for the optimizer used  |
|                                              |                                 | during the regression solve.                  |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `response_scaling`__            | Perform bounds-scaling on response values     |
|                                              |                                 | prior to surrogate emulation                  |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `tensor_grid`__                 | Use sub-sampled tensor-product quadrature     |
|                                              |                                 | points to build a polynomial chaos expansion. |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `collocation_points_sequence`__ | Sequence of collocation point counts used in  |
|                                              |                                 | a multi-stage expansion                       |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `collocation_ratio`__           | Set the number of points used to build a PCE  |
|                                              |                                 | via regression to be proportional to the      |
|                                              |                                 | number of terms in the expansion.             |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `start_order_sequence`__        | Sequence of start orders used in a            |
|                                              |                                 | multi-stage expansion                         |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `adapt_order`__                 | Activate adaptive procedure for determining   |
|                                              |                                 | the best basis order                          |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `kick_order`__                  | increment used when adapting the basis order  |
|                                              |                                 | in function train methods                     |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `max_order`__                   | Maximum polynomial order of each univariate   |
|                                              |                                 | function within the functional tensor train.  |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `max_cv_order_candidates`__     | Limit the number of cross-validation          |
|                                              |                                 | candidates for basis order                    |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `start_rank_sequence`__         | Sequence of start ranks used in a multi-stage |
|                                              |                                 | expansion                                     |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `adapt_rank`__                  | Activate adaptive procedure for determining   |
|                                              |                                 | best rank representation                      |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `kick_rank`__                   | The increment in rank employed during each    |
|                                              |                                 | iteration of the rank adaptation.             |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `max_rank`__                    | Limits the maximum rank that is explored      |
|                                              |                                 | during a rank adaptation.                     |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| Optional                                     | `max_cv_rank_candidates`__      | Limit the number of cross-validation          |
|                                              |                                 | candidates for rank                           |
+----------------------------------------------+---------------------------------+-----------------------------------------------+
| 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_function_train-max_iterations.html
__ method-multilevel_function_train-allocation_control.html
__ method-multilevel_function_train-convergence_tolerance.html
__ method-multilevel_function_train-metric_scale.html
__ method-multilevel_function_train-discrepancy_emulation.html
__ method-multilevel_function_train-rounding_tolerance.html
__ method-multilevel_function_train-arithmetic_tolerance.html
__ method-multilevel_function_train-regression_type.html
__ method-multilevel_function_train-max_solver_iterations.html
__ method-multilevel_function_train-max_cross_iterations.html
__ method-multilevel_function_train-solver_tolerance.html
__ method-multilevel_function_train-response_scaling.html
__ method-multilevel_function_train-tensor_grid.html
__ method-multilevel_function_train-collocation_points_sequence.html
__ method-multilevel_function_train-collocation_ratio.html
__ method-multilevel_function_train-start_order_sequence.html
__ method-multilevel_function_train-adapt_order.html
__ method-multilevel_function_train-kick_order.html
__ method-multilevel_function_train-max_order.html
__ method-multilevel_function_train-max_cv_order_candidates.html
__ method-multilevel_function_train-start_rank_sequence.html
__ method-multilevel_function_train-adapt_rank.html
__ method-multilevel_function_train-kick_rank.html
__ method-multilevel_function_train-max_rank.html
__ method-multilevel_function_train-max_cv_rank_candidates.html
__ method-multilevel_function_train-samples_on_emulator.html
__ method-multilevel_function_train-sample_type.html
__ method-multilevel_function_train-rng.html
__ method-multilevel_function_train-probability_refinement.html
__ method-multilevel_function_train-final_moments.html
__ method-multilevel_function_train-response_levels.html
__ method-multilevel_function_train-probability_levels.html
__ method-multilevel_function_train-reliability_levels.html
__ method-multilevel_function_train-gen_reliability_levels.html
__ method-multilevel_function_train-distribution.html
__ method-multilevel_function_train-variance_based_decomp.html
__ method-multilevel_function_train-diagonal_covariance.html
__ method-multilevel_function_train-full_covariance.html
__ method-multilevel_function_train-import_approx_points_file.html
__ method-multilevel_function_train-export_approx_points_file.html
__ method-multilevel_function_train-seed_sequence.html
__ method-multilevel_function_train-fixed_seed.html
__ method-multilevel_function_train-model_pointer.html



**Description**


As described in the :dakkw:`method-function_train` method and the
:dakkw:`model-surrogate-global-function_train` model,
the function train (FT) approximation is a polynomial expansion that exploits low rank
structure within the mapping from input random variables to output quantities of interest
(QoI).  For multilevel and multifidelity function train approximations, we decompose this
expansion into several constituent expansions, one per model form or solution control
level, where independent function train approximations are constructed for the
low-fidelity/coarse resolution model and one or more levels of model discrepancy.

In a three-model case with low-fidelity (L), medium-fidelity (M), and
high-fidelity (H) models and an additive discrepancy approach, we can denote this as:


.. math::  Q^H \approx \hat{Q}_{r_L}^L + \hat{\Delta}_{r_{ML}}^{ML} + \hat{\Delta}_{r_{HM}}^{HM} 

where :math:`\Delta^{ij}`  represents a discrepancy expansion computed from
:math:`Q^i - Q^j`  and reduced rank representations of these discrepancies may
be targeted ( :math:`r_{HM} < r_{ML} < r_L` ).

In multilevel approaches, sample allocation for the constituent expansions is
performed as described in :dakkw:`method-multilevel_function_train-allocation_control`.

*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.


