* Bug 16617 fixed: gamma() extended to incomplete cases
[scilab.git] / scilab / modules / special_functions / help / en_US / gamma.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 - 2016 - Scilab Enterprises
6  * Copyright (C) 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:id="gamma" xml:lang="en">
20     <refnamediv>
21         <refname>gamma</refname>
22         <refpurpose>gamma function, complete or incomplete normalized</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             y = gamma(u)
28             y = gamma(x, a)
29             y = gamma(x, a, b)
30             y = gamma(x, .., "upper")
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>u</term>
38                 <listitem>
39                     array of positive or negative real numbers
40                     <para/>
41                     <literal>gamma(u)</literal> and <literal>gamma(x,…)</literal> can be overloaded
42                     for complex numbers with <literal>%s_gamma_user()</literal>, and for other
43                     <varname>a</varname> types with the usual overload naming rule.
44                     <para/>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>x, a, b</term>
49                 <listitem>
50                     arrays of positive real numbers.
51                     If at least one input is not scalar, scalar ones are expanded to its size.
52                     If several inputs are not scalar, they must have the same size.
53                     <para/>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>y</term>
58                 <listitem>
59                     array of real numbers, with the size of <varname>u</varname>
60                     or of (the non-scalar) <varname>x</varname>, <varname>a</varname>,
61                     or <varname>b</varname>.
62                     <para/>
63                 </listitem>
64             </varlistentry>
65         </variablelist>
66     </refsection>
67     <refsection>
68         <title>Description</title>
69         <para>
70             <literal>gamma(…)</literal> computes and yields the complete or incomplete gamma
71             function for each element of its input(s), in an element-wise way. The complete
72             gamma function extends the factorial one to non-integer real positive or negative
73             numbers, as <literal>gamma(u+1)=u*gamma(u)</literal>.
74         </para>
75         <para>
76             <emphasis role="bold">gamma(u)</emphasis> computes
77             <latex style="display" fontsize="18" alt="Γ(u)= ∫_0→∞ t^{u-1}.exp(-t).dt">
78                 \Gamma(u)=\int_0^\infty\! t^{u-1}e^{-t}\,dt
79             </latex>
80         </para>
81         <refsect3>
82             <title>Incomplete normalized integrals</title>
83             <para>
84                 <emphasis role="bold">gamma(x, a)</emphasis> computes the integral
85                 <latex style="display" fontsize="18" alt="P(x,a)= ∫_0→x t^{a-1}.exp(-t).dt / Γ(a)">
86                     P(x,a)=\frac{1}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-t}\,dt
87                 </latex>
88             </para>
89             <para>
90                 <emphasis role="bold">gamma(x, a, b)</emphasis> computes the generalized integral
91                 <latex style="display" fontsize="18" alt="P(x,a,b)= ∫_0→x t^{a-1}.exp(-bt).dt . b^a / Γ(a)">
92                     P(x,a,b)=\frac{b^a}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-b\,t}\,dt
93                 </latex>
94             </para>
95             <para>
96                 <emphasis role="bold">gamma(x, a, "upper")</emphasis> computes accurately the
97                 complementary integral
98                 <latex style="display" fontsize="18" alt="Q(x,a)= ∫_x→∞ t^{a-1}.exp(-t).dt / Γ(a) = 1-P(x,a)">
99                     Q(x,a)=1-P(x,a)=\frac{1}{\Gamma(a)}\int_x^\infty\! t^{a-1}e^{-t}\,dt
100                 </latex>
101                 even for big x and P(x,a)→1. Finally,
102             </para>
103             <para>
104                 <emphasis role="bold">gamma(x, a, b, "upper")</emphasis> computes the generalized
105                 complementary integral
106                 <latex style="display" fontsize="18" alt="Q(x,a,b)= ∫_x→∞ t^{a-1}.exp(-bt).dt . b^a / Γ(a)">
107                     Q(x,a,b)=\frac{b^a}{\Gamma(a)}\int_x^\infty\! t^{a-1}e^{-b\,t}\,dt
108                 </latex>
109             </para>
110             <note>
111                 <para>
112                     The inverse incomplete normalized gamma function can be computed with
113                     <emphasis role="bold">x = cdfgam("X", a, b, y, 1-y)</emphasis>,
114                     that is the <varname>x</varname> bound such that
115                     <latex alt="y=∫_0→x t^{a-1}.exp(-bt).dt . b^a / Γ(a)">
116                     y=\frac{b^a}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-b\,t}\,dt
117                     </latex>
118                 </para>
119                 <para>
120                     Calling <emphasis role="bold">x = cdfgam("X", a, b, z-1, z)</emphasis> with
121                     <literal>z=1-y</literal> will be preferred when 0.5 &lt; y &lt; 1, to get a full
122                     accuracy on <varname>x</varname>.
123                 </para>
124             </note>
125         </refsect3>
126    </refsection>
127     <refsection>
128         <title>Examples</title>
129         <para>
130             Gamma as the extension of the factorial function to non-integer numbers:
131         </para>
132         <programlisting role="example"><![CDATA[
133 [gamma(2:7) ; factorial(1:6)]
134 gamma(1.5:7)
135 gamma(1.5:7) ./ gamma(0.5:6)
136      ]]></programlisting>
137         <screen><![CDATA[
138 --> [gamma(2:7) ; factorial(1:6)]
139  ans  =
140    1.   2.   6.   24.   120.   720.
141    1.   2.   6.   24.   120.   720.
142
143 --> gamma(1.5:7)
144  ans  =
145    0.8862269   1.3293404   3.323351   11.631728   52.342778   287.88528
146
147 --> gamma(1.5:7) ./ gamma(0.5:6)
148  ans  =
149    0.5   1.5   2.5   3.5   4.5   5.5
150 ]]></screen>
151         <para/>
152         <para>
153             Graph of the Gamma function around 0:
154         </para>
155         <programlisting role="example"><![CDATA[
156 [a, b] = (-3, 5);
157 x = linspace(a,b,40000);
158 y = gamma(x);
159 clf
160 plot2d(x, y, style=0, axesflag=5, rect=[a,-10,b,10])
161 title("$\Gamma(u)$", "fontsize",3.5)
162 xgrid(color("grey60"))
163      ]]></programlisting>
164         <scilab:image>
165             [a, b] = (-3, 5);
166             x = linspace(a,b,40000);
167             y = gamma(x);
168             clf
169             plot2d(x, y, style=0, axesflag=5, rect=[a,-10,b,10])
170             title("$\Gamma(u)$", "fontsize",3.5)
171             xgrid(color("grey60"))
172             gcf().axes_size = [550,400];
173         </scilab:image>
174         <para/>
175         <para>
176             Incomplete normalized P(x,a) gamma function:
177         </para>
178         <programlisting role="example"><![CDATA[
179 x = 0.1:0.2:8;
180 a = 0.1:0.2:7;
181 [X, A] = ndgrid(x, a);
182 P = gamma(X,A);
183 clf
184 gcf().color_map = coolcolormap(100);
185 surf(a,x,P)
186 title("$P(x,a)=\frac{1}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-t}\,dt$","fontsize",3.5)
187 xlabel(["" "a"], "fontsize",2)
188 ylabel("x", "fontsize",2)
189 zlabel("P(x,a)", "fontsize",2)
190 xgrid
191      ]]></programlisting>
192         <scilab:image>
193             x = 0.1:0.2:8;
194             a = 0.1:0.2:7;
195             [X, A] = ndgrid(x, a);
196             P = gamma(X,A);
197             clf
198             gcf().color_map = coolcolormap(100);
199             surf(a,x,P)
200             title("$P(x,a)=\frac{1}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-t}\,dt$","fontsize",3.5)
201             xlabel(["" "a"], "fontsize",2)
202             ylabel("x", "fontsize",2)
203             zlabel("P(x,a)", "fontsize",2)
204             xgrid
205             gca().rotation_angles = [64 18];
206         </scilab:image>
207         <para/>
208         <para>
209             Incomplete generalized normalized P(x,a,b) function:
210         </para>
211         <programlisting role="example"><![CDATA[
212 a = 0.1:0.2:8;
213 b = 0.1:0.2:7;
214 [A, B] = ndgrid(a, b);
215 P = gamma(1,A,B);
216 clf
217 gcf().color_map = parulacolormap(100);
218 surf(b,a,P)
219 title("$P(x,a,b)=\frac{b^a}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-b\,t}\,dt\quad for\quad x=1$","fontsize",3.7)
220 xlabel("b", "fontsize",2)
221 ylabel("a", "fontsize",2)
222 zlabel("")
223 gca().rotation_angles = [58 75];
224 xgrid
225      ]]></programlisting>
226         <scilab:image>
227             a = 0.1:0.2:8;
228             b = 0.1:0.2:7;
229             [A, B] = ndgrid(a, b);
230             P = gamma(1,A,B);
231             clf
232             gcf().color_map = parulacolormap(100);
233             surf(b,a,P)
234             title("$P(x,a,b)=\frac{b^a}{\Gamma(a)}\int_0^x\! t^{a-1}e^{-b\,t}\,dt\quad for\quad x=1$","fontsize",3.7)
235             xlabel("b", "fontsize",2)
236             ylabel("a", "fontsize",2)
237             zlabel("")
238             gca().rotation_angles = [58 75];
239             xgrid
240         </scilab:image>
241     </refsection>
242     <refsection role="see also">
243         <title>See also</title>
244         <simplelist type="inline">
245             <member>
246                 <link linkend="gammaln">gammaln</link>
247             </member>
248             <member>
249                 <link linkend="dlgamma">dlgamma</link>
250             </member>
251             <member>
252                 <link linkend="cdfgam">cdfgam</link>
253             </member>
254             <member>
255                 <link linkend="factorial">factorial</link>
256             </member>
257         </simplelist>
258     </refsection>
259     <refsection>
260         <title>History</title>
261         <revhistory>
262             <revision>
263                 <revnumber>5.4.0</revnumber>
264                 <revremark>Overloading allowed for list, mlist, tlist and hypermatrix types.</revremark>
265             </revision>
266             <revision>
267               <revnumber>6.0.2</revnumber>
268               <revremark>
269                 <itemizedlist>
270                   <listitem>
271                     The input can now be an hypermatrix.
272                   </listitem>
273                   <listitem>
274                     <literal>gamma</literal> can now be overloaded for complex numbers.
275                   </listitem>
276                 </itemizedlist>
277               </revremark>
278             </revision>
279             <revision>
280                 <revnumber>6.1.1</revnumber>
281                 <revremark>gamma(x,..) incomplete versions added.</revremark>
282             </revision>
283         </revhistory>
284     </refsection>
285 </refentry>