* Bugs 7562 + 15517 fixed: factorial() improved
[scilab.git] / scilab / modules / elementary_functions / help / ru_RU / discrete / factorial.xml
index b2d743d..f3edcd2 100644 (file)
@@ -1,10 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- *
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2011 - DIGITEO - Michael Baudin
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2018 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="factorial" xml:lang="ru">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
+        xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+        xmlns:scilab="http://www.scilab.org" xml:id="factorial" xml:lang="ru">
     <refnamediv>
         <refname>factorial</refname>
-        <refpurpose>Функция факториал</refpurpose>
+        <refpurpose>функция факториала : произведение первых n положительных целых чисел</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
         <synopsis>
-            f = factorial ( n )
-
+            f = factorial(n)
+            [f, p] = factorial(n)
+            [f, p, m] = factorial(n)
         </synopsis>
     </refsynopsisdiv>
-    <refsection>
-        <title>Параметры</title>
+    <refsection role="arguments">
+        <title>Аргументы</title>
         <variablelist>
             <varlistentry>
-                <term>n :</term>
+                <term>n</term>
+                <listitem>
+                    <para>
+                        скаляр, вектор, матрица или гиперматрица положительных целых чисел
+                        &lt;= 10<superscript>14</superscript>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>f</term>
+                <listitem>
+                    <para>
+                        массив чисел типа double того же размера, что и <literal>n</literal>:
+                        <literal>f(i) = n(i)!</literal>.
+                        Значения <varname>f</varname> могут быть вплоть до <literal>n=21</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>p</term>
                 <listitem>
                     <para>
-                        Матрица чисел удвоенной точности (double). Числа должны быть положительными целыми.
+                        массив чисел типа double того же размера, что и <literal>n</literal>:
+                        10 в степени <varname>f</varname>: <literal>p(i) = int(log10(f(i)!))</literal>.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>f :</term>
+                <term>m</term>
                 <listitem>
-                    <para> матрица чисел удвоенной точности.</para>
+                    <para>
+                        массив чисел типа double в интервале <literal>[1,10)</literal> того же размера, что и <literal>n</literal>:
+                        мантисса у <varname>f</varname> такая, что <literal>n(i)! = m(i) * 10^p(i)</literal>.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="description">
         <title>Описание</title>
         <para>
-            Возвращает факториал <literal>n</literal>, то есть, произведение всех целых чисел
-            1 * 2 * ... * n.
-        </para>
-        <para>
-            Эта функция переполняет разрядную сетку при n&gt;170.
+            Возвращает факториал от <literal>n</literal>, равный произведению <literal>1 * 2 * ... * n</literal>.
         </para>
+        <warning>
+            <varname>f</varname> превышает разрядную сетку при <literal>n&gt;170</literal> и всегда возвращает <literal>%inf</literal> для любого большего <literal>n</literal>.
+        </warning>
+        <note>
+            <itemizedlist>
+                <listitem>
+                    Для <literal>n</literal> в <literal>[22, 170]</literal> относительная точность
+                    <varname>f</varname> примерно равна <literal>%eps ~ 2e-16</literal>.
+                </listitem>
+                <listitem>
+                    Для <literal>n</literal> в <literal>[171, 1.0x10<superscript>14</superscript>]</literal> значение
+                    степени <varname>p</varname> равна точно и относительная точность мантиссы <varname>m</varname> 
+                    примерно равно <literal>n*%eps ~ n * 1e-16</literal> (см. последний пример).
+                </listitem>
+                <listitem>
+                    После <literal>n > 10.0<superscript>14</superscript></literal>,
+                    <varname>p</varname> становится > 1/%eps и ограничивается. Тогда нельзя более
+                    получить надёжную мантиссу.
+                </listitem>
+            </itemizedlist>
+        </note>
+               <para/>
     </refsection>
     <refsection>
+        <title>Граф</title>
+        <scilab:image>
+            x = (10^(0:13)).*.(1:9); x(1)=[]; x($)=1e14;
+            [f, p, m] = factorial(x);
+            plot2d("ll", x, p+log10(m))
+            xlabel("n", "fontsize",3)
+            title("$\mathsf{log_{10}(n!)}$", "fontsize", 4)
+            xgrid(color("grey70"), 1, 7)
+            set(gca(), "sub_ticks",[8 2], "tight_limits","on");
+            gca().data_bounds([1 4]) = [1 2e15];
+            gcf().axes_size = [840 470];
+        </scilab:image>
+    </refsection>
+    <refsection role="examples">
         <title>Примеры</title>
