mpfit

class eispac.extern.mpfit(fcn, xall=None, functkw={}, parinfo=None, ftol=1e-10, xtol=1e-10, gtol=1e-10, damp=0.0, maxiter=200, factor=100.0, nprint=1, iterfunct='default', iterkw={}, nocovar=0, rescale=0, autoderivative=1, quiet=0, diag=None, epsfcn=None, debug=0)

Bases: object

Perform Levenberg-Marquardt least-squares minimization, based on MINPACK-1.

Parameters:

• fcn (function) – The function to be minimized. The function should return the weighted deviations between the model and the data, as described above.

• xall (array-like) – An array of starting values for each of the parameters of the model. The number of parameters should be fewer than the number of measurements. This parameter is optional if the parinfo keyword is used (but see parinfo). The parinfo keyword provides a mechanism to fix or constrain individual parameters.

• autoderivative ({1, 0}) –

• (1) (If this is set) – automatically via a finite differencing procedure. If not set (0),

• computed (derivatives of the function will be) – automatically via a finite differencing procedure. If not set (0),

• your (then fcn must provide the (analytical) derivatives. To supply) –

• derivatives (own analytical) – Default: set (=1)

• autoderivative=0. (explicitly pass) – Default: set (=1)

• ftol (float, optional) –

  A nonnegative input variable. Termination occurs when both the actual and predicted relative reductions in the sum of squares are at most ftol (and status is accordingly set to 1 or 3). Therefore, ftol measures the relative error desired in the sum of squares.

  Default: 1E-10

• functkw (dict, optional) –

  A dictionary which contains the parameters to be passed to the user-supplied function specified by fcn via the standard Python keyword dictionary mechanism. This is the way you can pass additional data to your user-supplied function without using global variables.

  Consider the following example, if functkw =

  {‘xval’:[1.,2.,3.], ‘yval’:[1.,4.,9.], ‘errval’:[1.,1.,1.]}

  then the user-supplied function should be declared like this:

  def myfunct(p, fjac=None, xval=None, yval=None, errval=None):

  Default: {}, No extra parameters are passed to the function

• gtol (float, optional) –

  A nonnegative input variable. Termination occurs when the cosine of the angle between fvec and any column of the jacobian is at most gtol in absolute value (and status is accordingly set to 4). Therefore, gtol measures the orthogonality desired between the function vector and the columns of the jacobian.

  Default: 1e-10

• iterkw (dict, optional) –

  The keyword arguments to be passed to iterfunct via the dictionary keyword mechanism. This should be a dictionary and is similar in operation to FUNCTKW.

  Default: {}, No arguments are passed.

• iterfunct (function) –

  The name of a function to be called upon each NPRINT iteration of the MPFIT routine. It should be declared in the following way:

  def iterfunct(myfunct, p, iter, fnorm, functkw=None, parinfo=None,

  quiet=0, dof=None, [iterkw keywords here])

  # perform custom iteration update

  iterfunct must accept all three keyword parameters (FUNCTKW, PARINFO and QUIET).

  myfunct - The user-supplied function to be minimized, p - The current set of model parameters iter - The iteration number functkw - The arguments to be passed to myfunct. fnorm - The chi-squared value. quiet - Set when no textual output should be printed. dof - The number of degrees of freedom, normally the number of

  points less the number of free parameters.

  See below for documentation of parinfo.

  In implementation, iterfunct can perform updates to the terminal or graphical user interface, to provide feedback while the fit proceeds. If the fit is to be stopped for any reason, then iterfunct should return

• None (a status value between -15 and -1. Otherwise it should return) – (e.g. no return statement) or 0. In principle, iterfunct should probably

• values (not modify the parameter) –

• the (because it may interfere with) –

