* Bug 16234 fixed [special_functions]: airy() added
[scilab.git] / scilab / modules / special_functions / help / en_US / airy.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) 2019 - Samuel GOUGEON - Le Mans Université
5  *
6  * This file is hereby licensed under the terms of the GNU GPL v2.0,
7  * pursuant to article 5.3.4 of the CeCILL v.2.1.
8  * This file was originally licensed under the terms of the CeCILL v2.1,
9  * and continues to be available under such terms.
10  * For more information, see the COPYING file which you should have received
11  * along with this program.
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
15         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
16         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
17         xml:lang="en" xml:id="airy">
18     <refnamediv>
19         <refname>airy</refname>
20         <refpurpose>
21             Airy functions of the first and second kind, and their derivatives
22         </refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             a = airy(z)
28             a = airy(fun, z)
29             a = airy(fun, z, scaled)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>z</term>
37                 <listitem>
38                     array of decimal or complex numbers of any size, from scalr to hypermatrix.
39                 </listitem>
40                 <para/>
41             </varlistentry>
42             <varlistentry>
43                 <term>fun</term>
44                 <listitem>
45                     Selected Airy function to evaluate. It can be either a string among
46                     "Ai" "dAi" "Bi" "dBi", or an equivalent integer in [0, 3] (for compatibility
47                     with Octave and Julia)
48                     <table>
49                         <tr><td colspan="2" align="center"><emphasis role="bold">fun</emphasis></td>
50                             <td><emphasis role="bold">Description</emphasis></td></tr>
51                         <tr><td>0</td><td>"Ai"</td><td>Airy function of the first kind (default)</td></tr>
52                         <tr><td>1</td><td>"dAi"</td><td>Derivative Ai' of Ai</td></tr>
53                         <tr><td>2</td><td>"Bi"</td><td>Airy function of the second kind</td></tr>
54                         <tr><td>3</td><td>"dBi"</td><td>Derivative Bi' of Bi</td></tr>
55                     </table>
56                     <para/>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>scaled</term>
61                 <listitem>
62                     Single boolean or integer 0|1. Default %F. When <varname>scaled</varname> is
63                     %T or set to 1, the raw result is scaled by the following factors before
64                     being returned:
65                     <table>
66                         <tr style="white-space:nowrap"><td valign="bottom">Ai, dAi : </td>
67                             <td valign="top"><latex fontsize="15" alt="exp(z^1.5 * 2/3)">
68                                     exp\left(2\,z^{3/2}/ 3\right)
69                                 </latex>
70                             </td>
71                             <td>      </td>
72                             <td valign="bottom">Bi, dBi : </td>
73                             <td valign="top"><latex fontsize="15" alt="exp(-|real(z^1.5)| * 2/3)">
74                                     exp\left(-2\left|{\mathrm Re}\!\left(z^{3/2}\right)\right|/ 3\right)
75                                 </latex>
76                             </td>
77                         </tr>
78                     </table>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82     </refsection>
83     <refsection>
84         <title>Description</title>
85         <para>
86             For a real <emphasis>x</emphasis> variable, the Airy functions of the first and
87             second kind -- respectively Ai(x) and Bi(x) -- are independent real solutions
88             <emphasis>y(x)</emphasis> of the Airy differential equation
89             <emphasis>y'' = x.y</emphasis>. They are defined as the convergent integrals
90             <latex style="display" alt="Ai(x) = 1/π \int_0^∞ cos(t^3/3 + xt) dt">
91                 Ai(x) = {1 \over \pi} \int_0^\infty cos\left({t^3 \over 3} + xt\right)dt
92             </latex>
93             and
94             <latex style="display" alt="Bi(x) = 1/π \int_0^∞ [sin(t^3/3 + xt) + exp(-t^3/3 + xt)] dt">
95                 Bi(x) = {1 \over \pi} \int_0^\infty
96                 \left[ sin\left({t^3 \over 3} + xt\right) + exp\left(- {t^3 \over 3} + xt\right)\right] dt
97             </latex>
98         </para>
99         <para>
100             These definitions can be extended to the complex plane, for any <emphasis>z</emphasis>
101             complex variable, as
102             <latex style="display" fontsize="20" alt="Ai(z) = 1/2π \int_R exp(i(t^3/3 + zt)) dt">
103                 Ai(z) = {1 \over 2\pi} \int_{-\infty}^\infty e^{i\left({t^3 \over 3} + zt\right)}dt
104             </latex>
105         </para>
106         <para>
107             Let us note the properties
108             <latex style="display" alt="Ai(z´)=Ai(z)´  Bi(z´)=Bi(z)´ with z´ the complex conjugate.">
109                 Ai(\overline z) = \overline{Ai(z)} \quad Bi(\overline z) = \overline{Bi(z)} \quad
110                 Ai'(\overline z) = \overline{Ai'(z)} \quad Bi'(\overline z) = \overline{Bi'(z)}
111             </latex>
112         </para>
113         <para>
114             In Scilab, Ai, Bi, and their first derivative are computed through Bessel and gamma
115             functions.
116         </para>
117     </refsection>
118     <refsection>
119         <title>Examples</title>
120         <para>
121             With real numbers
122         </para>
123         <programlisting role="example"><![CDATA[
124 x = -10:0.05:3;
125 clf
126 drawlater
127
128 subplot(2,1,1)  // Ai, Bi
129 plot(x, airy(x), "b", x, airy(2,x), "r")
130 gca().margins(4) = 0.08;
131 gca().data_bounds(3:4) = [-0.5 1.25];
132 gca().tight_limits = "on";
133 xgrid(color("grey60"),1,7)
134 legend(["Ai(x)" "Bi(x)"],"in_upper_left")
135 title("Airy functions", "fontsize", 3)
136
137 subplot(2,1,2)  // Derivatives
138 plot(x, airy(1, x), "b", x, airy(3,x), "r")
139 legend(["Ai''(x)" "Bi''(x)"],"in_upper_left")
140 xlabel("x", "fontsize", 3)
141 gca().margins(3) = 0.08;
142 gca().x_location = "top";
143 gca().x_ticks.labels = emptystr(gca().x_ticks.labels);
144 gca().data_bounds(3:4) = [-1 2.5];
145 gca().tight_limits = "on";
146 xgrid(color("grey60"),1,7)
147
148 drawnow
149       ]]></programlisting>
150         <scilab:image><![CDATA[
151 x = -10:0.05:3;
152 clf
153 drawlater
154
155 subplot(2,1,1)  // Ai, Bi
156 plot(x, airy(x), "b", x, airy(2,x), "r")
157 gca().margins(4) = 0.08;
158 gca().data_bounds(3:4) = [-0.5 1.25];
159 gca().tight_limits = "on";
160 xgrid(color("grey60"),1,7)
161 legend(["Ai(x)" "Bi(x)"],"in_upper_left")
162 title("Airy functions", "fontsize", 3)
163
164 subplot(2,1,2)  // Derivatives
165 plot(x, airy(1, x), "b", x, airy(3,x), "r")
166 legend(["Ai''(x)" "Bi''(x)"],"in_upper_left")
167 xlabel("x", "fontsize", 3)
168 gca().margins(3) = 0.08;
169 gca().x_location = "top";
170 gca().x_ticks.labels = emptystr(gca().x_ticks.labels);
171 gca().data_bounds(3:4) = [-1 2.5];
172 gca().tight_limits = "on";
173 xgrid(color("grey60"),1,7)
174
175 drawnow
176         ]]></scilab:image>
177         <para/>
178         <para>
179             With scaling
180         </para>
181         <programlisting role="example"><![CDATA[
182 x = -10:0.05:3;
183 clf
184 drawlater
185
186 subplot(2,1,1)  // Ai, Ai scaled
187 plot(x, airy("Ai",x), x, airy("Ai",x, %t), "color", ["blue" "cyan"])
188 gca().margins(4) = 0.08;
189 gca().data_bounds(3:4) = [-0.5 1];
190 gca().tight_limits = "on";
191 xgrid(color("grey60"),1,7)
192 legend(["Ai(x)" "Ai(x) scaled"],"in_upper_left")
193 title("Airy functions raw vs scaled", "fontsize", 3)
194
195 subplot(2,1,2)  // Bi, Bi scaled
196 plot(x, airy("Bi", x), x, airy("Bi",x, %t), "color", ["red" "darkorange"])
197 legend(["Bi(x)" "Bi(x) scaled"],"in_upper_left")
198 xlabel("x", "fontsize", 3)
199 gca().margins(3) = 0.08;
200 gca().x_location = "top";
201 gca().x_ticks.labels = emptystr(gca().x_ticks.labels);
202 gca().data_bounds(3:4) = [-0.5 1.5];
203 gca().tight_limits = "on";
204 xgrid(color("grey60"),1,7)
205
206 gcf().children.children.children.thickness = 2;
207 drawnow
208       ]]></programlisting>
209         <scilab:image><![CDATA[
210             x = -10:0.05:3;
211             clf
212             drawlater
213
214             subplot(2,1,1)  // Ai, Ai scaled
215             plot(x, airy("Ai",x), x, airy("Ai",x, %t), "color", ["blue" "cyan"])
216             gca().margins(4) = 0.08;
217             gca().data_bounds(3:4) = [-0.5 1];
218             gca().tight_limits = "on";
219             xgrid(color("grey60"),1,7)
220             legend(["Ai(x)" "Ai(x) scaled"],"in_upper_left")
221             title("Airy functions raw vs scaled", "fontsize", 3)
222
223             subplot(2,1,2)  // Bi, Bi scaled
224             plot(x, airy("Bi", x), x, airy("Bi",x, %t), "color", ["red" "darkorange"])
225             legend(["Bi(x)" "Bi(x) scaled"],"in_upper_left")
226             xlabel("x", "fontsize", 3)
227             gca().margins(3) = 0.08;
228             gca().x_location = "top";
229             gca().x_ticks.labels = emptystr(gca().x_ticks.labels);
230             gca().data_bounds(3:4) = [-0.5 1.5];
231             gca().tight_limits = "on";
232             xgrid(color("grey60"),1,7)
233
234             gcf().children.children.children.thickness = 2;
235             gcf().axes_size = [600 570];
236             drawnow
237         ]]></scilab:image>
238         <para>
239             With complex numbers
240         </para>
241         <programlisting role="example"><![CDATA[
242 // Initializations
243 x = -4.5:0.2:2.5;
244 y = -3.5:0.2:3.5;
245 [X, Y] = meshgrid(x, y);
246 xph = -4.5:0.05:2.5;
247 yph = -3.5:0.05:3.5;
248 [Xph, Yph] = meshgrid(xph, yph);
249 clf
250 fig = gcf();
251 drawlater
252 [nc, cmin] = (100, 15);
253 fig.color_map = [0.6 0.6 0.6; jetcolormap(nc-1)];
254 meshColor = 1; // grey60 will be used for the mesh color
255 if ~isDocked(fig) then
256     fig.axes_size = [800 600];
257 end
258 fr = 0.55;
259
260
261 // |Ai|
262 xsetech([0 0 0.5 fr])
263 Z = X + %i*Y;
264 Z = airy(Z);
265 V = abs(Z);
266 [smin, smax] = (0, 5);
267 surf(x, y, V)
268 S = gce();
269 set(S, "color_flag",3, "color_mode",1, ..
270        "cdata_mapping","direct", "foreground",meshColor);
271 c = S.data.color;
272 c = cmin + (nc-cmin)*(c-smin)/(smax-smin);
273 S.data.color = c;
274 gca().zoom_box = [min(x) min(y) max(x) max(y) smin smax];
275 gca().rotation_angles = [47 -60];
276 xtitle("", "real(z)","imag(z)", "")
277 title("| Ai(z) |", "fontsize",3)
278 colorbar(smin, smax, [2, nc])
279
280 // arg(Ai)
281 xsetech([0 fr 0.5 (1-fr)])
282 Z = airy(Xph + %i*Yph);
283 V = atan(imag(Z),real(Z));
284 grayplot(xph, yph, V.')
285 xtitle("","real(z)", "imag(z)")
286 title("arg( Ai(z) )", "fontsize", 3)
287 gca().tight_limits = "on";
288 isoview
289 colorbar(,,[2 nc])
290 title(fig.children(1), "[rad]")
291
292
293 // |Bi|
294 xsetech([0.50 0 0.5 fr])
295 Z = X + %i*Y;
296 Z = airy(2, Z);
297 V = abs(Z);
298 [smin, smax] = (0, 5);
299 surf(x, y, V)
300 S = gce();
301 set(S, "color_flag",3, "color_mode",1, ..
302        "cdata_mapping","direct", "foreground",meshColor);
303 c = S.data.color;
304 c = cmin + (nc-cmin)*(c-smin)/(smax-smin);
305 S.data.color = c;
306 gca().zoom_box = [min(x) min(y) max(x) max(y) smin smax];
307 gca().rotation_angles = [40 -130];
308 xtitle("", "real(z)","imag(z)", "")
309 title("| Bi(z) |", "fontsize",3)
310 colorbar(smin, smax, [2, nc])
311
312 // arg(Bi)
313 xsetech([0.5 fr 0.5 (1-fr)])
314 Z = airy(3, Xph + %i*Yph);
315 V = atan(imag(Z),real(Z));
316 grayplot(xph, yph, V.')
317 xtitle("","real(z)", "imag(z)")
318 title("arg( Bi(z) )", "fontsize", 3)
319 gca().tight_limits = "on";
320 isoview
321 colorbar(,,[2 nc])
322 title(fig.children(1), "[rad]")
323
324 drawnow
325       ]]></programlisting>
326         <inlinemediaobject>
327             <imageobject>
328                 <imagedata fileref="../../../helptools/images/airy_z_numbers.png"  valign="middle"/>
329                 <!--
330                 <imagedata fileref="../images/airy_z_numbers.png"  valign="middle"/>
331                 -->
332             </imageobject>
333         </inlinemediaobject>
334         <!-- The same automated image is poorer and 2.5x bigger (150kB instead of 61kB)
335       <scilab:image><![CDATA[
336 ]]></scilab:image>
337         -->
338     </refsection>
339     <refsection role="see also">
340         <title>See also</title>
341         <simplelist type="inline">
342             <member>
343                 <link linkend="besseli">besseli</link>
344             </member>
345             <member>
346                 <link linkend="besselj">besselj</link>
347             </member>
348             <member>
349                 <link linkend="gamma">gamma</link>
350             </member>
351         </simplelist>
352     </refsection>
353     <refsection>
354         <title>History</title>
355         <revhistory>
356             <revision>
357                 <revnumber>6.1.0</revnumber>
358                 <revremark>
359                     <literal>airy()</literal> introduced.
360                 </revremark>
361             </revision>
362         </revhistory>
363     </refsection>
364 </refentry>