1builddir::build::BUILD::lmfibtu-ivl8d.d2li.mr2f::i::tbmuaminal:nd:u:la:mlBmUiInL(D3:):lmfit-v8.2.2::man::lmmin(3)
2
3
4

NAME

6       lmmin - Levenberg-Marquardt least-squares minimization (simple/legacy
7       API without error estimates)
8

SYNOPSIS

10       #include <lmmin.h>
11
12       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
20       extern const lm_control_struct lm_control_double;
21
22       extern const lm_control_struct lm_control_float;
23
24       extern const char *lm_infmsg[];
25
26       extern const char *lm_shortmsg[];
27

DESCRIPTION

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
35       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
39       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
43       Function arguments:
44
45       n_par
46           Number of free variables.  Length of parameter vector par.
47
48       par Parameter vector.  On input, it must contain a reasonable guess.
49           On output, it contains the solution found to minimize ||fvec||.
50
51       m_dat
52           Length of vector fvec.  Must statisfy n_par <= m_dat.
53
54       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
58       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
62       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
68       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
74           control has the following members (for more details, see the source
75           file lmstruct.h):
76
77           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
82           double control.xtol
83               Relative error between last two approximations.  Recommended
84               setting: as ftol.
85
86           double control.gtol
87               A measure for degeneracy.  Recommended setting: as ftol.
88
89           double control.epsilon
90               Step used to calculate the Jacobian.  Recommended setting: as
91               ftol, but definitely less than the accuracy of fvec.
92
93           double control.stepbound
94               Initial bound to steps in the outer loop, generally between
95               0.01 and 100; recommended value is 100.
96
97           int control.patience
98               Used to set the maximum number of function evaluations to
99               patience*n_par.
100
101           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
105           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
110           int control.verbosity
111               If nonzero, some progress information from within the LM
112               algorithm is written to control.stream.
113
114           int control.n_maxpri
115               -1, or maximum number of parameters to print.
116
117           int control.m_maxpri
118               -1, or maximum number of residuals to print.
119
120       status
121           A record used to return information about the minimization process:
122
123           double status.fnorm
124               Norm of the vector fvec;
125
126           int status.nfev
127               Actual number of iterations;
128
129           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
134           int status.userbreak
135               Set when termination has been forced by the user-supplied
136               routine evaluate.
137

NOTES

139   Initializing parameter records.
140       The parameter record control should always be initialized from supplied
141       default records:
142
143           lm_control_struct control = lm_control_double; /* or _float */
144
145       After this, parameters may be overwritten:
146
147           control.patience = 500; /* allow more iterations */
148           control.verbosity = 15; /* for verbose monitoring */
149
150       An application written this way is guaranteed to work even if new
151       parameters are added to lm_control_struct.
152
153       Conversely, addition of parameters is not considered an API change; it
154       may happen without increment of the major version number.
155

EXAMPLES

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
161           #include "lmmin.h"
162           #include <stdio.h>
163
164           /* 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
170           /* 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
177           /* 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
185               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
190           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
196               /* 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
202               data_struct data = { tx, tz, y, f };
203
204               /* auxiliary parameters */
205               lm_status_struct status;
206               lm_control_struct control = lm_control_double;
207               control.verbosity = 3;
208
209               /* perform the fit */
210               printf( "Fitting:\n" );
211               lmmin( n_par, par, m_dat, (const void*) &data, evaluate_surface,
212                      &control, &status );
213
214               /* print results */
215               printf( "\nResults:\n" );
216               printf( "status after %d function evaluations:\n  %s\n",
217                       status.nfev, lm_infmsg[status.outcome] );
218
219               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
225               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
233               return 0;
234           }
235
236   More examples
237       For more examples, see the homepage and directories demo/ and test/ in
238       the source distribution.
239

COPYING

241       Copyright (C):
242          1980-1999 University of Chicago
243          2004-2018 Joachim Wuttke, Forschungszentrum Juelich GmbH
244
245       Software: FreeBSD License
246
247       Documentation: Creative Commons Attribution Share Alike
248

SEE ALSO

250       lmmin2(3), lmcurve(3)
251
252       Homepage: http://apps.jcns.fz-juelich.de/lmfit
253

BUGS

255       Please send bug reports and suggestions to the author
256       <j.wuttke@fz-juelich.de>.
257
258
259
260perl v5.38.0               builddi2r0:2:3b-u0i7l-d2:0:BUILD::lmfit-v8.2.2::man::lmmin(3)
Impressum