GSL Routines — lsqfit 13.2.1 documentation

# GSL Routines

## Fitters

`lsqfit` uses routines from the GSL C-library provided it is installed and `lsqfit` is installed from source (not from a Python wheel); GSL is the open-source Gnu Scientific Library. To install `lsqfit` from source use

    python -m pip install lsqfit --no-binary lsqfit --no-cache-dir

making sure that command-line command `gsl-config` is on your `PATH`.

There are two GSL fitters that are available for use by `lsqfit.nonlinear_fit`:

class lsqfit.gsl_multifit(n, f, tol=(1e-5, 0.0, 0.0), maxit=1000, alg='lm', solver='qr', scaler='more', factor_up=3.0, factor_down=2.0, avmax=0.75)

  GSL fitter for nonlinear least-squares multidimensional fits.

  `gsl_multifit` is a function-class whose constructor does a least-squares fit by minimizing `sum_i f_i(x)**2` as a function of vector `x`.

  `gsl_multifit` is a wrapper for the `multifit` GSL routine.

  Parameters:

    - x0 (array of floats): Starting point for minimization.

    - n (positive int): Length of vector returned by the fit function `f(x)`.

    - f (array-valued function): `sum_i f_i(x)**2` is minimized

        by varying parameters `x`. The parameters are a 1-d `numpy` array of either numbers or `gvar.GVar`s.

    - tol (float or tuple): Assigning `tol=(xtol, gtol, ftol)` causes the

        fit to stop searching for a minimum when any of

        > `xtol >=` relative change in parameters between iterations

        > `gtol >=` relative size of gradient of `chi**2`

        > `ftol >=` relative change in `chi**2` between iterations

        is statisfied. See the GSL documentation for detailed definitions of the stopping conditions. Typically one sets `xtol=1/10**d` where `d` is the number of digits of precision desired in the result, while `gtol<<1` and `ftol<<1`. Setting `tol=eps` where `eps` is a number is equivalent to setting `tol=(eps,1e-10,1e-10)`. Setting `tol=(eps1,eps2)` is equivlent to setting `tol=(eps1,eps2,1e-10)`. Default is `tol=1e-5`. (Note: `ftol` option is disabled in some versions of the GSL library.)

    - maxit (int): Maximum number of iterations in search for minimum;

        default is 1000.

    - alg (str): GSL algorithm to use for minimization. The following

        options are supported (see GSL documentation for more information):

        > `'lm'`

        >   Levenberg-Marquardt algorithm (default).

        > `'lmaccel'`

        >   Levenberg-Marquardt algorithm with geodesic acceleration. Can be faster than `'lm'` but less stable. Stability is controlled by damping parameter `avmax`; setting it to zero turns acceleration off.

        > `'subspace2D'`

        >   2D generalization of dogleg algorithm. This can be substantially faster than the two `'lm'` algorithms.

        > `'dogleg'`

        >   dogleg algorithm.

        > `'ddogleg'`

        >   double dogleg algorithm.

    - scaler (str): Scaling method used in minimization. The following

        options are supported (see GSL documentation for more information):

        > `'more'`

        >   More rescaling, which makes the problem scale invariant. Default.

        > `'levenberg'`

        >   Levenberg rescaling, which is not scale invariant but may be more efficient in certain problems.

        > `'marquardt'`

        >   Marquardt rescaling. Probably not as good as the other two options.

    - solver (str): Method use to solve the linear equations for the

        solution from a given step. The following options are supported (see GSL documentation for more information):

        > `'qr'`

        >   QR decomposition of the Jacobian. Default.

        > `'cholesky'`

        >   Cholesky decomposition of the Jacobian. Can be substantially faster than `'qr'` but not as reliable for singular Jacobians.

        > `'svd'`

        >   SVD decomposition. The most robust for singular situations, but also the slowest.

    - factor_up (float): Factor by which search region is increased

        when a search step is accepted. Values that are too large destablize the search; values that are too small slow down the search. Default is `factor_up=3`.

    - factor_down (float): Factor by which search region is decreased

        when a search step is rejected. Values that are too large destablize the search; values that are too small slow down the search. Default is `factor_up=2`.

    - avmax (float): Damping parameter for geodesic acceleration. It

        is the maximum allowed value for the acceleration divided by the velocity. Smaller values imply less acceleration. Default is `avmax=0.75`.

  Attributes:

  > x (array):

  >   Location of the most recently computed (best) fit point.

  > cov (array):

  >   Covariance matrix at the minimum point.

  > description (str):

  >   Short description of internal fitter settings.

  > f (array):

  >   Fit function value `f(x)` at the minimum in the most recent fit.

  > J (array):

  >   Gradient `J_ij = df_i/dx[j]` for most recent fit.

  > nit (int):

  >   Number of function evaluations used in last fit to find the minimum.

  > stopping_criterion (int):

  >   Criterion used to stop fit:

  >   > 0. didn’t converge

  >   > 1. `xtol >=` relative change in parameters between iterations

  >   > 2. `gtol >=` relative size of gradient of `chi**2`

  >   > 3. `ftol >=` relative change in `chi**2` between iterations

  > error (str or None):

  >   `None` if fit successful; an error message otherwise.

