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