Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / help / en_US / 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  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="datafit" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate$</pubdate>
22   </info>
23
24   <refnamediv>
25     <refname>datafit</refname>
26
27     <refpurpose>Parameter identification based on measured data</refpurpose>
28   </refnamediv>
29
30   <refsynopsisdiv>
31     <title>Calling Sequence</title>
32
33     <synopsis>[p,err]=datafit([imp,] G [,DG],Z [,W],[contr],p0,[algo],[df0,[mem]],
34 [work],[stop],['in'])</synopsis>
35   </refsynopsisdiv>
36
37   <refsection>
38     <title>Parameters</title>
39
40     <variablelist>
41       <varlistentry>
42         <term>imp</term>
43
44         <listitem>
45           <para>scalar argument used to set the trace mode.
46           <literal>imp=0</literal> nothing (execpt errors) is reported,
47           <literal>imp=1</literal> initial and final reports,
48           <literal>imp=2</literal> adds a report per iteration,
49           <literal>imp&gt;2</literal> add reports on linear search. Warning,
50           most of these reports are written on the Scilab standard
51           output.</para>
52         </listitem>
53       </varlistentry>
54
55       <varlistentry>
56         <term>G</term>
57
58         <listitem>
59           <para>function descriptor (e=G(p,z), e: ne x 1, p: np x 1, z: nz x
60           1)</para>
61         </listitem>
62       </varlistentry>
63
64       <varlistentry>
65         <term>DG</term>
66
67         <listitem>
68           <para>partial of G wrt p function descriptor (optional; S=DG(p,z),
69           S: ne x np)</para>
70         </listitem>
71       </varlistentry>
72
73       <varlistentry>
74         <term>Z</term>
75
76         <listitem>
77           <para>matrix [z_1,z_2,...z_n] where z_i (nz x 1) is the ith
78           measurement</para>
79         </listitem>
80       </varlistentry>
81
82       <varlistentry>
83         <term>W</term>
84
85         <listitem>
86           <para>weighting matrix of size ne x ne (optional; defaut no
87           ponderation)</para>
88         </listitem>
89       </varlistentry>
90
91       <varlistentry>
92         <term>contr</term>
93
94         <listitem>
95           <para>: <literal>'b',binf,bsup</literal> with
96           <literal>binf</literal> and <literal>bsup</literal> real vectors
97           with same dimension as <literal>p0</literal>.
98           <literal>binf</literal> and <literal>bsup</literal> are lower and
99           upper bounds on <literal>p</literal>.</para>
100         </listitem>
101       </varlistentry>
102
103       <varlistentry>
104         <term>p0</term>
105
106         <listitem>
107           <para>initial guess (size np x 1)</para>
108         </listitem>
109       </varlistentry>
110
111       <varlistentry>
112         <term>algo</term>
113
114         <listitem>
115           <para>: <literal>'qn'</literal> or <literal>'gc'</literal> or
116           <literal>'nd'</literal> . This string stands for quasi-Newton
117           (default), conjugate gradient or non-differentiable respectively.
118           Note that <literal>'nd'</literal> does not accept bounds on
119           <literal>x</literal> ).</para>
120         </listitem>
121       </varlistentry>
122
123       <varlistentry>
124         <term>df0</term>
125
126         <listitem>
127           <para>real scalar. Guessed decreasing of <literal>f</literal> at
128           first iteration. (<literal>df0=1</literal> is the default
129           value).</para>
130         </listitem>
131       </varlistentry>
132
133       <varlistentry>
134         <term>mem :</term>
135
136         <listitem>
137           <para>integer, number of variables used to approximate the Hessian,
138           (<literal>algo='gc' or 'nd'</literal>). Default value is around
139           6.</para>
140         </listitem>
141       </varlistentry>
142
143       <varlistentry>
144         <term>stop</term>
145
146         <listitem>
147           <para>sequence of optional parameters controlling the convergence of
148           the algorithm. <literal> stop= 'ar',nap, [iter [,epsg [,epsf
149           [,epsx]]]]</literal></para>
150
151           <variablelist>
152             <varlistentry>
153               <term>"ar"</term>
154
155               <listitem>
156                 <para>reserved keyword for stopping rule selection defined as
157                 follows:</para>
158               </listitem>
159             </varlistentry>
160
161             <varlistentry>
162               <term>nap</term>
163
164               <listitem>
165                 <para>maximum number of calls to <literal>fun</literal>
166                 allowed.</para>
167               </listitem>
168             </varlistentry>
169
170             <varlistentry>
171               <term>iter</term>
172
173               <listitem>
174                 <para>maximum number of iterations allowed.</para>
175               </listitem>
176             </varlistentry>
177
178             <varlistentry>
179               <term>epsg</term>
180
181               <listitem>
182                 <para>threshold on gradient norm.</para>
183               </listitem>
184             </varlistentry>
185
186             <varlistentry>
187               <term>epsf</term>
188
189               <listitem>
190                 <para>threshold controlling decreasing of
191                 <literal>f</literal></para>
192               </listitem>
193             </varlistentry>
194
195             <varlistentry>
196               <term>epsx</term>
197
198               <listitem>
199                 <para>threshold controlling variation of <literal>x</literal>.
200                 This vector (possibly matrix) of same size as
201                 <literal>x0</literal> can be used to scale
202                 <literal>x</literal>.</para>
203               </listitem>
204             </varlistentry>
205           </variablelist>
206         </listitem>
207       </varlistentry>
208
209       <varlistentry>
210         <term>"in"</term>
211
212         <listitem>
213           <para>reserved keyword for initialization of parameters used when
214           <literal>fun</literal> in given as a Fortran routine (see
215           below).</para>
216         </listitem>
217       </varlistentry>
218
219       <varlistentry>
220         <term>p</term>
221
222         <listitem>
223           <para>Column vector, optimal solution found</para>
224         </listitem>
225       </varlistentry>
226
227       <varlistentry>
228         <term>err</term>
229
230         <listitem>
231           <para>scalar, least square error.</para>
232         </listitem>
233       </varlistentry>
234     </variablelist>
235   </refsection>
236
237   <refsection>
238     <title>Description</title>
239
240     <para><literal>datafit</literal> is used for fitting data to a model. For
241     a given function <literal>G(p,z)</literal>, this function finds the best
242     vector of parameters <literal>p</literal> for approximating
243     <literal>G(p,z_i)=0</literal> for a set of measurement vectors
244     <literal>z_i</literal>. Vector <literal>p</literal> is found by minimizing
245     <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></para>
246
247     <para><literal>datafit</literal> is an improved version of
248     <literal>fit_dat</literal>.</para>
249   </refsection>
250
251   <refsection>
252     <title>Examples</title>
253
254     <programlisting role="example"><![CDATA[ 
255 //generate the data
256 function y=FF(x,p),y=p(1)*(x-p(2))+p(3)*x.*x,endfunction
257 X=[];Y=[];
258 pg=[34;12;14] //parameter used to generate data
259 for x=0:.1:3, Y=[Y,FF(x,pg)+100*(rand()-.5)];X=[X,x];end
260 Z=[Y;X];
261
262 //The criterion function
263 function e=G(p,z),
264   y=z(1),x=z(2);
265   e=y-FF(x,p),
266 endfunction
267
268 //Solve the problem
269 p0=[3;5;10]     
270 [p,err]=datafit(G,Z,p0);
271
272 scf(0);clf()
273 plot2d(X,FF(X,pg),5) //the curve without noise
274 plot2d(X,Y,-1)  // the noisy data
275 plot2d(X,FF(X,p),12) //the solution
276
277 //the gradient of the criterion function
278 function s=DG(p,z),
279   a=p(1),b=p(2),c=p(3),y=z(1),x=z(2),
280   s=-[x-b,-a,x*x]
281 endfunction
282
283 [p,err]=datafit(G,DG,Z,p0);
284 scf(1);clf()
285 plot2d(X,FF(X,pg),5) //the curve without noise
286 plot2d(X,Y,-1)  // the noisy data
287 plot2d(X,FF(X,p),12) //the solution
288
289 // Add some bounds on the estimate of the parameters
290 // We want positive estimation (the result will not change)
291 [p,err]=datafit(G,DG,Z,'b',[0;0;0],[%inf;%inf;%inf],p0,algo='gc');
292 scf(1);clf()
293 plot2d(X,FF(X,pg),5) //the curve without noise
294 plot2d(X,Y,-1)  // the noisy data
295 plot2d(X,FF(X,p),12) //the solution
296  ]]></programlisting>
297   </refsection>
298
299   <refsection>
300     <title>See Also</title>
301
302     <simplelist type="inline">
303       <member><link linkend="lsqrsolve">lsqrsolve</link></member>
304
305       <member><link linkend="optim">optim</link></member>
306
307       <member><link linkend="leastsq">leastsq</link></member>
308     </simplelist>
309   </refsection>
310 </refentry>