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.
The primitive types supported are tied closely to those in C:
Numpy type | C type | Description |
---|---|---|
np.bool_ |
| Boolean (True or False) stored as a byte |
np.byte |
| Platform-defined |
np.ubyte |
| Platform-defined |
np.short |
| Platform-defined |
np.ushort |
| Platform-defined |
np.intc |
| Platform-defined |
np.uintc |
| Platform-defined |
np.int_ |
| Platform-defined |
np.uint |
| Platform-defined |
np.longlong |
| Platform-defined |
np.ulonglong |
| Platform-defined |
np.half / np.float16 | Half precision float:sign bit, 5 bits exponent, 10 bits mantissa | |
np.single |
| Platform-defined single precision float:typically sign bit, 8 bits exponent, 23 bits mantissa |
np.double |
| Platform-defined double precision float:typically sign bit, 11 bits exponent, 52 bits mantissa. |
np.longdouble |
| Platform-defined extended-precision float |
np.csingle |
| Complex number, represented by two single-precision floats (real and imaginary components) |
np.cdouble |
| Complex number, represented by two double-precision floats (real and imaginary components). |
np.clongdouble |
| Complex number, represented by two extended-precision floats (real and imaginary components). |
Since many of these have platform-dependent definitions, a set of fixed-sizealiases are provided:
Numpy type | C type | Description |
---|---|---|
np.int8 |
| Byte (-128 to 127) |
np.int16 |
| Integer (-32768 to 32767) |
np.int32 |
| Integer (-2147483648 to 2147483647) |
np.int64 |
| Integer (-9223372036854775808 to 9223372036854775807) |
np.uint8 |
| Unsigned integer (0 to 255) |
np.uint16 |
| Unsigned integer (0 to 65535) |
np.uint32 |
| Unsigned integer (0 to 4294967295) |
np.uint64 |
| Unsigned integer (0 to 18446744073709551615) |
np.intp |
| Integer used for indexing, typically the same as |
np.uintp |
| Integer large enough to hold a pointer |
np.float32 |
| |
np.float64 / np.float_ |
| Note that this matches the precision of the builtin python float. |
np.complex64 |
| Complex number, represented by two 32-bit floats (real and imaginary components) |
np.complex128 / np.complex_ |
| Note that this matches the precision of the builtin python complex. |
NumPy numerical types are instances of dtype
(data-type) objects, eachhaving unique characteristics. Once you have imported NumPy using
>>> import numpy as np
the dtypes are available as np.bool_
, np.float32
, etc.
Advanced types, not listed in the table above, are explored insection Structured arrays.
There are 5 basic numerical types representing booleans (bool), integers (int),unsigned integers (uint) floating point (float) and complex. Those with numbersin their name indicate the bitsize of the type (i.e. how many bits are neededto represent a single value in memory). Some types, such as int
andintp
, have differing bitsizes, dependent on the platforms (e.g. 32-bitvs. 64-bit machines). This should be taken into account when interfacingwith low-level code (such as C or Fortran) where the raw memory is addressed.
Data-types can be used as functions to convert python numbers to array scalars(see the array scalar section for an explanation), python sequences of numbersto arrays of that type, or as arguments to the dtype keyword that many numpyfunctions or methods accept. Some examples:
>>> import numpy as np>>> x = np.float32(1.0)>>> x1.0>>> y = np.int_([1,2,4])>>> yarray([1, 2, 4])>>> z = np.arange(3, dtype=np.uint8)>>> zarray([0, 1, 2], dtype=uint8)
Array types can also be referred to by character codes, mostly to retainbackward compatibility with older packages such as Numeric. Somedocumentation may still refer to these, for example:
>>> np.array([1, 2, 3], dtype='f')array([ 1., 2., 3.], dtype=float32)
We recommend using dtype objects instead.
To convert the type of an array, use the .astype() method (preferred) orthe type itself as a function. For example:
>>> z.astype(float) array([ 0., 1., 2.])>>> np.int8(z)array([0, 1, 2], dtype=int8)
Note that, above, we use the Python float object as a dtype. NumPy knowsthat int
refers to np.int_
, bool
means np.bool_
,that float
is np.float_
and complex
is np.complex_
.The other data-types do not have Python equivalents.
To determine the type of an array, look at the dtype attribute:
>>> z.dtypedtype('uint8')
dtype objects also contain information about the type, such as its bit-widthand its byte-order. The data type can also be used indirectly to queryproperties of the type, such as whether it is an integer:
>>> d = np.dtype(int)>>> ddtype('int32')>>> np.issubdtype(d, np.integer)True>>> np.issubdtype(d, np.floating)False
Array Scalars¶
NumPy generally returns elements of arrays as array scalars (a scalarwith an associated dtype). Array scalars differ from Python scalars, butfor the most part they can be used interchangeably (the primaryexception is for versions of Python older than v2.x, where integer arrayscalars cannot act as indices for lists and tuples). There are someexceptions, such as when code requires very specific attributes of a scalaror when it checks specifically whether a value is a Python scalar. Generally,problems are easily fixed by explicitly converting array scalarsto Python scalars, using the corresponding Python type function(e.g., int
, float
, complex
, str
, unicode
).
The primary advantage of using array scalars is thatthey preserve the array type (Python may not have a matching scalar typeavailable, e.g. int16
). Therefore, the use of array scalars ensuresidentical behaviour between arrays and scalars, irrespective of whether thevalue is inside an array or not. NumPy scalars also have many of the samemethods arrays do.
Overflow Errors¶
The fixed size of NumPy numeric types may cause overflow errors when a valuerequires 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>>> np.power(100, 8, dtype=np.int32)1874919424
The behaviour of NumPy and Python integer types differs significantly forinteger overflows and may confuse users expecting NumPy integers to behavesimilar to Python’s int
. Unlike NumPy, the size of Python’s int
isflexible. This means Python integers may expand to accommodate any integer andwill not overflow.
NumPy provides numpy.iinfo and numpy.finfo to verify theminimum or maximum values of NumPy integer and floating point valuesrespectively
>>> np.iinfo(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 integeriinfo(min=-2147483648, max=2147483647, dtype=int32)>>> np.iinfo(np.int64) # Bounds of a 64-bit integeriinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)
If 64-bit integers are still too small the result may be cast to afloating 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 int0>>> np.power(100, 100, dtype=np.float64)1e+200
Extended Precision¶
Python’s floating-point numbers are usually 64-bit floating-point numbers,nearly equivalent to np.float64
. In some unusual situations it may beuseful to use floating-point numbers with more precision. Whether thisis possible in numpy depends on the hardware and on the developmentenvironment: specifically, x86 machines provide hardware floating-pointwith 80-bit precision, and while most C compilers provide this as theirlong double
type, MSVC (standard for Windows builds) makeslong double
identical to double
(64 bits). NumPy makes thecompiler’s long double
available as np.longdouble
(andnp.clongdouble
for the complex numbers). You can find out what yournumpy provides with np.finfo(np.longdouble)
.
NumPy does not provide a dtype with more precision than C’slong double
; in particular, the 128-bit IEEE quad precisiondata type (FORTRAN’s REAL*16
) is not available.
For efficient memory alignment, np.longdouble
is usually storedpadded with zero bits, either to 96 or 128 bits. Which is more efficientdepends on hardware and development environment; typically on 32-bitsystems they are padded to 96 bits, while on 64-bit systems they aretypically padded to 128 bits. np.longdouble
is padded to the systemdefault; np.float96
and np.float128
are provided for users whowant specific padding. In spite of the names, np.float96
andnp.float128
provide only as much precision as np.longdouble
,that is, 80 bits on most x86 machines and 64 bits in standardWindows builds.
Be warned that even if np.longdouble
offers more precision thanpython float
, it is easy to lose that extra precision, sincepython often forces values to pass through float
. For example,the %
formatting operator requires its arguments to be convertedto standard python types, and it is therefore impossible to preserveextended precision even if many decimal places are requested. It canbe useful to test your code with the value1 + np.finfo(np.longdouble).eps
.