Added a more obvious message for numdiff and derivative obsolescence
[scilab.git] / scilab / modules / differential_equations / help / en_US / numdiff.xml
index f3c2124..6dab72e 100644 (file)
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2008 - INRIA
- * 
- * This file must be used under the terms of the CeCILL.
- * This source file is licensed as described in the file COPYING, which
- * you should have received as part of this distribution.  The terms
- * are also available at    
- * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
- *
- -->
+* Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+* Copyright (C) 2008 - INRIA
+* 
+* This file must be used under the terms of the CeCILL.
+* This source file is licensed as described in the file COPYING, which
+* you should have received as part of this distribution.  The terms
+* are also available at    
+* http://www.cecill.info/licences/Licence_CeCILL_V2.1-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 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>, 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
+   <refnamediv>
+      <refname>numdiff</refname>
+      <refpurpose>numerical gradient estimation at one point. <emphasis role="bold"> This function is obsolete. Please use the <link linkend="numderivative">numderivative</link> function instead.</emphasis></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>, 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 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)]
+         // 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 |--> myfun(x)
-// myfun contains 3 parameters: a, b and c
-function  f = myfun(x, a, b, c)
-  f = (x+a)^c + b
-endfunction
+         // 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)
+         // 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
+         // 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)
+         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 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]
+
+         ]]>
+      </programlisting>
+   </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="numderivative">numderivative</link>
+         </member>
+         <member>
+            <link linkend="external">external</link>
+         </member>
+      </simplelist>
+   </refsection>
+   <refsection>
+      <title>History</title>
+      <revhistory>
+         <revision>
+            <revnumber>5.5.0</revnumber>
+            <revremark>Tagged as obsolete. Will be removed in Scilab 6.0.0.</revremark>
+         </revision>
+      </revhistory>
+   </refsection>
+   <refsection>
+      <title>Appendix</title>
+      <para>
+         We now discuss how a script using the <literal>numdiff</literal> function can be
+         updated to use the <literal>numderivative</literal> function.
+      </para>
+      <para>
+         Consider the function:
+      </para>
+      <programlisting role="example">
+         <![CDATA[
+         function f = myfun(x)
+         f = x(1)*x(1)+x(1)*x(2)
+         endfunction
+         ]]>
+      </programlisting>
+      <para>
+         and the point:
+      </para>
+      <programlisting role="example">
+         <![CDATA[
+         x = [5 8]
+         ]]>
+      </programlisting>
+      <para>
+         Therefore, the statement:
+      </para>
+      <programlisting role="example">
+         <![CDATA[
+         g1 = numdiff(myfun, x)
+         ]]>
+      </programlisting>
+      <para>
+         can be replaced with
+      </para>
+      <programlisting role="example">
+         <![CDATA[
+         g2 = numderivative(myfun, x)
+         ]]>
+      </programlisting>
+      <para>
+         If having exactly the same step is important, we force the step to the same value as in
+         <literal>numdiff</literal>:
+      </para>
+      <programlisting role="example">
+         <![CDATA[
+         x = [5 8];
+         h = sqrt(%eps)*(1+1d-3*abs(x))
+         g1 = numdiff(myfun, x)
+         g2 = numderivative(myfun, x, h)
+         g1 == g2
+         ]]>
+      </programlisting>
+   </refsection>
 
- ]]>
-        </programlisting>
-    </refsection>
-    <refsection>
-        <title>History</title>
-        <para>
-            Starting from Scilab 5.5.0, the <literal>numdiff</literal> function is
-            obsolete. It will be removed in Scilab 6.0.0.
-            Please use the <literal>numderivative</literal> function instead.
-        </para>
-        <para>
-            We now discuss how a script using the <literal>numdiff</literal> function can be
-            updated to use the <literal>numderivative</literal> function.
-        </para>
-        <para>
-            Consider the function:
-        </para>
-        <programlisting role="example">
-            <![CDATA[
-function f = myfun(x)
-  f = x(1)*x(1)+x(1)*x(2)
-endfunction
-]]>
-        </programlisting>
-        <para>
-            and the point:
-        </para>
-        <programlisting role="example">
-            <![CDATA[
-x = [5 8]
-]]>
-        </programlisting>
-        <para>
-            Therefore, the statement:
-        </para>
-        <programlisting role="example">
-            <![CDATA[
-g1 = numdiff(myfun, x)
-]]>
-        </programlisting>
-        <para>
-            can be replaced with
-        </para>
-        <programlisting role="example">
-            <![CDATA[
-g2 = numderivative(myfun, x)
-]]>
-        </programlisting>
-        <para>
-            If having exactly the same step is important, we force the step to the same value as in
-            <literal>numdiff</literal>:
-        </para>
-        <programlisting role="example">
-            <![CDATA[
-x = [5 8];
-h = sqrt(%eps)*(1+1d-3*abs(x))
-g1 = numdiff(myfun, x)
-g2 = numderivative(myfun, x, h)
-g1 == g2
-]]>
-        </programlisting>
-    </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="numderivative">numderivative</link>
-            </member>
-            <member>
-                <link linkend="external">external</link>
-            </member>
-        </simplelist>
-    </refsection>
 </refentry>