gh-101594: Resolve a disambiguation of math.e vs the Euler's number #102040
Conversation
skirpichev
commented
Feb 19, 2023
•
skirpichev
commented
- Issue: Incorrect docstring of math.exp (math.e vs Euler's number) #101594
|
Few remarks:
|
| Return *e* raised to the power *x*, minus 1. Here *e* is the base of natural | ||
| logarithms. For small floats *x*, the subtraction in ``exp(x) - 1`` | ||
| can result in a `significant loss of precision | ||
| Return ``exp(x) - 1``. For small floats *x*, the direct subtraction |
There was a problem hiding this comment.
I find this first sentence misleading - it seems to suggest the Python expression exp(x) - 1 is returned. I think a words-only approach is best. Something like
Return the exponential function at *x*, minus 1.
With this change, I also don't think direct is needed.
Thoughts?
| @@ -644,7 +644,7 @@ PyDoc_STRVAR(cmath_log__doc__, | |||
| "\n" | |||
| "log(z[, base]) -> the logarithm of z to the given base.\n" | |||
| "\n" | |||
| "If the base not specified, returns the natural logarithm (base e) of z."); | |||
| "If the base not specified, returns the natural logarithm of z."); | |||
There was a problem hiding this comment.
| "If the base not specified, returns the natural logarithm of z."); | |
| "If the base is not specified, returns the natural logarithm of z."); |
There was a problem hiding this comment.
I know this is just something we inherited from a past commit, but reasonable to correct, no?
There was a problem hiding this comment.
I think the "base e" should be kept here; I think it's genuinely useful to those reading the docs who might otherwise expect the base to be 10 (or 2), and who haven't encountered the term "natural logarithm" before.
I understand that the goal of this PR is to resolve a theoretical ambiguity between the float value math.e and Euler's number, but I honestly don't think that ambiguity is likely to confuse people in practice.
For correctness, I'd suggest using *e* throughout (i.e., italicised normal text) when referring to Euler's number, and code-style formatting (using backticks) when referring to math.e. But I think this blanket removal of references to e is more harmful than helpful.
There was a problem hiding this comment.
I'd suggest using e throughout
It's almost tempting to suggest using U+1D452 ("𝑒", or 'MATHEMATICAL ITALIC SMALL E'). That's exactly the right character to use in this context, but it's outside the Unicode basic multilingual plane, and I suspect that there would be rendering problems on at least some platforms.
There was a problem hiding this comment.
I honestly don't think that ambiguity is likely to confuse people in practice.
Well, there was an example from the issue thread.
There was a problem hiding this comment.
Well, there was an example from the #101594 (comment).
Sorry, not convinced: you claim that Steven misinterpreted an e in the docstring as meaning math.e. Only @stevendaprano can tell us for sure, but I don't get that at all from his comment.
| @@ -957,12 +957,12 @@ cmath.log | |||
|
|
|||
| log(z[, base]) -> the logarithm of z to the given base. | |||
|
|
|||
| If the base not specified, returns the natural logarithm (base e) of z. | |||
| If the base not specified, returns the natural logarithm of z. | |||
There was a problem hiding this comment.
@OTheDev Good spot! It may be worth creating a separate PR to fix (i.e. a PR that just adds the missing "is"). That at least would be uncontroversial.
As things stand, I'm inclined to reject this PR - I don't think it represents an overall increase in clarity.
| @@ -85,8 +85,7 @@ Power and logarithmic functions | |||
|
|
|||
| .. function:: exp(x) | |||
|
|
|||
| Return *e* raised to the power *x*, where *e* is the base of natural | |||
| logarithms. | |||
| Return the exponential function at *x*. | |||
There was a problem hiding this comment.
I don't think this is an improvement. "exponential function" is ambiguous - the function 10**x is an exponential function, for example. (Or at least, many US pre-calculus texts describe it as such.)
We could follow the C standard's lead and use the wording "the base-e exponential function".
Or we could leave as-is. I don't think the existing wording is likely to confuse anyone.
There was a problem hiding this comment.
"exponential function" is ambiguous - the function 10**x is an exponential function, for example.
Hmm, I wasn't aware. Perhaps, I've checked too few sources...
https://mathworld.wolfram.com/ExponentialFunction.html
https://en.wikipedia.org/wiki/Exponential_function
A&S
encyclopediaofmath
maple
functions.wolfram.com
Less common seems to be "the exponential of" (Mathematica, numpy, matlab, mpfr/mpc).
Or we could leave as-is. I don't think the existing wording is likely to confuse anyone.
You can decide:) Here it is: #101594. If you think that this will not confuse readers - then it's ok to be as-is.
| Return *e* raised to the power *x*, where *e* = 2.718281... is the base | ||
| of natural logarithms. This is usually more accurate than ``math.e ** x`` | ||
| or ``pow(math.e, x)``. | ||
| Return the exponential function at *x*. This is usually more accurate |
There was a problem hiding this comment.
Again, the new description is ambiguous; I think the existing description is better.
|
Thanks for review. |
