.. _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).


