9697be51955d74b985a9c114e4019ff7e98d0417
[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  * 
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>