.. index::

   single: nonlinear least squares

   single: least squares, nonlinear

*******************************

Nonlinear Least-Squares Fitting

*******************************

.. include:: include.rst

This chapter describes functions for multidimensional nonlinear

least-squares fitting.  There are generally two classes of

algorithms for solving nonlinear least squares problems, which

fall under line search methods and trust region methods.

GSL currently implements only trust region methods and

provides the user with

full access to intermediate steps of the iteration. The user

also has the ability to tune a number of parameters which affect

low-level aspects of the algorithm which can help to accelerate

convergence for the specific problem at hand. GSL provides

two separate interfaces for nonlinear least squares fitting. The

first is designed for small to moderate sized problems, and the

second is designed for very large problems, which may or may not

have significant sparse structure.

The header file :file:`gsl_multifit_nlinear.h` contains prototypes for the

multidimensional nonlinear fitting functions and related declarations

relating to the small to moderate sized systems.

The header file :file:`gsl_multilarge_nlinear.h` contains prototypes for the

multidimensional nonlinear fitting functions and related declarations

relating to large systems.

.. index::

   single: nonlinear least squares, overview

Overview

========

The problem of multidimensional nonlinear least-squares fitting requires

the minimization of the squared residuals of :math:`n` functions,

:math:`f_i`, in :math:`p` parameters, :math:`x_i`,

.. only:: not texinfo

   .. math::

      \Phi(x) &= {1 \over 2} || f(x) ||^2 \\

              &= {1 \over 2} \sum_{i=1}^{n} f_i (x_1, \dots, x_p)^2

.. only:: texinfo

   ::

      \Phi(x) = (1/2) || f(x) ||^2

              = (1/2) \sum_{i=1}^{n} f_i(x_1, ..., x_p)^2 

In trust region methods, the objective (or cost) function :math:`\Phi(x)` is approximated

by a model function :math:`m_k(\delta)` in the vicinity of some point :math:`x_k`. The

model function is often simply a second order Taylor series expansion around the

point :math:`x_k`, ie:

.. only:: not texinfo

   .. math:: \Phi(x_k + \delta) \approx m_k(\delta) = \Phi(x_k) + g_k^T \delta + {1 \over 2} \delta^T B_k \delta

.. only:: texinfo

   ::

      \Phi(x_k + \delta) ~=~ m_k(\delta) = \Phi(x_k) + g_k^T \delta + 1/2 \delta^T B_k \delta

where :math:`g_k = \nabla \Phi(x_k) = J^T f` is the gradient vector at the point :math:`x_k`,

:math:`B_k = \nabla^2 \Phi(x_k)` is the Hessian matrix at :math:`x_k`, or some

approximation to it, and :math:`J` is the :math:`n`-by-:math:`p` Jacobian matrix

.. only:: not texinfo

   .. math:: J_{ij} = \partial f_i / \partial x_j

.. only:: texinfo

   ::

      J_{ij} = d f_i / d x_j

In order to find the next step :math:`\delta`, we minimize the model function

:math:`m_k(\delta)`, but search for solutions only within a region where

we trust that :math:`m_k(\delta)` is a good approximation to the objective

function :math:`\Phi(x_k + \delta)`. In other words,

we seek a solution of the trust region subproblem (TRS)

.. only:: not texinfo

   .. math:: \min_{\delta \in R^p} m_k(\delta) = \Phi(x_k) + g_k^T \delta + {1 \over 2} \delta^T B_k \delta, \qquad\hbox{s.t.}\quad || D_k \delta || \le \Delta_k

.. only:: texinfo

   ::

      \min_(\delta \in R^p) m_k(\delta), s.t. || D_k \delta || <= \Delta_k

where :math:`\Delta_k > 0` is the trust region radius and :math:`D_k` is

a scaling matrix. If :math:`D_k = I`, then the trust region is a ball

of radius :math:`\Delta_k` centered at :math:`x_k`. In some applications,

the parameter vector :math:`x` may have widely different scales. For

example, one parameter might be a temperature on the order of

:math:`10^3` K, while another might be a length on the order of

:math:`10^{-6}` m. In such cases, a spherical trust region may not

be the best choice, since if :math:`\Phi` changes rapidly along

directions with one scale, and more slowly along directions with

a different scale, the model function :math:`m_k` may be a poor

