From 34075a54e7aa10e80d41ef33ec7102292ecff0d5 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sat, 10 Jun 2017 15:56:14 +1200 Subject: DOC: BLD: fix lots of Sphinx warnings/errors. --- numpy/doc/basics.py | 60 ++++++++++++++++++++++++++--------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index dac236644..083d55a84 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -9,36 +9,36 @@ Array types and conversions between types NumPy supports a much greater variety of numerical types than Python does. This section shows which are available, and how to modify an array's data-type. -========== ========================================================== -Data type Description -========== ========================================================== -bool_ Boolean (True or False) stored as a byte -int_ Default integer type (same as C ``long``; normally either - ``int64`` or ``int32``) -intc Identical to C ``int`` (normally ``int32`` or ``int64``) -intp Integer used for indexing (same as C ``ssize_t``; normally - either ``int32`` or ``int64``) -int8 Byte (-128 to 127) -int16 Integer (-32768 to 32767) -int32 Integer (-2147483648 to 2147483647) -int64 Integer (-9223372036854775808 to 9223372036854775807) -uint8 Unsigned integer (0 to 255) -uint16 Unsigned integer (0 to 65535) -uint32 Unsigned integer (0 to 4294967295) -uint64 Unsigned integer (0 to 18446744073709551615) -float_ Shorthand for ``float64``. -float16 Half precision float: sign bit, 5 bits exponent, - 10 bits mantissa -float32 Single precision float: sign bit, 8 bits exponent, - 23 bits mantissa -float64 Double precision float: sign bit, 11 bits exponent, - 52 bits mantissa -complex_ Shorthand for ``complex128``. -complex64 Complex number, represented by two 32-bit floats (real - and imaginary components) -complex128 Complex number, represented by two 64-bit floats (real - and imaginary components) -========== ========================================================== +============ ========================================================== +Data type Description +============ ========================================================== +``bool_`` Boolean (True or False) stored as a byte +``int_`` Default integer type (same as C ``long``; normally either + ``int64`` or ``int32``) +intc Identical to C ``int`` (normally ``int32`` or ``int64``) +intp Integer used for indexing (same as C ``ssize_t``; normally + either ``int32`` or ``int64``) +int8 Byte (-128 to 127) +int16 Integer (-32768 to 32767) +int32 Integer (-2147483648 to 2147483647) +int64 Integer (-9223372036854775808 to 9223372036854775807) +uint8 Unsigned integer (0 to 255) +uint16 Unsigned integer (0 to 65535) +uint32 Unsigned integer (0 to 4294967295) +uint64 Unsigned integer (0 to 18446744073709551615) +``float_`` Shorthand for ``float64``. +float16 Half precision float: sign bit, 5 bits exponent, + 10 bits mantissa +float32 Single precision float: sign bit, 8 bits exponent, + 23 bits mantissa +float64 Double precision float: sign bit, 11 bits exponent, + 52 bits mantissa +``complex_`` Shorthand for ``complex128``. +complex64 Complex number, represented by two 32-bit floats (real + and imaginary components) +complex128 Complex number, represented by two 64-bit floats (real + and imaginary components) +============ ========================================================== Additionally to ``intc`` the platform dependent C integer types ``short``, ``long``, ``longlong`` and their unsigned versions are defined. -- cgit v1.2.1 From ec3710f9b5f9957e57cf11cadac34a8c3e69cc79 Mon Sep 17 00:00:00 2001 From: Dillon Niederhut Date: Fri, 14 Jul 2017 05:37:39 -0500 Subject: DOC: correct formatting of basic.types.html In the documentation for types allowed in numpy, missing spaces around the backticks for fixed-width formatting cause code examples to appear as plain text, or are causing plain text to appear as code. This commit fixes back tick spacing in the 'Extended Precision' section of the 'Data Types' page. --- 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 083d55a84..40fb0501e 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -155,11 +155,11 @@ with 80-bit precision, and while most C compilers provide this as their ``long double`` identical to ``double`` (64 bits). NumPy makes the compiler's ``long double`` available as ``np.longdouble`` (and ``np.clongdouble`` for the complex numbers). You can find out what your -numpy provides with``np.finfo(np.longdouble)``. +numpy provides with ``np.finfo(np.longdouble)``. NumPy does not provide a dtype with more precision than C -``long double``s; in particular, the 128-bit IEEE quad precision -data type (FORTRAN's ``REAL*16``) is not available. +``long double`` s; in particular, the 128-bit IEEE quad precision +data type (FORTRAN's ``REAL*16`` ) is not available. For efficient memory alignment, ``np.longdouble`` is usually stored padded with zero bits, either to 96 or 128 bits. Which is more efficient -- cgit v1.2.1 From 3d58387717eeb5d8aebe1d712ddbbd04adef2cb2 Mon Sep 17 00:00:00 2001 From: Dillon Niederhut Date: Thu, 27 Jul 2017 00:03:08 -0600 Subject: DOC: removes extraneous whitespace with escapes [ci-skip] --- 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 40fb0501e..b79fb2a86 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -155,11 +155,11 @@ with 80-bit precision, and while most C compilers provide this as their ``long double`` identical to ``double`` (64 bits). NumPy makes the compiler's ``long double`` available as ``np.longdouble`` (and ``np.clongdouble`` for the complex numbers). You can find out what your -numpy provides with ``np.finfo(np.longdouble)``. +numpy provides with ``np.finfo(np.longdouble)``\. NumPy does not provide a dtype with more precision than C -``long double`` s; in particular, the 128-bit IEEE quad precision -data type (FORTRAN's ``REAL*16`` ) is not available. +``long double``\s; in particular, the 128-bit IEEE quad precision +data type (FORTRAN's ``REAL*16``\) is not available. For efficient memory alignment, ``np.longdouble`` is usually stored padded with zero bits, either to 96 or 128 bits. Which is more efficient -- cgit v1.2.1 From fb004f8bc610b0cf52342d35314a9e0a0434e745 Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Tue, 1 Aug 2017 17:40:56 +0000 Subject: MAINT: Stop using the undocumented coercion-then-downcast feature of subdtype --- numpy/doc/basics.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index 083d55a84..10d7248c1 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -114,10 +114,10 @@ properties of the type, such as whether it is an integer:: >>> d dtype('int32') - >>> np.issubdtype(d, int) + >>> np.issubdtype(d, np.integer) True - >>> np.issubdtype(d, float) + >>> np.issubdtype(d, np.floating) False -- cgit v1.2.1 From b094453b73a3bf707e2e9864f45f8357e759763c Mon Sep 17 00:00:00 2001 From: Danny Hermes Date: Fri, 11 Aug 2017 12:04:29 -0700 Subject: DOC: Adding backslash between double-backtick and s. --- 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 10d7248c1..4943aa227 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -158,7 +158,7 @@ compiler's ``long double`` available as ``np.longdouble`` (and numpy provides with``np.finfo(np.longdouble)``. NumPy does not provide a dtype with more precision than C -``long double``s; in particular, the 128-bit IEEE quad precision +``long double``\s; in particular, the 128-bit IEEE quad precision data type (FORTRAN's ``REAL*16``) is not available. For efficient memory alignment, ``np.longdouble`` is usually stored -- cgit v1.2.1 From 01d5886a5ad760e7a27f2f7d715177fafb3777cd Mon Sep 17 00:00:00 2001 From: Dillon Niederhut Date: Fri, 11 Aug 2017 18:29:37 -0500 Subject: DOC: reverts some escapes [ci-skip] --- numpy/doc/basics.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index b79fb2a86..76d455cd0 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -155,10 +155,10 @@ with 80-bit precision, and while most C compilers provide this as their ``long double`` identical to ``double`` (64 bits). NumPy makes the compiler's ``long double`` available as ``np.longdouble`` (and ``np.clongdouble`` for the complex numbers). You can find out what your -numpy provides with ``np.finfo(np.longdouble)``\. +numpy provides with ``np.finfo(np.longdouble)``. NumPy does not provide a dtype with more precision than C -``long double``\s; in particular, the 128-bit IEEE quad precision +``long double``s; in particular, the 128-bit IEEE quad precision data type (FORTRAN's ``REAL*16``\) is not available. For efficient memory alignment, ``np.longdouble`` is usually stored -- cgit v1.2.1 From d12b8d835708018fbb4e2ce5c6a6c3f9abd6bbb0 Mon Sep 17 00:00:00 2001 From: Charles Harris Date: Sun, 13 Aug 2017 16:55:36 -0600 Subject: DOC, BUG: Fix Python 3.6 invalid escape sequence. The rst markup in numpy/doc/basics.py uses `\s`, which is interpreted by python 3.6 as a deprecated escape sequence. Fix by escaping the `\`. Closes #9551. [ci skip] --- numpy/doc/basics.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index d0d384a62..4d3ab046e 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -158,8 +158,8 @@ compiler's ``long double`` available as ``np.longdouble`` (and numpy provides with ``np.finfo(np.longdouble)``. NumPy does not provide a dtype with more precision than C -``long double``\s; in particular, the 128-bit IEEE quad precision -data type (FORTRAN's ``REAL*16``\) is not available. +``long double``\\s; in particular, the 128-bit IEEE quad precision +data type (FORTRAN's ``REAL*16``\\) is not available. For efficient memory alignment, ``np.longdouble`` is usually stored padded with zero bits, either to 96 or 128 bits. Which is more efficient -- cgit v1.2.1 From 8905b891950e66e69dd15c6144d56ad5dac90ae0 Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Thu, 30 Aug 2018 00:05:28 -0700 Subject: DOC: Make clear the connection between numpy types and C types --- numpy/doc/basics.py | 184 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 151 insertions(+), 33 deletions(-) (limited to 'numpy/doc/basics.py') diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index 4d3ab046e..c87a40ccd 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -9,39 +9,157 @@ Array types and conversions between types NumPy supports a much greater variety of numerical types than Python does. This section shows which are available, and how to modify an array's data-type. -============ ========================================================== -Data type Description -============ ========================================================== -``bool_`` Boolean (True or False) stored as a byte -``int_`` Default integer type (same as C ``long``; normally either - ``int64`` or ``int32``) -intc Identical to C ``int`` (normally ``int32`` or ``int64``) -intp Integer used for indexing (same as C ``ssize_t``; normally - either ``int32`` or ``int64``) -int8 Byte (-128 to 127) -int16 Integer (-32768 to 32767) -int32 Integer (-2147483648 to 2147483647) -int64 Integer (-9223372036854775808 to 9223372036854775807) -uint8 Unsigned integer (0 to 255) -uint16 Unsigned integer (0 to 65535) -uint32 Unsigned integer (0 to 4294967295) -uint64 Unsigned integer (0 to 18446744073709551615) -``float_`` Shorthand for ``float64``. -float16 Half precision float: sign bit, 5 bits exponent, - 10 bits mantissa -float32 Single precision float: sign bit, 8 bits exponent, - 23 bits mantissa -float64 Double precision float: sign bit, 11 bits exponent, - 52 bits mantissa -``complex_`` Shorthand for ``complex128``. -complex64 Complex number, represented by two 32-bit floats (real - and imaginary components) -complex128 Complex number, represented by two 64-bit floats (real - and imaginary components) -============ ========================================================== - -Additionally to ``intc`` the platform dependent C integer types ``short``, -``long``, ``longlong`` and their unsigned versions are defined. +The primitive types supported are tied closely to those in C: + +.. list-table:: + :header-rows: 1 + + * - Numpy type + - C type + - Description + + * - `np.bool` + - ``bool`` + - Boolean (True or False) stored as a byte + + * - `np.byte` + - ``signed char`` + - Platform-defined + + * - `np.ubyte` + - ``unsigned char`` + - Platform-defined + + * - `np.short` + - ``short`` + - Platform-defined + + * - `np.ushort` + - ``unsigned short`` + - Platform-defined + + * - `np.intc` + - ``int`` + - Platform-defined + + * - `np.uintc` + - ``unsigned int`` + - Platform-defined + + * - `np.int_` + - ``long`` + - Platform-defined + + * - `np.uint` + - ``unsigned long`` + - Platform-defined + + * - `np.longlong` + - ``long long`` + - Platform-defined + + * - `np.ulonglong` + - ``unsigned long long`` + - Platform-defined + + * - `np.half` / `np.float16` + - + - Half precision float: + sign bit, 5 bits exponent, 10 bits mantissa + + * - `np.single` + - ``float`` + - Platform-defined single precision float: + typically sign bit, 8 bits exponent, 23 bits mantissa + + * - `np.double` + - ``double`` + - Platform-defined double precision float: + typically sign bit, 11 bits exponent, 52 bits mantissa. + + * - `np.longdouble` + - ``long double`` + - Platform-defined extended-precision float + + * - `np.csingle` + - ``float complex`` + - Complex number, represented by two single-precision floats (real and imaginary components) + + * - `np.cdouble` + - ``double complex`` + - Complex number, represented by two double-precision floats (real and imaginary components). + + * - `np.clongdouble` + - ``long double complex`` + - Complex number, represented by two extended-precision floats (real and imaginary components). + + +Since many of these have platform-dependent definitions, a set of fixed-size +aliases are provided: + +.. list-table:: + :header-rows: 1 + + * - Numpy type + - C type + - Description + + * - `np.int8` + - ``int8_t`` + - Byte (-128 to 127) + + * - `np.int16` + - ``int16_t`` + - Integer (-32768 to 32767) + + * - `np.int32` + - ``int32_t`` + - Integer (-2147483648 to 2147483647) + + * - `np.int64` + - ``int64_t`` + - Integer (-9223372036854775808 to 9223372036854775807) + + * - `np.uint8` + - ``uint8_t`` + - Unsigned integer (0 to 255) + + * - `np.uint16` + - ``uint16_t`` + - Unsigned integer (0 to 65535) + + * - `np.uint32` + - ``uint32_t`` + - Unsigned integer (0 to 4294967295) + + * - `np.uint64` + - ``uint64_t`` + - Unsigned integer (0 to 18446744073709551615) + + * - `np.intp` + - ``intptr_t`` + - Integer used for indexing, typically the same as ``ssize_t`` + + * - `np.uintp` + - ``uintptr_t`` + - Integer large enough to hold a pointer + + * - `np.float32` + - ``float`` + - + + * - `np.float64` / `np.float_` + - ``double`` + - Note that this matches the precision of the builtin python `float`. + + * - `np.complex64` + - ``float complex`` + - Complex number, represented by two 32-bit floats (real and imaginary components) + + * - `np.complex128` / `np.complex_` + - ``double complex`` + - Note that this matches the precision of the builtin python `complex`. + NumPy numerical types are instances of ``dtype`` (data-type) objects, each having unique characteristics. Once you have imported NumPy using -- cgit v1.2.1 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