Add note about problems with math.fsum on x86 hardware.

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 574075933b5bf029f115d00e4c2ef7e85e443319..6f8d3c8aa05f0b0fdcbb970da81b99f405316376 100644 (file)
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -90,6 +90,32 @@ Number-theoretic and representation functions:
    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