- Elementary functions better organization. See bug #11723.
[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" version="5.0-subset Scilab" 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>vector, the argument of the function
38                         <literal>fun</literal>
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>dx</term>
44                 <listitem>
45                     <para>vector, the finite difference step. Default value is
46                         <literal>dx=sqrt(%eps)*(1+1d-3*abs(x))</literal>
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>g</term>
52                 <listitem>
53                     <para>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 <literal>fun(x)</literal> from
62             <literal>R^n</literal> to <literal>R^p</literal> computes the matrix
63             <literal>g</literal> such as
64         </para>
65         <programlisting role=""><![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 fun calling sequence is
73             <literal>y=fun(x)</literal>, and numdiff can be called as
74             <literal>g=numdiff(fun,x)</literal>. Else the function fun 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             <literal>numdiff</literal> 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 and derivate belong x(2): second component) is  
99 exact=[2*x(1)+x(2)  x(1)]
100
101 //example 2 (with parameters)
102 // myfun is a function from R to R:  x(1) |--> myfun(x) 
103 // myfun contains 3 parameters, a, b, c
104 function  f=myfun(x,a,b,c)
105   f=(x+a)^c+b
106 endfunction
107
108 a=3; b=4; c=2;
109 x=1
110 g2=numdiff(list(myfun,a,b,c),x)
111
112 // The exact gradient, i.e derivate belong x(1), is :
113 exact2=c*(x+a)^(c-1)
114  ]]></programlisting>
115     </refsection>
116     <refsection role="see also">
117         <title>See Also</title>
118         <simplelist type="inline">
119             <member>
120                 <link linkend="optim">optim</link>
121             </member>
122             <member>
123                 <link linkend="derivative">derivative</link>
124             </member>
125             <member>
126                 <link linkend="external">external</link>
127             </member>
128         </simplelist>
129     </refsection>
130 </refentry>