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