.. _method-multilevel_function_train: """"""""""""""""""""""""" multilevel_function_train """"""""""""""""""""""""" Multilevel uncertainty quantification using function train expansions .. toctree:: :hidden: :maxdepth: 1 method-multilevel_function_train-model_pointer method-multilevel_function_train-seed_sequence method-multilevel_function_train-fixed_seed 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-import_approx_points_file method-multilevel_function_train-export_approx_points_file method-multilevel_function_train-diagonal_covariance method-multilevel_function_train-full_covariance 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-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-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-rounding_tolerance method-multilevel_function_train-arithmetic_tolerance method-multilevel_function_train-discrepancy_emulation method-multilevel_function_train-refinement_metric method-multilevel_function_train-convergence_tolerance method-multilevel_function_train-allocation_control method-multilevel_function_train-max_iterations method-multilevel_function_train-id_method method-multilevel_function_train-output method-multilevel_function_train-final_solutions **Specification** - *Alias:* None - *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 | | | `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 | | | `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 | | | `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 (Choose One) | Covariance Type | covariance_type | `diagonal_covariance`__ | Display only the diagonal terms of the covariance matrix | + + + +---------------------------------+------------------------------------------------------------+ | | | | `full_covariance`__ | Display the full covariance matrix | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ | 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 | | | `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 | | | `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 | | | `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 | | | `discrepancy_emulation`__ | Formulation for emulation of model discrepancies. | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ | Optional | | | `refinement_metric`__ | Metric used for guiding adaptive refinement during UQ. | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ | Optional | | | `convergence_tolerance`__ | Stopping criterion based on objective function or | | | | | | statistics convergence | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ | Optional | | | `allocation_control`__ | Sample allocation approach for multilevel expansions | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ | Optional | | | `max_iterations`__ | Number of iterations allowed for optimizers and adaptive | | | | | | UQ methods | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ | 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 | +-------------------------+------------------------+--------------------+---------------------------------+------------------------------------------------------------+ .. __: method-multilevel_function_train-model_pointer.html __ method-multilevel_function_train-seed_sequence.html __ method-multilevel_function_train-fixed_seed.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-import_approx_points_file.html __ method-multilevel_function_train-export_approx_points_file.html __ method-multilevel_function_train-diagonal_covariance.html __ method-multilevel_function_train-full_covariance.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-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-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-rounding_tolerance.html __ method-multilevel_function_train-arithmetic_tolerance.html __ method-multilevel_function_train-discrepancy_emulation.html __ method-multilevel_function_train-refinement_metric.html __ method-multilevel_function_train-convergence_tolerance.html __ method-multilevel_function_train-allocation_control.html __ method-multilevel_function_train-max_iterations.html __ method-multilevel_function_train-id_method.html __ method-multilevel_function_train-output.html __ method-multilevel_function_train-final_solutions.html **Description** As described in the :dakkw:`method-function_train` method and the :dakkw:`model-global_surrogate-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.