[issue29956] math.exp documentation is misleading
New submission from Alexander Belopolsky: The math.exp(x) function is documented to "Return e**x" <https://docs.python.org/3/library/math.html#math.exp>. This is misleading because even in the simplest case, math.exp(x) is not the same as math.e ** x:
import math math.exp(2) - math.e ** 2 8.881784197001252e-16
I suggest using e<sup>x instead of e**x to distinguish between Python syntax and mathematical operation and change "Return e**x" to "Return e<sup>x, the base-e exponential of x." ---------- assignee: docs@python components: Documentation messages: 290937 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: math.exp documentation is misleading versions: Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: This is because math.e is not the same as e. ---------- nosy: +mark.dickinson, rhettinger, serhiy.storchaka, stutzbach, tim.peters _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Alexander Belopolsky added the comment:
This is because math.e is not the same as e.
Right. That's why I think it would be nice to distinguish math.e and the base of the natural logarithm typographically in the docs. Can we use sphinx math mode? If not, I would use italic for the mathematical e. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: *e*:sup:`x` ? I like this idea. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Raymond Hettinger added the comment: I suggest changing the main docs to match the existing docstring, "Return e raised to the power of x." The exp() function is a thin wrapper around the C math library and where it is documented as "compute e (the base of natural logarithms) raised to the power x" or "e raised to the power X (where e is the base of the natural system of logarithms, approximately 2.71828)." Our docs shouldn't make more or fewer promises than the upstream libraries are making. Perhaps there can be a general note about reading too much into the math module implementation details. We expect some relationships to only be approximate: log(x)+1≈log1p(x), log2(x)≈log(x,2.0), exp(lgamma(x))≈gamma(x), sqrt(x)≈x**0.5, etc. These are floating point math library "facts of life". * http://www.slac.stanford.edu/comp/unix/package/rtems/doc/html/libm/libm.info... * https://www.gnu.org/software/libc/manual/html_node/Exponents-and-Logarithms.... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Mark Dickinson added the comment:
I suggest changing the main docs to match the existing docstring, "Return e raised to the power of x."
+1 for this description. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Changes by Mark Dickinson <dickinsm@gmail.com>: ---------- pull_requests: +1133 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Mark Dickinson added the comment: PR made. New wording is: """ Return e raised to the power *x*, where e = 2.718281... is the base of natural logarithms. """ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Terry J. Reedy added the comment: Is math.exp(x) always more accurate than math.e ** x? If so, doc could say so. Otherwise, should this be closed? ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: Not always. For example for x = 0 both methods give the same exact result. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Mark Dickinson added the comment:
Is math.exp(x) always more accurate than math.e ** x?
As Serhiy says: not always, and in general the answer is going to depend on the relative quality of the libm implementations of pow and exp. But on typical machines, it is going to be true that `math.exp(x)` is a better (faster, more accurate) way of computing the exponential function than `math.e ** x`. (Similarly, `math.sqrt(x)` should be preferred over `x ** 0.5`.) I'm not sure whether it's worth encoding such recommendations in the documentation or not. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Raymond Hettinger added the comment:
Is math.exp(x) always more accurate than math.e ** x?
It is usually at least as accurate, but we can't really guarantee anything because math.exp does whatever the underlying C math library does (so good libary -> good result, bad library -> bad result). Rather than gum-up the math library docs, I suggest having a FAQ entry or wiki entry somewhere. Getting extreme accuracy is a nebulous topic in general and even more so in Python (where there is very little you can do to prevent double rounding and whatnot). In addition to extreme accuracy issues, there are also performance issues which will vary from implementation to implementation and from release to release. Historically, the docs have tried to rise above the fray and make very few if any promises about accuracy or speed. This should be doubly true when it comes to numerical methods which are a mix of art, science, and dark art (and where the answers to "what is best" may change depending on the range of input values). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Terry J. Reedy added the comment: To include corner cases, I should have asked 'at least as accurate' rather than 'more accurate'. It would be a sad libm that had specialized functions worse than pow, since the specialized functions could, at worse, use pow. For an expert point of view, the reason for math to have the specialized functions is to give access to functions in the libm of the compiler used. A beginner ignorant of such things might wonder whether exp and sqrt are just trivial abbreviations, and if not, which to use. I believe this question has appeared on python-list. It definitely has on StackOverflow. For e**x, there is, for instance, https://stackoverflow.com/questions/30756983/difference-between-math-exp2-an... with this comment "Voting to reopen. There's more going on here than simply "floating-point is inaccurate". In particular, as the two answers explain, there are good reasons to expect exp(x) to be more accurate than e**x. – Mark Dickinson " ;-). Searching "[python] math.sqrt pow" gets more hits. https://stackoverflow.com/questions/18965524/exponentiation-in-python-should... https://stackoverflow.com/questions/33684948/difference-between-1-2-math-sqr... and multiple questions about relative speed. So I am inclined to add "This is generally better than math.e ** x and math.pow(e, 0.5)." (for math.exp) and "than x ** 0.5 and math.pow(x, 0.5)" for math.sqrt, and similarly for cmath.sqrt). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Terry J. Reedy added the comment: Raymond added his comment while I was writing mine. A FAQ with added caveats might be even better, but it will be mostly missed. If we add one, I might add a comment to some of the SO questions. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Raymond Hettinger added the comment: FWIW, these kind of nuances really aren't beginner topics. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: Nuances of expm1(), log1p(), log2() and log10() aren't beginner topics, but they are documented. I think it wouldn't harm if add "This is usually more accurate than ``e ** x`` or ``pow(e, x)``." The only issue is how to distinguish ``math`` constant ``e`` from mathematical constant *e*. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Raymond Hettinger added the comment:
The only issue is how to distinguish ``math`` constant ``e`` from mathematical constant *e*.
Sorry, I think you're inventing an issue here. ``math.e`` is the nearest representable value to the mathematical constant *e*. This is no more interesting or useful that distinguishing ``math.pi`` from the mathematical constant *pi*. I don't know of any other language that tries to split hairs like this. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: This is the original issue, it isn't invented by me. ``math.e`` is the nearest representable value to the mathematical constant *e* and ``math.exp(x)`` is the nearest representable value to the mathematical constant *e* raised to the power *x*, but not the nearest representable value to ``math.e`` raised to the power *x*. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Changes by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- pull_requests: +1216 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: Proposed patch applies Mark's fix to math.expm1() and cmath.exp(), adds the accuracy note to math.exp(), adds italic to mathematical constants, fixes empty lines. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: Could anybody please make a review of PR 1073? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Serhiy Storchaka added the comment: New changeset dbaf746b6de0ee431c809d3175ab40ccc18898a8 by Serhiy Storchaka in branch 'master': bpo-29956: Improve the math.exp() related documentation. (#1073) https://github.com/python/cpython/commit/dbaf746b6de0ee431c809d3175ab40ccc18... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Mark Dickinson added the comment: Can this be closed? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
Changes by Alexander Belopolsky <alexander.belopolsky@gmail.com>: ---------- resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________
participants (5)
-
Alexander Belopolsky -
Mark Dickinson
-
Raymond Hettinger
-
Serhiy Storchaka
-
Terry J. Reedy