Massive indent of all codes:
[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>