class lsqfit.gsl_v1_multifit(x0, n, f, tol=1e-5, maxit=1000, alg='lmsder', analyzer=None)

  Fitter for nonlinear least-squares multidimensional fits. (GSL v1.)

  `gsl_v1_ multifit` is a function-class whose constructor does a least-squares fit by minimizing `sum_i f_i(x)**2` as a function of vector `x`.

  `gsl_v1_multifit` is a wrapper for the (older, v1) `multifit` GSL routine (see `nlin.h`). This package was used in earlier versions of `lsqfit` (<9.0) and is typically not as effective as `gsl_multifit`. It is included (for now) for legacy code.

  Parameters:

    - x0 (array of floats): Starting point for minimization.

    - n (positive int): Length of vector returned by the fit function `f(x)`.

    - f (array-valued function): `sum_i f_i(x)**2` is minimized

        by varying parameters `x`. The parameters are a 1-d `numpy` array of either numbers or `gvar.GVar`s.

    - tol (float or tuple): Assigning `tol=(xtol, gtol, ftol)` causes the

        fit to stop searching for a minimum when any of

        > `xtol >=` relative change in parameters between iterations

        > `gtol >=` relative size of gradient of `chi**2`

        > `ftol >=` relative change in `chi**2` between iterations

        is statisfied. See the GSL documentation for detailed definitions of the stopping conditions. Typically one sets `xtol=1/10**d` where `d` is the number of digits of precision desired in the result, while `gtol<<1` and `ftol<<1`. Setting `tol=eps` where `eps` is a number is equivalent to setting `tol=(eps,1e-10,1e-10)`. Setting `tol=(eps1,eps2)` is equivlent to setting `tol=(eps1,eps2,1e-10)`. Default is `tol=1e-5`. (Note: the `ftol` option is disabled in some versions of the GSL library.)

    - maxit (int): Maximum number of iterations in search for minimum;

        default is 1000.

    - alg (str): GSL algorithm to use for minimization. Two options are

        currently available: `"lmsder"`, the scaled LMDER algorithm (default); and `"lmder"`, the unscaled LMDER algorithm. With version 2 of the GSL library, another option is `"lmniel"`, which can be useful when there is much more data than parameters.

    - analyzer (callable): Optional function of `x,` `[...f_i(x)...],`

        `[[..df_ij(x)..]]` which is called after each iteration. This can be used to inspect intermediate steps in the minimization, if needed.

  Attributes:

  > x (array):

  >   Location of the most recently computed (best) fit point.

  > cov (array):

  >   Covariance matrix at the minimum point.

  > f (callable):

  >   Fit function value `f(x)` at the minimum in the most recent fit.

  > J (array):

  >   Gradient `J_ij = df_i/dx[j]` for most recent fit.

  > nit (int):

  >   Number of function evaluations used in last fit to find the minimum.

  > stopping_criterion (int):

  >   Criterion used to stop fit:

  >   > 0. didn’t converge

  >   > 1. `xtol >=` relative change in parameters between iterations

  >   > 2. `gtol >=` relative size of gradient of `chi**2`

  >   > 3. `ftol >=` relative change in `chi**2` between iterations

  > error (str or None):

  >   `None` if fit successful; an error message otherwise.

## Minimizer

The `lsqfit.empbayes_fit()` uses a minimizer from the GSL library to minimize `logGBF`.

class lsqfit.gsl_multiminex(x0, f, tol=1e-4, maxit=1000, step=1, alg='nmsimplex2', analyzer=None)

  Minimizer for multidimensional functions.

  `multiminex` is a function-class whose constructor minimizes a multidimensional function `f(x)` by varying vector `x`. This routine does not use user-supplied information about the gradient of `f(x)`.

  `multiminex` is a wrapper for the `multimin` GSL routine.

  Parameters:

    - x0 (array): Starting point for minimization search.

    - f (callable): Function `f(x)` to be minimized by varying vector `x`.

    - tol (float): Minimization stops when `x` has converged to with

        tolerance `tol`; default is `1e-4`.

    - maxit (int): Maximum number of iterations in search for minimum;

        default is 1000.

    - step (float): Initial step size to use in varying components of `x`;

        default is 1.

    - alg (str): GSL algorithm to use for minimization. Three options are

        currently available: `"nmsimplex"`, Nelder Mead Simplex algorithm; `"nmsimplex2"`, an improved version of `"nmsimplex"` (default); and `"nmsimplex2rand"`, a version of `"nmsimplex2"` with random shifts in the start position.

    - analyzer (callable): Optional function of `x`, which is called after

        each iteration. This can be used to inspect intermediate steps in the minimization, if needed.

  Attributes:

  > x (array):

  >   Location of the minimum.

  > f (float):

  >   Value of function `f(x)` at the minimum.

  > nit (int):

  >   Number of iterations required to find the minimum.

  > error (None or str):

  >   `None` if minimization successful; an error message otherwise.