The sub_method_pointer specifies the method block for the sub-iterator

Topics

This keyword is related to the topics:

block_pointer

Specification

Alias: none

Argument(s): STRING

Required/Optional	Dakota Keyword	Dakota Keyword Description
Optional	iterator_servers	Specify the number of iterator servers when Dakota is run in parallel
Optional	iterator_scheduling	Specify the scheduling of concurrent iterators when Dakota is run in parallel
Optional	processors_per_iterator	Specify the number of processors per iterator server when Dakota is run in parallel
Optional	primary_variable_mapping	Primary mappning of top-level variables to sub-model variables
Optional	secondary_variable_mapping	Secondary mappning of top-level variables to sub-model variables
Optional	primary_response_mapping	Primary mappning of sub-model responses to top-level responses
Optional	secondary_response_mapping	Secondary mappning of sub-model responses to top-level responses

Description

The sub_method_pointer specifies the method block for the sub-iterator.

See block_pointer for details about pointers.

Nested models may employ mappings for both the variable inputs to the sub-model and the response outputs from the sub-model. In the former case, the primary_variable_mapping and secondary_variable_mapping specifications are used to map from the active top-level variables into the sub-model variables, and in the latter case, the primary_response_mapping and secondary_response_mapping specifications are used to compute the sub-model response contributions to the top-level responses.

For the variable mappings, the primary and secondary specifications provide lists of strings which are used to target specific sub-model variables and their sub-parameters, respectively. The primary strings are matched to continuous or discrete variable labels such as 'cdv_1' (either user-supplied or default labels), and the secondary strings are matched to either real or integer random variable distribution parameters such as 'mean' or 'num_trials' (the form of the uncertain distribution parameter keyword that is appropriate for a single variable instance) or continuous or discrete design/state variable sub-parameters such as 'lower_bound' or 'upper_bound' (again, keyword form appropriate for a single variable instance). No coercion of types is supported, so real-valued top-level variables should map to either real-valued sub-model variables or real-valued sub-parameters and integer-valued top-level variables should map to either integer-valued sub-model variables or integer-valued sub-parameters. As long as these real versus integer constraints are satisfied, mappings are free to cross variable types (design, aleatory uncertain, epistemic uncertain, state) and domain types (continuous, discrete). Both primary_variable_mapping and secondary_variable_mapping specifications are optional, which is designed to support the following three possibilities:

If both primary and secondary variable mappings are specified, then an active top-level variable value will be inserted into the identified sub-parameter (the secondary mapping) for the identified sub-model variable (the primary mapping).
If a primary mapping is specified but a secondary mapping is not, then an active top-level variable value will be inserted into the identified sub-model variable value (the primary mapping).
If a primary mapping is not specified (corresponding secondary mappings, if specified, are ignored), then an active top-level variable value will be inserted into a corresponding sub-model variable, based on matching of variable types (e.g., top-level and sub-model variable specifications both allocate a set of 'continuous_design' variables which are active at the top level). Multiple sub-model variable types may be updated in this manner, provided that they are all active in the top-level variables. Since there is a direct variable correspondence for these default insertions, sub-model bounds and labels are also updated from the top-level bounds and labels in order to eliminate the need for redundant input file specifications. Thus, it is typical for the sub-model variables specification to only contain the minimal required information, such as the number of variables, for these insertion targets. The sub-model must allocate enough space for each of the types that will accept default insertions, and the leading set of matching sub-model variables are updated (i.e., the sub-model may allocate more than needed and the trailing set will be unmodified).

These different variable mapping possibilities may be used in any combination by employing empty strings ('') for particular omitted mappings (the number of strings in user-supplied primary and secondary variable mapping specifications must equal the total number of active top-level variables, including both continuous and discrete types). The ordering of the active variables is the same as shown in dakota.input.summary on Input Spec Summary and as presented in variables.

