Guide to NumPy - MIT

Guide to NumPy

Travis E. Oliphant, PhD Dec 7, 2006

This book is under restricted distribution using a Market-Determined, Temporary, Distribution-Restriction (MDTDR) system (see ) until October 31, 2010 at the latest. If you receive this book, you are asked not to copy it in any form (electronic or paper) until the temporary distribution-restriction lapses. If you have multiple users at an institution, you should either share a single copy using some form of digital library check-out, or buy multiple copies. The more copies purchased, the sooner the documentation can be released from this inconvenient distribution restriction. After October 31, 2010 this book may be freely copied in any format and used as source material for other books as long as acknowledgement of the original author is given. Your support of this temporary distribution restriction plays an essential role in allowing the author and others like him to produce more quality books and software.

1

Contents

I NumPy from Python

12

1 Origins of NumPy

13

2 Object Essentials

18

2.1 Data-Type Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.2 Basic indexing (slicing) . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.3 Memory Layout of ndarray . . . . . . . . . . . . . . . . . . . . . . 26

2.3.1 Contiguous Memory Layout . . . . . . . . . . . . . . . . . . . 26

2.3.2 Non-contiguous memory layout . . . . . . . . . . . . . . . . . 28

2.4 Universal Functions for arrays . . . . . . . . . . . . . . . . . . . . . . 30

2.5 Summary of new features . . . . . . . . . . . . . . . . . . . . . . . . 32

2.6 Summary of differences with Numeric . . . . . . . . . . . . . . . . . 34

2.6.1 First-step changes . . . . . . . . . . . . . . . . . . . . . . . . 34

2.6.2 Second-step changes . . . . . . . . . . . . . . . . . . . . . . . 37

2.6.3 Updating code that uses Numeric using alter codeN . . . . . 38

2.6.4 Changes to think about . . . . . . . . . . . . . . . . . . . . . 39

2.7 Summary of differences with Numarray . . . . . . . . . . . . . . . . 40

2.7.1 First-step changes . . . . . . . . . . . . . . . . . . . . . . . . 41

2.7.1.1 Import changes . . . . . . . . . . . . . . . . . . . . . 41

2.7.1.2 Attribute and method changes . . . . . . . . . . . . 42

2.7.2 Second-step changes . . . . . . . . . . . . . . . . . . . . . . . 43

2.7.3 Additional Extension modules . . . . . . . . . . . . . . . . . . 43

3 The Array Object

45

3.1 ndarray Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.1.1 Memory Layout attributes . . . . . . . . . . . . . . . . . . . . 45

3.1.2 Data Type attributes . . . . . . . . . . . . . . . . . . . . . . 49

2

3.1.3 Other attributes . . . . . . . . . . . . . . . . . . . . . . . . . 50 3.1.4 Array Interface attributes . . . . . . . . . . . . . . . . . . . . 52 3.2 ndarray Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 3.2.1 Array conversion . . . . . . . . . . . . . . . . . . . . . . . . . 54 3.2.2 Array shape manipulation . . . . . . . . . . . . . . . . . . . . 59 3.2.3 Array item selection and manipulation . . . . . . . . . . . . . 61 3.2.4 Array calculation . . . . . . . . . . . . . . . . . . . . . . . . . 65 3.3 Array Special Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 71 3.3.1 Methods for standard library functions . . . . . . . . . . . . . 71 3.3.2 Basic customization . . . . . . . . . . . . . . . . . . . . . . . 72 3.3.3 Container customization . . . . . . . . . . . . . . . . . . . . . 74 3.3.4 Arithmetic customization . . . . . . . . . . . . . . . . . . . . 75

3.3.4.1 Binary . . . . . . . . . . . . . . . . . . . . . . . . . 75 3.3.4.2 In-place . . . . . . . . . . . . . . . . . . . . . . . . . 77 3.3.4.3 Unary operations . . . . . . . . . . . . . . . . . . . 78 3.4 Array indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 3.4.1 Basic Slicing . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 3.4.2 Advanced selection . . . . . . . . . . . . . . . . . . . . . . . . 81 3.4.2.1 Integer . . . . . . . . . . . . . . . . . . . . . . . . . 81 3.4.2.2 Boolean . . . . . . . . . . . . . . . . . . . . . . . . . 83 3.4.3 Flat Iterator indexing . . . . . . . . . . . . . . . . . . . . . . 84

4 Basic Routines

85

4.1 Creating arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

4.2 Operations on two or more arrays . . . . . . . . . . . . . . . . . . . . 90

4.3 Printing arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

4.4 Functions redundant with methods . . . . . . . . . . . . . . . . . . 94

