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