1 =pod 2 3 =begin html 4 5 <link rel="stylesheet" href="podstyle.css" type="text/css" /> 6 7 =end html 8 9 =head1 NAME 10 11 lmcurve - Levenberg-Marquardt least-squares fit of a curve (t,y) 12 13 14 =head1 SYNOPSIS 15 16 B<#include <lmcurve.h>> 17 18 B<void lmcurve( const int> I<n_par>B<, double *>I<par>B<, const int> I<m_dat>B<, 19 constS< >double *>I<t>B<, constS< >double *>I<y>B<, 20 double (*>I<f>B<)( const double >I<ti>B<, const double *>I<par>B< ), 21 constS< >lm_control_struct *>I<control>B<, 22 lm_status_struct *>I<status>B<);> 23 24 B<void lmcurve_tyd( 25 const int> I<n_par>B<, double *>I<par>B<, const int> I<m_dat>B<, 26 constS< >double *>I<t>B<, constS< >double *>I<y>B<, constS< >double *>I<dy>B<, 27 double (*>I<f>B<)( const double >I<ti>B<, const double *>I<par>B< ), 28 constS< >lm_control_struct *>I<control>B<, 29 lm_status_struct *>I<status>B<);> 30 31 B<extern const lm_control_struct lm_control_double;> 32 33 B<extern const lm_control_struct lm_control_float;> 34 35 B<extern const char *lm_infmsg[];> 36 37 B<extern const char *lm_shortmsg[];> 38 39 =head1 DESCRIPTION 40 41 B<lmcurve()> and B<lmcurve_tyd()> wrap the more generic minimization function B<lmmin()>, for use in curve fitting. 42 43 B<lmcurve()> determines a vector I<par> that minimizes the sum of squared elements of a residue vector I<r>[i] := I<y>[i] - I<f>(I<t>[i];I<par>). Typically, B<lmcurve()> is used to approximate a data set I<t>,I<y> by a parametric function I<f>(I<ti>;I<par>). On success, I<par> represents a local minimum, not necessarily a global one; it may depend on its starting value. 44 45 B<lmcurve_tyd()> does the same for a data set I<t>,I<y>,I<dy>, where I<dy> represents the standard deviation of empirical data I<y>. Residues are computed as I<r>[i] := (I<y>[i] - I<f>(I<t>[i];I<par>))/I<dy>[i]. Users must ensure that all I<dy>[i] are positive. 46 47 48 Function arguments: 49 50 =over 51 52 =item I<n_par> 53 54 Number of free variables. 55 Length of parameter vector I<par>. 56 57 =item I<par> 58 59 Parameter vector. 60 On input, it must contain a reasonable guess. 61 On output, it contains the solution found to minimize ||I<r>||. 62 63 =item I<m_dat> 64 65 Number of data points. 66 Length of vectors I<t> and I<y>. 67 Must statisfy I<n_par> <= I<m_dat>. 68 69 =item I<t> 70 71 Array of length I<m_dat>. 72 Contains the abcissae (time, or "x") for which function I<f> will be evaluated. 73 74 =item I<y> 75 76 Array of length I<m_dat>. 77 Contains the ordinate values that shall be fitted. 78 79 =item I<dy> 80 81 Only in B<lmcurve_tyd()>. 82 Array of length I<m_dat>. 83 Contains the standard deviations of the values I<y>. 84 85 =item I<f> 86 87 A user-supplied parametric function I<f>(ti;I<par>). 88 89 =item I<control> 90 91 Parameter collection for tuning the fit procedure. 92 In most cases, the default &I<lm_control_double> is adequate. 93 If I<f> is only computed with single-precision accuracy, 94 I<&lm_control_float> should be used. 95 Parameters are explained in B<lmmin(3)>. 96 97 =item I<status> 98 99 A record used to return information about the minimization process: 100 For details, see B<lmmin(3)>. 101 102 =back 103 104 =head1 EXAMPLE 105 106 Fit a data set y(x) by a curve f(x;p): 107 108 #include "lmcurve.h" 109 #include <stdio.h> 110 111 /* model function: a parabola */ 112 113 double f( double t, const double *p ) 114 { 115 return p[0] + p[1]*t + p[2]*t*t; 116 } 117 118 int main() 119 { 120 int n = 3; /* number of parameters in model function f */ 121 double par[3] = { 100, 0, -10 }; /* really bad starting value */ 122 123 /* data points: a slightly distorted standard parabola */ 124 int m = 9; 125 int i; 126 double t[9] = { -4., -3., -2., -1., 0., 1., 2., 3., 4. }; 127 double y[9] = { 16.6, 9.9, 4.4, 1.1, 0., 1.1, 4.2, 9.3, 16.4 }; 128 129 lm_control_struct control = lm_control_double; 130 lm_status_struct status; 131 control.verbosity = 7; 132 133 printf( "Fitting ...\n" ); 134 lmcurve( n, par, m, t, y, f, &control, &status ); 135 136 printf( "Results:\n" ); 137 printf( "status after %d function evaluations:\n %s\n", 138 status.nfev, lm_infmsg[status.outcome] ); 139 140 printf("obtained parameters:\n"); 141 for ( i = 0; i < n; ++i) 142 printf(" par[%i] = %12g\n", i, par[i]); 143 printf("obtained norm:\n %12g\n", status.fnorm ); 144 145 printf("fitting data as follows:\n"); 146 for ( i = 0; i < m; ++i) 147 printf( " t[%2d]=%4g y=%6g fit=%10g residue=%12g\n", 148 i, t[i], y[i], f(t[i],par), y[i] - f(t[i],par) ); 149 150 return 0; 151 } 152 153 =head1 COPYING 154 155 Copyright (C) 2009-2015 Joachim Wuttke, Forschungszentrum Juelich GmbH 156 157 Software: FreeBSD License 158 159 Documentation: Creative Commons Attribution Share Alike 160 161 162 =head1 SEE ALSO 163 164 =begin html 165 166 <a href="http://apps.jcns.fz-juelich.de/man/lmmin.html"><b>lmmin</b>(3)</a> 167 168 =end html 169 170 =begin man 171 172 \fBlmmin\fR(3) 173 .PP 174 175 =end man 176 177 Homepage: http://apps.jcns.fz-juelich.de/lmfit 178 179 =head1 BUGS 180 181 Please send bug reports and suggestions to the author <j.wuttke (a] fz-juelich.de>. 182
