math.exp documentation is misleading

[abalkin]

BPO	29956
Nosy	@tim-one, @rhettinger, @terryjreedy, @mdickinson, @abalkin, @serhiy-storchaka
PRs	bpo-29956: Fix misleading documentation for math.exp. #951 bpo-29956: Improve the math.exp() related documentation. #1073

^{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:

assignee = None
closed_at = <Date 2017-05-08.17:14:18.504>
created_at = <Date 2017-03-31.20:08:37.038>
labels = ['3.7', 'docs']
title = 'math.exp documentation is misleading'
updated_at = <Date 2017-05-08.17:14:18.503>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2017-05-08.17:14:18.503>
actor = 'belopolsky'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-05-08.17:14:18.504>
closer = 'belopolsky'
components = ['Documentation']
creation = <Date 2017-03-31.20:08:37.038>
creator = 'belopolsky'
dependencies = []
files = []
hgrepos = []
issue_num = 29956
keywords = []
message_count = 21.0
messages = ['290937', '290939', '290940', '290941', '290948', '290978', '290986', '291285', '291322', '291381', '291387', '291389', '291390', '291391', '291393', '291401', '291410', '291412', '292963', '292971', '293180']
nosy_count = 8.0
nosy_names = ['tim.peters', 'rhettinger', 'terry.reedy', 'mark.dickinson', 'belopolsky', 'stutzbach', 'docs@python', 'serhiy.storchaka']
pr_nums = ['951', '1073']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29956'
versions = ['Python 3.7']

[abalkin]

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."

[serhiy-storchaka]

This is because math.e is not the same as e.

[abalkin]

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.

[serhiy-storchaka]

*e*:sup:`x` ? I like this idea.

[rhettinger]

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.exp.html

• https://www.gnu.org/software/libc/manual/html_node/Exponents-and-Logarithms.html

[mdickinson]

I suggest changing the main docs to match the existing docstring, "Return e raised to the power of x."

+1 for this description.

[mdickinson]

PR made. New wording is:

"""
Return e raised to the power *x*, where e = 2.718281... is the base of natural logarithms.
"""

[terryjreedy]

Is math.exp(x) always more accurate than math.e ** x? If so, doc could say so. Otherwise, should this be closed?

[serhiy-storchaka]

Not always. For example for x = 0 both methods give the same exact result.

[mdickinson]

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.

[rhettinger]

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).

[terryjreedy]

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-and-math-e2
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-i-prefer-operator-instead-of-math-pow-and-m
https://stackoverflow.com/questions/33684948/difference-between-1-2-math-sqrt-and-cmath-sqrt
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).

[terryjreedy]

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.

[rhettinger]

FWIW, these kind of nuances really aren't beginner topics.

[serhiy-storchaka]

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.

[rhettinger]

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.

[serhiy-storchaka]

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.

[serhiy-storchaka]

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.

[serhiy-storchaka]

Could anybody please make a review of PR 1073?

[serhiy-storchaka]

New changeset dbaf746 by Serhiy Storchaka in branch 'master':
bpo-29956: Improve the math.exp() related documentation. (bpo-1073)
dbaf746

[mdickinson]

Can this be closed?