* Bug #5694 fixed - numdiff help page fixed
[scilab.git] / scilab / modules / differential_equations / help / en_US / numdiff.xml
index 949a5f3..ee957a9 100644 (file)
@@ -1,5 +1,5 @@
-        <?xml version="1.0" encoding="UTF-8"?>
-    <!--
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * 
  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  *
  -->
-    <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">
-        <refnamediv>
-            <refname>numdiff</refname>
-            <refpurpose>numerical gradient estimation</refpurpose>
-        </refnamediv>
-        <refsynopsisdiv>
-            <title>Calling Sequence</title>
-            <synopsis>g = numdiff(fun, x [,dx])</synopsis>
-        </refsynopsisdiv>
-        <refsection>
-            <title>Arguments</title>
-            <variablelist>
-                <varlistentry>
-                    <term>fun</term>
-                    <listitem>
-                        <para>an external, Scilab function or list. See below for calling
-                            sequence, see also <link linkend="external">external</link> for
-                            details about external functions.
-                        </para>
-                    </listitem>
-                </varlistentry>
-                <varlistentry>
-                    <term>x</term>
-                    <listitem>
-                        <para>a vector, the argument of the function
-                            <varname>fun</varname>.
-                        </para>
-                    </listitem>
-                </varlistentry>
-                <varlistentry>
-                    <term>dx</term>
-                    <listitem>
-                        <para>a vector, the finite difference step. Default value is
-                            <code>dx=sqrt(%eps)*(1+1d-3*abs(x))</code>.
-                        </para>
-                    </listitem>
-                </varlistentry>
-                <varlistentry>
-                    <term>g</term>
-                    <listitem>
-                        <para>a vector, the estimated gradient.</para>
-                    </listitem>
-                </varlistentry>
-            </variablelist>
-        </refsection>
-        <refsection>
-            <title>Description</title>
-            <para>
-                Given a function <code>fun(x)</code> from
-                <code>R^n</code> to <code>R^p</code> computes the matrix
-                <varname>g</varname> such as
-            </para>
-            <programlisting role="no-scilab-exec"><![CDATA[
-g(i,j) = (df_i)/(dx_j)
+<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">
+    <refnamediv>
+        <refname>numdiff</refname>
+        <refpurpose>numerical gradient estimation at one point</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>g = numdiff(fun, x [,dx])</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>fun</term>
+                <listitem>
+                    <para>an external, Scilab function or list. See below for calling
+                        sequence, see also <link linkend="external">external</link> for
+                        details about external functions.
+                        f: R<superscript>n</superscript> --> R<superscript>p</superscript>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>x</term>
+                <listitem>
+                    <para>
+                        a vector of the <code>n</code> coordinates of the single point at which the gradient is sought.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>dx</term>
+                <listitem>
+                    <para>a vector, the finite difference step. Default value is
+                        <code>dx = sqrt(%eps)*(1+1d-3*abs(x))</code>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>g</term>
+                <listitem>
+                    <para>
+                        a matrix, the estimated gradient at the locus <varname>x</varname>.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Given a function <code>fun(x)</code> from
+            R<superscript>n</superscript> to R<superscript>p</superscript> computes the <code>p x n</code> matrix
+            <varname>g</varname> such that
+        </para>
+        <programlisting role="no-scilab-exec"><![CDATA[
+g(i,j) = [(df_i)/(dx_j)](x)
  ]]></programlisting>
-            <para>using finite difference methods.
-                Uses an order 1 formula.
-            </para>
-            <para>
-                Without parameters, the function <varname>fun</varname> calling sequence is
-                <code>y=fun(x)</code>, and <function>numdiff</function> can be called as
-                <code>g=numdiff(fun,x)</code>. Else the function <varname>fun</varname> calling
-                sequence must be <literal>y = fun(x, param_1, pararm_2, ..., param_q)</literal>.
-                If parameters <literal>param_1, param_2, ..., param_q</literal> exist then
-                <function>numdiff</function> can be called as follow
-                <literal>g=numdiff(list(fun, param_1, param_2, ..., param_q), x)</literal>.
-            </para>
-            <para>
-                See the 
-                <link linkend="derivative">derivative</link> with respect to numerical accuracy 
-                issues and comparison between the two algorithms.
-            </para>
-        </refsection>
-        <refsection>
-            <title>Examples</title>
-            <programlisting role="example"><![CDATA[ 
-// example 1 (without parameters)
-// myfun is a function from R^2 to R: (x(1),x(2)) |--> myfun(x)
-function f=myfun(x)
-  f=x(1)*x(1)+x(1)*x(2)
+        <para>using finite difference methods.
+            Uses an order 1 formula.
+        </para>
+        <para>
+            Without parameters, the function <varname>fun</varname> calling sequence is
+            <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
+            <code>g = numdiff(fun, x)</code>. Else the function <varname>fun</varname> calling
+            sequence must be <literal>y = fun(x, param_1, pararm_2, ..., param_q)</literal>.
+            If parameters <literal>param_1, param_2, ..., param_q</literal> exist then
+            <function>numdiff</function> can be called as follow
+            <literal>g = numdiff(list(fun, param_1, param_2, ..., param_q), x)</literal>.
+        </para>
+        <para>
+            See the 
+            <link linkend="derivative">derivative</link> with respect to numerical accuracy 
+            issues and comparison between the two algorithms.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+// Example 1 (without parameters)
+// myfun is a function from R^2 to R: (x(1), x(2)) |--> myfun(x)
+function f = myfun(x)
+  f = x(1)*x(1) + x(1)*x(2)
 endfunction
 
-x=[5 8]
-g=numdiff(myfun,x)
+x = [5 8];
+g = numdiff(myfun, x)
 
-// The exact gradient (i.e derivate belong x(1): first component
-// and derivate belong x(2): second component) is
-exact=[2*x(1)+x(2)  x(1)]
+// The exact gradient (i.e first component = derivate with respect to x(1)
+// and second component = derivate with respect to x(2)) is:
+exact = [2*x(1)+x(2)  x(1)]
 
-//example 2 (with parameters)
-// myfun is a function from R to R: x(1) |--> myfun(x)
-// myfun contains 3 parameters: a, b, c
-function  f=myfun(x,a,b,c)
-  f=(x+a)^c+b
+
+// Example 2 (with parameters)
+// myfun is a function from R to R: x |--> myfun(x)
+// myfun contains 3 parameters: a, b and c
+function  f = myfun(x, a, b, c)
+  f = (x+a)^c + b
 endfunction
 
-a=3; b=4; c=2;
-x=1
-g2=numdiff(list(myfun,a,b,c),x)
+a = 3; b = 4; c = 2;
+x = 1;
+g2 = numdiff(list(myfun, a, b, c), x)
+
+// The exact gradient, i.e derivate with respiect to x, is:
+exact2 = c*(x+a)^(c-1)
+
+
+// Example 3 (f: R^3 --> R^3)
+// 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))
+function f = myfun(x)
+  f(1) = x(1) * x(1);
+  f(2) = x(1) * x(2) * x(3);
+  f(3) = 2*x(1) + 2*x(2) + 2*x(3);
+endfunction
+
+x = [5 8 10];
+g = numdiff(myfun, x)
+
+// The exact gradient is:
+// [  df_1/dx_1  df_1/dx_2  df_1/dx_3 ;
+//    df_2/dx_1  df_2/dx_2  df_2/dx_3 ;
+//    df_3/dx_1  df_3/dx_2  df_3/dx_3 ; ]
+exact3 = [2*x(1) 0 0  ;  x(2)*x(3) x(1)*x(3) x(1)*x(2)  ;  2 2 2]
 
-// The exact gradient, i.e derivate belong x(1), is :
-exact2=c*(x+a)^(c-1)
  ]]></programlisting>
-        </refsection>
-        <refsection role="see also">
-            <title>See Also</title>
-            <simplelist type="inline">
-                <member>
-                    <link linkend="optim">optim</link>
-                </member>
-                <member>
-                    <link linkend="derivative">derivative</link>
-                </member>
-                <member>
-                    <link linkend="external">external</link>
-                </member>
-            </simplelist>
-        </refsection>
-    </refentry>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="interp">interp</link>
+            </member>
+            <member>
+                <link linkend="interp2d">interp2d</link>
+            </member>
+            <member>
+                <link linkend="splin">splin</link>
+            </member>
+            <member>
+                <link linkend="eval_cshep2d">eval_cshep2d</link>
+            </member>
+            <member>
+                <link linkend="optim">optim</link>
+            </member>
+            <member>
+                <link linkend="diff">diff</link>
+            </member>
+            <member>
+                <link linkend="derivative">derivative</link>
+            </member>
+            <member>
+                <link linkend="external">external</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>