Skip to content

Commit a7a98fb

Browse files
ahaldanemaxwell-aladago
authored andcommitted
DOC: update np.around docstring with note about floating-point error
Fixes numpy#14391 [ci-skip]
1 parent 56063c2 commit a7a98fb

1 file changed

Lines changed: 29 additions & 4 deletions

File tree

‎numpy/core/fromnumeric.py‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3125,10 +3125,35 @@ def around(a, decimals=0, out=None):
31253125
-----
31263126
For values exactly halfway between rounded decimal values, NumPy
31273127
rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0,
3128-
-0.5 and 0.5 round to 0.0, etc. Results may also be surprising due
3129-
to the inexact representation of decimal fractions in the IEEE
3130-
floating point standard [1]_ and errors introduced when scaling
3131-
by powers of ten.
3128+
-0.5 and 0.5 round to 0.0, etc.
3129+
3130+
``np.around`` uses a fast but sometimes inexact algorithm to round
3131+
floating-point datatypes. For positive `decimals` it is equivalent to
3132+
``np.true_divide(np.rint(a * 10**decimals), 10**decimals)``, which is
3133+
inexact for large floating-point values or large values of `decimals` due
3134+
the inexact representation of decimal fractions in the IEEE floating point
3135+
standard [1]_ and errors introduced when scaling by powers of ten. For
3136+
instance, note the extra "1" in the following:
3137+
3138+
>>> np.round(56294995342131.5, 3)
3139+
56294995342131.51
3140+
3141+
If your goal is to print such values with a fixed number of decimals, it is
3142+
preferable to use numpy's float printing routines to limit the number of
3143+
printed decimals:
3144+
3145+
>>> np.format_float_positional(56294995342131.5, precision=3)
3146+
'56294995342131.5'
3147+
3148+
The float printing routines use an accurate but much more computationally
3149+
demanding algorithm to compute the number of digits after the decimal
3150+
point.
3151+
3152+
Alternatively, Python's builtin `round` function uses a more accurate
3153+
but slower algorithm for 64-bit floating point values:
3154+
3155+
>>> round(56294995342131.5, 3)
3156+
56294995342131.5
31323157
31333158
References
31343159
----------

0 commit comments

Comments
 (0)