From a17060162911b5a056a45b44af01c7ef7661e9fb Mon Sep 17 00:00:00 2001
From: Sebastien Brisard <celestin@apache.org>
Date: Fri, 9 Nov 2012 19:03:28 +0000
Subject: [PATCH] In the users guide for special functions   - accuracy of
 current implementation of Beta.logBeta   - standard deviation of error (in
 ulps) is now provided for all special     functions that have already been
 evaluated.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1407594 13f79535-47bb-0310-9956-ffa450edef68
---
 src/site/apt/userguide/special.apt | 95 ++++++++++++++++++------------
 1 file changed, 57 insertions(+), 38 deletions(-)

diff --git a/src/site/apt/userguide/special.apt b/src/site/apt/userguide/special.apt
index efe913159..f06d0c410 100644
--- a/src/site/apt/userguide/special.apt
+++ b/src/site/apt/userguide/special.apt
@@ -44,29 +44,29 @@
 
 ** Gamma
 
-  <<<Gamma.gamma(x)>>> computes the Gamma function, \u0393(x),
+  <<<Gamma.gamma(x)>>> computes the Gamma function, Γ(x)
   (see {{{http://mathworld.wolfram.com/GammaFunction.html}MathWorld}},
   {{{http://dlmf.nist.gov/5}DLMF}}). The accuracy of the Commons-Math
   implementation is assessed by comparaison with high precision values computed
   with the {{{http://maxima.sourceforge.net/}Maxima}} Computer Algebra System.
 
-*---------------+----------------------------------------+-----------------+----------------+
-|| Interval     || Values tested                         || Average error  || Maximum error |
-*---------------+----------------------------------------+-----------------+----------------+
-| (-5.0, -4.0)  | <<<k / 1024, k = -5119, ..., -4097>>>  | 0.49 ulps       | 3.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
-| (-4.0, -3.0)  | <<<k / 1024, k = -4095, ..., -3073>>>  | 0.36 ulps       | 2.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
-| (-3.0, -2.0)  | <<<k / 1024, k = -3071, ..., -2049>>>  | 0.41 ulps       | 2.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
-| (-2.0, -1.0)  | <<<k / 1024, k = -2047, ..., -1025>>>  | 0.37 ulps       | 2.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
-| (-1.0, 0.0)   | <<<k / 1024, k = -1023, ..., -1>>>     | 0.46 ulps       | 2.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
-| (0.0, 8.0]    | <<<k / 1024, k = 1, ..., 8192>>>       | 0.33 ulps       | 2.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
-| (8.0, 141.0]  | <<<k / 64, k = 513, ..., 9024>>>       | 1.32 ulps       | 7.0 ulps       |
-*---------------+----------------------------------------+-----------------+----------------+
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+|| Interval      || Values tested                                || Average error  || Standard deviation  || Maximum error |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| -5 \< x \< -4  | <<<x[i] = i / 1024, i = -5119, ..., -4097>>>  | 0.49 ulps       | 0.57 ulps            | 3.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| -4 \< x \< -3  | <<<x[i] = i / 1024, i = -4095, ..., -3073>>>  | 0.36 ulps       | 0.51 ulps            | 2.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| -3 \< x \< -2  | <<<x[i] = i / 1024, i = -3071, ..., -2049>>>  | 0.41 ulps       | 0.53 ulps            | 2.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| -2 \< x \< -1  | <<<x[i] = i / 1024, i = -2047, ..., -1025>>>  | 0.37 ulps       | 0.50 ulps            | 2.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| -1 \< x \< 0   | <<<x[i] = i / 1024, i = -1023, ..., -1>>>     | 0.46 ulps       | 0.54 ulps            | 2.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| 0 \< x ≤ 8     | <<<x[i] = i / 1024, i = 1, ..., 8192>>>       | 0.33 ulps       | 0.48 ulps            | 2.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| 8 \< x ≤ 141   | <<<x[i] = i / 64, i = 513, ..., 9024>>>       | 1.32 ulps       | 1.19 ulps            | 7.0 ulps       |
+*----------------+-----------------------------------------------+-----------------+----------------------+----------------+
 
 ** Log Gamma
 
@@ -77,33 +77,52 @@
   implementation is assessed by comparaison with high precision values computed
   with the {{{http://maxima.sourceforge.net/}Maxima}} Computer Algebra System.
 
-*---------------------------------------------+---------------------------------------+-----------------+----------------+
-|| Interval                                   || Values tested                        || Average error  || Maximum error |
-*---------------------------------------------+---------------------------------------+-----------------+----------------+
-| (0.0, 8.0]                                  | <<<k / 1024, k = 1, ..., 8192>>>      | 0.32 ulps       | 4.0 ulps       |
-*---------------------------------------------+---------------------------------------+-----------------+----------------+
-| (8.0, 1024.0]                               | <<<k / 8, k = 65, ..., 8192>>>        | 0.43 ulps       | 3.0 ulps       |
-*---------------------------------------------+---------------------------------------+-----------------+----------------+
-| (1024.0, 8192.0]                            | <<<k, k = 1025, 8192>>>               | 0.53 ulps       | 3.0 ulps       |
-*---------------------------------------------+---------------------------------------+-----------------+----------------+
-| [8933.439345993791, 1.75555970201398e+305]  | <<<2**(k / 8), k = 105, ..., 8112>>>  | 0.35 ulps       | 2.0 ulps       |
-*---------------------------------------------+---------------------------------------+-----------------+----------------+
-
+*------------------------------------------------+-----------------------------------------------+-----------------+----------------------+----------------+
+|| Interval                                      || Values tested                                || Average error  || Standard deviation  || Maximum error |
+*------------------------------------------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| 0 \< x ≤ 8                                     | <<<x[i] = i / 1024, i = 1, ..., 8192>>>       | 0.32 ulps       | 0.50 ulps            | 4.0 ulps       |
+*------------------------------------------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| 8 \< x ≤ 1024                                  | <<<x[i] = i / 8, i = 65, ..., 8192>>>         | 0.43 ulps       | 0.53 ulps            | 3.0 ulps       |
+*------------------------------------------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| 1024 \< x ≤ 8192                               | <<<x[i], i = 1025, ..., 8192>>>               | 0.53 ulps       | 0.56 ulps            | 3.0 ulps       |
+*------------------------------------------------+-----------------------------------------------+-----------------+----------------------+----------------+
+| 8933.439345993791 ≤ x ≤ 1.75555970201398e+305  | <<<x[i] = 2**(i / 8), i = 105, ..., 8112>>>   | 0.35 ulps       | 0.49 ulps            | 2.0 ulps       |
+*------------------------------------------------+-----------------------------------------------+-----------------+----------------------+----------------+
+                                                                                                      
 ** Regularized Gamma
 
   <<<Gamma.regularizedGammaP(a, x)>>> computes the value of the regularized
   Gamma function, P(a, x)
   (see {{{http://mathworld.wolfram.com/RegularizedGammaFunction.html}MathWorld}}).
 
-* 5.4 Beta funtions
+* 5.4 Beta functions
 
   {{{../apidocs/org/apache/commons/math3/special/Beta.html}Beta}} contains
   several useful functions involving the Beta Function.
 
-*------------------+-----------------+-------------------------------------------------------------------------------------------------------------+
-|| Function        || Method         || Reference                                                                                                  |
-*------------------+-----------------+-------------------------------------------------------------------------------------------------------------+
-| Log Beta         | logBeta         | See {{{http://mathworld.wolfram.com/BetaFunction.html}Beta Function}} from MathWorld                        |
-*------------------+-----------------+-------------------------------------------------------------------------------------------------------------+
-| Regularized Beta | regularizedBeta | See {{{http://mathworld.wolfram.com/RegularizedBetaFunction.html}Regularized Beta Function}} from MathWorld |
-*------------------+-----------------+-------------------------------------------------------------------------------------------------------------+
+** Log Beta
+
+  <<<Beta.logBeta(a, b)>>> computes the value of the natural logarithm of the
+  Beta function, log B(a, b).
+  (see {{{http://mathworld.wolfram.com/BetaFunction.html}MathWorld}},
+  {{{http://dlmf.nist.gov/5.12}DLMF}}). The accuracy of the Commons-Math
+  implementation is assessed by comparaison with high precision values computed
+  with the {{{http://maxima.sourceforge.net/}Maxima}} Computer Algebra System.
+
+*----------------+----------------------------------------+-----------------+----------------------+----------------+
+|| Interval      || Values tested                         || Average error  || Standard deviation  || Maximum error  |
+*----------------+----------------------------------------+-----------------+----------------------+-----------------+
+| 0 \< x ≤ 8\    | <<<x[i] = i / 32, i = 1, ..., 256>>>\  | 5.04 ulps       | 270.99 ulps          | 46696.0 ulps    |
+| 0 \< y ≤ 8     | <<<y[j] = j / 32, j = 1, ..., 256>>>   |                 |                      |                 |
+*----------------+----------------------------------------+-----------------+----------------------+-----------------+
+| 0 \< x ≤ 8\    | <<<x[i] = i / 32, i = 1, ..., 256>>>\  | 9.75 ulps       | 149.42 ulps          | 19126.0 ulps    |
+| 8 \< y ≤ 16    | <<<y[j] = j / 32, j = 257, ..., 512>>> |                 |                      |                 |
+*----------------+----------------------------------------+-----------------+----------------------+-----------------+
+| 0 \< x ≤ 8\    | <<<x[i] = i / 32, i = 1, ..., 256>>>\  | 357.82 ulps     | 39297.58 ulps        | 8635522.0 ulps  |
+| 17 \< y ≤ 256  | <<<y[j] = j, j = 17, ..., 256>>>       |                 |                      |                 |
+*----------------+----------------------------------------+-----------------+----------------------+-----------------+
+
+** Regularized Beta
+
+  (see {{{http://mathworld.wolfram.com/RegularizedBetaFunction.html}MathWorld}})
+