DOC: Clarify tiny/xmin in finfo and machar (gh-16253) #16253
Conversation
This commit adds a note to the documentation of finfo clarifying that the attribute `tiny` does not represent the smallest positive usable number. Instead it refers to the smallest positive number with there being no leading 0's in the mantisse (normalized floating point number). Alternatively, `tiny` represents the smallest positive floating point number with full precision. The smallest positive subnormal floating point number is typically orders of magnitudes smaller, but has reduced precision since leading 0's in the mantisse are used to allow smaller exponents than indicated by `minexp`. The commit also adds a brief clarification to the docstring of machar. Closes numpy#16252
There was a problem hiding this comment.
This is a nice clarification for the docs; however, it might be worth considering replacing some of the text that has been added with an external reference. The descriptions are valuable and interesting, but a lot of the details are not NumPy-specific and thus a more brief summary followed by a reference might be more appropriate. IMO the wiki page on denormal numbers provides a nice overview of some of the details that have been added here.
More concise version of the clarification in finfo, as recommended by @rossbar.
Co-authored-by: Anirudh Subramanian <anirudh2290@apache.org>
numpy/core/getlimits.py
Outdated
| The smallest positive floating point number with there being no | ||
| leading 0's in the mantissa. Type of `tiny` is an appropriate | ||
| floating point type. |
There was a problem hiding this comment.
| The smallest positive floating point number with there being no | |
| leading 0's in the mantissa. Type of `tiny` is an appropriate | |
| floating point type. | |
| The smallest positive non-subnormal (see Notes) floating point | |
| number. Type of `tiny` is an appropriate floating point type. |
This is just my opinion, but I have a slight preference for leaving the details of denormal numbers (i.e. "being no leading 0's in the mantissa") out of the parameter description and instead refer to greater levels of detail outside of the parameters section.
LMK what you think!
There was a problem hiding this comment.
@rossbar That is fine with me, too.
Please take note that I used the phrase "being no leading 0's in the mantissa" since it already appeared in the description of another parameter in the same docstring. Cf. minexp.
To keep it consistent, I guess, we should modify the phrase there as well. What do you think?
There was a problem hiding this comment.
Yeah, I was suprised how often we used "mantissa" since I am not sure its a good start for a general audience. I liked the "with full precision", but overall, I guess a see notes is just the right way to explain it.
Mainly commenting, because it seemed to me like we can just drop the current second sentence, saying that it gives out the correct type seems pretty irrelevant (all of these are obviously returned as the same type as is being queried).
There was a problem hiding this comment.
As for "mantissa" - I think we should prefer "significand". See also this stronger opinion against mantissa
There was a problem hiding this comment.
Okay, I tried to combine these comments in the most recent commit. In particular, I tried
to avoid usage of the word mantissa if possible.
Regarding the matter "significand" vs. "mantissa": I have no strong feelings about this. The former is used in the IEEE 754-standard, while the latter seems to be a bit more common in the scientific computing literature. But I have no overview how often and where mantissa is in use within the NumPy documentation. For instance, finfo has the attribute nmant which would need to be renamed, too.
So, this topic might be a little beyond the scope of this PR.
Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>
Docstrings are modified to reflect recent comments to PR.
There was a problem hiding this comment.
The changes pertaining to Notes and tiny look good to me (except for a couple minor formatting notes). However, I think something might have been lost in the changes to minexp - I think the original wording "power of the base" or "power of ibeta" was valuable. I don't mind the getting rid of the explicit use of "mantissa" in favor of the "full precision" wording, but I think the removal of the description of the exponent should be undone.
Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>
|
Regarding However, in my opinion the descriptions given for each attribute currently differ somewhat in the level of detail. But perhaps this can be better addressed in a general revision that also deals with the "mantissa" vs. "significand" issue. |
|
Thanks @rk-mlu for improving this and Ross for the review! |
This commit adds a note to the documentation of finfo clarifying that
the attribute
tinydoes not represent the smallest positive usablenumber. Instead, it refers to the smallest positive number with there
being no leading 0's in the mantissa, that is, the smallest positive
normalized floating-point number.
Alternatively, one can say that
tinyis the smallest positive floatingpoint number with full precision. The smallest positive subnormal
floating point number is typically orders of magnitudes smaller, but
has reduced precision since leading 0's in the mantissa are used to
allow smaller exponents than indicated by
minexp.The commit also adds a brief clarification to the docstring of machar.
Closes #16252