scilab/modules/special_functions/help/en_US/bessel.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  * Copyright (C) 2012 - Scilab Enterprises - Adeline CARNIS
   6  *
   7  * This file must be used under the terms of the CeCILL.
   8  * This source file is licensed as described in the file COPYING, which
   9  * you should have received as part of this distribution.  The terms
  10  * are also available at
  11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  12  *
  13  -->
  14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="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" version="5.0-subset Scilab" xml:id="bessel" xml:lang="en">
  15   <refnamediv xml:id="besseli">
  16     <refname>besseli</refname>
  17     <refpurpose>Modified Bessel functions of the first kind (I sub
  18       alpha).
  19     </refpurpose>
  20   </refnamediv>
  21   <refnamediv xml:id="besselj">
  22     <refname>besselj</refname>
  23     <refpurpose>Bessel functions of the first kind (J sub alpha).</refpurpose>
  24   </refnamediv>
  25   <refnamediv xml:id="besselk">
  26     <refname>besselk</refname>
  27     <refpurpose>Modified Bessel functions of the second kind (K sub
  28       alpha).
  29     </refpurpose>
  30   </refnamediv>
  31   <refnamediv xml:id="bessely">
  32     <refname>bessely</refname>
  33     <refpurpose>Bessel functions of the second kind (Y sub
  34       alpha).
  35     </refpurpose>
  36   </refnamediv>
  37   <refnamediv xml:id="besselh">
  38     <refname>besselh</refname>
  39     <refpurpose>Bessel functions of the third kind (aka Hankel
  40       functions)
  41     </refpurpose>
  42   </refnamediv>
  43   <refsynopsisdiv>
  44     <title>Calling Sequence</title>
  45     <synopsis>y = besseli(alpha,x [,ice])
  46       y = besselj(alpha,x [,ice])
  47       y = besselk(alpha,x [,ice])
  48       y = bessely(alpha,x [,ice])
  49       y = besselh(alpha,x)
  50       y = besselh(alpha,K,x [,ice])
  51     </synopsis>
  52   </refsynopsisdiv>
  53   <refsection>
  54     <title>Arguments</title>
  55     <variablelist>
  56       <varlistentry>
  57         <term>x</term>
  58         <listitem>
  59           <para>real or complex vector.</para>
  60         </listitem>
  61       </varlistentry>
  62       <varlistentry>
  63         <term>alpha</term>
  64         <listitem>
  65           <para>real vector</para>
  66         </listitem>
  67       </varlistentry>
  68       <varlistentry>
  69         <term>ice</term>
  70         <listitem>
  71           <para>integer flag, with default value 0</para>
  72         </listitem>
  73       </varlistentry>
  74       <varlistentry>
  75         <term>K</term>
  76         <listitem>
  77           <para>integer, with possible values 1 or 2, the Hankel function
  78             type.
  79           </para>
  80         </listitem>
  81       </varlistentry>
  82     </variablelist>
  83   </refsection>
  84   <refsection>
  85     <title>Description</title>
  86     <itemizedlist>
  87       <listitem>
  88         <para>
  89           <literal>besseli(alpha,x)</literal> computes modified Bessel
  90           functions of the first kind (I sub alpha), for real order
  91           <literal>alpha</literal> and argument <literal>x</literal>.
  92           <literal>besseli(alpha,x,1)</literal> computes
  93           <literal>besseli(alpha,x).*exp(-abs(real(x)))</literal>.
  94         </para>
  95       </listitem>
  96       <listitem>
  97         <para>
  98           <literal>besselj(alpha,x)</literal> computes Bessel functions of
  99           the first kind (J sub alpha), for real order <literal>alpha</literal>
 100           and argument <literal>x</literal>.
 101           <literal>besselj(alpha,x,1)</literal> computes
 102           <literal>besselj(alpha,x).*exp(-abs(imag(x)))</literal>.
 103         </para>
 104       </listitem>
 105       <listitem>
 106         <para>
 107           <literal>besselk(alpha,x)</literal> computes modified Bessel
 108           functions of the second kind (K sub alpha), for real order
 109           <literal>alpha</literal> and argument <literal>x</literal>.
 110           <literal>besselk(alpha,x,1)</literal> computes
 111           <literal>besselk(alpha,x).*exp(x)</literal>.
 112         </para>
 113       </listitem>
 114       <listitem>
 115         <para>
 116           <literal>bessely(alpha,x)</literal> computes Bessel functions of
 117           the second kind (Y sub alpha), for real order <literal>alpha</literal>
 118           and argument <literal>x</literal>.
 119           <literal>bessely(alpha,x,1)</literal> computes
 120           <literal>bessely(alpha,x).*exp(-abs(imag(x)))</literal>.
 121         </para>
 122       </listitem>
 123       <listitem>
 124         <para>
 125           <literal>besselh(alpha [,K] ,x)</literal> computes Bessel
 126           functions of the third kind (Hankel function H1 or H2 depending on
 127           <literal>K</literal>), for real order <literal>alpha</literal> and
 128           argument <literal>x</literal>. If omitted <literal>K</literal> is
 129           supposed to be equal to 1. <literal>besselh(alpha,1,x,1)</literal>
 130           computes <literal>besselh(alpha,1,x).*exp(-%i*x)</literal> and
 131           <literal>besselh(alpha,2,x,1)</literal> computes
 132           <literal>besselh(alpha,2,x).*exp(%i*x)</literal>
 133         </para>
 134       </listitem>
 135     </itemizedlist>
 136   </refsection>
 137   <refsection>
 138     <title>Remarks</title>
 139     <para>
 140       If <literal>alpha</literal> and <literal>x</literal> are arrays of
 141       the same size, the result <literal>y</literal> is also that size. If
 142       either input is a scalar, it is expanded to the other input's size. If one
 143       input is a row vector and the other is a column vector, the
 144       result<literal>y</literal> is a two-dimensional table of function
 145       values.
 146     </para>
 147     <para>Y_alpha and J_alpha Bessel functions are 2 independent solutions of
 148       the Bessel 's differential equation :
 149     </para>
 150     <informalequation>
 151       <mediaobject>
 152         <imageobject>
 153           <imagedata align="center" fileref="../mml/bessel_equation1.mml"/>
 154         </imageobject>
 155       </mediaobject>
 156     </informalequation>
 157     <para>K_alpha and I_alpha modified Bessel functions are 2 independant
 158       solutions of the modified Bessel 's differential equation :
 159     </para>
 160     <informalequation>
 161       <mediaobject>
 162         <imageobject>
 163           <imagedata align="center" fileref="../mml/bessel_equation2.mml"/>
 164         </imageobject>
 165       </mediaobject>
 166     </informalequation>
 167     <para>H^1_alpha and H^2_alpha, the Hankel functions of first and second
 168       kind, are linear linear combinations of Bessel functions of the first and
 169       second kinds:
 170     </para>
 171     <informalequation>
 172       <mediaobject>
 173         <imageobject>
 174           <imagedata align="center" fileref="../mml/bessel_equation3.mml"/>
 175         </imageobject>
 176       </mediaobject>
 177     </informalequation>
 178   </refsection>
 179   <refsection>
 180     <title>Examples</title>
 181     <programlisting role="example"><![CDATA[
 182 //  besselI functions
 183 // ==================
 184    x = linspace(0.01,10,5000)';
 185    clf()
 186    subplot(2,1,1)
 187    plot2d(x,besseli(0:4,x), style=2:6)
 188    legend('I'+string(0:4),2);
 189    xtitle("Some modified Bessel functions of the first kind")
 190    subplot(2,1,2)
 191    plot2d(x,besseli(0:4,x,1), style=2:6)
 192    legend('I'+string(0:4),1);
 193    xtitle("Some modified scaled Bessel functions of the first kind")
 194  ]]></programlisting>
 195
 196 <scilab:image>
 197    x = linspace(0.01,10,5000)';
 198    clf()
 199    subplot(2,1,1)
 200    plot2d(x,besseli(0:4,x), style=2:6)
 201    legend('I'+string(0:4),2);
 202    xtitle("Some modified Bessel functions of the first kind")
 203    subplot(2,1,2)
 204    plot2d(x,besseli(0:4,x,1), style=2:6)
 205    legend('I'+string(0:4),1);
 206    xtitle("Some modified scaled Bessel functions of the first kind")
 207
 208 </scilab:image>
 209
 210
 211     <programlisting role="example"><![CDATA[
 212 // besselJ functions
 213 // =================
 214    clf()
 215    x = linspace(0,40,5000)';
 216    plot2d(x,besselj(0:4,x), style=2:6, leg="J0@J1@J2@J3@J4")
 217    legend('I'+string(0:4),1);
 218    xtitle("Some Bessel functions of the first kind")
 219  ]]></programlisting>
 220
 221 <scilab:image>
 222    x = linspace(0,40,5000)';
 223    plot2d(x,besselj(0:4,x), style=2:6, leg="J0@J1@J2@J3@J4")
 224    legend('I'+string(0:4),1);
 225    xtitle("Some Bessel functions of the first kind")
 226 </scilab:image>
 227
 228     <programlisting role="example"><![CDATA[
 229 // use the fact that J_(1/2)(x) = sqrt(2/(x pi)) sin(x)
 230 // to compare the algorithm of besselj(0.5,x) with a more direct formula
 231    x = linspace(0.1,40,5000)';
 232    y1 = besselj(0.5, x);
 233    y2 = sqrt(2 ./(%pi*x)).*sin(x);
 234    er = abs((y1-y2)./y2);
 235    ind = find(er > 0 & y2 ~= 0);
 236    clf()
 237    subplot(2,1,1)
 238    plot2d(x,y1,style=2)
 239    xtitle("besselj(0.5,x)")
 240    subplot(2,1,2)
 241    plot2d(x(ind), er(ind), style=2, logflag="nl")
 242    xtitle("relative error between 2 formulae for besselj(0.5,x)")
 243  ]]></programlisting>
 244
 245 <scilab:image><![CDATA[
 246    x = linspace(0.1,40,5000)';
 247    y1 = besselj(0.5, x);
 248    y2 = sqrt(2 ./(%pi*x)).*sin(x);
 249    er = abs((y1-y2)./y2);
 250    ind = find(er > 0 & y2 ~= 0);
 251    clf()
 252    subplot(2,1,1)
 253    plot2d(x,y1,style=2)
 254    xtitle("besselj(0.5,x)")
 255    subplot(2,1,2)
 256    plot2d(x(ind), er(ind), style=2, logflag="nl")
 257    xtitle("relative error between 2 formulae for besselj(0.5,x)")
 258  ]]></scilab:image>
 259
 260     <programlisting role="example"><![CDATA[
 261 // besselK functions
 262 // =================
 263    x = linspace(0.01,10,5000)';
 264    clf()
 265    subplot(2,1,1)
 266    plot2d(x,besselk(0:4,x), style=0:4, rect=[0,0,6,10])
 267    legend('K'+string(0:4),1);
 268    xtitle("Some modified Bessel functions of the second kind")
 269    subplot(2,1,2)
 270    plot2d(x,besselk(0:4,x,1), style=0:4, rect=[0,0,6,10])
 271    legend('K'+string(0:4),1);
 272    xtitle("Some modified scaled Bessel functions of the second kind")
 273  ]]></programlisting>
 274
 275 <scilab:image>
 276    x = linspace(0.01,10,5000)';
 277    clf()
 278    subplot(2,1,1)
 279    plot2d(x,besselk(0:4,x), style=0:4, rect=[0,0,6,10])
 280    legend('K'+string(0:4),1);
 281    xtitle("Some modified Bessel functions of the second kind")
 282    subplot(2,1,2)
 283    plot2d(x,besselk(0:4,x,1), style=0:4, rect=[0,0,6,10])
 284    legend('K'+string(0:4),1);
 285    xtitle("Some modified scaled Bessel functions of the second kind")
 286 </scilab:image>
 287
 288     <programlisting role="example"><![CDATA[
 289 // besselY functions
 290 // =================
 291    x = linspace(0.1,40,5000)'; // Y Bessel functions are unbounded  for x -> 0+
 292    clf()
 293    plot2d(x,bessely(0:4,x), style=0:4, rect=[0,-1.5,40,0.6])
 294    legend('Y'+string(0:4),4);
 295    xtitle("Some Bessel functions of the second kind")
 296  ]]></programlisting>
 297
 298 <scilab:image>
 299    x = linspace(0.1,40,5000)'; // Y Bessel functions are unbounded  for x -> 0+
 300    clf()
 301    plot2d(x,bessely(0:4,x), style=0:4, rect=[0,-1.5,40,0.6])
 302    legend('Y'+string(0:4),4);
 303    xtitle("Some Bessel functions of the second kind")
 304 </scilab:image>
 305
 306     <programlisting role="example"><![CDATA[
 307 // besselH functions
 308 // =================
 309    x=-4:0.025:2; y=-1.5:0.025:1.5;
 310    [X,Y] = ndgrid(x,y);
 311    H = besselh(0,1,X+%i*Y);
 312    clf();f=gcf();
 313    xset("fpf"," ")
 314    f.color_map=jetcolormap(16);
 315    contour2d(x,y,abs(H),0.2:0.2:3.2,strf="034",rect=[-4,-1.5,3,1.5])
 316    legends(string(0.2:0.2:3.2),1:16,"ur")
 317    xtitle("Level curves of |H1(0,z)|")
 318  ]]></programlisting>
 319
 320 <scilab:image>
 321    x=-4:0.025:2; y=-1.5:0.025:1.5;
 322    [X,Y] = ndgrid(x,y);
 323    H = besselh(0,1,X+%i*Y);
 324    clf();f=gcf();
 325    xset("fpf"," ")
 326    f.color_map=jetcolormap(16);
 327    contour2d(x,y,abs(H),0.2:0.2:3.2,strf="034",rect=[-4,-1.5,3,1.5])
 328    legends(string(0.2:0.2:3.2),1:16,"ur")
 329    xtitle("Level curves of |H1(0,z)|")
 330 </scilab:image>
 331
 332   </refsection>
 333   <refsection>
 334     <title>Used Functions</title>
 335     <para>The source codes can be found in SCI/modules/special_functions/src/fortran/slatec and
 336       SCI/modules/special_functions/src/fortran
 337     </para>
 338     <para>Slatec : dbesi.f, zbesi.f, dbesj.f, zbesj.f, dbesk.f, zbesk.f,
 339       dbesy.f, zbesy.f, zbesh.f
 340     </para>
 341     <para>Drivers to extend definition area (Serge Steer INRIA): dbesig.f,
 342       zbesig.f, dbesjg.f, zbesjg.f, dbeskg.f, zbeskg.f, dbesyg.f, zbesyg.f,
 343       zbeshg.f
 344     </para>
 345   </refsection>
 346 </refentry>