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