approximation to :math:`\Phi` along the rapidly changing directions.

In such problems, it may be best to use an elliptical trust region,

by setting :math:`D_k` to a diagonal matrix whose entries are designed

so that the scaled step :math:`D_k \delta` has entries of approximately the same

order of magnitude.

The trust region subproblem above normally amounts to solving a

linear least squares system (or multiple systems) for the step

:math:`\delta`. Once :math:`\delta` is computed, it is checked whether

or not it reduces the objective function :math:`\Phi(x)`. A useful

statistic for this is to look at the ratio

.. only:: not texinfo

   .. math:: \rho_k = { \Phi(x_k) - \Phi(x_k + \delta_k) \over m_k(0) - m_k(\delta_k) }

.. only:: texinfo

   ::

      \rho_k = ( \Phi(x_k) - \Phi(x_k + \delta_k) / ( m_k(0) - m_k(\delta_k) )

where the numerator is the actual reduction of the objective function

due to the step :math:`\delta_k`, and the denominator is the predicted

reduction due to the model :math:`m_k`. If :math:`\rho_k` is negative,

it means that the step :math:`\delta_k` increased the objective function

and so it is rejected. If :math:`\rho_k` is positive,

then we have found a step which reduced the objective function and

it is accepted. Furthermore, if :math:`\rho_k` is close to 1,

then this indicates that the model function is a good approximation

to the objective function in the trust region, and so on the next

iteration the trust region is enlarged in order to take more ambitious

steps. When a step is rejected, the trust region is made smaller and

the TRS is solved again. An outline for the general trust region method

used by GSL can now be given.

**Trust Region Algorithm**

1. Initialize: given :math:`x_0`, construct :math:`m_0(\delta)`, :math:`D_0` and :math:`\Delta_0 > 0`

2. For k = 0, 1, 2, ...

   a. If converged, then stop

   b. Solve TRS for trial step :math:`\delta_k`

   c. Evaluate trial step by computing :math:`\rho_k`

      1). if step is accepted, set :math:`x_{k+1} = x_k + \delta_k` and increase radius,

          :math:`\Delta_{k+1} = \alpha \Delta_k`

      2). if step is rejected, set :math:`x_{k+1} = x_k` and decrease radius,

          :math:`\Delta_{k+1} = {\Delta_k \over \beta}`; goto 2(b)

   d. Construct :math:`m_{k+1}(\delta)` and :math:`D_{k+1}`

GSL offers the user a number of different algorithms for solving the trust

region subproblem in 2(b), as well as different choices of scaling matrices

:math:`D_k` and different methods of updating the trust region radius

:math:`\Delta_k`. Therefore, while reasonable default methods are provided,

the user has a lot of control to fine-tune the various steps of the

algorithm for their specific problem.

Solving the Trust Region Subproblem (TRS)

=========================================

Below we describe the methods available for solving the trust region

subproblem. The methods available provide either exact or approximate

solutions to the trust region subproblem. In all algorithms below,

the Hessian matrix :math:`B_k` is approximated as :math:`B_k \approx J_k^T J_k`,

where :math:`J_k = J(x_k)`. In all methods, the solution of the TRS

involves solving a linear least squares system involving the Jacobian

matrix. For small to moderate sized problems (:code:`gsl_multifit_nlinear` interface),

this is accomplished by factoring the full Jacobian matrix, which is provided

by the user, with the Cholesky, QR, or SVD decompositions. For large systems

(:code:`gsl_multilarge_nlinear` interface), the user has two choices. One

is to solve the system iteratively, without needing to store the full

Jacobian matrix in memory. With this method, the user must provide a routine

to calculate the matrix-vector products :math:`J u` or :math:`J^T u` for a given vector :math:`u`.

This iterative method is particularly useful for systems where the Jacobian has

sparse structure, since forming matrix-vector products can be done cheaply. The

second option for large systems involves forming the normal equations matrix

:math:`J^T J` and then factoring it using a Cholesky decomposition. The normal

equations matrix is :math:`p`-by-:math:`p`, typically much smaller than the full

:math:`n`-by-:math:`p` Jacobian, and can usually be stored in memory even if the full

Jacobian matrix cannot. This option is useful for large, dense systems, or if the

iterative method has difficulty converging.

.. index::

   single: Levenberg-Marquardt algorithm

   single: nonlinear least squares, levenberg-marquardt

