* Bug #5694 fixed - numdiff help page fixed
[scilab.git] / scilab / modules / differential_equations / help / en_US / numdiff.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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="numdiff" xml:lang="en">
14     <refnamediv>
15         <refname>numdiff</refname>
16         <refpurpose>numerical gradient estimation at one point</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>g = numdiff(fun, x [,dx])</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>fun</term>
27                 <listitem>
28                     <para>an external, Scilab function or list. See below for calling
29                         sequence, see also <link linkend="external">external</link> for
30                         details about external functions.
31                         f: R<superscript>n</superscript> --> R<superscript>p</superscript>
32                     </para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>x</term>
37                 <listitem>
38                     <para>
39                         a vector of the <code>n</code> coordinates of the single point at which the gradient is sought.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>dx</term>
45                 <listitem>
46                     <para>a vector, the finite difference step. Default value is
47                         <code>dx = sqrt(%eps)*(1+1d-3*abs(x))</code>.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>g</term>
53                 <listitem>
54                     <para>
55                         a matrix, the estimated gradient at the locus <varname>x</varname>.
56                     </para>
57                 </listitem>
58             </varlistentry>
59         </variablelist>
60     </refsection>
61     <refsection>
62         <title>Description</title>
63         <para>
64             Given a function <code>fun(x)</code> from
65             R<superscript>n</superscript> to R<superscript>p</superscript> computes the <code>p x n</code> matrix
66             <varname>g</varname> such that
67         </para>
68         <programlisting role="no-scilab-exec"><![CDATA[
69 g(i,j) = [(df_i)/(dx_j)](x)
70  ]]></programlisting>
71         <para>using finite difference methods.
72             Uses an order 1 formula.
73         </para>
74         <para>
75             Without parameters, the function <varname>fun</varname> calling sequence is
76             <code>y = fun(x)</code>, with <varname>x</varname> &#8712; R<superscript>n</superscript> and <varname>y</varname> &#8712; R<superscript>p</superscript>, and <function>numdiff</function> can be called as
77             <code>g = numdiff(fun, x)</code>. Else the function <varname>fun</varname> calling
78             sequence must be <literal>y = fun(x, param_1, pararm_2, ..., param_q)</literal>.
79             If parameters <literal>param_1, param_2, ..., param_q</literal> exist then
80             <function>numdiff</function> can be called as follow
81             <literal>g = numdiff(list(fun, param_1, param_2, ..., param_q), x)</literal>.
82         </para>
83         <para>
84             See the 
85             <link linkend="derivative">derivative</link> with respect to numerical accuracy 
86             issues and comparison between the two algorithms.
87         </para>
88     </refsection>
89     <refsection>
90         <title>Examples</title>
91         <programlisting role="example"><![CDATA[
92 // Example 1 (without parameters)
93 // myfun is a function from R^2 to R: (x(1), x(2)) |--> myfun(x)
94 function f = myfun(x)
95   f = x(1)*x(1) + x(1)*x(2)
96 endfunction
97
98 x = [5 8];
99 g = numdiff(myfun, x)
100
101 // The exact gradient (i.e first component = derivate with respect to x(1)
102 // and second component = derivate with respect to x(2)) is:
103 exact = [2*x(1)+x(2)  x(1)]
104
105
106 // Example 2 (with parameters)
107 // myfun is a function from R to R: x |--> myfun(x)
108 // myfun contains 3 parameters: a, b and c
109 function  f = myfun(x, a, b, c)
110   f = (x+a)^c + b
111 endfunction
112
113 a = 3; b = 4; c = 2;
114 x = 1;
115 g2 = numdiff(list(myfun, a, b, c), x)
116
117 // The exact gradient, i.e derivate with respiect to x, is:
118 exact2 = c*(x+a)^(c-1)
119
120
121 // Example 3 (f: R^3 --> R^3)
122 // myfun is a function from R^2 to R^2: (x(1), x(2), x(3)) |--> (myfun(x)(1), myfun(x)(2), mfun(x)(3))
123 function f = myfun(x)
124   f(1) = x(1) * x(1);
125   f(2) = x(1) * x(2) * x(3);
126   f(3) = 2*x(1) + 2*x(2) + 2*x(3);
127 endfunction
128
129 x = [5 8 10];
130 g = numdiff(myfun, x)
131
132 // The exact gradient is:
133 // [  df_1/dx_1  df_1/dx_2  df_1/dx_3 ;
134 //    df_2/dx_1  df_2/dx_2  df_2/dx_3 ;
135 //    df_3/dx_1  df_3/dx_2  df_3/dx_3 ; ]
136 exact3 = [2*x(1) 0 0  ;  x(2)*x(3) x(1)*x(3) x(1)*x(2)  ;  2 2 2]
137
138  ]]></programlisting>
139     </refsection>
140     <refsection role="see also">
141         <title>See Also</title>
142         <simplelist type="inline">
143             <member>
144                 <link linkend="interp">interp</link>
145             </member>
146             <member>
147                 <link linkend="interp2d">interp2d</link>
148             </member>
149             <member>
150                 <link linkend="splin">splin</link>
151             </member>
152             <member>
153                 <link linkend="eval_cshep2d">eval_cshep2d</link>
154             </member>
155             <member>
156                 <link linkend="optim">optim</link>
157             </member>
158             <member>
159                 <link linkend="diff">diff</link>
160             </member>
161             <member>
162                 <link linkend="derivative">derivative</link>
163             </member>
164             <member>
165                 <link linkend="external">external</link>
166             </member>
167         </simplelist>
168     </refsection>
169 </refentry>