Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / help / en_US / derivative.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="derivative" xml:lang="en"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:svg="http://www.w3.org/2000/svg"
6           xmlns:ns4="http://www.w3.org/1999/xhtml"
7           xmlns:mml="http://www.w3.org/1998/Math/MathML"
8           xmlns:db="http://docbook.org/ns/docbook">
9   <info>
10     <pubdate>$LastChangedDate$</pubdate>
11   </info>
12
13   <refnamediv>
14     <refname>derivative</refname>
15
16     <refpurpose>approximate derivatives of a function</refpurpose>
17   </refnamediv>
18
19   <refsynopsisdiv>
20     <title>Calling Sequence</title>
21
22     <synopsis>derivative(F,x)
23 [J [,H]] = derivative(F,x [,h ,order ,H_form ,Q])</synopsis>
24   </refsynopsisdiv>
25
26   <refsection>
27     <title>Parameters</title>
28
29     <variablelist>
30       <varlistentry>
31         <term>F</term>
32
33         <listitem>
34           <para>a Scilab function F: <literal>R^n --&gt; R^m</literal> or a
35           <literal>list(F,p1,...,pk)</literal>, where F is a scilab function
36           in the form <literal>y=F(x,p1,...,pk)</literal>, p1, ..., pk being
37           any scilab objects (matrices, lists,...).</para>
38         </listitem>
39       </varlistentry>
40
41       <varlistentry>
42         <term>x</term>
43
44         <listitem>
45           <para>real column vector of dimension n.</para>
46         </listitem>
47       </varlistentry>
48
49       <varlistentry>
50         <term>h</term>
51
52         <listitem>
53           <para>(optional) real, the stepsize used in the finite difference
54           approximations.</para>
55         </listitem>
56       </varlistentry>
57
58       <varlistentry>
59         <term>order</term>
60
61         <listitem>
62           <para>(optional) integer, the order of the finite difference formula
63           used to approximate the derivatives (order = 1,2 or 4, default is
64           order=2 ).</para>
65         </listitem>
66       </varlistentry>
67
68       <varlistentry>
69         <term>H_form</term>
70
71         <listitem>
72           <para>(optional) string, the form in which the Hessean will be
73           returned. Possible forms are:</para>
74
75           <variablelist>
76             <varlistentry>
77               <term>H_form='default'</term>
78
79               <listitem>
80                 <para>H is a m x (<literal>n^2</literal>) matrix ; in this
81                 form, the k-th row of H corresponds to the Hessean of the k-th
82                 component of F, given as the following row vector :</para>
83
84                 <informalequation>
85                   <mediaobject>
86                     <imageobject>
87                       <imagedata align="center"
88                                  fileref="../mml/derivative_equation_1.mml" />
89                     </imageobject>
90                   </mediaobject>
91                 </informalequation>
92
93                 <para>((grad(F_k) being a row vector).</para>
94               </listitem>
95             </varlistentry>
96
97             <varlistentry>
98               <term>H_form='blockmat' :</term>
99
100               <listitem>
101                 <para>H is a (mxn) x n block matrix : the classic Hessean
102                 matrices (of each component of F) are stacked by row (H = [H1
103                 ; H2 ; ... ; Hm] in scilab syntax).</para>
104               </listitem>
105             </varlistentry>
106
107             <varlistentry>
108               <term>H_form='hypermat' :</term>
109
110               <listitem>
111                 <para>H is a n x n matrix for m=1, and a n x n x m hypermatrix
112                 otherwise. H(:,:,k) is the classic Hessean matrix of the k-th
113                 component of F.</para>
114               </listitem>
115             </varlistentry>
116           </variablelist>
117         </listitem>
118       </varlistentry>
119
120       <varlistentry>
121         <term>Q</term>
122
123         <listitem>
124           <para>(optional) real matrix, orthogonal (default is eye(n,n)). Q is added to have the possibility to remove
125             the arbitrariness of using the canonical basis to approximate the derivatives of a function and it should be an
126             orthogonal matrix. It is not mandatory but better to recover the derivative as you need the inverse matrix (and 
127             so simply Q' instead of inv(Q)).</para>
128         </listitem>
129       </varlistentry>
130
131       <varlistentry>
132         <term>J</term>
133         <listitem>
134           <para>approximated Jacobian</para>
135         </listitem>
136       </varlistentry>
137
138       <varlistentry>
139         <term>H</term>
140         <listitem>
141           <para>approximated Hessian</para>
142         </listitem>
143       </varlistentry>
144
145     </variablelist>
146   </refsection>
147
148   <refsection>
149     <title>Description</title>
150
151     <para>Numerical approximation of the first and second derivatives of a
152     function F: <literal> R^n --&gt; R^m</literal> at the point x. The
153     Jacobian is computed by approximating the directional derivatives of the
154     components of F in the direction of the columns of Q. (For m=1, v=Q(:,k) :
155     grad(F(x))*v = Dv(F(x)).) The second derivatives are computed by
156     composition of first order derivatives. If H is given in its default form
157     the Taylor series of F(x) up to terms of second order is given by :</para>
158
159     <informalequation>
160       <mediaobject>
161         <imageobject>
162           <imagedata align="center" fileref="../mml/derivative_equation_2.mml" />
163         </imageobject>
164       </mediaobject>
165     </informalequation>
166
167     <para>(([J,H]=derivative(F,x,H_form='default'), J=J(x), H=H(x).)</para>
168   </refsection>
169
170   <refsection>
171     <title>Remarks</title>
172
173     <para>Numerical approximation of derivatives is generally an unstable
174     process. The step size h must be small to get a low error but if it is too
175     small floating point errors will dominate by cancellation. As a rule of
176     thumb don't change the default step size. To work around numerical
177     difficulties one may also change the order and/or choose different
178     orthogonal matrices Q (the default is eye(n,n)), especially if the
179     approximate derivatives are used in optimization routines. All the
180     optional arguments may also be passed as named arguments, so that one can
181     use calls in the form :</para>
182
183     <programlisting><![CDATA[ 
184 derivative(F, x, H_form = "hypermat")
185 derivative(F, x, order = 4) etc.
186  ]]></programlisting>
187   </refsection>
188
189   <refsection>
190     <title>Examples</title>
191
192     <programlisting role="example"><![CDATA[ 
193 function y=F(x)
194   y=[sin(x(1)*x(2))+exp(x(2)*x(3)+x(1)) ; sum(x.^3)];
195 endfunction
196
197 function y=G(x,p) 
198   y=[sin(x(1)*x(2)*p)+exp(x(2)*x(3)+x(1)) ; sum(x.^3)];
199 endfunction
200
201 x=[1;2;3];[J,H]=derivative(F,x,H_form='blockmat')
202
203 n=3;
204 // form an orthogonal matrix :   
205 nu=0; while nu<n, [Q,nu]=colcomp(rand(n,n)); end  
206 for i=[1,2,4]
207   [J,H]=derivative(F,x,order=i,H_form='blockmat',Q=Q);
208   mprintf("order= %d \n",i);
209   H,
210 end
211
212 p=1;h=1e-3;
213 [J,H]=derivative(list(G,p),x,h,2,H_form='hypermat');H
214 [J,H]=derivative(list(G,p),x,h,4,Q=Q);H
215
216 // Taylor series example:
217 dx=1e-3*[1;1;-1];
218 [J,H]=derivative(F,x);
219 F(x+dx)
220 F(x+dx)-F(x)
221 F(x+dx)-F(x)-J*dx
222 F(x+dx)-F(x)-J*dx-1/2*H*(dx .*. dx)
223
224 // A trivial example
225 function y=f(x,A,p,w), y=x'*A*x+p'*x+w; endfunction
226 // with Jacobian and Hessean given by J(x)=x'*(A+A')+p', and H(x)=A+A'.
227 A = rand(3,3); p = rand(3,1); w = 1;
228 x = rand(3,1);
229 [J,H]=derivative(list(f,A,p,w),x,h=1,H_form='blockmat')
230
231 // Since f(x) is quadratic in x, approximate derivatives of order=2 or 4 by finite
232 // differences should be exact for all h~=0. The apparent errors are caused by
233 // cancellation in the floating point operations, so a "big" h is choosen.
234 // Comparison with the exact matrices:
235 Je = x'*(A+A')+p'
236 He = A+A'
237 clean(Je - J)
238 clean(He - H)
239  ]]></programlisting>
240   </refsection>
241
242   <refsection>
243     <title>See Also</title>
244
245     <simplelist type="inline">
246       <member><link linkend="numdiff">numdiff</link></member>
247
248       <member><link linkend="derivat">derivat</link></member>
249     </simplelist>
250   </refsection>
251
252   <refsection>
253     <title>Authors</title>
254
255     <para>Rainer von Seggern, Bruno Pincon</para>
256   </refsection>
257 </refentry>