Levenberg-Marquardt

-------------------

There is a theorem which states that if :math:`\delta_k` is a solution

to the trust region subproblem given above, then there exists

:math:`\mu_k \ge 0` such that

.. only:: not texinfo

   .. math:: \left( B_k + \mu_k D_k^T D_k \right) \delta_k = -g_k

.. only:: texinfo

   ::

      ( B_k + \mu_k D_k^T D_k ) \delta_k = -g_k

with :math:`\mu_k (\Delta_k - ||D_k \delta_k||) = 0`. This

forms the basis of the Levenberg-Marquardt algorithm, which controls

the trust region size by adjusting the parameter :math:`\mu_k`

rather than the radius :math:`\Delta_k` directly. For each radius

:math:`\Delta_k`, there is a unique parameter :math:`\mu_k` which

solves the TRS, and they have an inverse relationship, so that large values of

:math:`\mu_k` correspond to smaller trust regions, while small

values of :math:`\mu_k` correspond to larger trust regions.

With the approximation :math:`B_k \approx J_k^T J_k`, on each iteration,

in order to calculate the step :math:`\delta_k`,

the following linear least squares problem is solved:

.. only:: not texinfo

   .. math::

      \left[

        \begin{array}{c}

          J_k \\

          \sqrt{\mu_k} D_k

        \end{array}

      \right]

      \delta_k =

      -

      \left[

        \begin{array}{c}

          f_k \cr

          0

        \end{array}

      \right]

.. only:: texinfo

   ::

      [J_k; sqrt(mu_k) D_k] \delta_k = - [f_k; 0]

If the step :math:`\delta_k` is accepted, then

:math:`\mu_k` is decreased on the next iteration in order

to take a larger step, otherwise it is increased to take

a smaller step. The Levenberg-Marquardt algorithm provides

an exact solution of the trust region subproblem, but

typically has a higher computational cost per iteration

than the approximate methods discussed below, since it

may need to solve the least squares system above several

times for different values of :math:`\mu_k`.

.. index::

   single: Levenberg-Marquardt algorithm, geodesic acceleration

   single: nonlinear least squares, levenberg-marquardt, geodesic acceleration

Levenberg-Marquardt with Geodesic Acceleration

----------------------------------------------

This method applies a so-called geodesic acceleration correction to

the standard Levenberg-Marquardt step :math:`\delta_k` (Transtrum et al, 2011).

By interpreting :math:`\delta_k` as a first order step along a geodesic in the

model parameter space (ie: a velocity :math:`\delta_k = v_k`), the geodesic

acceleration :math:`a_k` is a second order correction along the

geodesic which is determined by solving the linear least squares system

.. only:: not texinfo

   .. math::

      \left[

        \begin{array}{c}

          J_k \\

          \sqrt{\mu_k} D_k

        \end{array}

      \right]

      a_k =

      -

      \left[

        \begin{array}{c}

          f_{vv}(x_k) \\

          0

        \end{array}

      \right]

.. only:: texinfo

   ::

      [J_k; sqrt(mu_k) D_k] a_k = - [f_vv(x_k); 0]

where :math:`f_{vv}` is the second directional derivative of

the residual vector in the velocity direction :math:`v`,

:math:`f_{vv}(x) = D_v^2 f = \sum_{\alpha\beta} v_{\alpha} v_{\beta} \partial_{\alpha} \partial_{\beta} f(x)`,

where :math:`\alpha` and :math:`\beta` are summed over the :math:`p`

parameters. The new total step is then :math:`\delta_k' = v_k + {1 \over 2}a_k`.

The second order correction :math:`a_k` can be calculated with a modest additional

cost, and has been shown to dramatically reduce the number of iterations

(and expensive Jacobian evaluations) required to reach convergence on a variety

of different problems. In order to utilize the geodesic acceleration, the user must supply a

function which provides the second directional derivative vector

:math:`f_{vv}(x)`, or alternatively the library can use a finite

difference method to estimate this vector with one additional function

evaluation of :math:`f(x + h v)` where :math:`h` is a tunable step size

(see the :code:`h_fvv` parameter description).

.. index::

   single: Dogleg algorithm

   single: nonlinear least squares, dogleg

Dogleg

------

This is Powell's dogleg method, which finds an approximate

solution to the trust region subproblem, by restricting

