Dakota Reference Manual
Version 6.4
LargeScale Engineering Optimization and Uncertainty Analysis

The sub_method_pointer
specifies the method block for the subiterator
This keyword is related to the topics:
Alias: none
Argument(s): STRING
Required/Optional  Description of Group  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 toplevel variables to submodel variables  
Optional  secondary_variable_mapping  Secondary mappning of toplevel variables to submodel variables  
Optional  primary_response_mapping  Primary mappning of submodel responses to toplevel responses  
Optional  secondary_response_mapping  Secondary mappning of submodel responses to toplevel responses 
The sub_method_pointer
specifies the method block for the subiterator.
See block_pointer for details about pointers.
A nested model performs an evaluation (variablestoresponses mapping) by running a complete subiterator (i.e. method) to completion. The subiterator, which is specified using the sub_method_pointer
, has its own model. This model, referred to here as the submodel, possesses its own variables and responses. Prior to every execution of the subiterator, information about the nested model's variables is injected into the submodel's variables. After the subiterator has completed, its results are passed back up to the nested model as responses.
Communication of variables information from a nested model to its subiterator, and in the opposite direction of subiterator results to nested model responses, is called mapping. (This mapping must not be confused with the variablestoresponses mapping that constitutes an evaluation.) Dakota allows considerable power and flexibility in how nested model mappings are performed. They are specified using four keywords: for the variables, primary_variable_mapping
and secondary_variable_mapping
; and for the responses, primary_response_mapping
and secondary_response_mapping
. They are described below.
Variable Mappings
In the variable mapping case, primary and secondary variable mapping specifications are used to map from the toplevel variables into the submodel variables. These mappings support three possibilities in any combination: (1) insertion of an active toplevel variable value into an identified submodel distribution parameter for an identified active submodel variable, (2) insertion of an active toplevel variable value into an identified active submodel variable value, and (3) addition of an active toplevel variable value as an inactive submodel variable, augmenting the active submodel variables.
For the variable mappings, the primary and secondary specifications are lists of strings that are used to target specific submodel variables and their subparameters, respectively. The primary strings are matched to submodel variable descriptors such as 'cdv_1'
(either usersupplied or default labels). The secondary strings are matched to random variable distribution parameters such as 'mean'
or 'num_trials'
or design/state variable subparameters such as 'lower_bound'
or 'upper_bound'
.
An important limitation is that realvalued toplevel variables must map to realvalued submodel variables or realvalued subparameters, and integervalued toplevel variables must map to either integervalued submodel variables or integervalued subparameters. However, 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 toplevel variable value will be inserted into the identified subparameter (the secondary mapping) for the identified submodel variable (the primary mapping).
If a primary mapping is specified but a secondary mapping is not, then an active toplevel variable value will be inserted into the identified submodel variable value (the primary mapping).
These different variable mapping possibilities may be used in any combination by employing empty strings ('') for particular omitted mappings (the number of strings in usersupplied primary and secondary variable mapping specifications must equal the total number of active toplevel 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 the variables section of this manual.
Inactive nested model variables are treated differently from those in the active view. 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, toplevel 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 outermost loop may become inactive at the next lower level, but still needs to be further propagated down to lower levels in the recursion.
Response Mappings
For the response mappings, the primary and secondary specifications determine how results from the completed subiterator are mapped into nested model responses. The response mapping defines a matrix which scales and combines the results from the inner loop into outer loop responses. Each row of the mapping corresponds to one outer loop response, and each column of the mapping corresponds to a result from the inner loop. The results returned from the submodel are best thought of as forming a column vector; the nested model responses are then the dotproduct of the mapping matrix and results vector. The number and type of results that are available and must be accounted for in the response mapping depends on the subiterator type:
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 userspecified 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 userspecified 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 subiterator response vector is empty in this case.
The primary_response_mapping
matrix maps subiterator results into toplevel objective functions, least squares terms, or generic response functions, depending on the declared toplevel response set. The secondary_response_mapping
matrix maps subiterator results into toplevel nonlinear inequality and equality constraints.
Summary
The nested model constructs admit a wide variety of multiiterator, multimodel solution approaches. For example, optimization within optimization (for hierarchical multidisciplinary optimization), uncertainty quantification within uncertainty quantification (for secondorder 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 epistemicaleatory UQ, optimization under uncertainty (OUU), and surrogatebased UQ.
Two examples are provided to illustrate nested models. The first is a relatively simple case. Although it is somewhat contrived, it demonstrates several features of nested models. A stepbystep explanation is provided below.
environment method_pointer 'opt' method id_method 'opt' asynch_pattern_search model_pointer 'outer_model' output verbose model id_model 'outer_model' variables_pointer 'outer_vars' responses_pointer 'outer_resps' nested sub_method_pointer 'UQ_method' primary_variable_mapping 'x1' 'x2' secondary_variable_mapping 'mean' 'mean' primary_response_mapping 0 0 0.3 0 0 0.7 variables id_variables 'outer_vars' continuous_design 2 descriptors 'x1_mean' 'x2_mean' lower_bounds 2.0 2.0 upper_bounds 2.0 2.0 responses id_responses 'outer_resps' objective_functions 1 descriptors 'sum_p no_gradients no_hessians method id_method 'UQ_method' sampling samples 30 seed 1234 model_pointer 'UQ_model' probability_levels 0.9 0.9 model id_model 'UQ_model' single variables_pointer 'inner_vars' responses_pointer 'inner_resps' interface_pointer 'inf' variables id_variables 'inner_vars' normal_uncertain 2 descriptors 'x1' 'x2' means 0.0 0.0 std_deviations 1.0 1.0 responses id_responses 'inner_resps' response_functions 2 descriptors 'f1' 'f2' no_gradients no_hessians interface id_interface 'inf' direct analysis_drivers 'text_book'
The example input is an 'optimization under uncertainty' or OUU. In an OUU, some statistic of the simulation response is optimized. In this case, a weighted sum of the 90th percentiles of two simulation responses from the text_book
driver is being minimized. The uncertainty in these responses is driven by uncertainty in the input variables, which are normally distributed. The means of the uncertain variables are the design variables in the optimization.
In Dakota, this is accomplished by nesting an uncertainty quantification method (sampling), which computes the 90th percentiles, within an optimizer (methodasynch_pattern_search
), which iteratively adjusts the variable means to minimize the objective. For every evaluation requested by the optimizer, the design variables (x1_mean
and x2_mean
in the example) are inserted into the means of the uncertain variables (x1
and x2
), then the sampling
study is run to completion, and finally the resulting statistics for the responses f1
and f2
are mapped into the responses sum_p
.
It may be helpful to sketch out the relationships between blocks as indicated by their various pointers in order to understand the nested structure of the study. The toplevel or outer method, 'opt'
, has a model named 'outer_model'
. This model refers to variables and responses blocks ('outer_vars'
and 'outer_resps'
) that are used by the optimizer. The 'outer_model'
block also refers to a submethod, 'UQ_method'
which defines the UQ study and has its own model, which in turn possess variables, an interface, and responses.
Next, note the primary and secondary variable mappings in 'outer_model'
, which specify that the values of the active design variables x1_mean
and x2_mean
are to be inserted into the means of the uncertain variables x1
and x2
.
The response mapping in 'outer_model'
is a matrix with a single row and six columns. The single row corresponds to the number of responses in the outer method. As described above, for each of our two submodel responses, the sampling
method returns a mean, a standard deviation, and a single probability level in that order to the nested model. There are a total of six results and accordingly six columns in the mapping matrix. The coefficients 0.3 and 0.7 in the matrix result in a weighted sum of the 90th percentiles:
The next example is a fragment of an input file, showing only the nested model itself. It illustrates more complex variable and response mappings.
primary_variable_mapping = '' '' 'X' 'Y' secondary_variable_mapping = '' '' 'mean' 'mean' primary_response_mapping = 1. 0. 0. 0. 0. 0. 0. 0. 0. secondary_response_mapping = 0. 0. 0. 1. 3. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 1. 3. 0.
The variable mappings correspond to 4 toplevel variables, the first two of which employ the default mappings from active toplevel variables to submodel variables of the same type (option 3 above) and the latter two of which are inserted into the mean distribution parameters of submodel variables 'X'
and 'Y'
(option 1 above).
The response mappings define a 3 by 9 matrix corresponding to 9 inner loop results and 3 outer loop response functions (one primary response function and 2 secondary functions, such as one objective and two constraints). Each row of the response mapping is a vector which is multiplied (i.e, with a dotproduct) against the 9 subiterator results to determine the outer loop function.
Consider again a UQ example with 3 response functions, each providing a mean, a standard deviation, and one level mapping (if no level mappings are specified, the responses would only have a mean and standard deviation). The primary response mapping can be seen to extract the first result from the inner loop, which would correspond to the mean of the first response function. This mapped subiterator response becomes a single objective function, least squares term, or generic response function at the outer level, as dictated by the toplevel response specification. The secondary response mapping maps the fourth subiterator result plus 3 times the fifth subiterator result (mean plus 3 standard deviations) into one toplevel nonlinear constraint and the seventh subiterator result plus 3 times the eighth subiterator result (mean plus 3 standard deviations) into another toplevel nonlinear constraint, where these toplevel nonlinear constraints may be inequality or equality, as dictated by the toplevel response specification.
Note that a common case is for each subiterator result to be mapped to a unique outer loop response (for example, in the nested UQ case where one wants to determine an interval on each inner loop statistic). In these simple cases, the response mapping would define an identity matrix.