Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / 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 version="5.0-subset Scilab" xml:id="numdiff" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate$</pubdate>
22   </info>
23
24   <refnamediv>
25     <refname>numdiff</refname>
26
27     <refpurpose>numerical gradient estimation</refpurpose>
28   </refnamediv>
29
30   <refsynopsisdiv>
31     <title>Calling Sequence</title>
32
33     <synopsis>g=numdiff(fun,x [,dx])</synopsis>
34   </refsynopsisdiv>
35
36   <refsection>
37     <title>Parameters</title>
38
39     <variablelist>
40       <varlistentry>
41         <term>fun</term>
42
43         <listitem>
44           <para>an external, Scilab function or list. See below for calling
45           sequence, see also <link linkend="external">external</link> for
46           details about external functions.</para>
47         </listitem>
48       </varlistentry>
49
50       <varlistentry>
51         <term>x</term>
52
53         <listitem>
54           <para>vector, the argument of the function
55           <literal>fun</literal></para>
56         </listitem>
57       </varlistentry>
58
59       <varlistentry>
60         <term>dx</term>
61
62         <listitem>
63           <para>vector, the finite difference step. Default value is
64           <literal>dx=sqrt(%eps)*(1+1d-3*abs(x))</literal></para>
65         </listitem>
66       </varlistentry>
67
68       <varlistentry>
69         <term>g</term>
70
71         <listitem>
72           <para>vector, the estimated gradient</para>
73         </listitem>
74       </varlistentry>
75     </variablelist>
76   </refsection>
77
78   <refsection>
79     <title>Description</title>
80
81     <para>given a function <literal>fun(x)</literal> from
82     <literal>R^n</literal> to <literal>R^p</literal> computes the matrix
83     <literal>g</literal> such as</para>
84
85     <programlisting role = ""><![CDATA[ 
86 [ d f ] [ i ] g = [ ---- ] ij [ d x ] [ j ]
87  ]]></programlisting>
88
89     <para>using finite difference methods.</para>
90
91     <para>Without parameters, the function fun calling sequence is
92     <literal>y=fun(x)</literal>, and numdiff can be called as
93     <literal>g=numdiff(fun,x)</literal>. Else the function fun calling
94     sequence must be <literal>y=fun(x,param_1,pararm_2,..,param_q)</literal>.
95     If parameters <literal>param_1,param_2,..param_q</literal> exist then
96     <literal>numdiff</literal> can be called as follow
97     <literal>g=numdiff(list(fun,param_1,param_2,..param_q),x)</literal>.</para>
98   </refsection>
99
100   <refsection>
101     <title>Examples</title>
102
103     <programlisting role="example"><![CDATA[ 
104 // example 1 (without parameters)
105 // myfun is a function from R^2 to R :   (x(1),x(2)) |--> myfun(x) 
106 function f=myfun(x)
107   f=x(1)*x(1)+x(1)*x(2)
108 endfunction
109
110 x=[5 8]
111 g=numdiff(myfun,x)
112
113 // The exact gradient (i.e derivate belong x(1) :first component and derivate belong x(2): second component) is  
114 exact=[2*x(1)+x(2)  x(1)]
115
116 //example 2 (with parameters)
117 // myfun is a function from R to R:  x(1) |--> myfun(x) 
118 // myfun contains 3 parameters, a, b, c
119 function  f=myfun(x,a,b,c)
120   f=(x+a)^c+b
121 endfunction
122
123 a=3; b=4; c=2;
124 x=1
125 g2=numdiff(list(myfun,a,b,c),x)
126
127 // The exact gradient, i.e derivate belong x(1), is :
128 exact2=c*(x+a)^(c-1)
129  ]]></programlisting>
130   </refsection>
131
132   <refsection>
133     <title>See Also</title>
134
135     <simplelist type="inline">
136       <member><link linkend="optim">optim</link></member>
137
138       <member><link linkend="external">external</link></member>
139     </simplelist>
140   </refsection>
141 </refentry>