14
14
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="leastsq" xml:lang="en">
16
<refname>leastsq</refname>
17
<refpurpose>Solves non-linear least squares problems</refpurpose>
20
<title>Calling Sequence</title>
24
fopt=leastsq(fun, dfun, x0)
25
fopt=leastsq(fun, cstr, x0)
26
fopt=leastsq(fun, dfun, cstr, x0)
27
fopt=leastsq(fun, dfun, cstr, x0, algo)
28
fopt=leastsq([imp], fun [,dfun] [,cstr],x0 [,algo],[df0,[mem]],[stop])
29
[fopt,xopt] = leastsq(...)
30
[fopt,xopt,gopt] = = leastsq(...)
34
<title>Arguments</title>
40
value of the function <literal>f(x)=||fun(x)||^2</literal>
41
at <literal>xopt</literal>
49
best value of <literal>x</literal> found to minimize
50
<literal>||fun(x)||^2</literal>
58
gradient of <literal>f</literal> at
59
<literal>xopt</literal>
67
a scilab function or a list defining a function from
68
<literal>R^n</literal> to <literal>R^m</literal> (see more
69
details in DESCRIPTION).
77
real vector (initial guess of the variable to be
86
a scilab function or a string defining the Jacobian matrix of
87
<literal>fun</literal> (see more details in DESCRIPTION).
95
bound constraints on <literal>x</literal>. They must be
96
introduced by the string keyword <literal>'b'</literal> followed by
97
the lower bound <literal>binf</literal> then by the upper bound
98
<literal>bsup</literal> (so <literal>cstr</literal> appears as
99
<literal>'b',binf,bsup</literal> in the calling sequence). Those
100
bounds are real vectors with same dimension than
101
<literal>x0</literal> (-%inf and +%inf may be used for dimension
102
which are unrestricted).
110
a string with possible values: <literal>'qn'</literal> or
111
<literal>'gc'</literal> or <literal>'nd'</literal>. These strings
112
stand for quasi-Newton (default), conjugate gradient or
113
non-differentiable respectively. Note that <literal>'nd'</literal>
114
does not accept bounds on <literal>x</literal>.
122
scalar argument used to set the trace mode.
123
<literal>imp=0</literal> nothing (except errors) is reported,
124
<literal>imp=1</literal> initial and final reports,
125
<literal>imp=2</literal> adds a report per iteration,
126
<literal>imp>2</literal> add reports on linear search. Warning,
127
most of these reports are written on the Scilab standard
136
real scalar. Guessed decreasing of
137
<literal>||fun||^2</literal> at first iteration.
138
(<literal>df0=1</literal> is the default value).
146
integer, number of variables used to approximate the Hessean
147
(second derivatives) of <literal>f</literal> when
148
<literal>algo</literal><literal>='qn'</literal>. Default value is
157
sequence of optional parameters controlling the convergence of
158
the algorithm. They are introduced by the keyword
159
<literal>'ar'</literal>, the sequence being of the form
160
<literal>'ar',nap, [iter [,epsg [,epsf [,epsx]]]]</literal>
167
maximum number of calls to <literal>fun</literal>
175
<para>maximum number of iterations allowed.</para>
181
<para>threshold on gradient norm.</para>
188
threshold controlling decreasing of
197
threshold controlling variation of <literal>x</literal>.
198
This vector (possibly matrix) of same size as
199
<literal>x0</literal> can be used to scale
200
<literal>x</literal>.
210
<title>Description</title>
212
The <literal>leastsq</literal> function
219
\textrm{minimize } \|f(x)\|^2=f_1(x)^2 + f_2(x)^2+\ldots+f_m(x)^2
225
where <literal>f</literal> is a function from
226
<literal>R^n</literal> to <literal>R^m</literal>.
227
Bound constraints cab be imposed on <literal>x</literal>.
231
<title>How to provide fun and dfun</title>
233
<literal>fun</literal> can be a scilab function (case
234
1) or a fortran or a C routine linked to scilab (case 2).
241
When <literal>fun</literal> is a Scilab function, its calling
16
<refname>leastsq</refname>
17
<refpurpose>Solves non-linear least squares problems</refpurpose>
20
<title>Calling Sequence</title>
24
fopt=leastsq(fun, dfun, x0)
25
fopt=leastsq(fun, cstr, x0)
26
fopt=leastsq(fun, dfun, cstr, x0)
27
fopt=leastsq(fun, dfun, cstr, x0, algo)
28
fopt=leastsq([imp], fun [,dfun] [,cstr],x0 [,algo],[df0,[mem]],[stop])
29
[fopt,xopt] = leastsq(...)
30
[fopt,xopt,gopt] = = leastsq(...)
34
<title>Arguments</title>
40
value of the function <literal>f(x)=||fun(x)||^2</literal>
41
at <literal>xopt</literal>
49
best value of <literal>x</literal> found to minimize
50
<literal>||fun(x)||^2</literal>
58
gradient of <literal>f</literal> at
59
<literal>xopt</literal>
67
a scilab function or a list defining a function from
68
<literal>R^n</literal> to <literal>R^m</literal> (see more
69
details in DESCRIPTION).
77
real vector (initial guess of the variable to be
86
a scilab function or a string defining the Jacobian matrix of
87
<literal>fun</literal> (see more details in DESCRIPTION).
95
bound constraints on <literal>x</literal>. They must be
96
introduced by the string keyword <literal>'b'</literal> followed by
97
the lower bound <literal>binf</literal> then by the upper bound
98
<literal>bsup</literal> (so <literal>cstr</literal> appears as
99
<literal>'b',binf,bsup</literal> in the calling sequence). Those
100
bounds are real vectors with same dimension than
101
<literal>x0</literal> (-%inf and +%inf may be used for dimension
102
which are unrestricted).
110
a string with possible values: <literal>'qn'</literal> or
111
<literal>'gc'</literal> or <literal>'nd'</literal>. These strings
112
stand for quasi-Newton (default), conjugate gradient or
113
non-differentiable respectively. Note that <literal>'nd'</literal>
114
does not accept bounds on <literal>x</literal>.
122
scalar argument used to set the trace mode.
123
<literal>imp=0</literal> nothing (except errors) is reported,
124
<literal>imp=1</literal> initial and final reports,
125
<literal>imp=2</literal> adds a report per iteration,
126
<literal>imp>2</literal> add reports on linear search. Warning,
127
most of these reports are written on the Scilab standard
136
real scalar. Guessed decreasing of
137
<literal>||fun||^2</literal> at first iteration.
138
(<literal>df0=1</literal> is the default value).
146
integer, number of variables used to approximate the Hessean
147
(second derivatives) of <literal>f</literal> when
148
<literal>algo</literal><literal>='qn'</literal>. Default value is
157
sequence of optional parameters controlling the convergence of
158
the algorithm. They are introduced by the keyword
159
<literal>'ar'</literal>, the sequence being of the form
160
<literal>'ar',nap, [iter [,epsg [,epsf [,epsx]]]]</literal>
167
maximum number of calls to <literal>fun</literal>
175
<para>maximum number of iterations allowed.</para>
181
<para>threshold on gradient norm.</para>
188
threshold controlling decreasing of
197
threshold controlling variation of <literal>x</literal>.
198
This vector (possibly matrix) of same size as
199
<literal>x0</literal> can be used to scale
200
<literal>x</literal>.
210
<title>Description</title>
212
The <literal>leastsq</literal> function
219
\textrm{minimize } \|f(x)\|^2=f_1(x)^2 + f_2(x)^2+\ldots+f_m(x)^2
225
where <literal>f</literal> is a function from
226
<literal>R^n</literal> to <literal>R^m</literal>.
227
Bound constraints cab be imposed on <literal>x</literal>.
231
<title>How to provide fun and dfun</title>
233
<literal>fun</literal> can be a scilab function (case
234
1) or a fortran or a C routine linked to scilab (case 2).
241
When <literal>fun</literal> is a Scilab function, its calling
246
In the case where the cost function needs extra parameters,
246
In the case where the cost function needs extra parameters,
251
In this case, we provide <literal>fun</literal> as a list,
252
which contains <literal>list(f,a1,a2,...)</literal>.
260
When <literal>fun</literal> is a Fortran or C
261
routine, it must be <literal>list(fun_name,m[,a1,a2,...])</literal> in the calling sequence of
262
<literal>leastsq</literal>, where <literal>fun_name</literal> is
263
a 1-by-1 matrix of strings, the name of the routine which must be linked to Scilab (see
264
<link linkend="link">link</link>). The header must be, in Fortran:
251
In this case, we provide <literal>fun</literal> as a list,
252
which contains <literal>list(f,a1,a2,...)</literal>.
260
When <literal>fun</literal> is a Fortran or C
261
routine, it must be <literal>list(fun_name,m[,a1,a2,...])</literal> in the calling sequence of
262
<literal>leastsq</literal>, where <literal>fun_name</literal> is
263
a 1-by-1 matrix of strings, the name of the routine which must be linked to Scilab (see
264
<link linkend="link">link</link>). The header must be, in Fortran:
267
267
subroutine fun(m, n, x, params, y)
269
269
double precision x(n), params(*), y(m)
273
273
void fun(int *m, int *n, double *x, double *params, double *y)
276
where <literal>n</literal> is the dimension of vector
277
<literal>x</literal>, <literal>m</literal> the dimension of vector
278
<literal>y</literal>, with <literal>y=fun(x)</literal>, and
279
<literal>params</literal> is a vector which contains the optional
280
parameters <literal>a1, a2, ...</literal>. Each
281
parameter may be a vector, for instance if
282
<literal>a1</literal> has 3 components, the description of
283
<literal>a2</literal> begin from
284
<literal>params(4)</literal> (in fortran), and from
285
<literal>params[3]</literal> (in C).
286
Note that even if <literal>fun</literal> does not need supplementary parameters you
287
must anyway write the fortran code with a <literal>params</literal>
288
argument (which is then unused in the subroutine core).
294
By default, the algorithm uses a finite difference approximation
295
of the Jacobian matrix.
296
The Jacobian matrix can be provided by defining the function
297
<literal>dfun</literal>, where to the
298
optimizer it may be given as a usual scilab function or
299
as a fortran or a C routine linked to scilab.
306
when <literal>dfun</literal> is a scilab function, its calling
276
where <literal>n</literal> is the dimension of vector
277
<literal>x</literal>, <literal>m</literal> the dimension of vector
278
<literal>y</literal>, with <literal>y=fun(x)</literal>, and
279
<literal>params</literal> is a vector which contains the optional
280
parameters <literal>a1, a2, ...</literal>. Each
281
parameter may be a vector, for instance if
282
<literal>a1</literal> has 3 components, the description of
283
<literal>a2</literal> begin from
284
<literal>params(4)</literal> (in fortran), and from
285
<literal>params[3]</literal> (in C).
286
Note that even if <literal>fun</literal> does not need supplementary parameters you
287
must anyway write the fortran code with a <literal>params</literal>
288
argument (which is then unused in the subroutine core).
294
By default, the algorithm uses a finite difference approximation
295
of the Jacobian matrix.
296
The Jacobian matrix can be provided by defining the function
297
<literal>dfun</literal>, where to the
298
optimizer it may be given as a usual scilab function or
299
as a fortran or a C routine linked to scilab.
306
when <literal>dfun</literal> is a scilab function, its calling
311
where <literal>y(i,j)=dfi/dxj</literal>.
312
If extra parameters are required by <literal>fun</literal>, i.e. if arguments
313
<literal>a1,a2,...</literal> are required, they are passed also to
314
<literal>dfun</literal>, which must have header
311
where <literal>y(i,j)=dfi/dxj</literal>.
312
If extra parameters are required by <literal>fun</literal>, i.e. if arguments
313
<literal>a1,a2,...</literal> are required, they are passed also to
314
<literal>dfun</literal>, which must have header
316
316
y=dfun(x,a1,a2,...)
318
Note that, even if <literal>dfun</literal>
319
needs extra parameters, it must appear simply as
320
<literal>dfun</literal> in the calling sequence of
321
<literal>leastsq</literal>.
329
When <literal>dfun</literal> is defined by a Fortran or C
330
routine it must be a string, the name of the function linked to
332
The calling sequences must be, in Fortran:
318
Note that, even if <literal>dfun</literal>
319
needs extra parameters, it must appear simply as
320
<literal>dfun</literal> in the calling sequence of
321
<literal>leastsq</literal>.
329
When <literal>dfun</literal> is defined by a Fortran or C
330
routine it must be a string, the name of the function linked to
332
The calling sequences must be, in Fortran:
334
334
subroutine dfun(m, n, x, params, y)
336
336
double precision x(n), params(*), y(m,n)
340
340
void fun(int *m, int *n, double *x, double *params, double *y)
343
In the C case <literal>y(i,j)=dfi/dxj</literal> must be
344
stored in <literal>y[m*(j-1)+i-1]</literal>.
351
<title>Remarks</title>
353
Like <link linkend="datafit">datafit</link>,
354
<literal>leastsq</literal> is a front end onto the <link linkend="optim">optim</link> function. If you want to try the
355
Levenberg-Marquard method instead, use <link linkend="lsqrsolve">lsqrsolve</link>.
358
A least squares problem may be solved directly with the <link linkend="optim">optim</link> function ; in this case the function <link linkend="NDcost">NDcost</link> may be useful to compute the derivatives
359
(see the <link linkend="NDcost">NDcost</link> help page which provides a
360
simple example for parameters identification of a differential
365
<title>Examples</title>
367
We will show different calling possibilities of leastsq on one (trivial) example
368
which is non linear but does not really need to be solved with leastsq (applying
369
log linearizes the model and the problem may be solved with linear algebra).
370
In this example we look for the 2 parameters x(1) and x(2) of a simple
371
exponential decay model (x(1) being the unknow initial value and x(2) the
374
<programlisting role="example"><![CDATA[
343
In the C case <literal>y(i,j)=dfi/dxj</literal> must be
344
stored in <literal>y[m*(j-1)+i-1]</literal>.
351
<title>Remarks</title>
353
Like <link linkend="datafit">datafit</link>,
354
<literal>leastsq</literal> is a front end onto the <link linkend="optim">optim</link> function. If you want to try the
355
Levenberg-Marquard method instead, use <link linkend="lsqrsolve">lsqrsolve</link>.
358
A least squares problem may be solved directly with the <link linkend="optim">optim</link> function ; in this case the function <link linkend="NDcost">NDcost</link> may be useful to compute the derivatives
359
(see the <link linkend="NDcost">NDcost</link> help page which provides a
360
simple example for parameters identification of a differential
365
<title>Examples</title>
367
We will show different calling possibilities of leastsq on one (trivial) example
368
which is non linear but does not really need to be solved with leastsq (applying
369
log linearizes the model and the problem may be solved with linear algebra).
370
In this example we look for the 2 parameters x(1) and x(2) of a simple
371
exponential decay model (x(1) being the unknow initial value and x(2) the
374
<programlisting role="example"><
added
removed
modules/optimization/help/en_US/leastsq.xml