• iterfunct=None (algorithm's stability. In practice it is allowed. Set) –

• internal (if there is no user-defined routine and you don't want the) –

• called. (default routine be) – Default: an internal routine is used to print the parameter values.

• maxiter (int, optional) – The maximum number of iterations to perform. If the number is exceeded, then the status value is set to 5 and MPFIT returns. Default: 200 iterations

• nocovar ({0, 1}) – Set this keyword to prevent the calculation of the covariance matrix before returning (see COVAR) Default: clear (=0), The covariance matrix is returned

• nprint (int, optional) – The frequency with which iterfunct is called. A value of 1 indicates that iterfunct is called with every iteration, while 2 indicates every other iteration, etc. Note that several Levenberg-Marquardt attempts can be made in a single iteration. Default: 1

• parinfo (list of dicts, optional) –

  Provides a mechanism for more sophisticated constraints to be placed on

  parameter values. When parinfo is not passed, then it is assumed that all parameters are free and unconstrained. Values in parinfo are never modified during a call to MPFIT. PARINFO should be a list of

• dictionaries –

• can (one list entry for each parameter. The dictionary) –

• insensitive) (have the following keys (all keys are optional and case) –

  ‘value’ : float the starting parameter value (see also the XALL parameter).

  ’fixed’ : {0, 1} If set (1), the parameter value will be held fixed. Fixed parameters are not varied by MPFIT, but are passed on to MYFUNCT for evaluation.

  ’limited’ : two-element int array. If the first/second element is set (1), then the parameter is bounded on the lower/upper side. A parameter can be bounded on both sides. Both LIMITED and LIMITS must be given together.

  ’limits’ : two-element float array. Gives the parameter limits on the lower and upper sides, respectively. A value will only be used as a limit if the corresponding value of LIMITED is set (=1). Both LIMITED and LIMITS must be given together.

  ’parname’ : str Name of the parameter. The fitting code of MPFIT does not use this tag in any way. However, the default iterfunct will print the parameter name, if available.

  ’step’ : float Step size to be used in calculating the numerical derivatives. If set to zero, then the step size is computed automatically. Ignored when AUTODERIVATIVE=0.

  ’mpside’ : {0, 1, -1, 2} The sidedness of the finite difference when computing

  numerical derivatives. This field can take four values:

  0 - one-sided derivative computed automatically 1 - one-sided derivative (f(x+h) - f(x))/h -1 - one-sided derivative (f(x) - f(x-h))/h 2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

  Where H is the STEP parameter described above. The “automatic”

  one-sided derivative method will chose a direction for the finite difference which does not violate any constraints. The other methods do not perform this check. The two-sided method is in principle more precise, but requires twice as many function evaluations. Default: 0.

  ’mpmaxstep’ : float The maximum change to be made in the parameter value. During the fitting process, the parameter will never be changed by more than this value in one iteration. A value of 0 indicates no maximum. Default: 0.

  ’tied’ : str String expression which “ties” the parameter to other free or fixed parameters. Any expression involving constants and the parameter array “P” are permitted. Example: if parameter 2 is always to be twice parameter 1 then use the following:

  parinfo[2].tied = ‘2 * p[1]’.

  Since they are totally constrained, tied parameters are

  considered to be fixed; no errors are computed for them. NOTE: the PARNAME can’t be used in expressions.

  ’mpprint’ : {1, 0} If set to 1, then the default iterfunct will print the

  parameter value. If set to 0, the parameter value will not

  be printed. This tag can be used to selectively print only a few parameter values out of many. Default: 1 (all parameters printed)

  Default value: None, All parameters are free and unconstrained.

• quiet ({0, 1}) – Set this keyword = 1 when no textual output should be printed by MPFIT

• damp (float, optional) – A scalar number, indicating the cut-off value of residuals where “damping” will occur. Residuals with magnitudes greater than this number will be replaced by their hyperbolic tangent. This partially mitigates the so-called large residual problem inherent in least-squares solvers (as for the test problem CURVI, http://www.maxthis.com/curviex.htm). A value of 0 indicates no damping.

• Note (DAMP doesn't work with autoderivative=0. Default: 0) –

• xtol (float, optional) –

  A nonnegative input variable. Termination occurs when the relative error

  between two consecutive iterates is at most xtol (and status is accordingly set to 2 or 3). Therefore, xtol measures the relative error desired in the approximate solution. Default: 1E-10

Returns:

The results are attributes of this class, e.g. mpfit.status, mpfit.errmsg, mpfit.params, npfit.niter, mpfit.covar.

.statusint

An integer status code is returned. All values greater than zero

can represent success (however .status == 5 may indicate failure to

converge). It can have one of the following values:

-16

A parameter or function value has become infinite or an undefined number. This is usually a consequence of numerical overflow in the user’s model function, which must be avoided.

-15 to -1

These are error codes that either MYFUNCT or iterfunct may return to terminate the fitting process. Values from -15 to -1 are reserved for the user functions and will not clash with MPFIT.

0 Improper input parameters.

1 Both actual and predicted relative reductions in the sum of squares

are at most ftol.

2 Relative error between two consecutive iterates is at most xtol

3 Conditions for status = 1 and status = 2 both hold.

4 The cosine of the angle between fvec and any column of the jacobian

is at most gtol in absolute value.

5 The maximum number of iterations has been reached.

6 ftol is too small. No further reduction in the sum of squares is

possible.

7 xtol is too small. No further improvement in the approximate solution

x is possible.

8 gtol is too small. fvec is orthogonal to the columns of the jacobian

to machine precision.

.fnormfloat

The value of the summed squared residuals for the returned parameter values.

.covararray-like

The covariance matrix for the set of parameters returned by MPFIT. The matrix is NxN where N is the number of parameters. The square root of the diagonal elements gives the formal 1-sigma statistical errors on the parameters if errors were treated “properly” in fcn. Parameter errors are also returned in .perror.

To compute the correlation matrix, pcor, use this example:

cov = mpfit.covar pcor = cov * 0. for i in range(n):

for j in range(n):

pcor[i,j] = cov[i,j]/sqrt(cov[i,i]*cov[j,j])

If nocovar is set or MPFIT terminated abnormally, then .covar is set to a scalar with value None.

.errmsgstr

A string error or warning message is returned.

.nfevint

The number of calls to MYFUNCT performed.

.niterint

The number of iterations completed.

.perrorarray-like

The formal 1-sigma errors in each parameter, computed from the covariance matrix. If a parameter is held fixed, or if it touches a boundary, then the error is reported as zero.

If the fit is unweighted (i.e. no errors were given, or the weights were uniformly set to unity), then .perror will probably not represent the true parameter uncertainties.

If you can assume that the true reduced chi-squared value is unity – meaning that the fit is implicitly assumed to be of good quality – then the estimated parameter uncertainties can be computed by scaling .perror by the measured chi-squared value.

dof = len(x) - len(mpfit.params) # deg of freedom # scaled uncertainties pcerror = mpfit.perror * sqrt(mpfit.fnorm / dof)

Return type:

mpfit class object

Attributes Summary

blas_enorm32
blas_enorm64

Methods Summary

calc_covar(rr[, ipvt, tol])
call(fcn, x, functkw[, fjac])
defiter(fcn, x, iter[, fnorm, functkw, ...])
enorm(vec)
fdjac2(fcn, x, fvec[, step, ulimited, ...])
lmpar(r, ipvt, diag, qtb, delta, x, sdiag[, par])
parinfo([parinfo, key, default, n])
qrfac(a[, pivot])
qrsolv(r, ipvt, diag, qtb, sdiag)
tie(p[, ptied])

Attributes Documentation

blas_enorm32 = <fortran dnrm2>

blas_enorm64 = <fortran dnrm2>

Methods Documentation

calc_covar(rr, ipvt=None, tol=1e-14)

call(fcn, x, functkw, fjac=None)

defiter(fcn, x, iter, fnorm=None, functkw=None, quiet=0, iterstop=None, parinfo=None, format=None, pformat='%.10g', dof=1)

enorm(vec)

fdjac2(fcn, x, fvec, step=None, ulimited=None, ulimit=None, dside=None, epsfcn=None, autoderivative=1, functkw=None, xall=None, ifree=None, dstep=None)

lmpar(r, ipvt, diag, qtb, delta, x, sdiag, par=None)

parinfo(parinfo=None, key='a', default=None, n=0)

qrfac(a, pivot=0)

qrsolv(r, ipvt, diag, qtb, sdiag)

tie(p, ptied=None)