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