its search to a piecewise linear "dogleg" path,

composed of the origin, the Cauchy point which represents

the model minimizer along the steepest descent direction,

and the Gauss-Newton point, which is the overall minimizer

of the unconstrained model. The Gauss-Newton step is calculated by

solving

.. math:: J_k \delta_{gn} = -f_k

which is the main computational task for each iteration,

but only needs to be performed once per iteration. If

the Gauss-Newton point is inside the trust region, it is

selected as the step. If it is outside, the method then

calculates the Cauchy point, which is located along the

gradient direction. If the Cauchy point is also outside

the trust region, the method assumes that it is still far

from the minimum and so proceeds along the gradient

direction, truncating the step at the trust region

boundary. If the Cauchy point is inside the trust region,

with the Gauss-Newton point outside, the method

uses a dogleg step, which is a linear combination of the

gradient direction and the Gauss-Newton direction, stopping at the trust

region boundary.

.. index::

   single: double Dogleg algorithm

   single: Dogleg algorithm, double

   single: nonlinear least squares, double dogleg

Double Dogleg

-------------

This method is an improvement over the classical dogleg

algorithm, which attempts to include information about

the Gauss-Newton step while the iteration is still far from

the minimum. When the Cauchy point is inside the trust region

and the Gauss-Newton point is outside, the method computes

a scaled Gauss-Newton point and then takes a dogleg step

between the Cauchy point and the scaled Gauss-Newton point.

The scaling is calculated to ensure that the reduction

in the model :math:`m_k` is about the same as the reduction

provided by the Cauchy point.

Two Dimensional Subspace

------------------------

The dogleg methods restrict the search for the TRS solution

to a 1D curve defined by the Cauchy and Gauss-Newton points.

An improvement to this is to search for a solution using

the full two dimensional subspace spanned by the Cauchy

and Gauss-Newton directions. The dogleg path is of course

inside this subspace, and so this method solves the TRS

at least as accurately as the dogleg methods. Since this

method searches a larger subspace for a solution, it can

converge more quickly than dogleg on some problems. Because

the subspace is only two dimensional, this method is

very efficient and the main computation per iteration is

to determine the Gauss-Newton point.

Steihaug-Toint Conjugate Gradient

---------------------------------

One difficulty of the dogleg methods is calculating the

Gauss-Newton step when the Jacobian matrix is singular. The

Steihaug-Toint method also computes a generalized dogleg

step, but avoids solving for the Gauss-Newton step directly,

instead using an iterative conjugate gradient algorithm. This

method performs well at points where the Jacobian is singular,

and is also suitable for large-scale problems where factoring

the Jacobian matrix could be prohibitively expensive.

Weighted Nonlinear Least-Squares

================================

Weighted nonlinear least-squares fitting minimizes the function

.. only:: not texinfo

   .. math::

      \Phi(x) &= {1 \over 2} || f ||_W^2 \\

              &= {1 \over 2} \sum_{i=1}^{n} w_i f_i (x_1, \dots, x_p)^2

.. only:: texinfo

   ::

      \Phi(x) = (1/2) || f(x) ||_W^2

              = (1/2) \sum_{i=1}^{n} f_i(x_1, ..., x_p)^2 

where :math:`W = \diag(w_1,w_2,...,w_n)` is the weighting matrix,

and :math:`||f||_W^2 = f^T W f`.

The weights :math:`w_i` are commonly defined as :math:`w_i = 1/\sigma_i^2`,

where :math:`\sigma_i` is the error in the :math:`i`-th measurement.

A simple change of variables :math:`\tilde{f} = W^{1 \over 2} f` yields

:math:`\Phi(x) = {1 \over 2} ||\tilde{f}||^2`, which is in the

same form as the unweighted case. The user can either perform this

transform directly on their function residuals and Jacobian, or use

the :func:`gsl_multifit_nlinear_winit` interface which automatically

performs the correct scaling. To manually perform this transformation,

the residuals and Jacobian should be modified according to

.. only:: not texinfo

   .. math::

      \tilde{f}_i & = \sqrt{w_i} f_i = {f_i \over \sigma_i} \\

      \tilde{J}_{ij} & = \sqrt{w_i} { \partial f_i \over \partial x_j } = { 1 \over \sigma_i} { \partial f_i \over \partial x_j }

