nmrglue.leastsqbound¶

Constrained multivariate least-squares optimization

This module is imported as nmrglue.leastsqbound and can be called as such.

Developer Functions¶

nmrglue.analysis.leastsqbound.leastsqbound(func, x0, args=(), bounds=None, Dfun=None, full_output=0, col_deriv=0, ftol=1.49012e-08, xtol=1.49012e-08, gtol=0.0, maxfev=0, epsfcn=0.0, factor=100, diag=None)[source]¶

Bounded minimization of the sum of squares of a set of equations.

x = arg min(sum(func(y)**2,axis=0))
         y

Parameters

funccallable: should take at least one (possibly length N vector) argument and returns M floating point numbers.
x0ndarray: The starting estimate for the minimization.
argstuple: Any extra arguments to func are placed in this tuple.
boundslist: (min, max) pairs for each element in x, defining the bounds on that parameter. Use None for one of min or max when there is no bound in that direction.
Dfuncallable: A function or method to compute the Jacobian of func with derivatives across the rows. If this is None, the Jacobian will be estimated.
full_outputbool: non-zero to return all optional outputs.
col_derivbool: non-zero to specify that the Jacobian function computes derivatives down the columns (faster, because there is no transpose operation).
ftolfloat: Relative error desired in the sum of squares.
xtolfloat: Relative error desired in the approximate solution.
gtolfloat: Orthogonality desired between the function vector and the columns of the Jacobian.
maxfevint: The maximum number of calls to the function. If zero, then 100*(N+1) is the maximum where N is the number of elements in x0.
epsfcnfloat: A suitable step length for the forward-difference approximation of the Jacobian (for Dfun=None). If epsfcn is less than the machine precision, it is assumed that the relative errors in the functions are of the order of the machine precision.
factorfloat: A parameter determining the initial step bound (factor * || diag * x||). Should be in interval (0.1, 100).
diagsequence: N positive entries that serve as a scale factors for the variables.

Returns

xndarray

The solution (or the result of the last iteration for an unsuccessful call).

cov_xndarray

Uses the fjac and ipvt optional outputs to construct an estimate of the jacobian around the solution. None if a singular matrix encountered (indicates very flat curvature in some direction). This matrix must be multiplied by the residual standard deviation to get the covariance of the parameter estimates – see curve_fit.

infodictdict

a dictionary of optional outputs with the key s:

- 'nfev' : the number of function calls
- 'fvec' : the function evaluated at the output
- 'fjac' : A permutation of the R matrix of a QR
         factorization of the final approximate
         Jacobian matrix, stored column wise.
         Together with ipvt, the covariance of the
         estimate can be approximated.
- 'ipvt' : an integer array of length N which defines
         a permutation matrix, p, such that
         fjac*p = q*r, where r is upper triangular
         with diagonal elements of nonincreasing
         magnitude. Column j of p is column ipvt(j)
         of the identity matrix.
- 'qtf'  : the vector (transpose(q) * fvec).

mesgstr

A string message giving information about the cause of failure.

ierint

An integer flag. If it is equal to 1, 2, 3 or 4, the solution was found. Otherwise, the solution was not found. In either case, the optional output variable ‘mesg’ gives more information.

Notes

“leastsq” is a wrapper around MINPACK’s lmdif and lmder algorithms.

cov_x is a Jacobian approximation to the Hessian of the least squares objective function. This approximation assumes that the objective function is based on the difference between some observed target data (ydata) and a (non-linear) function of the parameters f(xdata, params)

func(params) = ydata - f(xdata, params)

so that the objective function is

  min   sum((ydata - f(xdata, params))**2, axis=0)
params

Contraints on the parameters are enforced using an internal parameter list with appropiate transformations such that these internal parameters can be optimized without constraints. The transfomation between a given internal parameter, p_i, and a external parameter, p_e, are as follows:

With min and max bounds defined

p_i = arcsin((2 * (p_e - min) / (max - min)) - 1.)
p_e = min + ((max - min) / 2.) * (sin(p_i) + 1.)

With only max defined

p_i = sqrt((max - p_e + 1.)**2 - 1.)
p_e = max + 1. - sqrt(p_i**2 + 1.)

With only min defined

p_i = sqrt((p_e - min + 1.)**2 - 1.)
p_e = min - 1. + sqrt(p_i**2 + 1.)

These transfomations are used in the MINUIT package, and described in detail in the section 1.3.1 of the MINUIT User’s Guide.

References

1. James and M. Winkler. MINUIT User’s Guide, July 16, 2004.