4.5 Dealing with data types . . . . . . . . . . . . . . . . . . . . . . . . . 94

5 Additional Convenience Routines

96

5.1 Shape functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

5.2 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

5.3 Polynomial functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

5.4 Set Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

5.5 Array construction using index tricks . . . . . . . . . . . . . . . . . . 112

5.6 Other indexing devices . . . . . . . . . . . . . . . . . . . . . . . . . . 115

5.7 Two-dimensional functions . . . . . . . . . . . . . . . . . . . . . . . . 116

3

5.8 More data type functions . . . . . . . . . . . . . . . . . . . . . . . . 118 5.9 Functions that behave like ufuncs . . . . . . . . . . . . . . . . . . . . 121 5.10 Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . 121 5.11 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

6 Scalar objects

126

6.1 Attributes of array scalars . . . . . . . . . . . . . . . . . . . . . . . . 127

6.2 Methods of array scalars . . . . . . . . . . . . . . . . . . . . . . . . . 129

6.3 Defining New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

7 Data-type (dtype) Objects

131

7.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

7.2 Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

7.3 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

8 Standard Classes

138

8.1 Special attributes and methods recognized by NumPy . . . . . . . . 139

8.2 Matrix Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

8.3 Memory-mapped-file arrays . . . . . . . . . . . . . . . . . . . . . . . 142

8.4 Character arrays (numpy.char) . . . . . . . . . . . . . . . . . . . . . 143

8.5 Record Arrays (numpy.rec) . . . . . . . . . . . . . . . . . . . . . . . 144

8.6 Masked Arrays (numpy.ma) . . . . . . . . . . . . . . . . . . . . . . . 148

8.7 Standard container class . . . . . . . . . . . . . . . . . . . . . . . . . 149

8.8 Array Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

8.8.1 Default iteration . . . . . . . . . . . . . . . . . . . . . . . . . 150

8.8.2 Flat iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

8.8.3 N-dimensional enumeration . . . . . . . . . . . . . . . . . . . 151

8.8.4 Iterator for broadcasting . . . . . . . . . . . . . . . . . . . . . 151

9 Universal Functions

153

9.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

9.1.1 Broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

9.1.2 Output type determination . . . . . . . . . . . . . . . . . . . 154

9.1.3 Use of internal buffers . . . . . . . . . . . . . . . . . . . . . . 155

9.1.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . 155

9.1.5 Optional keyword arguments . . . . . . . . . . . . . . . . . . 156

9.2 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

9.3 Casting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

4

9.4 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 9.4.1 Reduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 9.4.2 Accumulate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 9.4.3 Reduceat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 9.4.4 Outer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

9.5 Available ufuncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 9.5.1 Math operations . . . . . . . . . . . . . . . . . . . . . . . . . 164 9.5.2 Trigonometric functions . . . . . . . . . . . . . . . . . . . . . 167 9.5.3 Bit-twiddling functions . . . . . . . . . . . . . . . . . . . . . . 168 9.5.4 Comparison functions . . . . . . . . . . . . . . . . . . . . . . 169 9.5.5 Floating functions . . . . . . . . . . . . . . . . . . . . . . . . 171

10 Basic Modules

174

10.1 Linear Algebra (linalg) . . . . . . . . . . . . . . . . . . . . . . . . 174

10.2 Discrete Fourier Transforms (fft) . . . . . . . . . . . . . . . . . . . 177

10.3 Random Numbers (random) . . . . . . . . . . . . . . . . . . . . . . 181

10.3.1 Discrete Distributions . . . . . . . . . . . . . . . . . . . . . . 181

10.3.2 Continuous Distributions . . . . . . . . . . . . . . . . . . . . 184

10.3.3 Miscellaneous utilities . . . . . . . . . . . . . . . . . . . . . . 190

10.4 Matrix-specific functions (matlib) . . . . . . . . . . . . . . . . . . . . 191

10.5 Ctypes utiltity functions (ctypeslib) . . . . . . . . . . . . . . . . . . 191

11 Testing and Packaging

192

11.1 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

11.2 NumPy Distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

11.2.1 misc util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

11.2.2 Other modules . . . . . . . . . . . . . . . . . . . . . . . . . . 202

11.3 Conversion of .src files . . . . . . . . . . . . . . . . . . . . . . . . . . 203

11.3.1 Fortran files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

11.3.1.1 Named repeat rule . . . . . . . . . . . . . . . . . . . 204

11.3.1.2 Short repeat rule . . . . . . . . . . . . . . . . . . . . 204

11.3.1.3 Pre-defined names . . . . . . . . . . . . . . . . . . . 204

11.3.2 Other files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

II C-API

206

12 New Python Types and C-Structures

207

5

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download