NumPy Reference
Release 1.15.1
Written by the NumPy community
August 23, 2018
CONTENTS
1 Array objects
The N-dimensional array (ndarray) .
Scalars .
.
.
.
.
.
.
.
.
.
1.1
1.2
.
1.3 Data type objects (dtype) .
.
1.4
.
1.5
.
1.6
1.7 Masked arrays
.
1.8
.
1.9 Datetimes and Timedeltas .
.
Indexing .
.
Iterating Over Arrays .
.
Standard array subclasses
.
.
.
The Array Interface
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . .
. . .
. . . . .
. . . . . . .
3
3
. . . . . . . . . . . . . . . . . .
46
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
62
.
. . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
77
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
85
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
97
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2 Constants
363
3 Universal functions (ufunc)
.
Broadcasting .
.
.
.
.
.
3.1
.
3.2 Output type determination .
3.3 Use of internal buffers .
.
.
.
3.4
3.5
.
.
3.6 Overriding Ufunc behavior .
3.7
.
.
.
3.8 Available ufuncs .
Error handling .
Casting Rules .
.
ufunc .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
371
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4 Routines
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Binary operations .
String operations .
C-Types Foreign Function Interface (numpy.ctypeslib) . . . . . .
.
4.1 Array creation routines .
4.2 Array manipulation routines .
.
4.3
4.4
.
4.5
4.6 Datetime Support Functions .
4.7 Data type routines
.
4.8 Optionally Scipy-accelerated routines (numpy.dual) . . . .
4.9 Mathematical functions with automatic domain (numpy.emath) . . . . . . . . .
4.10 Floating point error handling .
4.11 Discrete Fourier Transform (numpy.fft) . . . . . .
.
4.12 Financial functions .
.
4.13 Functional programming .
.
4.14 NumPy-specific help functions .
.
4.15 Indexing routines .
4.16 Input and output
.
.
395
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
.
. . . . . . 518
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
.
. . . . . . . . . . . 540
. . . . . . . 541
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
. . . . . . . . . . . . . . . . 546
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
. . . . . . .
. . . . . .
. . . . .
. . . .
. . . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
i
.
.
.
.
.
.
.
.
.
.
.
. . .
. . . . .
. . . . . .
. . . . . . .
. . . . . . . . . . . . . . . . . . . . . 650
4.17 Linear algebra (numpy.linalg)
.
4.18 Logic functions .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
4.19 Mathematical functions
4.20 Matrix library (numpy.matlib) . . . .
. . . . . . . . . . . . . . . . . . . . . . 799
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
4.21 Miscellaneous routines .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
.
.
4.22 Padding Arrays .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
4.23 Polynomials
.
.
.
4.24 Random sampling (numpy.random)
. . . . . . . . . . . . . . . . . . . . . . 987
4.25 Set routines .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
4.26 Sorting, searching, and counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117
4.27 Statistics
4.28 Test Support (numpy.testing) . . . .
. . . . . . . . . . . . . . . . . . . . . . 1158
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
4.29 Window functions
. . . . . . . .
. . . . . . .
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5 Packaging (numpy.distutils)
5.1 Modules in numpy.distutils . . . . .
5.2
5.3
Building Installable C libraries .
Conversion of .src files
.
.
.
1187
. . . . . . . . . . . . . . . . . . 1187
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1197
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . 1199
. . . . .
. . . . .
. . . . .
. . .
. . .
.
6 NumPy C-API
Python Types and C-Structures
System configuration .
.
.
.
.
.
.
.
.
.
6.1
6.2
.
6.3 Data Type API
6.4 Array API
.
.
.
6.5 Array Iterator API
6.6 UFunc API .
.
6.7 Generalized Universal Function API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.8 NumPy core libraries .
6.9
.
1201
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
.
. 1284
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292
C API Deprecations
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7 NumPy internals
1295
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295
7.1 NumPy C Code Explanations
7.2
. 1302
7.3 Multidimensional Array Indexing Order Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
Internal organization of numpy arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
8 NumPy and SWIG
8.1
Testing the numpy.i Typemaps .
.
1305
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
1323
1325
1335
1337
9 Acknowledgements
Bibliography
Python Module Index
Index
ii
NumPy Reference, Release 1.15.1
Release 1.15
Date August 23, 2018
This reference manual details functions, modules, and objects included in NumPy, describing what they are and what
they do. For learning how to use NumPy, see also user.
CONTENTS
1
NumPy Reference, Release 1.15.1
2
CONTENTS
CHAPTER
ONE
ARRAY OBJECTS
NumPy provides an N-dimensional array type, the ndarray, which describes a collection of “items” of the same type.
The items can be indexed using for example N integers.
All ndarrays are homogenous: every item takes up the same size block of memory, and all blocks are interpreted in
exactly the same way. How each item in the array is to be interpreted is specified by a separate data-type object, one
of which is associated with every array. In addition to basic types (integers, floats, etc.), the data type objects can also
represent data structures.
An item extracted from an array, e.g., by indexing, is represented by a Python object whose type is one of the array
scalar types built in NumPy. The array scalars allow easy manipulation of also more complicated arrangements of
data.
Fig. 1: Figure Conceptual diagram showing the relationship between the three fundamental objects used to describe
the data in an array: 1) the ndarray itself, 2) the data-type object that describes the layout of a single fixed-size element
of the array, 3) the array-scalar Python object that is returned when a single element of the array is accessed.
1.1 The N-dimensional array (ndarray)
An ndarray is a (usually fixed-size) multidimensional container of items of the same type and size. The number
of dimensions and items in an array is defined by its shape, which is a tuple of N positive integers that specify
the sizes of each dimension. The type of items in the array is specified by a separate data-type object (dtype), one of
which is associated with each ndarray.
As with other container objects in Python, the contents of an ndarray can be accessed and modified by indexing or
slicing the array (using, for example, N integers), and via the methods and attributes of the ndarray.
3
NumPy Reference, Release 1.15.1
Different ndarrays can share the same data, so that changes made in one ndarray may be visible in another. That
is, an ndarray can be a “view” to another ndarray, and the data it is referring to is taken care of by the “base” ndarray.
ndarrays can also be views to memory owned by Python strings or objects implementing the buffer or array
interfaces.
Example
A 2-dimensional array of size 2 x 3, composed of 4-byte integer elements:
>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
>>> type(x)
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')
The array can be indexed using Python container-like syntax:
>>> # The element of x in the *second* row, *third* column, namely, 6.
>>> x[1, 2]
For example slicing can produce views of the array:
>>> y = x[:,1]
>>> y
array([2, 5])
>>> y[0] = 9 # this also changes the corresponding element in x
>>> y
array([9, 5])
>>> x
array([[1, 9, 3],
[4, 5, 6]])
1.1.1 Constructing arrays
New arrays can be constructed using the routines detailed in Array creation routines, and also by using the low-level
ndarray constructor:
ndarray(shape[, dtype, buffer, offset, . . . ])
An array object represents a multidimensional, homoge-
neous array of fixed-size items.
class numpy.ndarray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)
An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type
object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory,
whether it is an integer, a floating point number, or something else, etc.)
Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The
parameters given here refer to a low-level method (ndarray(. . . )) for instantiating an array.
For more information, refer to the numpy module and examine the methods and attributes of an array.
Parameters
(for the __new__ method; see Notes below)
4
Chapter 1. Array objects