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>