1builddir::build::BUILD::lmfbiuti-lvd8d.i2lr.m:2f::ib:tumiamlnad:n::u:laBmlUmIiLnD2:(:3l)mfit-v8.2.2::man::lmmin2(3)
2
3
4

NAME

6       lmmin2 - Levenberg-Marquardt least-squares minimization with error
7       estimation
8

SYNOPSIS

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

DESCRIPTION

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
36       The legacy function lmmin(3) provides a simplified API without error
37       estimates.
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, 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
52       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
57       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
62       m_dat
63           Length of vector fvec.  Must statisfy n_par <= m_dat.
64
65       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
69       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
73       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
79       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
85           control has the following members (for more details, see the source
86           file lmstruct.h):
87
88           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
93           double control.xtol
94               Relative error between last two approximations.  Recommended
95               setting: as ftol.
96
97           double control.gtol
98               A measure for degeneracy.  Recommended setting: as ftol.
99
100           double control.epsilon
101               Step used to calculate the Jacobian.  Recommended setting: as
102               ftol, but definitely less than the accuracy of fvec.
103
104           double control.stepbound
105               Initial bound to steps in the outer loop, generally between
106               0.01 and 100; recommended value is 100.
107
108           int control.patience
109               Used to set the maximum number of function evaluations to
110               patience*n_par.
111
112           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
116           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
121           int control.verbosity
122               If nonzero, some progress information from within the LM
123               algorithm is written to control.stream.
124
125           int control.n_maxpri
126               -1, or maximum number of parameters to print.
127
128           int control.m_maxpri
129               -1, or maximum number of residuals to print.
130
131       status
132           A record used to return information about the minimization process:
133
134           double status.fnorm
135               Norm of the vector fvec;
136
137           int status.nfev
138               Actual number of iterations;
139
140           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
145           int status.userbreak
146               Set when termination has been forced by the user-supplied
147               routine evaluate.
148

NOTES

150   Initializing parameter records.
151       The parameter record control should always be initialized from supplied
152       default records:
153
154           lm_control_struct control = lm_control_double; /* or _float */
155
156       After this, parameters may be overwritten:
157
158           control.patience = 500; /* allow more iterations */
159           control.verbosity = 15; /* for verbose monitoring */
160
161       An application written this way is guaranteed to work even if new
162       parameters are added to lm_control_struct.
163
164       Conversely, addition of parameters is not considered an API change; it
165       may happen without increment of the major version number.
166

EXAMPLES

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
172           #include "lmmin.h"
173           #include <stdio.h>
174
175           /* 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
181           /* 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
188           /* 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
196               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
201           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
209               /* 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
215               data_struct data = { tx, tz, y, f };
216
217               /* auxiliary parameters */
218               lm_status_struct status;
219               lm_control_struct control = lm_control_double;
220               control.verbosity = 3;
221
222               /* 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
227               /* print results */
228               printf( "\nResults:\n" );
229               printf( "status after %d function evaluations:\n  %s\n",
230                       status.nfev, lm_infmsg[status.outcome] );
231
232               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
238               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
246               return 0;
247           }
248
249   More examples
250       For more examples, see the homepage and directories demo/ and test/ in
251       the source distribution.
252

COPYING

254       Copyright (C):
255          1980-1999 University of Chicago
256          2004-2018 Joachim Wuttke, Forschungszentrum Juelich GmbH
257
258       Software: FreeBSD License
259
260       Documentation: Creative Commons Attribution Share Alike
261

SEE ALSO

263       lmmin(3), lmcurve(3)
264
265       Homepage: http://apps.jcns.fz-juelich.de/lmfit
266

BUGS

268       Please send bug reports and suggestions to the author
269       <j.wuttke@fz-juelich.de>.
270
271
272
273perl v5.32.1              builddir2:0:2b1u-i0l1d-:2:6BUILD::lmfit-v8.2.2::man::lmmin2(3)
Impressum