Dakota Reference Manual: nl2sol

| Dakota Reference Manual Version 6.15 Explore and Predict with Confidence

- Main Page
- Related Pages

All Pages
nl2sol

Trust-region method for nonlinear least squares

## Topics

This keyword is related to the topics:

- nonlinear_least_squares

## Specification

Alias: none

Argument(s): none

Child Keywords:

| Required/Optional | Description of Group | Dakota Keyword | Dakota Keyword Description
--- | --- | --- | --- | ---
| Optional | function_precision | Specify the maximum precision of the analysis code responses
| Optional | absolute_conv_tol | Absolute convergence tolerance
| Optional | x_conv_tol | X-convergence tolerance
| Optional | singular_conv_tol | Singular convergence tolerance
| Optional | singular_radius | Singular radius
| Optional | false_conv_tol | False convergence tolerance
| Optional | initial_trust_radius | Initial trust region radius
| Optional | covariance | Determine how the final covariance matrix is computed
| Optional | regression_diagnostics | Turn on regression diagnostics
| Optional | convergence_tolerance | Stopping criterion based on objective function or statistics convergence
| Optional | max_iterations | Number of iterations allowed for optimizers and adaptive UQ methods
| Optional | speculative | Compute speculative gradients
| Optional | max_function_evaluations | Number of function evaluations allowed for optimizers
| Optional | scaling | Turn on scaling for variables, responses, and constraints
| Optional | model_pointer | Identifier for model block to be used by a method

## Description

NL2SOL is available as `nl2sol` and addresses unconstrained and bound-constrained least squares problems. It uses a trust-region method (and thus can be viewed as a generalization of the Levenberg-Marquardt algorithm) and adaptively chooses between two Hessian approximations, the Gauss-Newton approximation alone and the Gauss-Newton approximation plus a quasi-Newton approximation to the rest of the Hessian. Even on small-residual problems, the latter Hessian approximation can be useful when the starting guess is far from the solution. On problems that are not over-parameterized (i.e., that do not involve more optimization variables than the data support), NL2SOL usually exhibits fast convergence.

Several internal NL2SOL convergence tolerances are adjusted in response to `function_precision`, which gives the relative precision to which responses are computed.

These tolerances may also be specified explicitly using:

- `convergence_tolerance` (NL2SOL's `rfctol`)
- `x_conv_tol` (NL2SOL's `xctol`)
- `absolute_conv_tol` (NL2SOL's `afctol`)
- `singular_conv_tol` (NL2SOL's `sctol`)
- `false_conv_tol` (NL2SOL's `xftol`)
- `initial_trust_radius` (NL2SOL's `lmax0`)

The internal NL2SOL defaults can be obtained for many of these controls by specifying the value -1. The internal defaults are often functions of machine epsilon (as limited by `function_precision`).

Expected HDF5 Output

If Dakota was built with HDF5 support and run with the hdf5 keyword, this method writes the following results to HDF5:

- Best Parameters
- Best Nonlinear Constraints
- Calibration (when calibration_terms are specified)
- Parameter Confidence Intervals (when num_experiments equals 1)

## Examples

An example of `nl2sol` is given below, and is discussed in the User's Manual.

Note that in this usage of calibration_terms, the driver script `rosenbrock`, is returning "residuals", which the `nl2sol` method is attempting to minimze. Another use case is to provide a data file, which Dakota will attempt to match the model responses to. See calibration_data_file. Finally, as of Dakota 6.2, the field data capability may be used with `nl2sol`. That is, the user can specify field simulation data and field experiment data, and Dakota will interpolate and provide the proper residuals for the calibration.

    # Dakota Input File: rosen_opt_nls.in
    environment
      tabular_data
        tabular_data_file = 'rosen_opt_nls.dat'

    method
      max_iterations = 100
      convergence_tolerance = 1e-4
      nl2sol

    model
      single

    variables
      continuous_design = 2
        initial_point    -1.2      1.0
        lower_bounds     -2.0     -2.0
        upper_bounds      2.0      2.0
        descriptors       'x1'     "x2"

    interface
      analysis_driver = 'rosenbrock'
        direct

    responses
      calibration_terms = 2
      analytic_gradients
      no_hessians

## Theory

NL2SOL has a variety of internal controls as described in AT&T Bell Labs CS TR 153 (http://cm.bell-labs.com/cm/cs/cstr/153.ps.gz). A number of existing Dakota controls (method independent controls and responses controls) are mapped into these NL2SOL internal controls. In particular, Dakota's `convergence_tolerance`, `max_iterations`, `max_function_evaluations`, and `fd_gradient_step_size` are mapped directly into NL2SOL's `rfctol`, `mxiter`, `mxfcal`, and `dltfdj` controls, respectively. In addition, Dakota's `fd_hessian_step_size` is mapped into both `delta0` and `dltfdc`, and Dakota's `output` verbosity is mapped into NL2SOL's `auxprt` and `outlev` (for `normal/`verbose/`debug` `output`,` NL2SOL` prints initial guess, final solution, solution statistics, nondefault values, and changes to the active bound constraint set on every iteration; for `quiet` `output`, NL2SOL prints only the initial guess and final solution; and for `silent` `output`, NL2SOL output is suppressed).

## See Also

These keywords may also be of interest:

- nlssol_sqp
- optpp_g_newton
- field_calibration_terms