.. only:: texinfo

   ::

      f~_i = f_i / \sigma_i

      J~_ij = 1 / \sigma_i df_i/dx_j

For large systems, the user must perform their own weighting.

.. _sec_tunable-parameters:

Tunable Parameters

==================

The user can tune nearly all aspects of the iteration at allocation

time. For the :code:`gsl_multifit_nlinear` interface, the user may

modify the :type:`gsl_multifit_nlinear_parameters` structure, which is

defined as follows:

.. type:: gsl_multifit_nlinear_parameters

   ::

      typedef struct

      {

        const gsl_multifit_nlinear_trs *trs;        /* trust region subproblem method */

        const gsl_multifit_nlinear_scale *scale;    /* scaling method */

        const gsl_multifit_nlinear_solver *solver;  /* solver method */

        gsl_multifit_nlinear_fdtype fdtype;         /* finite difference method */

        double factor_up;                           /* factor for increasing trust radius */

        double factor_down;                         /* factor for decreasing trust radius */

        double avmax;                               /* max allowed |a|/|v| */

        double h_df;                                /* step size for finite difference Jacobian */

        double h_fvv;                               /* step size for finite difference fvv */

      } gsl_multifit_nlinear_parameters;

For the :code:`gsl_multilarge_nlinear` interface, the user may

modify the :type:`gsl_multilarge_nlinear_parameters` structure, which is

defined as follows:

.. type:: gsl_multilarge_nlinear_parameters

   ::

      typedef struct

      {

        const gsl_multilarge_nlinear_trs *trs;       /* trust region subproblem method */

        const gsl_multilarge_nlinear_scale *scale;   /* scaling method */

        const gsl_multilarge_nlinear_solver *solver; /* solver method */

        gsl_multilarge_nlinear_fdtype fdtype;        /* finite difference method */

        double factor_up;                            /* factor for increasing trust radius */

        double factor_down;                          /* factor for decreasing trust radius */

        double avmax;                                /* max allowed |a|/|v| */

        double h_df;                                 /* step size for finite difference Jacobian */

        double h_fvv;                                /* step size for finite difference fvv */

        size_t max_iter;                             /* maximum iterations for trs method */

        double tol;                                  /* tolerance for solving trs */

      } gsl_multilarge_nlinear_parameters;

Each of these parameters is discussed in further detail below.

.. type:: gsl_multifit_nlinear_trs

          gsl_multilarge_nlinear_trs

   The parameter :data:`trs` determines the method used to solve the trust region

   subproblem, and may be selected from the following choices,

   .. var:: gsl_multifit_nlinear_trs_lm

            gsl_multilarge_nlinear_trs_lm

      This selects the Levenberg-Marquardt algorithm.

   .. var:: gsl_multifit_nlinear_trs_lmaccel

            gsl_multilarge_nlinear_trs_lmaccel

      This selects the Levenberg-Marquardt algorithm with geodesic

      acceleration.

   .. var:: gsl_multifit_nlinear_trs_dogleg

            gsl_multilarge_nlinear_trs_dogleg

      This selects the dogleg algorithm.

   .. var:: gsl_multifit_nlinear_trs_ddogleg

            gsl_multilarge_nlinear_trs_ddogleg

      This selects the double dogleg algorithm.

   .. var:: gsl_multifit_nlinear_trs_subspace2D

            gsl_multilarge_nlinear_trs_subspace2D

      This selects the 2D subspace algorithm.

   .. var:: gsl_multilarge_nlinear_trs_cgst

      This selects the Steihaug-Toint conjugate gradient algorithm. This

      method is available only for large systems.