+        <para>Таблица первых точных значений факториала n! :</para>
         <programlisting role="example"><![CDATA[
-// Делаем таблицу факториала
-n = (0:30)';
+format(22);
+n = (0:21)';
 [n factorial(n)]
-
-// Смотрим пределы факториала: f(171)=%inf
+format(10);
+   ]]></programlisting>
+   <screen><![CDATA[
+--> [n factorial(n)]
+ ans  =
+   0.    1.
+   1.    1.
+   2.    2.
+   3.    6.
+   4.    24.
+   5.    120.
+   6.    720.
+   7.    5040.
+   8.    40320.
+   9.    362880.
+   10.   3628800.
+   11.   39916800.
+   12.   479001600.
+   13.   6227020800.
+   14.   87178291200.
+   15.   1307674368000.
+   16.   20922789888000.
+   17.   355687428096000.
+   18.   6402373705728000.
+   19.   121645100408832000.
+   20.   2432902008176640000.
+   21.   51090942171709440000.
+]]></screen>
+        <para>Округление значения factorial() в большую сторону в представлении с плавающей запятой:</para>
+      <programlisting role="example"><![CDATA[
 factorial(170) // 7.257415615307998967e306
 factorial(171) // %inf
-
-// Построим на графике функцию во всём её диапазоне.
-scf();
-plot ( 1:170 , factorial , "b-o" );xgrid
-h = gcf();
-h.children.log_flags="nln";
-
    ]]></programlisting>
+        <para>Построение графика функции во всём её интервале:</para>
+      <programlisting role="example"><![CDATA[
+x = (10^(0:13)).*.(1:9); x(1)=[]; x($)=1e14;
+[f, p, m] = factorial(x);
+clf
+plot2d("ll", x, p+log10(m))
+xlabel("n", "fontsize",3)
+title("$\mathsf{log_{10}(n!)}$", "fontsize", 4)
+xgrid(color("grey70"), 1, 7)
+set(gca(), "sub_ticks",[8 2], "tight_limits","on");
+gca().data_bounds([1 4]) = [1 2e15];
+gcf().axes_size = [850 480];
+   ]]></programlisting>
+        <para>Относительные ошибки factorial():</para>
+      <programlisting role="example"><![CDATA[
+n = 10^(1:14)';
+[f, p, m] = factorial(n);
+// Точная (ограниченная) мантисса для n = 10^(1:14) :
+m0 = [
+   3.6288000000000000  9.3326215443944153  4.0238726007709377 ..  // n = 10     100   1000
+   2.8462596809170545  2.8242294079603479                     ..  // n = 10000  100000
+   8.2639316883312401  1.2024233400515904  1.6172037949214624 ..  // n = 1e6    1e7   1e8
+   9.9046265792229937  2.3257962056730834  3.7489285991050270 ..  // n = 1e9    1e10  1e11
+   1.4036611603737561  2.4033300843401153  1.6456020559872979     // n = 1e12   1e13  1e14
+   ]';
+r_err = m./m0 - 1;
+[n r_err]
+   ]]></programlisting>
+   <screen><![CDATA[
+--> [n r_err]
+ ans  =
+   10.          0.
+   100.        -5.551D-16
+   1000.        1.132D-13
+   10000.       1.918D-12
+   100000.      6.611D-12
+   1000000.     9.962D-11
+   10000000.    5.048D-08
+   100000000.   1.050D-08
+   1.000D+09   0.0000001
+   1.000D+10   0.0000019
+   1.000D+11   0.0000062
+   1.000D+12   0.0001327
+   1.000D+13   0.0004839
+   1.000D+14   0.0071116
+]]></screen>
     </refsection>
-    <refsection>
-        <title>Литература</title>
-        <para>"Introduction to discrete probabilities", Michael Baudin, 2011</para>
+    <refsection role="see also">
+        <title>Смотрите также</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="cumprod">cumprod</link>
+            </member>
+            <member>
+                <link linkend="gamma">gamma</link>
+            </member>
+            <member>
+                <link linkend="gammaln">gammaln</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1</revnumber>
+                <revdescription>
+                    Расширение вплоть до n = 10<superscript>14</superscript>.
+                    Добавлено <varname>p</varname> в 10-й степени и вывод мантиссы <varname>m</varname>.
+                </revdescription>
+            </revision>
+        </revhistory>
     </refsection>
-</refentry>
+</refentry>
\ No newline at end of file