1builddir::build::BUILD::lmfit-8b.u2i:ll:mdmfdaiintr:::m:labmnumuiialnld(:3:)BUILD::lmfit-8.2::man::lmmin(3)
2
6 lmmin - Levenberg-Marquardt least-squares minimization (simple/legacy
7 API without error estimates)
8
10 #include <lmmin.h>
11 void lmmin( const int n_par, double *par, const int m_dat,
13 const void *y, const void *data,
14 void *evaluate(
15 const double *par, const int m_dat,
16 const void *data, double *fvec, int *userbreak),
17 const lm_control_struct *control,
18 lm_status_struct *status );
19 extern const lm_control_struct lm_control_double;
21 extern const lm_control_struct lm_control_float;
23 extern const char *lm_infmsg[];
25 extern const char *lm_shortmsg[];
27
29 lmmin() determines a vector par that minimizes the sum of squared
30 elements of fvec-y. The vector fvec is computed by a user-supplied
31 function evaluate(); the vector y contains user-provided values. On
32 success, par represents a local minimum, not necessarily a global one;
33 it may depend on its starting value.
34 This is a simple wrapper of the function lmmin2(3), which also returns
36 error estimates. Conversely, the function lmcurve(3) provides an even
37 simpler wrapper, for use in curve fitting.
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. On input, it must contain a reasonable guess.
49 On output, it contains the solution found to minimize ||fvec||.
50 m_dat
52 Length of vector fvec. Must statisfy n_par <= m_dat.
53 y Input vector of length m_dat. May also be the null pointer; in
55 this case, lmmin() minimizes the squared sum of fvec instead of
56 fvec-y.
57 data
59 This pointer is ignored by the fit algorithm, except for appearing
60 as an argument in all calls to the user-supplied routine evaluate.
61 evaluate
63 Pointer to a user-supplied function that computes m_dat elements of
64 vector fvec for a given parameter vector par. If evaluate return
65 with *userbreak set to a negative value, lmmin() will interrupt the
66 fitting and terminate.
67 control
69 Parameter collection for tuning the fit procedure. In most cases,
70 the default &lm_control_double is adequate. If f is only computed
71 with single-precision accuracy, &lm_control_float should be used.
72 See also below, NOTES on initializing parameter records.
73 control has the following members (for more details, see the source
75 file lmstruct.h):
76 double control.ftol
78 Relative error desired in the sum of squares. Recommended
79 setting: somewhat above machine precision; less if fvec is
80 computed with reduced accuracy.
81 double control.xtol
83 Relative error between last two approximations. Recommended
84 setting: as ftol.
85 double control.gtol
87 A measure for degeneracy. Recommended setting: as ftol.
88 double control.epsilon
90 Step used to calculate the Jacobian. Recommended setting: as
91 ftol, but definitely less than the accuracy of fvec.
92 double control.stepbound
94 Initial bound to steps in the outer loop, generally between
95 0.01 and 100; recommended value is 100.
96 int control.patience
98 Used to set the maximum number of function evaluations to
99 patience*n_par.
100 int control.scale_diag
102 Logical switch (0 or 1). If 1, then scale parameters to their
103 initial value. This is the recommended setting.
104 FILE* control.msgfile
106 Progress messages will be written to this file. Typically
107 stdout or stderr. The value NULL will be interpreted as
108 stdout.
109 int control.verbosity
111 If nonzero, some progress information from within the LM
112 algorithm is written to control.stream.
113 int control.n_maxpri
115 -1, or maximum number of parameters to print.
116 int control.m_maxpri
118 -1, or maximum number of residuals to print.
119 status
121 A record used to return information about the minimization process:
122 double status.fnorm
124 Norm of the vector fvec;
125 int status.nfev
127 Actual number of iterations;
128 int status.outcome
130 Status of minimization; for the corresponding text message,
131 print lm_infmsg[status.outcome]; for a short code, print
132 lm_shortmsg[status.outcome].
133 int status.userbreak
135 Set when termination has been forced by the user-supplied
136 routine evaluate.
137
139 Initializing parameter records.
140 The parameter record control should always be initialized from supplied
141 default records:
142 lm_control_struct control = lm_control_double; /* or _float */
144 After this, parameters may be overwritten:
146 control.patience = 500; /* allow more iterations */
148 control.verbosity = 15; /* for verbose monitoring */
149 An application written this way is guaranteed to work even if new
151 parameters are added to lm_control_struct.
152 Conversely, addition of parameters is not considered an API change; it
154 may happen without increment of the major version number.
155
157 Fitting a surface
158 Fit a data set y(t) by a function f(t;p) where t is a two-dimensional
159 vector:
160 #include "lmmin.h"
162 #include <stdio.h>
163 /* fit model: a plane p0 + p1*tx + p2*tz */
165 double f( double tx, double tz, const double *p )
166 {
167 return p[0] + p[1]*tx + p[2]*tz;
168 }
169 /* data structure to transmit data arays and fit model */
171 typedef struct {
172 double *tx, *tz;
173 double *y;
174 double (*f)( double tx, double tz, const double *p );
175 } data_struct;
176 /* function evaluation, determination of residues */
178 void evaluate_surface( const double *par, int m_dat,
179 const void *data, double *fvec, int *userbreak )
180 {
181 /* for readability, explicit type conversion */
182 data_struct *D;
183 D = (data_struct*)data;
184 int i;
186 for ( i = 0; i < m_dat; i++ )
187 fvec[i] = D->y[i] - D->f( D->tx[i], D->tz[i], par );
188 }
189 int main()
191 {
192 /* parameter vector */
193 int n_par = 3; /* number of parameters in model function f */
194 double par[3] = { -1, 0, 1 }; /* arbitrary starting value */
195 /* data points */
197 int m_dat = 4;
198 double tx[4] = { -1, -1, 1, 1 };
199 double tz[4] = { -1, 1, -1, 1 };
200 double y[4] = { 0, 1, 1, 2 };
201 data_struct data = { tx, tz, y, f };
203 /* auxiliary parameters */
205 lm_status_struct status;
206 lm_control_struct control = lm_control_double;
207 control.verbosity = 3;
208 /* perform the fit */
210 printf( "Fitting:\n" );
211 lmmin( n_par, par, m_dat, (const void*) &data, evaluate_surface,
212 &control, &status );
213 /* print results */
215 printf( "\nResults:\n" );
216 printf( "status after %d function evaluations:\n %s\n",
217 status.nfev, lm_infmsg[status.outcome] );
218 printf("obtained parameters:\n");
220 int i;
221 for ( i=0; i<n_par; ++i )
222 printf(" par[%i] = %12g\n", i, par[i]);
223 printf("obtained norm:\n %12g\n", status.fnorm );
224 printf("fitting data as follows:\n");
226 double ff;
227 for ( i=0; i<m_dat; ++i ){
228 ff = f(tx[i], tz[i], par);
229 printf( " t[%2d]=%12g,%12g y=%12g fit=%12g residue=%12g\n",
230 i, tx[i], tz[i], y[i], ff, y[i] - ff );
231 }
232 return 0;
234 }
235 More examples
237 For more examples, see the homepage and directories demo/ and test/ in
238 the source distribution.
239
241 Copyright (C):
242 1980-1999 University of Chicago
243 2004-2018 Joachim Wuttke, Forschungszentrum Juelich GmbH
244 Software: FreeBSD License
246 Documentation: Creative Commons Attribution Share Alike
248
250 lmmin2(3), lmcurve(3)
251 Homepage: http://apps.jcns.fz-juelich.de/lmfit
253
255 Please send bug reports and suggestions to the author
256 <j.wuttke@fz-juelich.de>.
257perl v5.30.0 buil2d0d1i9r-:0:7b-u2i5ld::BUILD::lmfit-8.2::man::lmmin(3)