.. type:: gsl_multifit_nlinear_scale

          gsl_multilarge_nlinear_scale

   The parameter :data:`scale` determines the diagonal scaling matrix :math:`D` and

   may be selected from the following choices,

   .. var:: gsl_multifit_nlinear_scale_more

            gsl_multilarge_nlinear_scale_more

      This damping strategy was suggested by |More|, and

      corresponds to :math:`D^T D = \max(\diag(J^T J))`,

      in other words the maximum elements of

      :math:`\diag(J^T J)` encountered thus far in the iteration.

      This choice of :math:`D` makes the problem scale-invariant,

      so that if the model parameters :math:`x_i` are each scaled

      by an arbitrary constant, :math:`\tilde{x}_i = a_i x_i`, then

      the sequence of iterates produced by the algorithm would

      be unchanged. This method can work very well in cases

      where the model parameters have widely different scales

      (ie: if some parameters are measured in nanometers, while others

      are measured in degrees Kelvin). This strategy has been proven

      effective on a large class of problems and so it is the library

      default, but it may not be the best choice for all problems.

   .. var:: gsl_multifit_nlinear_scale_levenberg

            gsl_multilarge_nlinear_scale_levenberg

      This damping strategy was originally suggested by Levenberg, and

      corresponds to :math:`D^T D = I`. This method has also proven

      effective on a large class of problems, but is not scale-invariant.

      However, some authors (e.g. Transtrum and Sethna 2012) argue

      that this choice is better for problems which are susceptible

      to parameter evaporation (ie: parameters go to infinity)

   .. var:: gsl_multifit_nlinear_scale_marquardt

            gsl_multilarge_nlinear_scale_marquardt

      This damping strategy was suggested by Marquardt, and

      corresponds to :math:`D^T D = \diag(J^T J)`. This

      method is scale-invariant, but it is generally considered

      inferior to both the Levenberg and |More| strategies, though

      may work well on certain classes of problems.

.. type:: gsl_multifit_nlinear_solver

          gsl_multilarge_nlinear_solver

   Solving the trust region subproblem on each iteration almost always

   requires the solution of the following linear least squares system

   .. only:: not texinfo

      .. math::

         \left[

           \begin{array}{c}

             J \\

             \sqrt{\mu} D

           \end{array}

         \right]

         \delta =

         -

         \left[

           \begin{array}{c}

             f \\

             0

           \end{array}

         \right]

   .. only:: texinfo

      ::

         [J; sqrt(mu) D] \delta = - [f; 0]

   The :data:`solver` parameter determines how the system is

   solved and can be selected from the following choices:

   .. var:: gsl_multifit_nlinear_solver_qr

      This method solves the system using a rank revealing QR

      decomposition of the Jacobian :math:`J`. This method will

      produce reliable solutions in cases where the Jacobian

      is rank deficient or near-singular but does require about

      twice as many operations as the Cholesky method discussed

      below.

   .. var:: gsl_multifit_nlinear_solver_cholesky

            gsl_multilarge_nlinear_solver_cholesky

      This method solves the alternate normal equations problem

      .. only:: not texinfo

         .. math:: \left( J^T J + \mu D^T D \right) \delta = -J^T f

      .. only:: texinfo

         ::

            ( J^T J + \mu D^T D ) \delta = -J^T f

      by using a Cholesky decomposition of the matrix

      :math:`J^T J + \mu D^T D`. This method is faster than the

      QR approach, however it is susceptible to numerical instabilities

      if the Jacobian matrix is rank deficient or near-singular. In

      these cases, an attempt is made to reduce the condition number

      of the matrix using Jacobi preconditioning, but for highly

      ill-conditioned problems the QR approach is better. If it is

      known that the Jacobian matrix is well conditioned, this method

      is accurate and will perform faster than the QR approach.

   .. var:: gsl_multifit_nlinear_solver_svd

      This method solves the system using a singular value

      decomposition of the Jacobian :math:`J`. This method will

      produce the most reliable solutions for ill-conditioned Jacobians

      but is also the slowest solver method.

