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