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