From e3322b40d6e53a1f4efae9ce3c24f8f5cf58a190 Mon Sep 17 00:00:00 2001 From: kai Date: Sun, 17 Mar 2019 16:26:09 +0800 Subject: DOC: Add description of overflow errorrs Unlike Python, NumPy integers have fixed sizes. This can lead to confusion when a integer overflow occurs and users expect NumPy integer types to behave similarily to Python integers. This commit explains integer overflow, an example and potential work arounds. --- numpy/doc/basics.py | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index c87a40ccd..002682487 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -260,6 +260,45 @@ identical behaviour between arrays and scalars, irrespective of whether the value is inside an array or not. NumPy scalars also have many of the same methods arrays do. +Overflow Errors +=============== + +The fixed size of NumPy numeric types may cause overflow errors when a value +requires more memory than available in the data type. For example, `np.power` +evaluates ``100 * 10 ** 8`` correctly for 64-bit integers, but gives +1874919424 (incorrect) for a 32-bit integer. + + >>> np.power(100, 8, dtype=np.int64) + 10000000000000000 + >>> np.power(100, 8, dtype=np.int32) + 1874919424 + +The behaviour of NumPy and Python integer types differs significantly for +integer overflows and may confuse users expecting NumPy integers to behave +similar to Python's ``int``. Unlike NumPy, the size of Python's ``int`` is +flexible. This means Python integers may expand to accomodate any integer and +will not overflow. + +NumPy provides `numpy.iinfo` and `numpy.finfo` to verify the +minimum or maximum values of NumPy integer and floating point values +respectively :: + + >>> np.iinfo(np.int) # Bounds of the default integer on this system. + iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64) + >>> np.iinfo(np.int32) # Bounds of a 32-bit integer + iinfo(min=-2147483648, max=2147483647, dtype=int32) + >>> np.iinfo(np.int64) # Bounds of a 64-bit integer + iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)s + +If 64-bit integers are still too small the result may be cast to a +floating point number. Floating point numbers offer a larger, but inexact, +range of possible values. + + >>> np.power(100, 100, dtype=np.int64) # Incorrect even with 64-bit int + 0 + >>> np.power(100, 100, dtype=np.float64) + 1e+200 + Extended Precision ================== -- cgit v1.2.1 From 41e14f938587f95c2c0091c05b850bbd5b86354b Mon Sep 17 00:00:00 2001 From: Kai Striega Date: Tue, 19 Mar 2019 15:02:54 +0800 Subject: DOC: Remove extra letter from docs --- numpy/doc/basics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index 002682487..8f9044a0a 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -288,7 +288,7 @@ respectively :: >>> np.iinfo(np.int32) # Bounds of a 32-bit integer iinfo(min=-2147483648, max=2147483647, dtype=int32) >>> np.iinfo(np.int64) # Bounds of a 64-bit integer - iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)s + iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64) If 64-bit integers are still too small the result may be cast to a floating point number. Floating point numbers offer a larger, but inexact, -- cgit v1.2.1 From 9006a1d35fb1a1ebcdbcd0852f6086a73f7a5961 Mon Sep 17 00:00:00 2001 From: Kai Striega Date: Tue, 19 Mar 2019 15:37:18 +0800 Subject: DOC: Minor fix in Integer Overflow doc Change `np.power` -> `numpy.power` to make it reference the function's documentation --- numpy/doc/basics.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index 8f9044a0a..61f5bf4ef 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -264,9 +264,9 @@ Overflow Errors =============== The fixed size of NumPy numeric types may cause overflow errors when a value -requires more memory than available in the data type. For example, `np.power` -evaluates ``100 * 10 ** 8`` correctly for 64-bit integers, but gives -1874919424 (incorrect) for a 32-bit integer. +requires more memory than available in the data type. For example, +`numpy.power` evaluates ``100 * 10 ** 8`` correctly for 64-bit integers, +but gives 1874919424 (incorrect) for a 32-bit integer. >>> np.power(100, 8, dtype=np.int64) 10000000000000000 -- cgit v1.2.1