* Bug #9305 fixed - In the optimisation help page, new chapter "Least Squares functions"
[scilab.git] / scilab / modules / optimization / help / en_US / nonlinearleastsquares / datafit.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  * Copyright (C) 2011 - DIGITEO - Michael Baudin
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
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" xmlns:scilab="http://www.scilab.org" xml:id="datafit" xml:lang="en">
15     <refnamediv>
16         <refname>datafit</refname>
17         <refpurpose>Parameter identification based on measured data</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[p,err]=datafit([imp,] G [,DG],Z [,W],[contr],p0,[algo],[df0,[mem]],
22             [work],[stop],['in'])
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>imp</term>
30                 <listitem>
31                     <para>scalar argument used to set the trace mode.
32                         <literal>imp=0</literal> nothing (execpt errors) is reported,
33                         <literal>imp=1</literal> initial and final reports,
34                         <literal>imp=2</literal> adds a report per iteration,
35                         <literal>imp&gt;2</literal> add reports on linear search. Warning,
36                         most of these reports are written on the Scilab standard
37                         output.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>G</term>
43                 <listitem>
44                     <para>function descriptor (e=G(p,z), e: ne x 1, p: np x 1, z: nz x
45                         1)
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>DG</term>
51                 <listitem>
52                     <para>partial of G wrt p function descriptor (optional; S=DG(p,z),
53                         S: ne x np)
54                     </para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>Z</term>
59                 <listitem>
60                     <para>matrix [z_1,z_2,...z_n] where z_i (nz x 1) is the ith
61                         measurement
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>W</term>
67                 <listitem>
68                     <para>weighting matrix of size ne x ne (optional; defaut no
69                         ponderation)
70                     </para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>contr</term>
75                 <listitem>
76                     <para>
77                         <literal>'b',binf,bsup</literal> with
78                         <literal>binf</literal> and <literal>bsup</literal> real vectors
79                         with same dimension as <literal>p0</literal>.
80                         <literal>binf</literal> and <literal>bsup</literal> are lower and
81                         upper bounds on <literal>p</literal>.
82                     </para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>p0</term>
87                 <listitem>
88                     <para>initial guess (size np x 1)</para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>algo</term>
93                 <listitem>
94                     <para>
95                         <literal>'qn'</literal> or <literal>'gc'</literal> or
96                         <literal>'nd'</literal> . This string stands for quasi-Newton
97                         (default), conjugate gradient or non-differentiable respectively.
98                         Note that <literal>'nd'</literal> does not accept bounds on
99                         <literal>x</literal> ).
100                     </para>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>df0</term>
105                 <listitem>
106                     <para>
107                         real scalar. Guessed decreasing of <literal>f</literal> at
108                         first iteration. (<literal>df0=1</literal> is the default
109                         value).
110                     </para>
111                 </listitem>
112             </varlistentry>
113             <varlistentry>
114                 <term>mem :</term>
115                 <listitem>
116                     <para>integer, number of variables used to approximate the Hessian,
117                         (<literal>algo='gc' or 'nd'</literal>). Default value is around
118                         6.
119                     </para>
120                 </listitem>
121             </varlistentry>
122             <varlistentry>
123                 <term>stop</term>
124                 <listitem>
125                     <para>sequence of optional parameters controlling the convergence of
126                         the algorithm. <literal> stop= 'ar',nap, [iter [,epsg [,epsf
127                             [,epsx]]]]
128                         </literal>
129                     </para>
130                     <variablelist>
131                         <varlistentry>
132                             <term>"ar"</term>
133                             <listitem>
134                                 <para>reserved keyword for stopping rule selection defined as
135                                     follows:
136                                 </para>
137                             </listitem>
138                         </varlistentry>
139                         <varlistentry>
140                             <term>nap</term>
141                             <listitem>
142                                 <para>
143                                     maximum number of calls to <literal>fun</literal>
144                                     allowed.
145                                 </para>
146                             </listitem>
147                         </varlistentry>
148                         <varlistentry>
149                             <term>iter</term>
150                             <listitem>
151                                 <para>maximum number of iterations allowed.</para>
152                             </listitem>
153                         </varlistentry>
154                         <varlistentry>
155                             <term>epsg</term>
156                             <listitem>
157                                 <para>threshold on gradient norm.</para>
158                             </listitem>
159                         </varlistentry>
160                         <varlistentry>
161                             <term>epsf</term>
162                             <listitem>
163                                 <para>threshold controlling decreasing of
164                                     <literal>f</literal>
165                                 </para>
166                             </listitem>
167                         </varlistentry>
168                         <varlistentry>
169                             <term>epsx</term>
170                             <listitem>
171                                 <para>
172                                     threshold controlling variation of <literal>x</literal>.
173                                     This vector (possibly matrix) of same size as
174                                     <literal>x0</literal> can be used to scale
175                                     <literal>x</literal>.
176                                 </para>
177                             </listitem>
178                         </varlistentry>
179                     </variablelist>
180                 </listitem>
181             </varlistentry>
182             <varlistentry>
183                 <term>"in"</term>
184                 <listitem>
185                     <para>reserved keyword for initialization of parameters used when
186                         <literal>fun</literal> in given as a Fortran routine (see
187                         below).
188                     </para>
189                 </listitem>
190             </varlistentry>
191             <varlistentry>
192                 <term>p</term>
193                 <listitem>
194                     <para>Column vector, optimal solution found</para>
195                 </listitem>
196             </varlistentry>
197             <varlistentry>
198                 <term>err</term>
199                 <listitem>
200                     <para>scalar, least square error.</para>
201                 </listitem>
202             </varlistentry>
203         </variablelist>
204     </refsection>
205     <refsection>
206         <title>Description</title>
207         <para>
208             <literal>datafit</literal> is used for fitting data to a model. For
209             a given function <literal>G(p,z)</literal>, this function finds the best
210             vector of parameters <literal>p</literal> for approximating
211             <literal>G(p,z_i)=0</literal> for a set of measurement vectors
212             <literal>z_i</literal>. Vector <literal>p</literal> is found by minimizing
213             <literal>G(p,z_1)'WG(p,z_1)+G(p,z_2)'WG(p,z_2)+...+G(p,z_n)'WG(p,z_n)</literal>
214         </para>
215         <para>
216             <literal>datafit</literal> is an improved version of
217             <literal>fit_dat</literal>.
218         </para>
219     </refsection>
220     <refsection>
221         <title>Examples</title>
222         <programlisting role="example"><![CDATA[ 
223 //generate the data
224 function y=FF(x,p)
225   y=p(1)*(x-p(2))+p(3)*x.*x
226 endfunction
227
228 X=[];
229 Y=[];
230 pg=[34;12;14] //parameter used to generate data
231 for x=0:.1:3
232   Y=[Y,FF(x,pg)+100*(rand()-.5)];
233   X=[X,x];
234 end
235 Z=[Y;X];
236
237 //The criterion function
238 function e=G(p,z),
239   y=z(1),x=z(2);
240   e=y-FF(x,p),
241 endfunction
242
243 //Solve the problem
244 p0=[3;5;10]     
245 [p,err]=datafit(G,Z,p0);
246
247 scf(0);clf()
248 plot2d(X,FF(X,pg),5) //the curve without noise
249 plot2d(X,Y,-1)  // the noisy data
250 plot2d(X,FF(X,p),12) //the solution
251  ]]></programlisting>
252         <scilab:image>
253             function y=FF(x,p)
254             y=p(1)*(x-p(2))+p(3)*x.*x
255             endfunction
256             
257             X=[];Y=[];
258             pg=[34;12;14]
259             for x=0:.1:3
260             Y=[Y,FF(x,pg)+100*(rand()-.5)];
261             X=[X,x];
262             end
263             Z=[Y;X];
264             
265             function e=G(p,z),
266             y=z(1),x=z(2);
267             e=y-FF(x,p),
268             endfunction
269             
270             p0=[3;5;10] 
271             [p,err]=datafit(G,Z,p0);
272             
273             scf(0);clf()
274             plot2d(X,FF(X,pg),5)
275             plot2d(X,Y,-1)
276             plot2d(X,FF(X,p),12)
277         </scilab:image>
278         <programlisting role="example"><![CDATA[ 
279 //generate the data
280 function y=FF(x,p)
281   y=p(1)*(x-p(2))+p(3)*x.*x
282 endfunction
283
284 //the gradient of the criterion function
285 function s=DG(p,z),
286   a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
287   s=-[x-b,-a,x*x]
288 endfunction
289
290 function e=G(p,z),
291   y=z(1),x=z(2);
292   e=y-FF(x,p),
293 endfunction
294
295 X=[];Y=[];
296 pg=[34;12;14]
297 for x=0:.1:3
298   Y=[Y,FF(x,pg)+100*(rand()-.5)];
299   X=[X,x];
300 end
301 Z=[Y;X];
302
303 p0=[3;5;10]     
304 [p,err]=datafit(G,DG,Z,p0);
305 scf(1);
306 clf()
307 plot2d(X,FF(X,pg),5) //the curve without noise
308 plot2d(X,Y,-1)  // the noisy data
309 plot2d(X,FF(X,p),12) //the solution
310  ]]></programlisting>
311         <scilab:image>
312             function y=FF(x,p)
313             y=p(1)*(x-p(2))+p(3)*x.*x
314             endfunction
315             
316             function s=DG(p,z),
317             a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
318             s=-[x-b,-a,x*x]
319             endfunction
320             
321             function e=G(p,z),
322             y=z(1),x=z(2);
323             e=y-FF(x,p),
324             endfunction
325             
326             X=[];Y=[];
327             pg=[34;12;14]
328             for x=0:.1:3
329             Y=[Y,FF(x,pg)+100*(rand()-.5)];
330             X=[X,x];
331             end
332             Z=[Y;X];
333             
334             p0=[3;5;10] 
335             [p,err]=datafit(G,DG,Z,p0);
336             scf(1);
337             clf()
338             plot2d(X,FF(X,pg),5)
339             plot2d(X,Y,-1)
340             plot2d(X,FF(X,p),12)
341         </scilab:image>
342         <programlisting role="example"><![CDATA[
343 //generate the data
344 function y=FF(x,p)
345   y=p(1)*(x-p(2))+p(3)*x.*x
346 endfunction
347
348 //the gradient of the criterion function
349 function s=DG(p,z),
350   a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
351   s=-[x-b,-a,x*x]
352 endfunction
353
354 function e=G(p,z),
355   y=z(1),x=z(2);
356   e=y-FF(x,p),
357 endfunction
358
359 X=[];Y=[];
360 pg=[34;12;14]
361 for x=0:.1:3
362   Y=[Y,FF(x,pg)+100*(rand()-.5)];
363   X=[X,x];
364 end
365 Z=[Y;X];
366
367 p0=[3;5;10]     
368
369 // Add some bounds on the estimate of the parameters
370 // We want positive estimation (the result will not change)
371 [p,err]=datafit(G,DG,Z,'b',[0;0;0],[%inf;%inf;%inf],p0,algo='gc');
372 scf(1);
373 clf()
374 plot2d(X,FF(X,pg),5) //the curve without noise
375 plot2d(X,Y,-1)  // the noisy data
376 plot2d(X,FF(X,p),12) //the solution
377  ]]></programlisting>
378         <scilab:image>
379             function y=FF(x,p)
380             y=p(1)*(x-p(2))+p(3)*x.*x
381             endfunction
382             
383             function s=DG(p,z),
384             a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
385             s=-[x-b,-a,x*x]
386             endfunction
387             
388             function e=G(p,z),
389             y=z(1),x=z(2);
390             e=y-FF(x,p),
391             endfunction
392             
393             X=[];Y=[];
394             pg=[34;12;14]
395             for x=0:.1:3
396             Y=[Y,FF(x,pg)+100*(rand()-.5)];
397             X=[X,x];
398             end
399             Z=[Y;X];
400             
401             p0=[3;5;10] 
402             
403             [p,err]=datafit(G,DG,Z,'b',[0;0;0],[%inf;%inf;%inf],p0,algo='gc');
404             scf(1);
405             clf()
406             plot2d(X,FF(X,pg),5)
407             plot2d(X,Y,-1)
408             plot2d(X,FF(X,p),12)
409         </scilab:image>
410     </refsection>
411     <refsection role="see also">
412         <title>See Also</title>
413         <simplelist type="inline">
414             <member>
415                 <link linkend="lsqrsolve">lsqrsolve</link>
416             </member>
417             <member>
418                 <link linkend="optim">optim</link>
419             </member>
420             <member>
421                 <link linkend="leastsq">leastsq</link>
422             </member>
423         </simplelist>
424     </refsection>
425 </refentry>