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>vector, the argument of the function
  38                         <literal>fun</literal>
  39                     </para>
  40                 </listitem>
  41             </varlistentry>
  42             <varlistentry>
  43                 <term>dx</term>
  44                 <listitem>
  45                     <para>vector, the finite difference step. Default value is
  46                         <literal>dx=sqrt(%eps)*(1+1d-3*abs(x))</literal>
  47                     </para>
  48                 </listitem>
  49             </varlistentry>
  50             <varlistentry>
  51                 <term>g</term>
  52                 <listitem>
  53                     <para>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 <literal>fun(x)</literal> from
  62             <literal>R^n</literal> to <literal>R^p</literal> computes the matrix
  63             <literal>g</literal> such as
  64         </para>
  65         <programlisting role=""><![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 fun calling sequence is
  73             <literal>y=fun(x)</literal>, and numdiff can be called as
  74             <literal>g=numdiff(fun,x)</literal>. Else the function fun 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             <literal>numdiff</literal> 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 and derivate belong x(2): second component) is
  99 exact=[2*x(1)+x(2)  x(1)]
 100
 101 //example 2 (with parameters)
 102 // myfun is a function from R to R:  x(1) |--> myfun(x)
 103 // myfun contains 3 parameters, a, b, c
 104 function  f=myfun(x,a,b,c)
 105   f=(x+a)^c+b
 106 endfunction
 107
 108 a=3; b=4; c=2;
 109 x=1
 110 g2=numdiff(list(myfun,a,b,c),x)
 111
 112 // The exact gradient, i.e derivate belong x(1), is :
 113 exact2=c*(x+a)^(c-1)
 114  ]]></programlisting>
 115     </refsection>
 116     <refsection role="see also">
 117         <title>See Also</title>
 118         <simplelist type="inline">
 119             <member>
 120                 <link linkend="optim">optim</link>
 121             </member>
 122             <member>
 123                 <link linkend="derivative">derivative</link>
 124             </member>
 125             <member>
 126                 <link linkend="external">external</link>
 127             </member>
 128         </simplelist>
 129     </refsection>
 130 </refentry>