blob: 3a13359a67095a7b762c4fff805210dd54424a59 [file] [log] [blame]
 =pod =begin html =end html =head1 NAME lmcurve - Levenberg-Marquardt least-squares fit of a curve (t,y) =head1 SYNOPSIS B<#include > B IB<, double *>IB<, const int> IB<, constS< >double *>IB<, constS< >double *>IB<, double (*>IB<)( const double >IB<, const double *>IB< ), constS< >lm_control_struct *>IB<, lm_status_struct *>IB<);> B IB<, double *>IB<, const int> IB<, constS< >double *>IB<, constS< >double *>IB<, constS< >double *>IB<, double (*>IB<)( const double >IB<, const double *>IB< ), constS< >lm_control_struct *>IB<, lm_status_struct *>IB<);> B B B B =head1 DESCRIPTION B and B wrap the more generic minimization function B, for use in curve fitting. B determines a vector I that minimizes the sum of squared elements of a residue vector I[i] := I[i] - I(I[i];I). Typically, B is used to approximate a data set I,I by a parametric function I(I;I). On success, I represents a local minimum, not necessarily a global one; it may depend on its starting value. B does the same for a data set I,I,I, where I represents the standard deviation of empirical data I. Residues are computed as I[i] := (I[i] - I(I[i];I))/I[i]. Users must ensure that all I[i] are positive. Function arguments: =over =item I Number of free variables. Length of parameter vector I. =item I Parameter vector. On input, it must contain a reasonable guess. On output, it contains the solution found to minimize ||I||. =item I Number of data points. Length of vectors I and I. Must statisfy I <= I. =item I Array of length I. Contains the abcissae (time, or "x") for which function I will be evaluated. =item I Array of length I. Contains the ordinate values that shall be fitted. =item I Only in B. Array of length I. Contains the standard deviations of the values I. =item I A user-supplied parametric function I(ti;I). =item I Parameter collection for tuning the fit procedure. In most cases, the default &I is adequate. If I is only computed with single-precision accuracy, I<&lm_control_float> should be used. Parameters are explained in B. =item I A record used to return information about the minimization process: For details, see B. =back =head1 EXAMPLE Fit a data set y(x) by a curve f(x;p): #include "lmcurve.h" #include /* model function: a parabola */ double f( double t, const double *p ) { return p[0] + p[1]*t + p[2]*t*t; } int main() { int n = 3; /* number of parameters in model function f */ double par[3] = { 100, 0, -10 }; /* really bad starting value */ /* data points: a slightly distorted standard parabola */ int m = 9; int i; double t[9] = { -4., -3., -2., -1., 0., 1., 2., 3., 4. }; double y[9] = { 16.6, 9.9, 4.4, 1.1, 0., 1.1, 4.2, 9.3, 16.4 }; lm_control_struct control = lm_control_double; lm_status_struct status; control.verbosity = 7; printf( "Fitting ...\n" ); lmcurve( n, par, m, t, y, f, &control, &status ); printf( "Results:\n" ); printf( "status after %d function evaluations:\n %s\n", status.nfev, lm_infmsg[status.outcome] ); printf("obtained parameters:\n"); for ( i = 0; i < n; ++i) printf(" par[%i] = %12g\n", i, par[i]); printf("obtained norm:\n %12g\n", status.fnorm ); printf("fitting data as follows:\n"); for ( i = 0; i < m; ++i) printf( " t[%2d]=%4g y=%6g fit=%10g residue=%12g\n", i, t[i], y[i], f(t[i],par), y[i] - f(t[i],par) ); return 0; } =head1 COPYING Copyright (C) 2009-2015 Joachim Wuttke, Forschungszentrum Juelich GmbH Software: FreeBSD License Documentation: Creative Commons Attribution Share Alike =head1 SEE ALSO =begin html lmmin(3) =end html =begin man \fBlmmin\fR(3) .PP =end man Homepage: http://apps.jcns.fz-juelich.de/lmfit =head1 BUGS Please send bug reports and suggestions to the author .