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