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>