If inactive variables are present at the outer level, then the default type 3 mapping is used for these variables; that is, outer loop inactive variables are inserted into inner loop variables (active or inactive) based on matching of variable types, top-level bounds and labels are also propagated, the inner loop must allocate sufficient space to receive the outer loop values, and the leading subset within this inner loop allocation is updated. This capability is important for allowing nesting beyond two levels, since an active variable at the outer-most loop may become inactive at the next lower level, but still needs to be further propagated down to lower levels in the recursion.

For the response mappings, the primary and secondary specifications provide real-valued multipliers to be applied to sub-iterator response results so that the responses from the inner loop can be mapped into a new set of responses at the outer loop. For example, if the nested model is being employed within a mixed aleatory-epistemic uncertainty quantification, then aleatory statistics from the inner loop (such as moments of the response) are mapped to the outer level, where minima and maxima of these aleatory statistics are computed as functions of the epistemic parameters. The response mapping defines a matrix which scales the values from the inner loop and determines their position in the outer loop response vector. Each row of the mapping corresponds to one outer loop response, where each column of the mapping corresponds to a value from the inner loop. Depending on the number of responses and the particular attributes calculated on the inner loop, there will be a vector of inner loop response values that need to be accounted for in the mapping. This vector of inner loop response results is defined as follows for different sub-iterator types:

optimization: the final objective function(s) and nonlinear constraints
nonlinear least squares: the final least squares terms and nonlinear constraints
aleatory uncertainty quantification (UQ): for each response function, a mean statistic, a standard deviation statistic, and all probability/reliability/generalized reliability/response level results for any user-specified response_levels, probability_levels, reliability_levels, and/or gen_reliability_levels, in that order.
epistemic and mixed aleatory/epistemic UQ using interval estimation methods: lower and upper interval bounds for each response function.
epistemic and mixed aleatory/epistemic UQ using evidence methods: for each response function, lower and upper interval bounds (belief and plausibility) for all probability/reliability/generalized reliability/response level results computed from any user-specified response_levels, probability_levels, reliability_levels, and/or gen_reliability_levels, in that order.
parameter studies and design of experiments: for optimization and least squares response data sets, the best solution found (lowest constraint violation if infeasible, lowest composite objective function if feasible). For generic response data sets, a best solution metric is not defined, so the sub-iterator response vector is empty in this case.

The primary values map sub-iterator response results into top-level objective functions, least squares terms, or generic response functions, depending on the declared top-level response set. The secondary values map sub-iterator response results into top-level nonlinear inequality and equality constraints.

Nested models utilize a sub-iterator and a sub-model to perform a complete iterative study as part of every evaluation of the model. This sub-iteration accepts variables from the outer level, performs the sub-level analysis, and computes a set of sub-level responses which are passed back up to the outer level. Mappings are employed for both the variable inputs to the sub-model and the response outputs from the sub-model.

In the variable mapping case, primary and secondary variable mapping specifications are used to map from the top-level variables into the sub-model variables. These mappings support three possibilities in any combination: (1) insertion of an active top-level variable value into an identified sub-model distribution parameter for an identified active sub-model variable, (2) insertion of an active top-level variable value into an identified active sub-model variable value, and (3) addition of an active top-level variable value as an inactive sub-model variable, augmenting the active sub-model variables.

In the response mapping case, primary and secondary response mapping specifications are used to map from the sub-model responses back to the top-level responses. These specifications provide real-valued multipliers that are applied to the sub-iterator response results to define the outer level response set. These nested data results may be combined with non-nested data through use of the "optional interface" component within nested models.

The nested model constructs admit a wide variety of multi-iterator, multi-model solution approaches. For example, optimization within optimization (for hierarchical multidisciplinary optimization), uncertainty quantification within uncertainty quantification (for second-order probability), uncertainty quantification within optimization (for optimization under uncertainty), and optimization within uncertainty quantification (for uncertainty of optima) are all supported, with and without surrogate model indirection. Several examples of nested model usage are provided in the Users Manual, most notably mixed epistemic-aleatory UQ, optimization under uncertainty (OUU), and surrogate-based UQ.