.. type:: gsl_multifit_nlinear_fdtype

   The parameter :data:`fdtype` specifies whether to use forward or centered

   differences when approximating the Jacobian. This is only

   used when an analytic Jacobian is not provided to the solver.

   This parameter may be set to one of the following choices.

   .. macro:: GSL_MULTIFIT_NLINEAR_FWDIFF

      This specifies a forward finite difference to approximate

      the Jacobian matrix. The Jacobian matrix will be calculated as

      .. only:: not texinfo

         .. math:: J_{ij} = {1 \over \Delta_j} \left( f_i(x + \Delta_j e_j) - f_i(x) \right)

      .. only:: texinfo

         ::

            J_ij = 1 / \Delta_j ( f_i(x + \Delta_j e_j) - f_i(x) )

      where :math:`\Delta_j = h |x_j|` and :math:`e_j` is the standard

      :math:`j`-th Cartesian unit basis vector so that

      :math:`x + \Delta_j e_j` represents a small (forward) perturbation of

      the :math:`j`-th parameter by an amount :math:`\Delta_j`. The perturbation

      :math:`\Delta_j` is proportional to the current value :math:`|x_j|` which

      helps to calculate an accurate Jacobian when the various parameters have

      different scale sizes. The value of :math:`h` is specified by the :code:`h_df`

      parameter. The accuracy of this method is :math:`O(h)`, and evaluating this

      matrix requires an additional :math:`p` function evaluations.

   .. macro:: GSL_MULTIFIT_NLINEAR_CTRDIFF

      This specifies a centered finite difference to approximate

      the Jacobian matrix. The Jacobian matrix will be calculated as

      .. only:: not texinfo

         .. math:: J_{ij} = {1 \over \Delta_j} \left( f_i(x + {1 \over 2} \Delta_j e_j) - f_i(x - {1 \over 2} \Delta_j e_j) \right)

      .. only:: texinfo

         ::

            J_ij = 1 / \Delta_j ( f_i(x + 1/2 \Delta_j e_j) - f_i(x - 1/2 \Delta_j e_j) )

      See above for a description of :math:`\Delta_j`. The accuracy of this

      method is :math:`O(h^2)`, but evaluating this

      matrix requires an additional :math:`2p` function evaluations.

:code:`double factor_up`

When a step is accepted, the trust region radius will be increased

by this factor. The default value is :math:`3`.

:code:`double factor_down`

When a step is rejected, the trust region radius will be decreased

by this factor. The default value is :math:`2`.

:code:`double avmax`

When using geodesic acceleration to solve a nonlinear least squares problem,

an important parameter to monitor is the ratio of the acceleration term

to the velocity term,

.. only:: not texinfo

   .. math:: { ||a|| \over ||v|| }

.. only:: texinfo

   ::

      |a| / |v|

If this ratio is small, it means the acceleration correction

is contributing very little to the step. This could be because

the problem is not "nonlinear" enough to benefit from

the acceleration. If the ratio is large (:math:`> 1`) it

means that the acceleration is larger than the velocity,

which shouldn't happen since the step represents a truncated

series and so the second order term :math:`a` should be smaller than

the first order term :math:`v` to guarantee convergence.

Therefore any steps with a ratio larger than the parameter

:data:`avmax` are rejected. :data:`avmax` is set to 0.75 by default.

For problems which experience difficulty converging, this threshold

could be lowered.

:code:`double h_df`

This parameter specifies the step size for approximating the

Jacobian matrix with finite differences. It is set to

:math:`\sqrt{\epsilon}` by default, where :math:`\epsilon`

is :macro:`GSL_DBL_EPSILON`.

:code:`double h_fvv`

When using geodesic acceleration, the user must either supply

a function to calculate :math:`f_{vv}(x)` or the library

can estimate this second directional derivative using a finite

difference method. When using finite differences, the library

must calculate :math:`f(x + h v)` where :math:`h` represents

a small step in the velocity direction. The parameter

:data:`h_fvv` defines this step size and is set to 0.02 by

default.

Initializing the Solver

=======================

.. type:: gsl_multifit_nlinear_type

   This structure specifies the type of algorithm which will be used

   to solve a nonlinear least squares problem. It may be selected from the

   following choices,

   .. var:: gsl_multifit_nlinear_trust

      This specifies a trust region method. It is currently the only implemented

      nonlinear least squares method.

.. function:: gsl_multifit_nlinear_workspace * gsl_multifit_nlinear_alloc (const gsl_multifit_nlinear_type * T, const gsl_multifit_nlinear_parameters * params, const size_t n, const size_t p)

              gsl_multilarge_nlinear_workspace * gsl_multilarge_nlinear_alloc (const gsl_multilarge_nlinear_type * T, const gsl_multilarge_nlinear_parameters * params, const size_t n, const size_t p)

   These functions return a pointer to a newly allocated instance of a

   derivative solver of type :data:`T` for :data:`n` observations and :data:`p`

   parameters. The :data:`params` input specifies a tunable set of

   parameters which will affect important details in each iteration

   of the trust region subproblem algorithm. It is recommended to start

   with the suggested default parameters (see

   :func:`gsl_multifit_nlinear_default_parameters` and

   :func:`gsl_multilarge_nlinear_default_parameters`) and then tune

   the parameters once the code is working correctly. See

   :ref:`sec_tunable-parameters`.

   for descriptions of the various parameters.

   For example, the following code creates an instance of a

   Levenberg-Marquardt solver for 100 data points and 3 parameters,

   using suggested defaults::

      const gsl_multifit_nlinear_type * T = gsl_multifit_nlinear_trust;

      gsl_multifit_nlinear_parameters params = gsl_multifit_nlinear_default_parameters();

      gsl_multifit_nlinear_workspace * w = gsl_multifit_nlinear_alloc (T, &params, 100, 3);

   The number of observations :data:`n` must be greater than or equal to

   parameters :data:`p`.

   If there is insufficient memory to create the solver then the function

   returns a null pointer and the error handler is invoked with an error

   code of :macro:`GSL_ENOMEM`.

