@@ -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