.. _responses-calibration_terms: """"""""""""""""" calibration_terms """"""""""""""""" Response type suitable for calibration or least squares .. toctree:: :hidden: :maxdepth: 1 responses-calibration_terms-scalar_calibration_terms responses-calibration_terms-field_calibration_terms responses-calibration_terms-primary_scales responses-calibration_terms-weights responses-calibration_terms-calibration_data responses-calibration_terms-calibration_data_file responses-calibration_terms-simulation_variance responses-calibration_terms-nonlinear_inequality_constraints responses-calibration_terms-nonlinear_equality_constraints **Specification** - *Alias:* least_squares_terms num_least_squares_terms - *Arguments:* INTEGER **Child Keywords:** +-------------------------+--------------------+--------------------------------------+---------------------------------------------+ | Required/Optional | Description of | Dakota Keyword | Dakota Keyword Description | | | Group | | | +=========================+====================+======================================+=============================================+ | Optional | `scalar_calibration_terms`__ | Number of scalar calibration terms | +----------------------------------------------+--------------------------------------+---------------------------------------------+ | Optional | `field_calibration_terms`__ | Number of field calibration terms | +----------------------------------------------+--------------------------------------+---------------------------------------------+ | Optional | `primary_scales`__ | Characteristic values to scale each | | | | calibration term | +----------------------------------------------+--------------------------------------+---------------------------------------------+ | Optional | `weights`__ | Specify weights for each objective function | +-------------------------+--------------------+--------------------------------------+---------------------------------------------+ | Optional (Choose One) | Calibration Data | `calibration_data`__ | Supply field or mixed field/scalar | | | | | calibration data | | | +--------------------------------------+---------------------------------------------+ | | | `calibration_data_file`__ | Supply scalar calibration data only | +-------------------------+--------------------+--------------------------------------+---------------------------------------------+ | Optional | `simulation_variance`__ | Variance applied to simulation responses | +----------------------------------------------+--------------------------------------+---------------------------------------------+ | Optional | `nonlinear_inequality_constraints`__ | Group to specify nonlinear inequality | | | | constraints | +----------------------------------------------+--------------------------------------+---------------------------------------------+ | Optional | `nonlinear_equality_constraints`__ | Group to specify nonlinear equality | | | | constraints | +----------------------------------------------+--------------------------------------+---------------------------------------------+ .. __: responses-calibration_terms-scalar_calibration_terms.html __ responses-calibration_terms-field_calibration_terms.html __ responses-calibration_terms-primary_scales.html __ responses-calibration_terms-weights.html __ responses-calibration_terms-calibration_data.html __ responses-calibration_terms-calibration_data_file.html __ responses-calibration_terms-simulation_variance.html __ responses-calibration_terms-nonlinear_inequality_constraints.html __ responses-calibration_terms-nonlinear_equality_constraints.html **Description** Responses for a calibration study are specified using ``calibration_terms`` and optional keywords for weighting/scaling, data, and constraints. In general when calibrating, Dakota automatically tunes parameters :math:`\theta` to minimize discrepancies or residuals between the model and the data: .. math:: R_{i} = y^{Model}_i(\theta) - y^{Data}_{i}. Note that the problem specification affects what must be returned to Dakota in the :dakkw:`interface-analysis_drivers-fork-results_file` : - If calibration data *is not specified*, then each of the calibration terms returned to Dakota through the :dakkw:`interface` is a residual :math:`R_{i}` to be driven toward zero. - If calibration data *is specified*, then each of the calibration terms returned to Dakota must be a response :math:` y^{Model}_i(\theta)` , which Dakota will difference with the data in the specified data file. *Constraints* (See general problem formulation at :dakkw:`responses-objective_functions`.) The keywords :dakkw:`responses-calibration_terms-nonlinear_inequality_constraints` and :dakkw:`responses-calibration_terms-nonlinear_equality_constraints` specify the number of nonlinear inequality constraints \em g, and nonlinear equality constraints \em h, respectively. When interfacing to external applications, the responses must be returned to Dakota in this order in the :dakkw:`interface-analysis_drivers-fork-results_file` : 0. calibration terms nonlinear inequality constraints nonlinear equality constraints An optimization problem's linear constraints are provided to the solver at startup only and do not need to be included in the data returned on every function evaluation. Linear constraints are therefore specified in the :dakkw:`variables` block through the :dakkw:`variables-linear_inequality_constraint_matrix` :math:`A_i` and :dakkw:`variables-linear_equality_constraint_matrix` :math:`A_e` . Lower and upper bounds on the design variables \em x are also specified in the :dakkw:`variables` block. *Problem Transformations* Weighting or scaling calibration terms is often appropriate to account for measurement error or to condition the problem for easier solution. Weighting or scaling transformations are applied in the following order: 1. When present, observation error variance :math:`\sigma_i` or full covariance :math:`\Sigma` , optionally specified through ``experiment_variance_type``, is applied to residuals first: .. math:: R^{(1)}_i = \frac{R_{i}}{\sigma_{i}} = \frac{y^{Model}_i(\theta) - y^{Data}_{i}}{\sigma_{i}} \textrm{, or} .. math:: R^{(1)} = \Sigma^{-1/2} R = \Sigma^{-1/2} \left(y^{Model}(\theta) - y^{Data}\right), resulting in the typical variance-weighted least squares formulation .. math:: \textrm{min}_\theta \; R(\theta)^T \Sigma^{-1} R(\theta) 2. Any active scaling transformations are applied next, e.g., for characteristic value scaling: .. math:: R^{(2)}_i = \frac{R^{(1)}_i}{s_i} 3. Finally the optional weights are applied in a way that preserves backward compatibility: .. math:: R^{(3)}_i = \sqrt{w_i}{R^{(2)}_i} so the ultimate least squares formulation, e.g., in a scaled and weighted case would be .. math:: f = \sum_{i=1}^{n} w_i \left( \frac{y^{Model}_i - y^{Data}_i}{s_i} \right)^2 *Note that specifying observation error variance and weights are mutually exclusive in a calibration problem.* **Theory** Dakota calibration terms are typically used to solve problems of parameter estimation, system identification, and model calibration/inversion. Local least squares calibration problems are most efficiently solved using special-purpose least squares solvers such as Gauss-Newton or Levenberg-Marquardt; however, they may also be solved using any general-purpose optimization algorithm in Dakota. While Dakota can solve these problems with either least squares or optimization algorithms, the response data sets to be returned from the simulator are different when using :dakkw:`responses-objective_functions` versus :dakkw:`responses-calibration_terms`. Least squares calibration involves a set of residual functions, whereas optimization involves a single objective function (sum of the squares of the residuals), i.e., .. math:: f = \sum_{i=1}^{n} R_i^2 = \sum_{i=1}^{n} \left(y^{Model}_i(\theta) - y^{Data}_{i} \right)^2 where *f* is the objective function and the set of :math:`R_i` are the residual functions, most commonly defined as the difference between a model response and data. Therefore, function values and derivative data in the least squares case involve the values and derivatives of the residual functions, whereas the optimization case involves values and derivatives of the sum of squares objective function. This means that in the least squares calibration case, the user must return each of ``n`` residuals separately as a separate calibration term. Switching between the two approaches sometimes requires different simulation interfaces capable of returning the different granularity of response data required, although Dakota supports automatic recasting of residuals into a sum of squares for presentation to an optimization method. Typically, the user must compute the difference between the model results and the observations when computing the residuals. However, the user has the option of specifying the observational data (e.g. from physical experiments or other sources) in a file.