1builddir::build::BUILD::lmfbiuti-lvd8d.i2lr.m:2f::ib:tumiamlnad:n::u:laBmlUmIiLnD2:(:3l)mfit-v8.2.2::man::lmmin2(3)
2
6 lmmin2 - Levenberg-Marquardt least-squares minimization with error
7 estimation
8
10 #include <lmmin.h>
11 void lmmin2( const int n_par, double *par, double *parerr, double
13 *covar,
14 const int m_dat, const void *y, const void *data,
15 void *evaluate(
16 const double *par, const int m_dat,
17 const void *data, double *fvec, int *userbreak),
18 const lm_control_struct *control,
19 lm_status_struct *status );
20 extern const lm_control_struct lm_control_double;
22 extern const lm_control_struct lm_control_float;
24 extern const char *lm_infmsg[];
26 extern const char *lm_shortmsg[];
28
30 lmmin2() determines a vector par that minimizes the sum of squared
31 elements of fvec-y. The vector fvec is computed by a user-supplied
32 function evaluate(); the vector y contains user-provided values. On
33 success, par represents a local minimum, not necessarily a global one;
34 it may depend on its starting value.
35 The legacy function lmmin(3) provides a simplified API without error
37 estimates.
38 The Levenberg-Marquardt minimization starts with a steepest-descent
40 exploration of the parameter space, and achieves rapid convergence by
41 crossing over into the Newton-Gauss method.
42 Function arguments:
44 n_par
46 Number of free variables. Length of parameter vector par.
47 par Parameter vector, of length n_par. On input, it must contain a
49 reasonable guess. On output, it contains the solution found to
50 minimize ||fvec||.
51 parerr
53 Parameter error vector, either of length n_par, or NULL. On
54 output, unless it is NULL, it contains the parameter uncertainties,
55 estimated from the diagonal elements of the covariance matrix.
56 covar
58 Covariance matrix, stored as vector of length n_par*n_par, or NULL.
59 On output, unless it is NULL, it contains the covariance matrix.
60 NOT YET IMPLEMENTED!
61 m_dat
63 Length of vector fvec. Must statisfy n_par <= m_dat.
64 y Input vector of length m_dat. May also be the null pointer; in
66 this case, lmmin() minimizes the squared sum of fvec instead of
67 fvec-y.
68 data
70 This pointer is ignored by the fit algorithm, except for appearing
71 as an argument in all calls to the user-supplied routine evaluate.
72 evaluate
74 Pointer to a user-supplied function that computes m_dat elements of
75 vector fvec for a given parameter vector par. If evaluate return
76 with *userbreak set to a negative value, lmmin() will interrupt the
77 fitting and terminate.
78 control
80 Parameter collection for tuning the fit procedure. In most cases,
81 the default &lm_control_double is adequate. If f is only computed
82 with single-precision accuracy, &lm_control_float should be used.
83 See also below, NOTES on initializing parameter records.
84 control has the following members (for more details, see the source
86 file lmstruct.h):
87 double control.ftol
89 Relative error desired in the sum of squares. Recommended
90 setting: somewhat above machine precision; less if fvec is
91 computed with reduced accuracy.
92 double control.xtol
94 Relative error between last two approximations. Recommended
95 setting: as ftol.
96 double control.gtol
98 A measure for degeneracy. Recommended setting: as ftol.
99 double control.epsilon
101 Step used to calculate the Jacobian. Recommended setting: as
102 ftol, but definitely less than the accuracy of fvec.
103 double control.stepbound
105 Initial bound to steps in the outer loop, generally between
106 0.01 and 100; recommended value is 100.
107 int control.patience
109 Used to set the maximum number of function evaluations to
110 patience*n_par.
111 int control.scale_diag
113 Logical switch (0 or 1). If 1, then scale parameters to their
114 initial value. This is the recommended setting.
115 FILE* control.msgfile
117 Progress messages will be written to this file. Typically
118 stdout or stderr. The value NULL will be interpreted as
119 stdout.
120 int control.verbosity
122 If nonzero, some progress information from within the LM
123 algorithm is written to control.stream.
124 int control.n_maxpri
126 -1, or maximum number of parameters to print.
127 int control.m_maxpri
129 -1, or maximum number of residuals to print.
130 status
132 A record used to return information about the minimization process:
133 double status.fnorm
135 Norm of the vector fvec;
136 int status.nfev
138 Actual number of iterations;
139 int status.outcome
141 Status of minimization; for the corresponding text message,
142 print lm_infmsg[status.outcome]; for a short code, print
143 lm_shortmsg[status.outcome].
144 int status.userbreak
146 Set when termination has been forced by the user-supplied
147 routine evaluate.
148
150 Initializing parameter records.
151 The parameter record control should always be initialized from supplied
152 default records:
153 lm_control_struct control = lm_control_double; /* or _float */
155 After this, parameters may be overwritten:
157 control.patience = 500; /* allow more iterations */
159 control.verbosity = 15; /* for verbose monitoring */
160 An application written this way is guaranteed to work even if new
162 parameters are added to lm_control_struct.
163 Conversely, addition of parameters is not considered an API change; it
165 may happen without increment of the major version number.
166
168 Fitting a surface
169 Fit a data set y(t) by a function f(t;p) where t is a two-dimensional
170 vector:
171 #include "lmmin.h"
173 #include <stdio.h>
174 /* fit model: a plane p0 + p1*tx + p2*tz */
176 double f( double tx, double tz, const double *p )
177 {
178 return p[0] + p[1]*tx + p[2]*tz;
179 }
180 /* data structure to transmit data arays and fit model */
182 typedef struct {
183 double *tx, *tz;
184 double *y;
185 double (*f)( double tx, double tz, const double *p );
186 } data_struct;
187 /* function evaluation, determination of residues */
189 void evaluate_surface( const double *par, int m_dat,
190 const void *data, double *fvec, int *userbreak )
191 {
192 /* for readability, explicit type conversion */
193 data_struct *D;
194 D = (data_struct*)data;
195 int i;
197 for ( i = 0; i < m_dat; i++ )
198 fvec[i] = D->y[i] - D->f( D->tx[i], D->tz[i], par );
199 }
200 int main()
202 {
203 /* parameter vector */
204 int n_par = 3; /* number of parameters in model function f */
205 double par[3] = { -1, 0, 1 }; /* arbitrary starting value */
206 double parerr[3];
207 double covar[9];
208 /* data points */
210 int m_dat = 4;
211 double tx[4] = { -1, -1, 1, 1 };
212 double tz[4] = { -1, 1, -1, 1 };
213 double y[4] = { 0, 1, 1, 2 };
214 data_struct data = { tx, tz, y, f };
216 /* auxiliary parameters */
218 lm_status_struct status;
219 lm_control_struct control = lm_control_double;
220 control.verbosity = 3;
221 /* perform the fit */
223 printf( "Fitting:\n" );
224 lmmin2( n_par, par, parerr, covar, m_dat, (const void*) &data,
225 evaluate_surface, &control, &status );
226 /* print results */
228 printf( "\nResults:\n" );
229 printf( "status after %d function evaluations:\n %s\n",
230 status.nfev, lm_infmsg[status.outcome] );
231 printf("obtained parameters:\n");
233 int i;
234 for ( i=0; i<n_par; ++i )
235 printf(" par[%i] = %12g +- %12g\n", i, par[i], parerr[i]);
236 printf("obtained norm:\n %12g\n", status.fnorm );
237 printf("fitting data as follows:\n");
239 double ff;
240 for ( i=0; i<m_dat; ++i ){
241 ff = f(tx[i], tz[i], par);
242 printf( " t[%2d]=%12g,%12g y=%12g fit=%12g residue=%12g\n",
243 i, tx[i], tz[i], y[i], ff, y[i] - ff );
244 }
245 return 0;
247 }
248 More examples
250 For more examples, see the homepage and directories demo/ and test/ in
251 the source distribution.
252
254 Copyright (C):
255 1980-1999 University of Chicago
256 2004-2018 Joachim Wuttke, Forschungszentrum Juelich GmbH
257 Software: FreeBSD License
259 Documentation: Creative Commons Attribution Share Alike
261
263 lmmin(3), lmcurve(3)
264 Homepage: http://apps.jcns.fz-juelich.de/lmfit
266
268 Please send bug reports and suggestions to the author
269 <j.wuttke@fz-juelich.de>.
270perl v5.36.0 builddir2:0:2b2u-i0l7d-:2:1BUILD::lmfit-v8.2.2::man::lmmin2(3)