.. function:: gsl_multifit_nlinear_parameters gsl_multifit_nlinear_default_parameters (void)

              gsl_multilarge_nlinear_parameters gsl_multilarge_nlinear_default_parameters (void)

   These functions return a set of recommended default parameters

   for use in solving nonlinear least squares problems. The user

   can tune each parameter to improve the performance on their

   particular problem, see :ref:`sec_tunable-parameters`.

.. function:: int gsl_multifit_nlinear_init (const gsl_vector * x, gsl_multifit_nlinear_fdf * fdf, gsl_multifit_nlinear_workspace * w)

              int gsl_multifit_nlinear_winit (const gsl_vector * x, const gsl_vector * wts, gsl_multifit_nlinear_fdf * fdf, gsl_multifit_nlinear_workspace * w)

              int gsl_multilarge_nlinear_init (const gsl_vector * x, gsl_multilarge_nlinear_fdf * fdf, gsl_multilarge_nlinear_workspace * w)

   These functions initialize, or reinitialize, an existing workspace :data:`w`

   to use the system :data:`fdf` and the initial guess

   :data:`x`. See :ref:`sec_providing-function-minimized`

   for a description of the :data:`fdf` structure.

   Optionally, a weight vector :data:`wts` can be given to perform

   a weighted nonlinear regression. Here, the weighting matrix is

   :math:`W = \diag(w_1,w_2,...,w_n)`.

.. function:: void gsl_multifit_nlinear_free (gsl_multifit_nlinear_workspace * w)

              void gsl_multilarge_nlinear_free (gsl_multilarge_nlinear_workspace * w)

   These functions free all the memory associated with the workspace :data:`w`.

.. function:: const char * gsl_multifit_nlinear_name (const gsl_multifit_nlinear_workspace * w)

              const char * gsl_multilarge_nlinear_name (const gsl_multilarge_nlinear_workspace * w)

   These functions return a pointer to the name of the solver.  For example::

      printf ("w is a '%s' solver\n", gsl_multifit_nlinear_name (w));

   would print something like :code:`w is a 'trust-region' solver`.

.. function:: const char * gsl_multifit_nlinear_trs_name (const gsl_multifit_nlinear_workspace * w)

              const char * gsl_multilarge_nlinear_trs_name (const gsl_multilarge_nlinear_workspace * w)

   These functions return a pointer to the name of the trust region subproblem

   method.  For example::

      printf ("w is a '%s' solver\n", gsl_multifit_nlinear_trs_name (w));

   would print something like :code:`w is a 'levenberg-marquardt' solver`.

.. _sec_providing-function-minimized:

Providing the Function to be Minimized

======================================

The user must provide :math:`n` functions of :math:`p` variables for the

minimization algorithm to operate on.  In order to allow for

arbitrary parameters the functions are defined by the following data

types:

.. type:: gsl_multifit_nlinear_fdf

   This data type defines a general system of functions with arbitrary parameters,

   the corresponding Jacobian matrix of derivatives, and optionally the

   second directional derivative of the functions for geodesic acceleration.

   :code:`int (* f) (const gsl_vector * x, void * params, gsl_vector * f)`

      This function should store the :math:`n` components of the vector

      :math:`f(x)` in :data:`f` for argument :data:`x` and arbitrary parameters :data:`params`,

      returning an appropriate error code if the function cannot be computed.

   :code:`int (* df) (const gsl_vector * x, void * params, gsl_matrix * J)`

      This function should store the :data:`n`-by-:data:`p` matrix result

      .. only:: not texinfo

         .. math:: J_{ij} = \partial f_i(x) / \partial x_j