77c6556dbff38e1daee6a77161564a6c5534197c
[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         <para>
219             <literal>datafit</literal> is an improved version of
220             <literal>fit_dat</literal>.
221         </para>
222     </refsection>
223     <refsection>
224         <title>Examples</title>
225         <programlisting role="example"><![CDATA[ 
226 //generate the data
227 function y=FF(x,p)
228   y=p(1)*(x-p(2))+p(3)*x.*x
229 endfunction
230
231 X=[];
232 Y=[];
233 pg=[34;12;14] //parameter used to generate data
234 for x=0:.1:3
235   Y=[Y,FF(x,pg)+100*(rand()-.5)];
236   X=[X,x];
237 end
238 Z=[Y;X];
239
240 //The criterion function
241 function e=G(p,z),
242   y=z(1),x=z(2);
243   e=y-FF(x,p),
244 endfunction
245
246 //Solve the problem
247 p0=[3;5;10]     
248 [p,err]=datafit(G,Z,p0);
249
250 scf(0);clf()
251 plot2d(X,FF(X,pg),5) //the curve without noise
252 plot2d(X,Y,-1)  // the noisy data
253 plot2d(X,FF(X,p),12) //the solution
254  ]]></programlisting>
255         <scilab:image>
256             function y=FF(x,p)
257             y=p(1)*(x-p(2))+p(3)*x.*x
258             endfunction
259             
260             X=[];Y=[];
261             pg=[34;12;14]
262             for x=0:.1:3
263             Y=[Y,FF(x,pg)+100*(rand()-.5)];
264             X=[X,x];
265             end
266             Z=[Y;X];
267             
268             function e=G(p,z),
269             y=z(1),x=z(2);
270             e=y-FF(x,p),
271             endfunction
272             
273             p0=[3;5;10] 
274             [p,err]=datafit(G,Z,p0);
275             
276             scf(0);clf()
277             plot2d(X,FF(X,pg),5)
278             plot2d(X,Y,-1)
279             plot2d(X,FF(X,p),12)
280         </scilab:image>
281         <programlisting role="example"><![CDATA[ 
282 //generate the data
283 function y=FF(x,p)
284   y=p(1)*(x-p(2))+p(3)*x.*x
285 endfunction
286
287 //the gradient of the criterion function
288 function s=DG(p,z),
289   a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
290   s=-[x-b,-a,x*x]
291 endfunction
292
293 function e=G(p,z),
294   y=z(1),x=z(2);
295   e=y-FF(x,p),
296 endfunction
297
298 X=[];Y=[];
299 pg=[34;12;14]
300 for x=0:.1:3
301   Y=[Y,FF(x,pg)+100*(rand()-.5)];
302   X=[X,x];
303 end
304 Z=[Y;X];
305
306 p0=[3;5;10]     
307 [p,err]=datafit(G,DG,Z,p0);
308 scf(1);
309 clf()
310 plot2d(X,FF(X,pg),5) //the curve without noise
311 plot2d(X,Y,-1)  // the noisy data
312 plot2d(X,FF(X,p),12) //the solution
313  ]]></programlisting>
314         <scilab:image>
315             function y=FF(x,p)
316             y=p(1)*(x-p(2))+p(3)*x.*x
317             endfunction
318             
319             function s=DG(p,z),
320             a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
321             s=-[x-b,-a,x*x]
322             endfunction
323             
324             function e=G(p,z),
325             y=z(1),x=z(2);
326             e=y-FF(x,p),
327             endfunction
328             
329             X=[];Y=[];
330             pg=[34;12;14]
331             for x=0:.1:3
332             Y=[Y,FF(x,pg)+100*(rand()-.5)];
333             X=[X,x];
334             end
335             Z=[Y;X];
336             
337             p0=[3;5;10] 
338             [p,err]=datafit(G,DG,Z,p0);
339             scf(1);
340             clf()
341             plot2d(X,FF(X,pg),5)
342             plot2d(X,Y,-1)
343             plot2d(X,FF(X,p),12)
344         </scilab:image>
345         <programlisting role="example"><![CDATA[
346 //generate the data
347 function y=FF(x,p)
348   y=p(1)*(x-p(2))+p(3)*x.*x
349 endfunction
350
351 //the gradient of the criterion function
352 function s=DG(p,z),
353   a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
354   s=-[x-b,-a,x*x]
355 endfunction
356
357 function e=G(p,z),
358   y=z(1),x=z(2);
359   e=y-FF(x,p),
360 endfunction
361
362 X=[];Y=[];
363 pg=[34;12;14]
364 for x=0:.1:3
365   Y=[Y,FF(x,pg)+100*(rand()-.5)];
366   X=[X,x];
367 end
368 Z=[Y;X];
369
370 p0=[3;5;10]     
371
372 // Add some bounds on the estimate of the parameters
373 // We want positive estimation (the result will not change)
374 [p,err]=datafit(G,DG,Z,'b',[0;0;0],[%inf;%inf;%inf],p0,algo='gc');
375 scf(1);
376 clf()
377 plot2d(X,FF(X,pg),5) //the curve without noise
378 plot2d(X,Y,-1)  // the noisy data
379 plot2d(X,FF(X,p),12) //the solution
380  ]]></programlisting>
381         <scilab:image>
382             function y=FF(x,p)
383             y=p(1)*(x-p(2))+p(3)*x.*x
384             endfunction
385             
386             function s=DG(p,z),
387             a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
388             s=-[x-b,-a,x*x]
389             endfunction
390             
391             function e=G(p,z),
392             y=z(1),x=z(2);
393             e=y-FF(x,p),
394             endfunction
395             
396             X=[];Y=[];
397             pg=[34;12;14]
398             for x=0:.1:3
399             Y=[Y,FF(x,pg)+100*(rand()-.5)];
400             X=[X,x];
401             end
402             Z=[Y;X];
403             
404             p0=[3;5;10] 
405             
406             [p,err]=datafit(G,DG,Z,'b',[0;0;0],[%inf;%inf;%inf],p0,algo='gc');
407             scf(1);
408             clf()
409             plot2d(X,FF(X,pg),5)
410             plot2d(X,Y,-1)
411             plot2d(X,FF(X,p),12)
412         </scilab:image>
413     </refsection>
414     <refsection role="see also">
415         <title>See Also</title>
416         <simplelist type="inline">
417             <member>
418                 <link linkend="lsqrsolve">lsqrsolve</link>
419             </member>
420             <member>
421                 <link linkend="optim">optim</link>
422             </member>
423             <member>
424                 <link linkend="leastsq">leastsq</link>
425             </member>
426         </simplelist>
427     </refsection>
428 </refentry>