[doc] bessel page: hardly readable MML equations => LaTeX
[scilab.git] / 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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2019 - Samuel GOUGEON
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"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org"  xml:id="bessel" xml:lang="en">
21     <refnamediv xml:id="besseli">
22         <refname>besseli</refname>
23         <refpurpose>Modified Bessel functions of the first kind (I sub
24             alpha).
25         </refpurpose>
26     </refnamediv>
27     <refnamediv xml:id="besselj">
28         <refname>besselj</refname>
29       <refpurpose>Bessel functions of the first kind (J<subscript>α</subscript>).</refpurpose>
30     </refnamediv>
31     <refnamediv xml:id="besselk">
32         <refname>besselk</refname>
33         <refpurpose>Modified Bessel functions of the second kind (K<subscript>α</subscript>).
34         </refpurpose>
35     </refnamediv>
36     <refnamediv xml:id="bessely">
37         <refname>bessely</refname>
38         <refpurpose>Bessel functions of the second kind (Y<subscript>α</subscript>).
39         </refpurpose>
40     </refnamediv>
41     <refnamediv xml:id="besselh">
42         <refname>besselh</refname>
43         <refpurpose>Bessel functions of the third kind (aka Hankel functions)
44         </refpurpose>
45     </refnamediv>
46     <refsynopsisdiv>
47         <title>Syntax</title>
48         <synopsis>
49             y = besseli(alpha, x [,ice])
50             y = besselj(alpha, x [,ice])
51             y = besselk(alpha, x [,ice])
52             y = bessely(alpha, x [,ice])
53             y = besselh(alpha, x)
54             y = besselh(alpha, K, x [,ice])
55         </synopsis>
56     </refsynopsisdiv>
57     <refsection>
58         <title>Arguments</title>
59         <variablelist>
60             <varlistentry>
61                 <term>x</term>
62                 <listitem>
63                     <para>real or complex vector.</para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>alpha</term>
68                 <listitem>
69                     <para>real vector</para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>ice</term>
74                 <listitem>
75                     <para>integer flag, with default value 0</para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>K</term>
80                 <listitem>
81                     <para>integer, with possible values 1 or 2, the Hankel function 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<subscript>α</subscript>), for real order
94                     <varname>alpha</varname> and argument <varname>x</varname>.
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 the fisrt
102                     kind (J<subscript>α</subscript>), for real order <varname>alpha</varname>
103                     and argument <varname>x</varname>.
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<subscript>α</subscript>), for real order
112                     <varname>alpha</varname> and argument <varname>x</varname>.
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 the second
120                     kind (Y<subscript>alpha</subscript>), for real order <varname>alpha</varname>
121                     and argument <varname>x</varname>.
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 <varname>alpha</varname> and
131                     argument <varname>x</varname>. 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 <varname>alpha</varname> and <varname>x</varname> 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>
151             Y<subscript>α</subscript> and J<subscript>α</subscript> Bessel functions are 2
152             independent solutions of the Bessel 's differential equation :
153         </para>
154         <latex style="display" alt="x^2.(d^2y/d^2x) + x.dy/dx + (x^2 - alpha^2).y = 0,  alpha ≥ 0">
155             {x^2} \cdot {{d^2 y} \over {dx^2}} + x \cdot {{dy} \over {dx}} + (x^2 - \alpha^2) \cdot y = 0,
156             \quad\alpha\ge0
157         </latex>
158         <para>
159             K<subscript>α</subscript> and I<subscript>α</subscript> modified Bessel functions
160             are 2 independent solutions of the modified Bessel 's differential equation :
161         </para>
162         <latex style="display" alt="x^2.(d^2y/d^2x) + x.dy/dx + (alpha^2 - x^2).y = 0,  alpha ≥ 0">
163             {x^2} \cdot {{d^2 y} \over {dx^2}} + x \cdot {{dy} \over {dx}} + (\alpha^2 - x^2) \cdot y = 0,
164             \quad\alpha\ge0
165         </latex>
166         <para>
167             H<subscript>α</subscript><superscript>1</superscript> and
168             H<subscript>α</subscript><superscript>2</superscript>, the Hankel functions of first
169             and second kind, are linear linear combinations of Bessel functions of the first and
170             second kinds:
171         </para>
172         <latex style="display" alt="H^1_α(z) = J_α(z) + i \cdot Y_α(z)  \n
173 H^2_α(z) = J_α(z) - i \cdot Y_α(z)">
174             H^1_{\alpha}(z) = J_{\alpha}(z) + i \cdot Y_{\alpha}(z) \\
175             H^2_{\alpha}(z) = J_{\alpha}(z) - i \cdot Y_{\alpha}(z)
176         </latex>
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         <scilab:image>
195             x = linspace(0.01,10,5000)';
196             clf()
197             subplot(2,1,1)
198             plot2d(x,besseli(0:4,x), style=2:6)
199             legend('I'+string(0:4),2);
200             xtitle("Some modified Bessel functions of the first kind")
201             subplot(2,1,2)
202             plot2d(x,besseli(0:4,x,1), style=2:6)
203             legend('I'+string(0:4),1);
204             xtitle("Some modified scaled Bessel functions of the first kind")
205         </scilab:image>
206         <para/>
207         <programlisting role="example"><![CDATA[
208     // besselJ functions
209     // -----------------
210     clf
211     x = linspace(0,40,5000)';
212     plot2d(x,besselj(0:4,x), style=2:6, leg="J0@J1@J2@J3@J4")
213     legend('I'+string(0:4),1);
214     xtitle("Some Bessel functions of the first kind")
215  ]]></programlisting>
216
217         <scilab:image>
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         </scilab:image>
223         <para/>
224         <programlisting role="example"><![CDATA[
225 // use the fact that J_(1/2)(x) = sqrt(2/(x pi)) sin(x)
226 // to compare the algorithm of besselj(0.5,x) with a more direct formula
227    x = linspace(0.1,40,5000)';
228    y1 = besselj(0.5, x);
229    y2 = sqrt(2 ./(%pi*x)).*sin(x);
230    er = abs((y1-y2)./y2);
231    ind = find(er > 0 & y2 ~= 0);
232    clf()
233    subplot(2,1,1)
234    plot2d(x,y1,style=2)
235    xtitle("besselj(0.5,x)")
236    subplot(2,1,2)
237    plot2d(x(ind), er(ind), style=2, logflag="nl")
238    xtitle("relative error between 2 formulae for besselj(0.5,x)")
239  ]]></programlisting>
240         <scilab:image><![CDATA[
241    x = linspace(0.1,40,5000)';
242    y1 = besselj(0.5, x);
243    y2 = sqrt(2 ./(%pi*x)).*sin(x);
244    er = abs((y1-y2)./y2);
245    ind = find(er > 0 & y2 ~= 0);
246    clf()
247    subplot(2,1,1)
248    plot2d(x,y1,style=2)
249    xtitle("besselj(0.5,x)")
250    subplot(2,1,2)
251    plot2d(x(ind), er(ind), style=2, logflag="nl")
252    xtitle("relative error between 2 formulae for besselj(0.5,x)")
253  ]]></scilab:image>
254
255         <para/>
256         <programlisting role="example"><![CDATA[
257 // besselK functions
258 // =================
259    x = linspace(0.01,10,5000)';
260    clf()
261    subplot(2,1,1)
262    plot2d(x,besselk(0:4,x), style=0:4, rect=[0,0,6,10])
263    legend('K'+string(0:4),1);
264    xtitle("Some modified Bessel functions of the second kind")
265    subplot(2,1,2)
266    plot2d(x,besselk(0:4,x,1), style=0:4, rect=[0,0,6,10])
267    legend('K'+string(0:4),1);
268    xtitle("Some modified scaled Bessel functions of the second kind")
269  ]]></programlisting>
270         <scilab:image>
271             x = linspace(0.01,10,5000)';
272             clf()
273             subplot(2,1,1)
274             plot2d(x,besselk(0:4,x), style=0:4, rect=[0,0,6,10])
275             legend('K'+string(0:4),1);
276             xtitle("Some modified Bessel functions of the second kind")
277             subplot(2,1,2)
278             plot2d(x,besselk(0:4,x,1), style=0:4, rect=[0,0,6,10])
279             legend('K'+string(0:4),1);
280             xtitle("Some modified scaled Bessel functions of the second kind")
281         </scilab:image>
282
283         <para/>
284         <programlisting role="example"><![CDATA[
285 // besselY functions
286 // =================
287    x = linspace(0.1,40,5000)'; // Y Bessel functions are unbounded  for x -> 0+
288    clf()
289    plot2d(x,bessely(0:4,x), style=0:4, rect=[0,-1.5,40,0.6])
290    legend('Y'+string(0:4),4);
291    xtitle("Some Bessel functions of the second kind")
292  ]]></programlisting>
293         <scilab:image>
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         </scilab:image>
300
301         <para/>
302         <programlisting role="example"><![CDATA[
303 // besselH functions
304 // =================
305    x=-4:0.025:2; y=-1.5:0.025:1.5;
306    [X,Y] = ndgrid(x,y);
307    H = besselh(0,1,X+%i*Y);
308    clf();f=gcf();
309    xset("fpf"," ")
310    f.color_map=jetcolormap(16);
311    contour2d(x,y,abs(H),0.2:0.2:3.2,strf="034",rect=[-4,-1.5,3,1.5])
312    legends(string(0.2:0.2:3.2),1:16,"ur")
313    xtitle("Level curves of |H1(0,z)|")
314  ]]></programlisting>
315         <scilab:image>
316             x=-4:0.025:2; y=-1.5:0.025:1.5;
317             [X,Y] = ndgrid(x,y);
318             H = besselh(0,1,X+%i*Y);
319             clf();f=gcf();
320             xset("fpf"," ")
321             f.color_map=jetcolormap(16);
322             contour2d(x,y,abs(H),0.2:0.2:3.2,strf="034",rect=[-4,-1.5,3,1.5])
323             legends(string(0.2:0.2:3.2),1:16,"ur")
324             xtitle("Level curves of |H1(0,z)|")
325         </scilab:image>
326     </refsection>
327     <refsection>
328         <title>Used Functions</title>
329         <para>The source codes can be found in SCI/modules/special_functions/src/fortran/slatec and
330             SCI/modules/special_functions/src/fortran
331         </para>
332         <para>Slatec : dbesi.f, zbesi.f, dbesj.f, zbesj.f, dbesk.f, zbesk.f,
333             dbesy.f, zbesy.f, zbesh.f
334         </para>
335         <para>Drivers to extend definition area (Serge Steer INRIA): dbesig.f,
336             zbesig.f, dbesjg.f, zbesjg.f, dbeskg.f, zbeskg.f, dbesyg.f, zbesyg.f,
337             zbeshg.f
338         </para>
339     </refsection>
340 </refentry>