Revision of help page for numdiff (en_US).
[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</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                     </para>
32                 </listitem>
33             </varlistentry>
34             <varlistentry>
35                 <term>x</term>
36                 <listitem>
37                     <para>a vector, the argument of the function
38                         <varname>fun</varname>.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>dx</term>
44                 <listitem>
45                     <para>a vector, the finite difference step. Default value is
46                         <code>dx=sqrt(%eps)*(1+1d-3*abs(x))</code>.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>g</term>
52                 <listitem>
53                     <para>a vector, the estimated gradient.</para>
54                 </listitem>
55             </varlistentry>
56         </variablelist>
57     </refsection>
58     <refsection>
59         <title>Description</title>
60         <para>
61             Given a function <code>fun(x)</code> from
62             <code>R^n</code> to <code>R^p</code> computes the matrix
63             <varname>g</varname> such as
64         </para>
65         <programlisting role="no-scilab-exec"><![CDATA[
66 g(i,j) = (df_i)/(dx_j)
67  ]]></programlisting>
68         <para>using finite difference methods.
69             Uses an order 1 formula.
70         </para>
71         <para>
72             Without parameters, the function <varname>fun</varname> calling sequence is
73               <code>y=fun(x)</code>, and <function>numdiff</function> can be called as
74             <code>g=numdiff(fun,x)</code>. Else the function <varname>fun</varname> calling
75             sequence must be <literal>y = fun(x, param_1, pararm_2, ..., param_q)</literal>.
76             If parameters <literal>param_1, param_2, ..., param_q</literal> exist then
77             <function>numdiff</function> can be called as follow
78             <literal>g=numdiff(list(fun, param_1, param_2, ..., param_q), x)</literal>.
79         </para>
80         <para>
81             See the 
82             <link linkend="derivative">derivative</link> with respect to numerical accuracy 
83             issues and comparison between the two algorithms.
84         </para>
85     </refsection>
86     <refsection>
87         <title>Examples</title>
88         <programlisting role="example"><![CDATA[ 
89 // example 1 (without parameters)
90 // myfun is a function from R^2 to R: (x(1),x(2)) |--> myfun(x)
91 function f=myfun(x)
92   f=x(1)*x(1)+x(1)*x(2)
93 endfunction
94
95 x=[5 8]
96 g=numdiff(myfun,x)
97
98 // The exact gradient (i.e derivate belong x(1): first component
99 // and derivate belong x(2): second component) is
100 exact=[2*x(1)+x(2)  x(1)]
101
102 //example 2 (with parameters)
103 // myfun is a function from R to R: x(1) |--> myfun(x)
104 // myfun contains 3 parameters: a, b, c
105 function  f=myfun(x,a,b,c)
106   f=(x+a)^c+b
107 endfunction
108
109 a=3; b=4; c=2;
110 x=1
111 g2=numdiff(list(myfun,a,b,c),x)
112
113 // The exact gradient, i.e derivate belong x(1), is :
114 exact2=c*(x+a)^(c-1)
115  ]]></programlisting>
116     </refsection>
117     <refsection role="see also">
118         <title>See Also</title>
119         <simplelist type="inline">
120             <member>
121                 <link linkend="optim">optim</link>
122             </member>
123             <member>
124                 <link linkend="derivative">derivative</link>
125             </member>
126             <member>
127                 <link linkend="external">external</link>
128             </member>
129         </simplelist>
130     </refsection>
131 </refentry>