diff options
Diffstat (limited to 'math/nlfit/doc')
| -rw-r--r-- | math/nlfit/doc/nlerrors.hlp | 67 | ||||
| -rw-r--r-- | math/nlfit/doc/nleval.hlp | 35 | ||||
| -rw-r--r-- | math/nlfit/doc/nlfit.hd | 12 | ||||
| -rw-r--r-- | math/nlfit/doc/nlfit.hlp | 81 | ||||
| -rw-r--r-- | math/nlfit/doc/nlfit.men | 8 | ||||
| -rw-r--r-- | math/nlfit/doc/nlfree.hlp | 26 | ||||
| -rw-r--r-- | math/nlfit/doc/nlinit.hlp | 86 | ||||
| -rw-r--r-- | math/nlfit/doc/nllmfit.hlp | 172 | ||||
| -rw-r--r-- | math/nlfit/doc/nlpget.hlp | 38 | ||||
| -rw-r--r-- | math/nlfit/doc/nlstat.hlp | 57 | ||||
| -rw-r--r-- | math/nlfit/doc/nlvector.hlp | 43 |
11 files changed, 625 insertions, 0 deletions
diff --git a/math/nlfit/doc/nlerrors.hlp b/math/nlfit/doc/nlerrors.hlp new file mode 100644 index 00000000..3b463c14 --- /dev/null +++ b/math/nlfit/doc/nlerrors.hlp @@ -0,0 +1,67 @@ +.help nlerrors Feb91 "Nlfit Package" +.ih +NAME +nlerrors -- compute the fit statistics and errors in the parameters +.ih +SYNOPSIS +nlerrors[rd] (nl, z, zfit, w, npts, variance, chisqr, errors) + +.nf +pointer nl # curve descriptor +real/double z[npts] # array of input function values +real/double zfit[npts] # array of fitted function values +real/double w[npts] # array of weights +int npts # number of data points +real/double variance # the computed variance of the fit +real/double chisqr # the computed reduced chi-square of the fit +real/double errors[*] # errors in the fitted parameters +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor structure. +.le +.ls z +Array of function values. +.le +.ls zfit +Array of fitted function values. +.le +.ls w +Array of weights. +.le +.ls npts +The number of data points. +.le +.ls variance +The computed variance of the fit. +.le +.ls chisqr +The computed reduced chi-squared of the fit. +.le +.ls errors +Array of errors in the computed parameters. +.le +.ih +DESCRIPTION +Compute the variance and reduced chi-squared of the fit and the +errors in the fitted parameters. +.ih +NOTES +The reduced chi-squared of the fit is the square root of the sum of the +weighted squares of the residuals divided by the number of degrees of freedom. +The variance of the fit is the square root of the sum of the +squares of the residuals divided by the number of degrees of freedom. +If the weighting is uniform, then the reduced chi-squared is equal to the +variance of the fit. +The error of the j-th parameter is the square root of the j-th diagonal +element of the inverse of the data matrix. If the weighting is uniform, +then the errors are scaled by the square root of the variance of the data. + +The zfit array can be computed by a call to the nlvector[rd] routine. +The size of the array required to hold the output error array can be +determined by a call to nlstati. +.ih +SEE ALSO +nlvector,nlstat +.endhelp diff --git a/math/nlfit/doc/nleval.hlp b/math/nlfit/doc/nleval.hlp new file mode 100644 index 00000000..f0bbb400 --- /dev/null +++ b/math/nlfit/doc/nleval.hlp @@ -0,0 +1,35 @@ +.help nleval Feb91 "Nlfit Package" +.ih +NAME +nleval -- evaluate the fitted function at a single point +.ih +SYNOPSIS +z = nleval[rd] (nl, x, nvars) + +.nf +pointer nl # curve descriptor +real/double x[nvars] # array of variables +int nvars # the number of variables +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor structure. +.le +.ls x +Array of variable values at which the curve is to be evaluated. +.le +.ls nvars +The number of variables. +.le +.ih +DESCRIPTION +Evaluate the curve at the specified point. NLEVAL is a real or double +function which returns the fitted z value. +.ih +NOTES +NLEVAL uses the parameter array stored in the curve descriptor structure. +.ih +SEE ALSO +nlvector +.endhelp diff --git a/math/nlfit/doc/nlfit.hd b/math/nlfit/doc/nlfit.hd new file mode 100644 index 00000000..13bb3065 --- /dev/null +++ b/math/nlfit/doc/nlfit.hd @@ -0,0 +1,12 @@ +# Help directory for the NLFIT (non-linear least-squares fitting) package. + +$nlfit = "math$nlfit/" + +nlerrors hlp = nlerrors.hlp, src = nlfit$nlerrorsr.x +nleval hlp = nleval.hlp, src = nlfit$nlevalr.x +nlinit hlp = nlinit.hlp, src = nlfit$nlinitr.x +nlfit hlp = nlfit.hlp, src = nlfit$nlfitr.x +nlfree hlp = nlfree.hlp, src = nlfit$nlfreer.x +nlpget hlp = nlpget.hlp, src = nlfit$nlpgetr.x +nlstat hlp = nlstat.hlp, src = nlfit$nlstatr.x +nlvector hlp = nlvector.hlp, src = nlfit$nlvectorr.x diff --git a/math/nlfit/doc/nlfit.hlp b/math/nlfit/doc/nlfit.hlp new file mode 100644 index 00000000..8ed82512 --- /dev/null +++ b/math/nlfit/doc/nlfit.hlp @@ -0,0 +1,81 @@ +.help nlfit Feb91 "Nlfit Package" +.ih +NAME +nlfit -- fit a curve to a set of data values +.ih +SYNOPSIS +nlfit (nl, x, z, w, npts, nvars, wtflag, ier) + +.nf +pointer nl # curve descriptor +real/double x[npts*nvars] # variable values (stored as x[nvars,npts]) +real/double z[npts] # array of z values +real/double w[npts] # array of weights +int npts # number of data points +int wtflag # type of weighting +int ier # error code +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor structure. +.le +.ls x +Array of x values. +.le +.ls z +Array of function values. +.le +.ls w +Array of weights. +.le +.ls npts +The number of data points. +.le +.ls wtflag +Type of weighting. The options are WTS_USER, WTS_UNIFORM, WTS_CHISQ and +WTS_SCATTER. If wtflag = WTS_USER individual weights for each data point +are supplied by the calling program and points with zero-valued weights are +not included in the fit. If wtflag = WTS_UNIFORM, all weights are assigned +values of 1. If wtflag = WTS_CHISQ the weights are set equal to the +reciprocal of the function value. If wtflag = WTS_SCATTER the fitting +routine adds a scatter term to the weights if the reduced chi-squared of +the fit is significantly greater than 1. +.le +.ls ier +Error code for the fit. The options are DONE, SINGULAR, +NO_DEG_FREEDOM and NOT_DONE. If ier = SINGULAR, the numerical routines +will compute a +solution but one or more of the coefficients will be +zero. If ier = NO_DEG_FREEDOM, there were too few data points to solve the +matrix equations and the routine returns without fitting the data. +If ier = NOT_DONE, the fit could not achieve the desired tolerance with +the given input data in the specified maximum number of iterations. +.le +.ih +DESCRIPTION +NLFIT accumulate the data into the appropriate internal matrices and vectors +and does the fit. +.ih +NOTES +The permitted values of the input wtflag argument to nlfit[rd] are the +following. + +.nf +define WTS_USER # User enters weights +define WTS_UNIFORM # Equal weights +define WTS_CHISQ # Chi-squared weights +define WTS_SCATTER # Weights include scatter term +.fi + +The permitted error values returned from nlfit[rd] are the following. + +.nf +define DONE 0 # Solution converged +define SINGULAR 1 # Singular matrix +define NO_DEG_FREEDOM 2 # Too few points +define NOT_DONE 3 # Solution did not converge +.fi +.ih +SEE ALSO +.endhelp diff --git a/math/nlfit/doc/nlfit.men b/math/nlfit/doc/nlfit.men new file mode 100644 index 00000000..5fb68623 --- /dev/null +++ b/math/nlfit/doc/nlfit.men @@ -0,0 +1,8 @@ + nlerrors - Compute the fits statistics and errors in the parameters + nlfit - Fit the function + nlfree - Free memory allocated by nlinit + nlinit - Initialize the fitting routines + nlpget - Get the values of the fitted parameters + nlstat - Get the value of an NLFIT parameter + nleval - Evaluate the curve at a given point + nlvector - Evaluate the curve at an array of points diff --git a/math/nlfit/doc/nlfree.hlp b/math/nlfit/doc/nlfree.hlp new file mode 100644 index 00000000..9688d5e7 --- /dev/null +++ b/math/nlfit/doc/nlfree.hlp @@ -0,0 +1,26 @@ +.help nlfree Feb91 "Nlfit Package" +.ih +NAME +nlfree -- free the curve descriptor structure +.ih +SYNOPSIS +nlfree[rd] (nl) + +.nf +pointer nl # curve descriptor +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor structure. +.le +.ih +DESCRIPTION +Frees the curve descriptor structure. +.ih +NOTES +NLFREE should be called after each curve fit. +.ih +SEE ALSO +nlinit +.endhelp diff --git a/math/nlfit/doc/nlinit.hlp b/math/nlfit/doc/nlinit.hlp new file mode 100644 index 00000000..94e5e5a9 --- /dev/null +++ b/math/nlfit/doc/nlinit.hlp @@ -0,0 +1,86 @@ +.help nlinit Feb91 "Nlfit Package" +.ih +NAME +nlinit -- initialise curve descriptor +.ih +SYNOPSIS +include <math/nlfit.h> + +nlinit[rd] (nl, fnc, dfnc, params, dparams, nparams, plist, nfparams, + tol, itmax) + +.nf +pointer nl # curve descriptor +int fnc # address of first user-supplied function +int dfnc # address of second user-supplied function +real/double params[nparams] # list of initial parameter values +real/double dparams[nparams]# list of parameter increments +int nparams # number of parameters +int plist[nparams] # list of parameters to be fit +int nfparams # number of parameters to be fit +real/double tol # fitting tolerance +int itmax # maximum number of iterations +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor structure. +.le +.ls fnc +The address of the user-supplied subroutine fncname for evaluating the function +to be fit. The calling sequence of fncname is the following. + +.nf +fncname (x, nvars, params, nparams, zfit) +.fi +.le +.ls dfnc +The address of the user-supplied subroutine dfncname for evaluating the +function to be fit and its derivatives with respect to the parameters. +The calling sequence of dfncname is the following. + +.nf +dfncname (x, nvars, params, dparams, nparams, zfit, derivs) +.fi +.le +.ls params +An array containing initial values of all the parameters, including both +those to be fit and those that are to be held constant. +.le +.ls dparams +An array parameter increment values over which the derivatives are to be +computed empirically. If equations are supplied for the derivatives +inside dfnc, the dparams array is not used. +.le +.ls nparams +The total number of parameters in the user-supplied function. +.le +.ls plist +The list of parameters to be fit. Plist is an integer array containing +the indices of those parameters in params to be fit. +.le +.ls nfparams +The total number of parameters to be fit. +.le +.ls tol +The fitting tolerance. If the difference in the chi-squared +from one iteration to the next is less than the fitting tolerance +times the current chi-squared, the fit has converged. +.le +.ls itmax +The maximum number of fitting iterations. Itmax must be greater than +or equal to 3. +.le +.ih +DESCRIPTION +Allocate space for the curve descriptor structure and the arrays and +vectors used by the numerical routines. Initialize all arrays and vectors +to zero. Return the curve descriptor to the calling routine. +.ih +NOTES +NLINIT must be the first NLFIT routine called. NLINIT returns a NULL pointer +if it encounters an illegal parameter list. +.ih +SEE ALSO +nlfree +.endhelp diff --git a/math/nlfit/doc/nllmfit.hlp b/math/nlfit/doc/nllmfit.hlp new file mode 100644 index 00000000..59309133 --- /dev/null +++ b/math/nlfit/doc/nllmfit.hlp @@ -0,0 +1,172 @@ +.help nlfit Feb91 "Math Package" +.ih +NAME +nlfit -- Levenberg-Marquardt non-linear least-squares fitting package +.ih +SYNOPSIS +The principal entry points into the NLFIT package are listed below. + +.nf + nlinit - Initialize the fitting routines + nlstat - Get the value of an NLFIT parameter + nlpget - Get the values of the fitted parameters + nlfree - Free memory allocated by nlinit + nlfit - Fit the function + nleval - Evaluate the curve at a given point + nlvector - Evaluate the curve at an array of points + nlerrors - Compute the fits statistics and errors in the parameters +.fi + +The calling sequences for the above routines are listed below. The [ird] +stand for integer, real and double precision versions of each routine +respectively. + +.nf + nlinit[rd] (nl, address(fnc), address(dfnc), params, dparams, + nparams, plist, nfparams, tol, itmax) + ival = nlstati (nl, param) + [rd]val = nlstat[rd] (nl, param) + nlpget[rd] (nl, params, nparams) + nlfree[rd] (nl) + nlfit[rd] (nl, x, z, w, npts, nvars, wtflag, ier) + [rd]val = nleval[rd] (nl, x, nvars) + nlvector[rd] (nl, x, zfit, npts, nvars) + nlerrors[rd] (nl, z, zfit, wts, npts, variance, chisqr, errors) +.fi + +The user supplied functions fnc and dfnc must have the following form. + +.nf + fnc (x, nvars, params, nparams, zfit) + dfnc (x, nvars, params, dparams, nparams, zfit, derivs) +.fi + +The addresses of these functions can be obtained by a call to lcopr as +follows. + +.nf + address = locpr (fnc) +.fi + +.ih +DESCRIPTION +The NLFIT package provides a set of routines for fitting data to non-linear +functions of several variables using least squares techniques. +NLFIT uses the Levenberg-Marquardt +method to solve for the parameters of a user specified non-linear equation. +The user must supply two subroutines. The first subroutine evaluates the +function in terms of its parameters. The second subroutine evaluates the +function and its derivatives in terms of its parameters. The user must +also supply initial +guesses for the parameters and parameter increments, the list of +parameters to be varied during the fitting process, a fitting +tolerance and the maximum number of iterations. +.ih +NOTES +The poackage definitions for NLFIT can be found in the file +lib$math/nlfit.h. In order to make these definitions available +to the calling program, the user must insert the statement +"include <math/nlfit.h>" inside the calling program. + +The permitted values for the param argument in nlstat[ird] are the following. + +.nf +define NLNPARAMS integer # Number of parameters +define NLNFPARAMS integer # Number of fitted parameters +define NLITMAX integer # Maximum number of iterations +define NLITER integer # Current number of iterations +define NLNPTS integer # Number of points +define NLSUMSQ real/double # Current reduced chi-squared +define NLOLDSQ real/double # Previous reduced chi-squared +define NLLAMBDA real/double # Value of lambda factor +define NLTOL real/double # Fitting tolerance in %chi-squared +define NLSCATTER real/double # Mean scatter in the fit +.fi + +The permitted values of the wtflag argument in nlfit[rd] are the following. + +.nf +define WTS_USER # User enters weights +define WTS_UNIFORM # Equal weights +define WTS_CHISQ # Chi-squared weights +define WTS_SCATTER # Weights include scatter term +.fi + +The permitted error values returned from nlfit[rd] are the following. + +.nf +define DONE 0 # Solution converged +define SINGULAR 1 # Singular matrix +define NO_DEG_FREEDOM 2 # Too few points +define NOT_DONE 3 # Solution did not converge +.fi +.ih +REFERENCES +1. Bevington,P.R., 1969, Data Reduction and Error Analysis for the Physical +Sciences, Chapter 11, page 235. + +2. Press, W.H. et al., 1986, Numerical Recipes: The Art of Scientific +Computing, Chapter 14, page 523 +.ih +EXAMPLES +.nf +Example 1: Fit a curve to the data using uniform weighting. Fit all the +parameters. + + # Include nlfit definitions + include <math/nlfit.h> + + # Declare the variables + int nparams, nfparams, itmax, npts, nvars, ier + int plist[nparams] + real tol, variance, chisqr + real params[nparams], dparams[nparams], vars[nvars,npts], z[npts] + real w[npts], zfit[npts], errors[nparams] + + # Declare the functions + extern fncname(), dfncname() + int locpr() + + begin + ... get data, set initial values of all parameters, parameter + ... increments, tol and itmax + + # Define list of variables to be fitted + nfparams = nparams + do i = 1, nparams + plist[i] = i + + # Fit only parameters 1,3 and 5 + #nfparams = 3 + #plist[1] = 1 + #plist[2] = 3 + #plist[3] = 5 + + # Initialize the fitting routines + call nlinitr (nl, locpr (fncname), locpr (dfncname), + params, dparams, nparams, plist, nfparams, tol, itmax) + + # Fit the data + call nlfitr (nl, x, z, w, npts, nvars, WTS_UNIFORM, ier) + if (ier != DONE) + ... take error action + + # Compute the statistics of the fit + call nlvectorr (nl, x, zfit, npts, nvars) + call nlerrorsr (nl, z, zfit, wts, npts, variance, chisqr, + errors) + + # Get the values of the fitted parameters + call nlpgetr (nl, params, nparams) + call nlfreer (nl) + + # Print the parameters and their errors. + do i = 1, nparams { + call printf ("%d %g %g\n") + call pargi (i) + call pargr (params[i]) + call pargr (errors[i]) + } + end +.fi +.endhelp diff --git a/math/nlfit/doc/nlpget.hlp b/math/nlfit/doc/nlpget.hlp new file mode 100644 index 00000000..07f2ef5e --- /dev/null +++ b/math/nlfit/doc/nlpget.hlp @@ -0,0 +1,38 @@ +.help nlpget Feb91 "Nlfit Package" + +.ih +NAME +nlpget -- get the number and values of the fitted parameters +.ih +SYNOPSIS +nlpget[rd] (nl, params, nparams) + +.nf +pointer nl # curve descriptor +real/double params[nparams] # the parameters array +int nparams # the number of parameters +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor. +.le +.ls params +Array of fitted parameters. +.le +.ls nparameters +The total number of parameters. +.le +.ih +DESCRIPTION +NLPGET fetches the parameters array and the number of parameters from the +curve descriptor structure. All the parameters, both those that were +fit and those that were held constant are output. +.ih +NOTES +The array size required to hold the output parameters can be determined +by a call to nlstati. +.ih +SEE ALSO +nlstat +.endhelp diff --git a/math/nlfit/doc/nlstat.hlp b/math/nlfit/doc/nlstat.hlp new file mode 100644 index 00000000..a745a663 --- /dev/null +++ b/math/nlfit/doc/nlstat.hlp @@ -0,0 +1,57 @@ +.help nlstat Feb91 "Nlfit Package" +.ih +NAME +nlstat[ird] -- get an NLFIT parameter +.ih +SYNOPSIS +include <math/nlfit.h> + +[ird]val = nlstat[ird] (nl, parameter) + +.nf +pointer nl # curve descriptor +int parameter # parameter to be returned +.fi +.ih +ARGUMENTS +.ls nl +The pointer to the curve descriptor structure. +.le +.ls parameter +Parameter to be return. Definitions in nlfit.h are: + +.nf +NLNPARAMS integer # Number of parameters +NLNFPARAMS integer # Number of fitted parameters +NLITMAX integer # Maximum number of iterations +NLITER integer # Current number of iterations +NLNPTS integer # Number of points +NLSUMSQ real/double # Current reduced chi-squared +NLOLDSQ real/double # Previous reduced chi-squared +NLLAMBDA real/double # Value of lambda factor +NLTOL real/double # Fitting tolerance in %chi-squared +NLSCATTER real/double # Mean scatter in the fit +.fi +.le +.ih +DESCRIPTION +The values of integer, real or double parameters are returned. +The parameters include the number of parameters, the number of fitted +parameters, the maximum number of iterations, the number of iterations, +the total number of points, the current chi-squared, the previous +chi-squared, the lambda factor, the fitting tolerance and the fitted +scatter term. +.ih +EXAMPLES +.nf +include <math/nlfit.h> + +int nlstati() + +call malloc (buf, nlstati (nl, NLNPARAMS), TY_REAL) +call nlpgetr (nl, Memr[buf], nparams) +.fi +.ih +SEE ALSO +nlpget +.endhelp diff --git a/math/nlfit/doc/nlvector.hlp b/math/nlfit/doc/nlvector.hlp new file mode 100644 index 00000000..98308cc3 --- /dev/null +++ b/math/nlfit/doc/nlvector.hlp @@ -0,0 +1,43 @@ +.help nlvector Feb91 "Nlfit Package" +.ih +NAME +nlvector -- evaluate the fitted curve at a set of points +.ih +SYNOPSIS +nlvector[rd] (nl, x, zfit, npts, nvars) + +.nf +pointer nl # curve descriptor +real/double x[nvars*npts] # array of variables stored as x[nvars,npts] +real/double zfit[npts] # array of fitted function values +int npts # number of data points +int nvars # number of variables +.fi +.ih +ARGUMENTS +.ls nl +Pointer to the curve descriptor structure. +.le +.ls x +Array of variable values for all the data points. +.le +.ls zfit +Array of fitted function values. +.le +.ls npts +The number of data points at which the curve is to be evaluated. +.le +.ls nvars +The number of variables in the fitted function. +.le +.ih +DESCRIPTION +Fit the curve to an array of data points. +.ih +NOTES +NLVECTOR uses the coefficient array stored in the curfit descriptor +structure. +.ih +SEE ALSO +nleval +.endhelp |