Clarify docs for math.log1p()

[rhettinger]

BPO	37454
Nosy	@tim-one, @rhettinger, @mdickinson, @stevendaprano
Files	study_log1p.py: Accuracy tests

^{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 2019-08-23.06:59:20.577>
created_at = <Date 2019-06-30.22:19:38.280>
labels = ['invalid', '3.8', '3.9', 'docs']
title = 'Clarify docs for math.log1p()'
updated_at = <Date 2019-08-23.15:08:15.767>
user = 'https://github.com/rhettinger'

bugs.python.org fields:

activity = <Date 2019-08-23.15:08:15.767>
actor = 'tim.peters'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-08-23.06:59:20.577>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2019-06-30.22:19:38.280>
creator = 'rhettinger'
dependencies = []
files = ['48448']
hgrepos = []
issue_num = 37454
keywords = []
message_count = 6.0
messages = ['346942', '346966', '346969', '347034', '350257', '350305']
nosy_count = 5.0
nosy_names = ['tim.peters', 'rhettinger', 'mark.dickinson', 'steven.daprano', 'docs@python']
pr_nums = []
priority = 'low'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue37454'
versions = ['Python 3.8', 'Python 3.9']

[rhettinger]

Currently the docs say, "The result is calculated in a way which is accurate for x near zero."

That is somewhat vague. Some quick tests show that it is often more accurate than log() for the whole range of 0.0 < x < 1.0; however, for x < 0.0 it is always worse.

Since the function is just a pass-through to the C library, we probably can't make any guarantees. On the other hand, it is hard to know when this function is preferred without some guidance.

[mdickinson]

however, for x < 0.0 it is always worse

That's quite surprising. Which platform? And can you give some example inputs and outputs? With a good math library, I'd expect log1p(x) to almost always be at least as accurate as log(1 + x), and substantially more accurate for small x (say abs(x) < 1e-5). If that's not happening, we may want to substitute our own implementation for the system implementation on some platforms (in the same was as we did for lgamma, erf, and friends).

[mdickinson]

Ah, now I've looked at the script. There's an issue with using random.random() to create "small" values for testing, since its result is always an integer multiple of 2**-53. That means in particular that if x = random.random(), then 1 - x is always exactly representable (and 1 + x is also exactly representable approximately half of the time), so there's no loss of accuracy in the intermediate step of computing log(1 + x) if x = -random.random().

Here's what I get if I run your script exactly as it stands (Python 3.7.3, macOS 10.14.5)

mirzakhani:Desktop mdickinson$ python test.py
Counter({'equal': 51839, 'offset_log': 41988, 'regular_log': 6173})
Counter({'equal': 93727, 'regular_log': 6273})

But if I replace each random.random() call with 1e-3 * random.random(), in order to test small values of x, here's what I get:

mirzakhani:Desktop mdickinson$ python test.py
Counter({'offset_log': 99945, 'equal': 55})
Counter({'offset_log': 99893, 'equal': 107})

[tim-one]

Mark's analysis is spot-on - good eye :-)

Here under 3.7.3 [MSC v.1916 64 bit (AMD64)] on win32, in the original script it makes no difference at all for negative "small x" (where, as Mark said, 1 - random.random() is exactly representable):

Counter({'equal': 50058, 'offset_log': 41936, 'regular_log': 8006})
Counter({'equal': 100000})

Changing to Mark's 1e-3 * random.random():

Counter({'offset_log': 99958, 'equal': 42})
Counter({'offset_log': 99884, 'equal': 116})

And going on to use 1e-6 instead:

Counter({'offset_log': 100000})
Counter({'offset_log': 100000})

[rhettinger]

Sometimes you guys make me feel dumb as a rock. Sorry for the distraction.

[tim-one]

Sometimes you guys make me feel dumb as a rock.

I expect we all do that favor for each other at times ;-)