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