Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / help / en_US / lsqrsolve.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="lsqrsolve" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate: 2008-04-15 18:15:23 +0200 (Tue, 15 Apr 2008)
22     $</pubdate>
23   </info>
24
25   <refnamediv>
26     <refname>lsqrsolve</refname>
27
28     <refpurpose>minimize the sum of the squares of nonlinear functions,
29     levenberg-marquardt algorithm</refpurpose>
30   </refnamediv>
31
32   <refsynopsisdiv>
33     <title>Calling Sequence</title>
34
35     <synopsis>[x [,v [,info]]]=lsqrsolve(x0,fct,m [,stop [,diag]])
36 [x [,v [,info]]]=lsqrsolve(x0,fct,m ,fjac [,stop [,diag]])</synopsis>
37   </refsynopsisdiv>
38
39   <refsection>
40     <title>Parameters</title>
41
42     <variablelist>
43       <varlistentry>
44         <term>x0</term>
45
46         <listitem>
47           <para>real vector of size <literal>n </literal>(initial estimate of
48           the solution vector).</para>
49         </listitem>
50       </varlistentry>
51
52       <varlistentry>
53         <term>fct</term>
54
55         <listitem>
56           <para>external (i.e function or list or string).</para>
57         </listitem>
58       </varlistentry>
59
60       <varlistentry>
61         <term>m</term>
62
63         <listitem>
64           <para>integer, the number of functions. <literal>m</literal> must be
65           greater than or equal to <literal>n</literal>.</para>
66         </listitem>
67       </varlistentry>
68
69       <varlistentry>
70         <term>fjac</term>
71
72         <listitem>
73           <para>external (i.e function or list or string).</para>
74         </listitem>
75       </varlistentry>
76
77       <varlistentry>
78         <term>stop</term>
79
80         <listitem>
81           <para>optional vector
82           <literal>[ftol,xtol,gtol,maxfev,epsfcn,factor]</literal> the default
83           value is <literal>[1.d-8,1.d-8,1.d-5,1000,0,100]</literal></para>
84
85           <variablelist>
86             <varlistentry>
87               <term>ftol</term>
88
89               <listitem>
90                 <para>A positive real number,termination occurs when both the
91                 actual and predicted relative reductions in the sum of squares
92                 are at most <literal>ftol</literal>. therefore,
93                 <literal>ftol</literal> measures the relative error desired in
94                 the sum of squares.</para>
95               </listitem>
96             </varlistentry>
97
98             <varlistentry>
99               <term>xtol</term>
100
101               <listitem>
102                 <para>A positive real number, termination occurs when the
103                 relative error between two consecutive iterates is at most
104                 <literal>xtol</literal>. therefore, <literal>xtol</literal>
105                 measures the relative error desired in the approximate
106                 solution.</para>
107               </listitem>
108             </varlistentry>
109
110             <varlistentry>
111               <term>gtol</term>
112
113               <listitem>
114                 <para>A nonnegative input variable. termination occurs when
115                 the cosine of the angle between <literal>fct</literal>(x) and
116                 any column of the jacobian is at most <literal>gtol</literal>
117                 in absolute value. therefore, <literal>gtol </literal>measures
118                 the orthogonality desired between the function vector and the
119                 columns of the jacobian.</para>
120               </listitem>
121             </varlistentry>
122
123             <varlistentry>
124               <term>maxfev</term>
125
126               <listitem>
127                 <para>A positive integer, termination occurs when the number
128                 of calls to <literal>fct</literal> is at least maxfev by the
129                 end of an iteration.</para>
130               </listitem>
131             </varlistentry>
132
133             <varlistentry>
134               <term>epsfcn</term>
135
136               <listitem>
137                 <para>A positive real number, used in determining a suitable
138                 step length for the forward-difference approximation. this
139                 approximation assumes that the relative errors in the
140                 functions are of the order of <literal>epsfcn</literal>. if
141                 <literal>epsfcn</literal> is less than the machine precision,
142                 it is assumed that the relative errors in the functions are of
143                 the order of the machine precision.</para>
144               </listitem>
145             </varlistentry>
146
147             <varlistentry>
148               <term>factor</term>
149
150               <listitem>
151                 <para>A positive real number, used in determining the initial
152                 step bound. this bound is set to the product of factor and the
153                 euclidean norm of <literal>diag*x</literal> if nonzero, or
154                 else to <literal>factor</literal> itself. in most cases
155                 <literal>factor</literal> should lie in the interval
156                 <literal>(0.1,100)</literal>. <literal>100</literal> is a
157                 generally recommended value.</para>
158               </listitem>
159             </varlistentry>
160           </variablelist>
161         </listitem>
162       </varlistentry>
163
164       <varlistentry>
165         <term>diag</term>
166
167         <listitem>
168           <para>is an array of length <literal>n</literal>.
169           <literal>diag</literal> must contain positive entries that serve as
170           multiplicative scale factors for the variables.</para>
171         </listitem>
172       </varlistentry>
173
174       <varlistentry>
175         <term>x :</term>
176
177         <listitem>
178           <para>real vector (final estimate of the solution vector).</para>
179         </listitem>
180       </varlistentry>
181
182       <varlistentry>
183         <term>v :</term>
184
185         <listitem>
186           <para>real vector (value of <literal>fct(x)</literal>).</para>
187         </listitem>
188       </varlistentry>
189
190       <varlistentry>
191         <term>info</term>
192
193         <listitem>
194           <para>termination indicator</para>
195
196           <variablelist>
197             <varlistentry>
198               <term>0</term>
199
200               <listitem>
201                 <para>improper input parameters.</para>
202               </listitem>
203             </varlistentry>
204
205             <varlistentry>
206               <term>1</term>
207
208               <listitem>
209                 <para>algorithm estimates that the relative error between
210                 <literal>x</literal> and the solution is at most
211                 <literal>tol</literal>.</para>
212               </listitem>
213             </varlistentry>
214
215             <varlistentry>
216               <term>2</term>
217
218               <listitem>
219                 <para>number of calls to <literal>fcn</literal> reached</para>
220               </listitem>
221             </varlistentry>
222
223             <varlistentry>
224               <term>3</term>
225
226               <listitem>
227                 <para><literal>tol</literal> is too small. No further
228                 improvement in the approximate solution <literal>x</literal>
229                 is possible.</para>
230               </listitem>
231             </varlistentry>
232
233             <varlistentry>
234               <term>4</term>
235
236               <listitem>
237                 <para>iteration is not making good progress.</para>
238               </listitem>
239             </varlistentry>
240
241             <varlistentry>
242               <term>5</term>
243
244               <listitem>
245                 <para>number of calls to <literal>fcn</literal> has reached or
246                 exceeded <literal>maxfev</literal></para>
247               </listitem>
248             </varlistentry>
249
250             <varlistentry>
251               <term>6</term>
252
253               <listitem>
254                 <para><literal>ftol</literal> is too small. no further
255                 reduction in the sum of squares is possible.</para>
256               </listitem>
257             </varlistentry>
258
259             <varlistentry>
260               <term>7</term>
261
262               <listitem>
263                 <para><literal>xtol</literal> is too small. no further
264                 improvement in the approximate solution<literal>x</literal> is
265                 possible.</para>
266               </listitem>
267             </varlistentry>
268
269             <varlistentry>
270               <term>8</term>
271
272               <listitem>
273                 <para><literal>gtol</literal> is too small.
274                 <literal>fvec</literal> is orthogonal to the columns of the
275                 jacobian to machine precision.</para>
276               </listitem>
277             </varlistentry>
278           </variablelist>
279         </listitem>
280       </varlistentry>
281     </variablelist>
282   </refsection>
283
284   <refsection>
285     <title>Description</title>
286
287     <para>minimize the sum of the squares of m nonlinear functions in n
288     variables by a modification of the levenberg-marquardt algorithm. the user
289     must provide a subroutine which calculates the functions. the jacobian is
290     then calculated by a forward-difference approximation.</para>
291
292     <para>minimize <literal>sum(fct(x,m).^2)</literal> where
293     <literal>fct</literal> is function from <literal>R^n</literal> to
294     <literal>R^m</literal></para>
295
296     <para><literal>fct</literal> should be :</para>
297
298     <itemizedlist>
299       <listitem>
300         <para>a Scilab function whose calling sequence is
301         <literal>v=fct(x,m)</literal> given <literal>x</literal> and
302         <literal>m</literal>.</para>
303       </listitem>
304
305       <listitem>
306         <para>a character string which refers to a C or Fortran routine which
307         must be linked to Scilab.</para>
308
309         <para>Fortran calling sequence should be
310         <literal>fct(m,n,x,v,iflag)</literal> where <literal>m</literal>,
311         <literal>n</literal>, <literal>iflag</literal> are integers,
312         <literal>x</literal> a double precision vector of size
313         <literal>n</literal> and <literal>v</literal> a double precision
314         vector of size <literal>m</literal>.</para>
315
316         <para>C calling sequence should be <literal>fct(int *m, int *n, double
317         x[],double v[],int *iflag)</literal></para>
318       </listitem>
319     </itemizedlist>
320
321     <para><literal>fjac</literal> is an external which returns
322     <literal>v=d(fct)/dx (x)</literal>. it should be :</para>
323
324     <variablelist>
325       <varlistentry>
326         <term>a Scilab function</term>
327
328         <listitem>
329           <para>whose calling sequence is <literal>J=fjac(x,m)</literal> given
330           <literal>x</literal> and <literal>m</literal>.</para>
331         </listitem>
332       </varlistentry>
333
334       <varlistentry>
335         <term>a character string</term>
336
337         <listitem>
338           <para>it refers to a C or Fortran routine which must be linked to
339           Scilab.</para>
340
341           <para>Fortran calling sequence should be
342           <literal>fjac(m,n,x,jac,iflag)</literal> where <literal>m</literal>,
343           <literal>n</literal>, <literal>iflag</literal> are integers,
344           <literal>x</literal> a double precision vector of size
345           <literal>n</literal> and <literal>jac</literal> a double precision
346           vector of size <literal>m*n</literal>.</para>
347
348           <para>C calling sequence should be <literal>fjac(int *m, int *n,
349           double x[],double v[],int *iflag)</literal></para>
350         </listitem>
351       </varlistentry>
352     </variablelist>
353
354     <para>return -1 in iflag to stop the algoritm if the function or jacobian
355     could not be evaluated.</para>
356   </refsection>
357
358   <refsection>
359     <title>Examples</title>
360
361     <programlisting role="example"><![CDATA[ 
362 // A simple example with lsqrsolve 
363 a=[1,7;
364    2,8
365    4 3];
366 b=[10;11;-1];
367
368 function y=f1(x,m)
369   y=a*x+b;
370 endfunction
371
372 [xsol,v]=lsqrsolve([100;100],f1,3)
373 xsol+a\b
374
375 function y=fj1(x,m)
376   y=a;
377 endfunction
378
379 [xsol,v]=lsqrsolve([100;100],f1,3,fj1)
380 xsol+a\b
381
382 // Data fitting problem
383 // 1 build the data
384 a=34;b=12;c=14;
385
386 deff('y=FF(x)','y=a*(x-b)+c*x.*x');
387 X=(0:.1:3)';Y=FF(X)+100*(rand()-.5);
388
389 //solve
390 function e=f1(abc,m)
391   a=abc(1);b=abc(2),c=abc(3),
392   e=Y-(a*(X-b)+c*X.*X);
393 endfunction
394
395 [abc,v]=lsqrsolve([10;10;10],f1,size(X,1));
396 abc
397 norm(v)
398  ]]></programlisting>
399   </refsection>
400
401   <refsection>
402     <title>See Also</title>
403
404     <simplelist type="inline">
405       <member><link linkend="external">external</link></member>
406
407       <member><link linkend="qpsolve">qpsolve</link></member>
408
409       <member><link linkend="optim">optim</link></member>
410
411       <member><link linkend="fsolve">fsolve</link></member>
412     </simplelist>
413   </refsection>
414
415   <refsection>
416     <title>Used Functions</title>
417
418     <para>lmdif, lmder from minpack, Argonne National Laboratory.</para>
419   </refsection>
420 </refentry>