.. _method-function_train:
""""""""""""""
function_train
""""""""""""""
UQ method leveraging a functional tensor train surrogate model.
.. toctree::
:hidden:
:maxdepth: 1
method-function_train-p_refinement
method-function_train-max_refinement_iterations
method-function_train-convergence_tolerance
method-function_train-metric_scale
method-function_train-regression_type
method-function_train-max_solver_iterations
method-function_train-max_cross_iterations
method-function_train-solver_tolerance
method-function_train-response_scaling
method-function_train-tensor_grid
method-function_train-collocation_points
method-function_train-collocation_ratio
method-function_train-rounding_tolerance
method-function_train-arithmetic_tolerance
method-function_train-start_order
method-function_train-adapt_order
method-function_train-kick_order
method-function_train-max_order
method-function_train-max_cv_order_candidates
method-function_train-start_rank
method-function_train-adapt_rank
method-function_train-kick_rank
method-function_train-max_rank
method-function_train-max_cv_rank_candidates
method-function_train-samples_on_emulator
method-function_train-sample_type
method-function_train-rng
method-function_train-probability_refinement
method-function_train-final_moments
method-function_train-response_levels
method-function_train-probability_levels
method-function_train-reliability_levels
method-function_train-gen_reliability_levels
method-function_train-distribution
method-function_train-variance_based_decomp
method-function_train-diagonal_covariance
method-function_train-full_covariance
method-function_train-import_approx_points_file
method-function_train-export_approx_points_file
method-function_train-seed
method-function_train-fixed_seed
method-function_train-model_pointer
**Specification**
- *Alias:* None
- *Arguments:* None
**Child Keywords:**
+-------------------------+--------------------+-------------------------------+-----------------------------------------------+
| Required/Optional | Description of | Dakota Keyword | Dakota Keyword Description |
| | Group | | |
+=========================+====================+===============================+===============================================+
| Optional | `p_refinement`__ | Automatic polynomial order refinement |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional | `max_refinement_iterations`__ | Maximum number of expansion refinement |
| | | iterations |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| 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 | `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. |
+-------------------------+--------------------+-------------------------------+-----------------------------------------------+
| Required (Choose One) | Collocation | `collocation_points`__ | Number of collocation points used to estimate |
| | Control | | expansion coefficients |
| | +-------------------------------+-----------------------------------------------+
| | | `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 | `start_order`__ | (Initial) polynomial order of each univariate |
| | | function within the functional tensor train. |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| 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`__ | The initial rank used for the starting point |
| | | during a rank adaptation. |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| 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`__ | Seed of the random number generator |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| 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-function_train-p_refinement.html
__ method-function_train-max_refinement_iterations.html
__ method-function_train-convergence_tolerance.html
__ method-function_train-metric_scale.html
__ method-function_train-regression_type.html
__ method-function_train-max_solver_iterations.html
__ method-function_train-max_cross_iterations.html
__ method-function_train-solver_tolerance.html
__ method-function_train-response_scaling.html
__ method-function_train-tensor_grid.html
__ method-function_train-collocation_points.html
__ method-function_train-collocation_ratio.html
__ method-function_train-rounding_tolerance.html
__ method-function_train-arithmetic_tolerance.html
__ method-function_train-start_order.html
__ method-function_train-adapt_order.html
__ method-function_train-kick_order.html
__ method-function_train-max_order.html
__ method-function_train-max_cv_order_candidates.html
__ method-function_train-start_rank.html
__ method-function_train-adapt_rank.html
__ method-function_train-kick_rank.html
__ method-function_train-max_rank.html
__ method-function_train-max_cv_rank_candidates.html
__ method-function_train-samples_on_emulator.html
__ method-function_train-sample_type.html
__ method-function_train-rng.html
__ method-function_train-probability_refinement.html
__ method-function_train-final_moments.html
__ method-function_train-response_levels.html
__ method-function_train-probability_levels.html
__ method-function_train-reliability_levels.html
__ method-function_train-gen_reliability_levels.html
__ method-function_train-distribution.html
__ method-function_train-variance_based_decomp.html
__ method-function_train-diagonal_covariance.html
__ method-function_train-full_covariance.html
__ method-function_train-import_approx_points_file.html
__ method-function_train-export_approx_points_file.html
__ method-function_train-seed.html
__ method-function_train-fixed_seed.html
__ method-function_train-model_pointer.html
**Description**
Tensor train decompositions are approximations that exploit low rank structure
in an input-output mapping. Refer to the :dakkw:`model-surrogate-global-function_train`
surrogate model for additional details.
*Usage Tips*
This method is a self-contained method alternative to the
:dakkw:`model-surrogate-global-function_train` surrogate model specification, similar
to current method specifications for polynomial chaos and stochastic collocation.
In particular, this ``function_train`` method specification directly couples with a
simulation model (optionally identified with a ``model_pointer``) and an additional
``function`` train surrogate model specification is not required as these options
have been embedded within the method specification.
**Examples**
.. code-block::
method,
function_train
start_order = 2
start_rank = 2 kick_rank = 2 max_rank = 10
adapt_rank
solver_tolerance = 1e-12
rounding_tolerance = 1e-12
convergence_tol = 1e-6
collocation_points = 100
samples_on_emulator = 100000
seed = 531
response_levels = .1 1. 50. 100. 500. 1000.
variance_based_decomp