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 at one point</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                         f: R<superscript>n</superscript> --> R<superscript>p</superscript>
  32                     </para>
  33                 </listitem>
  34             </varlistentry>
  35             <varlistentry>
  36                 <term>x</term>
  37                 <listitem>
  38                     <para>
  39                         a vector of the <code>n</code> coordinates of the single point at which the gradient is sought.
  40                     </para>
  41                 </listitem>
  42             </varlistentry>
  43             <varlistentry>
  44                 <term>dx</term>
  45                 <listitem>
  46                     <para>a vector, the finite difference step. Default value is
  47                         <code>dx = sqrt(%eps)*(1+1d-3*abs(x))</code>.
  48                     </para>
  49                 </listitem>
  50             </varlistentry>
  51             <varlistentry>
  52                 <term>g</term>
  53                 <listitem>
  54                     <para>
  55                         a matrix, the estimated gradient at the locus <varname>x</varname>.
  56                     </para>
  57                 </listitem>
  58             </varlistentry>
  59         </variablelist>
  60     </refsection>
  61     <refsection>
  62         <title>Description</title>
  63         <para>
  64             Given a function <code>fun(x)</code> from
  65             R<superscript>n</superscript> to R<superscript>p</superscript> computes the <code>p x n</code> matrix
  66             <varname>g</varname> such that
  67         </para>
  68         <programlisting role="no-scilab-exec"><![CDATA[
  69 g(i,j) = [(df_i)/(dx_j)](x)
  70  ]]></programlisting>
  71         <para>using finite difference methods.
  72             Uses an order 1 formula.
  73         </para>
  74         <para>
  75             Without parameters, the function <varname>fun</varname> calling sequence is
  76             <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
  77             <code>g = numdiff(fun, x)</code>. Else the function <varname>fun</varname> calling
  78             sequence must be <literal>y = fun(x, param_1, pararm_2, ..., param_q)</literal>.
  79             If parameters <literal>param_1, param_2, ..., param_q</literal> exist then
  80             <function>numdiff</function> can be called as follow
  81             <literal>g = numdiff(list(fun, param_1, param_2, ..., param_q), x)</literal>.
  82         </para>
  83         <para>
  84             See the
  85             <link linkend="derivative">derivative</link> with respect to numerical accuracy
  86             issues and comparison between the two algorithms.
  87         </para>
  88     </refsection>
  89     <refsection>
  90         <title>Examples</title>
  91         <programlisting role="example"><![CDATA[
  92 // Example 1 (without parameters)
  93 // myfun is a function from R^2 to R: (x(1), x(2)) |--> myfun(x)
  94 function f = myfun(x)
  95   f = x(1)*x(1) + x(1)*x(2)
  96 endfunction
  97
  98 x = [5 8];
  99 g = numdiff(myfun, x)
 100
 101 // The exact gradient (i.e first component = derivate with respect to x(1)
 102 // and second component = derivate with respect to x(2)) is:
 103 exact = [2*x(1)+x(2)  x(1)]
 104
 105
 106 // Example 2 (with parameters)
 107 // myfun is a function from R to R: x |--> myfun(x)
 108 // myfun contains 3 parameters: a, b and c
 109 function  f = myfun(x, a, b, c)
 110   f = (x+a)^c + b
 111 endfunction
 112
 113 a = 3; b = 4; c = 2;
 114 x = 1;
 115 g2 = numdiff(list(myfun, a, b, c), x)
 116
 117 // The exact gradient, i.e derivate with respiect to x, is:
 118 exact2 = c*(x+a)^(c-1)
 119
 120
 121 // Example 3 (f: R^3 --> R^3)
 122 // 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))
 123 function f = myfun(x)
 124   f(1) = x(1) * x(1);
 125   f(2) = x(1) * x(2) * x(3);
 126   f(3) = 2*x(1) + 2*x(2) + 2*x(3);
 127 endfunction
 128
 129 x = [5 8 10];
 130 g = numdiff(myfun, x)
 131
 132 // The exact gradient is:
 133 // [  df_1/dx_1  df_1/dx_2  df_1/dx_3 ;
 134 //    df_2/dx_1  df_2/dx_2  df_2/dx_3 ;
 135 //    df_3/dx_1  df_3/dx_2  df_3/dx_3 ; ]
 136 exact3 = [2*x(1) 0 0  ;  x(2)*x(3) x(1)*x(3) x(1)*x(2)  ;  2 2 2]
 137
 138  ]]></programlisting>
 139     </refsection>
 140     <refsection role="see also">
 141         <title>See Also</title>
 142         <simplelist type="inline">
 143             <member>
 144                 <link linkend="interp">interp</link>
 145             </member>
 146             <member>
 147                 <link linkend="interp2d">interp2d</link>
 148             </member>
 149             <member>
 150                 <link linkend="splin">splin</link>
 151             </member>
 152             <member>
 153                 <link linkend="eval_cshep2d">eval_cshep2d</link>
 154             </member>
 155             <member>
 156                 <link linkend="optim">optim</link>
 157             </member>
 158             <member>
 159                 <link linkend="diff">diff</link>
 160             </member>
 161             <member>
 162                 <link linkend="derivative">derivative</link>
 163             </member>
 164             <member>
 165                 <link linkend="external">external</link>
 166             </member>
 167         </simplelist>
 168     </refsection>
 169 </refentry>