Merged revisions 65258,65292,65299,65308-65309,65315,65326 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r65258 | mark.dickinson | 2008-07-27 08:15:29 +0100 (Sun, 27 Jul 2008) | 4 lines
Remove math.sum tests related to overflow, special values, and behaviour
near the extremes of the floating-point range. (The behaviour of math.sum
should be regarded as undefined in these cases.)
........
r65292 | mark.dickinson | 2008-07-29 19:45:38 +0100 (Tue, 29 Jul 2008) | 4 lines
More modifications to tests for math.sum: replace the Python
version of msum by a version using a different algorithm, and
use the new float.fromhex method to specify test results exactly.
........
r65299 | mark.dickinson | 2008-07-30 13:01:41 +0100 (Wed, 30 Jul 2008) | 5 lines
Fix special-value handling for math.sum.
Also minor cleanups to the code: fix tabbing, remove
trailing whitespace, and reformat to fit into 80
columns.
........
r65308 | mark.dickinson | 2008-07-30 17:20:10 +0100 (Wed, 30 Jul 2008) | 2 lines
Rename math.sum to math.fsum
........
r65309 | mark.dickinson | 2008-07-30 17:25:16 +0100 (Wed, 30 Jul 2008) | 3 lines
Replace math.sum with math.fsum in a couple of comments
that were missed by r65308
........
r65315 | mark.dickinson | 2008-07-30 21:23:15 +0100 (Wed, 30 Jul 2008) | 2 lines
Add note about problems with math.fsum on x86 hardware.
........
r65326 | mark.dickinson | 2008-07-31 15:48:32 +0100 (Thu, 31 Jul 2008) | 2 lines
Rename testSum to testFsum and move it to proper place in test_math.py
........
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index c8090b5..df4ec1b 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -76,6 +76,42 @@
apart" the internal representation of a float in a portable way.
+.. function:: fsum(iterable)
+
+ Return an accurate floating point sum of values in the iterable. Avoids
+ loss of precision by tracking multiple intermediate partial sums. The
+ algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
+ typical case where the rounding mode is half-even.
+
+ .. note::
+
+ On platforms where arithmetic results are not correctly rounded,
+ :func:`fsum` may occasionally produce incorrect results; these
+ results should be no less accurate than those from the builtin
+ :func:`sum` function, but nevertheless may have arbitrarily
+ large relative error.
+
+ In particular, this affects some older Intel hardware (for
+ example Pentium and earlier x86 processors) that makes use of
+ 'extended precision' floating-point registers with 64 bits of
+ precision instead of the 53 bits of precision provided by a C
+ double. Arithmetic operations using these registers may be
+ doubly rounded (rounded first to 64 bits, and then rerounded to
+ 53 bits), leading to incorrectly rounded results. To test
+ whether your machine is one of those affected, try the following
+ at a Python prompt::
+
+ >>> 1e16 + 2.9999
+ 10000000000000002.0
+
+ Machines subject to the double-rounding problem described above
+ are likely to print ``10000000000000004.0`` instead of
+ ``10000000000000002.0``.
+
+
+ .. versionadded:: 2.6
+
+
.. function:: isinf(x)
Checks if the float *x* is positive or negative infinite.
@@ -100,12 +136,6 @@
Return the fractional and integer parts of *x*. Both results carry the sign of
*x*, and both are floats.
-.. function:: sum(iterable)
-
- Return an accurate floating point sum of values in the iterable. Avoids
- loss of precision by tracking multiple intermediate partial sums. The
- algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
- typical case where the rounding mode is half-even.
.. function:: trunc(x)