DOC: Representing big float32 numbers as string
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 32.8k
- Forks
- 12.8k
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 197
Description
Issue with current documentation:
While working with float numbers using np.float32 datatype I noticed that using rather big numbers (which does not have fraction) and printing them (or just representing as string) can mislead.
Example code below shows, how representing np.float32 number as string can mislead.
import numpy as np
num = np.nextafter(np.float32(134217720), np.float32(np.inf))
print(num) # 134217730
Number 134217720 belongs to the interval $[2^{26}, 2^{27}]$, where precision (or the smallest difference between two nearest numbers) is 8. So if we what to take the next after 134217720 we should get 134217728 (which can directly stored as float32 without conversion error unlike 134217730).
Even if 134217728 casted to np.float32 datatype and we want to represent it as a string, we will get 134217730
num = np.float32(134217728)
print(num) # 134217730
Going deeper, I found that there is a format_float_positional function which is responsible for representing float as a string (I don't know how do __str__ or __repr__ functions work for np.float32 but looks like they have the same behavior). It has a unique parament which is True by default. From documentation:
If True, use a digit-generation strategy which gives the shortest representation which uniquely identifies the floating-point number from other values of the same type, by judicious rounding
So it means that 134217730 is a shortest unique representation for 134217728 made by judicious rounding (Dragon4 algorithm), which looks weird. And as the number becomes bigger inaccuracy by rounding increases.
Of course this kind of representation is more convenient when you work with small numbers, but in this case (especially if you don't about float representation at all) it misleads.
Idea or request for content:
So I don't know is it a bug, but may be it's a good idea to make a remark in docs describing that effect starting with large numbers.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the linked format_float_positional implementation in numpy/core/arrayprint.py and its API documentation, focusing on the unique=True behavior for large float32 values. Check how the existing documentation presents string conversion and determine where a remark would fit. Done means documenting the potentially surprising rounded representation and adding an appropriate example or explanation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- numpy, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100