New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
math.exp documentation is misleading #74142
Comments
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." |
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. |
*e*:sup:`x` ? I like this idea. |
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". |
+1 for this description. |
PR made. New wording is: """ |
Is math.exp(x) always more accurate than math.e ** x? If so, doc could say so. Otherwise, should this be closed? |
Not always. For example for x = 0 both methods give the same exact result. |
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 |
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). |
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, Searching "[python] math.sqrt pow" gets more hits. 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). |
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. |
FWIW, these kind of nuances really aren't beginner topics. |
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 The only issue is how to distinguish |
Sorry, I think you're inventing an issue here. |
This is the original issue, it isn't invented by me. |
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. |
Could anybody please make a review of PR 1073? |
Can this be closed? |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: