* Bugs 7562 + 15517 fixed: factorial() improved
[scilab.git] / scilab / modules / elementary_functions / help / en_US / discrete / factorial.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) 2018 - Samuel GOUGEON
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:ns3="http://www.w3.org/1999/xhtml"
16         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
17         xmlns:scilab="http://www.scilab.org" xml:id="factorial" xml:lang="en">
18     <refnamediv>
19         <refname>factorial</refname>
20         <refpurpose>factorial function : product of the n first positive integers</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>
25             f = factorial(n)
26             [f, p] = factorial(n)
27             [f, p, m] = factorial(n)
28         </synopsis>
29     </refsynopsisdiv>
30     <refsection role="arguments">
31         <title>Arguments</title>
32         <variablelist>
33             <varlistentry>
34                 <term>n</term>
35                 <listitem>
36                     <para>
37                         scalar, vector, matrix or hypermatrix of positive integers
38                         &lt;= 10<superscript>14</superscript>.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>f</term>
44                 <listitem>
45                     <para>
46                         array of doubles, of the sizes of n: <literal>f(i) = n(i)!</literal>.
47                         <varname>f</varname> values are exact up to <literal>n=21</literal> included.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>p</term>
53                 <listitem>
54                     <para>
55                         array of doubles, of the sizes of n: power of 10 of <varname>f</varname>:
56                         <literal>p(i) = int(log10(f(i)!))</literal>.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>m</term>
62                 <listitem>
63                     <para>
64                         array of doubles in [1,10[, of the sizes of n: Mantissae of <varname>f</varname>,
65                         such that <literal>n(i)! = m(i) * 10^p(i)</literal>.
66                     </para>
67                 </listitem>
68             </varlistentry>
69         </variablelist>
70     </refsection>
71     <refsection role="description">
72         <title>Description</title>
73         <para>
74             Returns the factorial of n, that is the product 1 * 2 * ... * n.
75         </para>
76         <warning>
77             <varname>f</varname> overflows as soon as n&gt;170 and always returns %inf for any
78             bigger n.
79         </warning>
80         <note>
81             <itemizedlist>
82                 <listitem>
83                     For <literal>n in [22, 170]</literal>, the relative accuracy of
84                     <varname>f</varname> is roughly <literal>%eps ~ 2e-16</literal>.
85                 </listitem>
86                 <listitem>
87                     For <literal>n in [171, 1.0x10<superscript>14</superscript>]</literal>, the
88                     power <varname>p</varname> value is exact, and the relative accuracy of the
89                     mantissa <varname>m</varname> goes roughly as
90                     <literal>n*%eps ~ n * 1e-16</literal> (see the last example).
91                 </listitem>
92                 <listitem>
93                     Beyond <literal>n > 10.0<superscript>14</superscript></literal>,
94                     <varname>p</varname> becomes > 1/%eps and gets truncated. It is then no longer
95                     possible to retrieve a reliable mantissa.
96                 </listitem>
97             </itemizedlist>
98         </note>
99                 <para/>
100     </refsection>
101     <refsection>
102         <title>Graph</title>
103         <scilab:image>
104             x = (10^(0:13)).*.(1:9); x(1)=[]; x($)=1e14;
105             [f, p, m] = factorial(x);
106             plot2d("ll", x, p+log10(m))
107             xlabel("n", "fontsize",3)
108             title("$\mathsf{log_{10}(n!)}$", "fontsize", 4)
109             xgrid(color("grey70"), 1, 7)
110             set(gca(), "sub_ticks",[8 2], "tight_limits","on");
111             gca().data_bounds([1 4]) = [1 2e15];
112             gcf().axes_size = [840 470];
113         </scilab:image>
114     </refsection>
115     <refsection role="examples">
116         <title>Examples</title>
117         <para>Table of the first n! exact values :</para>
118         <programlisting role="example"><![CDATA[
119 format(22);
120 n = (0:21)';
121 [n factorial(n)]
122 format(10);
123    ]]></programlisting>
124    <screen><![CDATA[
125 --> [n factorial(n)]
126  ans  =
127    0.    1.
128    1.    1.
129    2.    2.
130    3.    6.
131    4.    24.
132    5.    120.
133    6.    720.
134    7.    5040.
135    8.    40320.
136    9.    362880.
137    10.   3628800.
138    11.   39916800.
139    12.   479001600.
140    13.   6227020800.
141    14.   87178291200.
142    15.   1307674368000.
143    16.   20922789888000.
144    17.   355687428096000.
145    18.   6402373705728000.
146    19.   121645100408832000.
147    20.   2432902008176640000.
148    21.   51090942171709440000.
149 ]]></screen>
150         <para>Ceiling of factorial() in floating point representation:</para>
151       <programlisting role="example"><![CDATA[
152 factorial(170) // 7.257415615307998967e306
153 factorial(171) // %inf
154    ]]></programlisting>
155         <para>Plot the function on its whole range:</para>
156       <programlisting role="example"><![CDATA[
157 x = (10^(0:13)).*.(1:9); x(1)=[]; x($)=1e14;
158 [f, p, m] = factorial(x);
159 clf
160 plot2d("ll", x, p+log10(m))
161 xlabel("n", "fontsize",3)
162 title("$\mathsf{log_{10}(n!)}$", "fontsize", 4)
163 xgrid(color("grey70"), 1, 7)
164 set(gca(), "sub_ticks",[8 2], "tight_limits","on");
165 gca().data_bounds([1 4]) = [1 2e15];
166 gcf().axes_size = [850 480];
167    ]]></programlisting>
168         <para>Relative factorial() errors:</para>
169       <programlisting role="example"><![CDATA[
170 n = 10^(1:14)';
171 [f, p, m] = factorial(n);
172 // Exact (truncated) mantissae for n = 10^(1:14) :
173 m0 = [
174    3.6288000000000000  9.3326215443944153  4.0238726007709377 ..  // n = 10     100   1000
175    2.8462596809170545  2.8242294079603479                     ..  // n = 10000  100000
176    8.2639316883312401  1.2024233400515904  1.6172037949214624 ..  // n = 1e6    1e7   1e8
177    9.9046265792229937  2.3257962056730834  3.7489285991050270 ..  // n = 1e9    1e10  1e11
178    1.4036611603737561  2.4033300843401153  1.6456020559872979     // n = 1e12   1e13  1e14
179    ]';
180 r_err = m./m0 - 1;
181 [n r_err]
182    ]]></programlisting>
183    <screen><![CDATA[
184 --> [n r_err]
185  ans  =
186    10.          0.
187    100.        -5.551D-16
188    1000.        1.132D-13
189    10000.       1.918D-12
190    100000.      6.611D-12
191    1000000.     9.962D-11
192    10000000.    5.048D-08
193    100000000.   1.050D-08
194    1.000D+09   0.0000001
195    1.000D+10   0.0000019
196    1.000D+11   0.0000062
197    1.000D+12   0.0001327
198    1.000D+13   0.0004839
199    1.000D+14   0.0071116
200 ]]></screen>
201     </refsection>
202     <refsection role="see also">
203         <title>See Also</title>
204         <simplelist type="inline">
205             <member>
206                 <link linkend="cumprod">cumprod</link>
207             </member>
208             <member>
209                 <link linkend="gamma">gamma</link>
210             </member>
211             <member>
212                 <link linkend="gammaln">gammaln</link>
213             </member>
214         </simplelist>
215     </refsection>
216     <refsection role="history">
217         <title>History</title>
218         <revhistory>
219             <revision>
220                 <revnumber>6.1</revnumber>
221                 <revdescription>
222                     Extension up to n = 10<superscript>14</superscript>. <varname>p</varname>
223                     10-power and <varname>m</varname> mantissa output added.
224                 </revdescription>
225             </revision>
226         </revhistory>
227     </refsection>
228 </refentry>