.. _method-nl2sol: """""" nl2sol """""" Trust-region method for nonlinear least squares **Topics** nonlinear_least_squares .. toctree:: :hidden: :maxdepth: 1 method-nl2sol-function_precision method-nl2sol-absolute_conv_tol method-nl2sol-x_conv_tol method-nl2sol-singular_conv_tol method-nl2sol-singular_radius method-nl2sol-false_conv_tol method-nl2sol-initial_trust_radius method-nl2sol-covariance method-nl2sol-regression_diagnostics method-nl2sol-convergence_tolerance method-nl2sol-max_iterations method-nl2sol-speculative method-nl2sol-max_function_evaluations method-nl2sol-scaling method-nl2sol-model_pointer **Specification** - *Alias:* None - *Arguments:* None **Child Keywords:** +-------------------------+--------------------+------------------------------+---------------------------------------------+ | Required/Optional | Description of | Dakota Keyword | Dakota Keyword Description | | | Group | | | +=========================+====================+==============================+=============================================+ | 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 | +----------------------------------------------+------------------------------+---------------------------------------------+ .. __: method-nl2sol-function_precision.html __ method-nl2sol-absolute_conv_tol.html __ method-nl2sol-x_conv_tol.html __ method-nl2sol-singular_conv_tol.html __ method-nl2sol-singular_radius.html __ method-nl2sol-false_conv_tol.html __ method-nl2sol-initial_trust_radius.html __ method-nl2sol-covariance.html __ method-nl2sol-regression_diagnostics.html __ method-nl2sol-convergence_tolerance.html __ method-nl2sol-max_iterations.html __ method-nl2sol-speculative.html __ method-nl2sol-max_function_evaluations.html __ method-nl2sol-scaling.html __ method-nl2sol-model_pointer.html **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 :dakkw:`environment-results_output-hdf5` keyword, this method writes the following results to HDF5: - :ref:`hdf5_results-best_params` - :ref:`hdf5_results-best_constraints` - :ref:`hdf5_results-calibration` (when :dakkw:`responses-calibration_terms` are specified) - :ref:`hdf5_results-lsq_confidence_intervals` (when :dakkw:`responses-calibration_terms-calibration_data-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 :dakkw:`responses-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 :dakkw:`responses-calibration_terms-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. .. code-block:: # 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).