02f7583d2d3f8d9ab0ebeda8a309cee0055668ed
[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  *
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>