Massive indent of all codes:
[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>