GSL Routines — lsqfit 9.1 documentation

# GSL Routines

## Fitters

`lsqfit` uses routines from the GSL C-library provided it is installed; GSL is the open-source Gnu Scientific Library. There are two fitters that are available for use by `lsqfit.nonlinear_fit`.

class `lsqfit.` `gsl_multifit`

  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`.

  `lsqfit.gsl_multifit` objects have the following 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`

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

  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 – 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.

  `lsqfit.gsl_v1_multifit` objects have the following 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 – Optional function of `x`, which is called after each iteration. This can be used to inspect intermediate steps in the minimization, if needed.

  `lsqfit.gsl_multiminex` objects have the following 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.