Added a more obvious message for numdiff and derivative obsolescence
[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.1-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. <emphasis role="bold"> This function is obsolete. Please use the <link linkend="numderivative">numderivative</link> function instead.</emphasis></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>
29                   an external, Scilab function or list. See below for calling
30                   sequence, see also <link linkend="external">external</link> for
31                   details about external functions.
32                   f: R<superscript>n</superscript> --> R<superscript>p</superscript>
33                </para>
34             </listitem>
35          </varlistentry>
36          <varlistentry>
37             <term>x</term>
38             <listitem>
39                <para>
40                   a vector of the <code>n</code> coordinates of the single point at which the gradient is sought.
41                </para>
42             </listitem>
43          </varlistentry>
44          <varlistentry>
45             <term>dx</term>
46             <listitem>
47                <para>
48                   a vector, the finite difference step. Default value is
49                   <code>dx = sqrt(%eps)*(1+1d-3*abs(x))</code>.
50                </para>
51             </listitem>
52          </varlistentry>
53          <varlistentry>
54             <term>g</term>
55             <listitem>
56                <para>
57                   a matrix, the estimated gradient at the locus <varname>x</varname>.
58                </para>
59             </listitem>
60          </varlistentry>
61       </variablelist>
62    </refsection>
63    <refsection>
64       <title>Description</title>
65       <para>
66          Given a function <code>fun(x)</code> from
67          R<superscript>n</superscript> to R<superscript>p</superscript> computes the <code>p x n</code> matrix
68          <varname>g</varname> such that
69       </para>
70       <programlisting role="no-scilab-exec">
71          <![CDATA[
72          g(i,j) = [(df_i)/(dx_j)](x)
73          ]]>
74       </programlisting>
75       <para>
76          using finite difference methods.
77          Uses an order 1 formula.
78       </para>
79       <para>
80          Without parameters, the function <varname>fun</varname> calling sequence is
81          <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
82          <code>g = numdiff(fun, x)</code>. Else the function <varname>fun</varname> calling
83          sequence must be <literal>y = fun(x, param_1, pararm_2, ..., param_q)</literal>.
84          If parameters <literal>param_1, param_2, ..., param_q</literal> exist then
85          <function>numdiff</function> can be called as follow
86          <literal>g = numdiff(list(fun, param_1, param_2, ..., param_q), x)</literal>.
87       </para>
88       <para>
89          See the
90          <link linkend="derivative">derivative</link> with respect to numerical accuracy
91          issues and comparison between the two algorithms.
92       </para>
93    </refsection>
94    <refsection>
95       <title>Examples</title>
96       <programlisting role="example">
97          <![CDATA[
98          // Example 1 (without parameters)
99          // myfun is a function from R^2 to R: (x(1), x(2)) |--> myfun(x)
100          function f = myfun(x)
101          f = x(1)*x(1) + x(1)*x(2)
102          endfunction
103
104          x = [5 8];
105          g = numdiff(myfun, x)
106
107          // The exact gradient (i.e first component = derivate with respect to x(1)
108          // and second component = derivate with respect to x(2)) is:
109          exact = [2*x(1)+x(2)  x(1)]
110
111
112          // Example 2 (with parameters)
113          // myfun is a function from R to R: x |--> myfun(x)
114          // myfun contains 3 parameters: a, b and c
115          function  f = myfun(x, a, b, c)
116          f = (x+a)^c + b
117          endfunction
118
119          a = 3; b = 4; c = 2;
120          x = 1;
121          g2 = numdiff(list(myfun, a, b, c), x)
122
123          // The exact gradient, i.e derivate with respiect to x, is:
124          exact2 = c*(x+a)^(c-1)
125
126
127          // Example 3 (f: R^3 --> R^3)
128          // 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))
129          function f = myfun(x)
130          f(1) = x(1) * x(1);
131          f(2) = x(1) * x(2) * x(3);
132          f(3) = 2*x(1) + 2*x(2) + 2*x(3);
133          endfunction
134
135          x = [5 8 10];
136          g = numdiff(myfun, x)
137
138          // The exact gradient is:
139          // [  df_1/dx_1  df_1/dx_2  df_1/dx_3 ;
140          //    df_2/dx_1  df_2/dx_2  df_2/dx_3 ;
141          //    df_3/dx_1  df_3/dx_2  df_3/dx_3 ; ]
142          exact3 = [2*x(1) 0 0  ;  x(2)*x(3) x(1)*x(3) x(1)*x(2)  ;  2 2 2]
143
144          ]]>
145       </programlisting>
146    </refsection>
147    <refsection role="see also">
148       <title>See Also</title>
149       <simplelist type="inline">
150          <member>
151             <link linkend="interp">interp</link>
152          </member>
153          <member>
154             <link linkend="interp2d">interp2d</link>
155          </member>
156          <member>
157             <link linkend="splin">splin</link>
158          </member>
159          <member>
160             <link linkend="eval_cshep2d">eval_cshep2d</link>
161          </member>
162          <member>
163             <link linkend="optim">optim</link>
164          </member>
165          <member>
166             <link linkend="diff">diff</link>
167          </member>
168          <member>
169             <link linkend="derivative">derivative</link>
170          </member>
171          <member>
172             <link linkend="numderivative">numderivative</link>
173          </member>
174          <member>
175             <link linkend="external">external</link>
176          </member>
177       </simplelist>
178    </refsection>
179    <refsection>
180       <title>History</title>
181       <revhistory>
182          <revision>
183             <revnumber>5.5.0</revnumber>
184             <revremark>Tagged as obsolete. Will be removed in Scilab 6.0.0.</revremark>
185          </revision>
186       </revhistory>
187    </refsection>
188    <refsection>
189       <title>Appendix</title>
190       <para>
191          We now discuss how a script using the <literal>numdiff</literal> function can be
192          updated to use the <literal>numderivative</literal> function.
193       </para>
194       <para>
195          Consider the function:
196       </para>
197       <programlisting role="example">
198          <![CDATA[
199          function f = myfun(x)
200          f = x(1)*x(1)+x(1)*x(2)
201          endfunction
202          ]]>
203       </programlisting>
204       <para>
205          and the point:
206       </para>
207       <programlisting role="example">
208          <![CDATA[
209          x = [5 8]
210          ]]>
211       </programlisting>
212       <para>
213          Therefore, the statement:
214       </para>
215       <programlisting role="example">
216          <![CDATA[
217          g1 = numdiff(myfun, x)
218          ]]>
219       </programlisting>
220       <para>
221          can be replaced with
222       </para>
223       <programlisting role="example">
224          <![CDATA[
225          g2 = numderivative(myfun, x)
226          ]]>
227       </programlisting>
228       <para>
229          If having exactly the same step is important, we force the step to the same value as in
230          <literal>numdiff</literal>:
231       </para>
232       <programlisting role="example">
233          <![CDATA[
234          x = [5 8];
235          h = sqrt(%eps)*(1+1d-3*abs(x))
236          g1 = numdiff(myfun, x)
237          g2 = numderivative(myfun, x, h)
238          g1 == g2
239          ]]>
240       </programlisting>
241    </refsection>
242
243 </refentry>