Evenly round to the given number of decimals. Parameters ---------- a : array_like Input data. decimals : int, optional Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left
(a, decimals=0, out=None)
| 3268 | |
| 3269 | @array_function_dispatch(_round_dispatcher) |
| 3270 | def round(a, decimals=0, out=None): |
| 3271 | """ |
| 3272 | Evenly round to the given number of decimals. |
| 3273 | |
| 3274 | Parameters |
| 3275 | ---------- |
| 3276 | a : array_like |
| 3277 | Input data. |
| 3278 | decimals : int, optional |
| 3279 | Number of decimal places to round to (default: 0). If |
| 3280 | decimals is negative, it specifies the number of positions to |
| 3281 | the left of the decimal point. |
| 3282 | out : ndarray, optional |
| 3283 | Alternative output array in which to place the result. It must have |
| 3284 | the same shape as the expected output, but the type of the output |
| 3285 | values will be cast if necessary. See :ref:`ufuncs-output-type` for more |
| 3286 | details. |
| 3287 | |
| 3288 | Returns |
| 3289 | ------- |
| 3290 | rounded_array : ndarray |
| 3291 | An array of the same type as `a`, containing the rounded values. |
| 3292 | Unless `out` was specified, a new array is created. A reference to |
| 3293 | the result is returned. |
| 3294 | |
| 3295 | The real and imaginary parts of complex numbers are rounded |
| 3296 | separately. The result of rounding a float is a float. |
| 3297 | |
| 3298 | See Also |
| 3299 | -------- |
| 3300 | ndarray.round : equivalent method |
| 3301 | around : an alias for this function |
| 3302 | ceil, fix, floor, rint, trunc |
| 3303 | |
| 3304 | |
| 3305 | Notes |
| 3306 | ----- |
| 3307 | For values exactly halfway between rounded decimal values, NumPy |
| 3308 | rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0, |
| 3309 | -0.5 and 0.5 round to 0.0, etc. |
| 3310 | |
| 3311 | ``np.round`` uses a fast but sometimes inexact algorithm to round |
| 3312 | floating-point datatypes. For positive `decimals` it is equivalent to |
| 3313 | ``np.true_divide(np.rint(a * 10**decimals), 10**decimals)``, which has |
| 3314 | error due to the inexact representation of decimal fractions in the IEEE |
| 3315 | floating point standard [1]_ and errors introduced when scaling by powers |
| 3316 | of ten. For instance, note the extra "1" in the following: |
| 3317 | |
| 3318 | >>> np.round(56294995342131.5, 3) |
| 3319 | 56294995342131.51 |
| 3320 | |
| 3321 | If your goal is to print such values with a fixed number of decimals, it is |
| 3322 | preferable to use numpy's float printing routines to limit the number of |
| 3323 | printed decimals: |
| 3324 | |
| 3325 | >>> np.format_float_positional(56294995342131.5, precision=3) |
| 3326 | '56294995342131.5' |
| 3327 |