Guide to NumPy

Guide to NumPy

Travis E. Oliphant, PhD

Dec 7, 2006

This book is under restricted distribution using a Market-Determined, Tempo-

rary, Distribution-Restriction (MDTDR) system (see http://www.trelgo l.com) until

October 31, 2010 at the latest. If you receive this book, you are a sked not to c opy it

in any fo rm (electronic or paper) until the temporar y distribution-re striction 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

1

Contents

I NumPy from Python 12

1 Origins of NumPy 13

2 Object Essentials 18

2.1 Data-Type Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 20

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.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 a ttributes . . . . . . . . . . . . . . . . . . . . 46

3.2.2 Array shape manipulation . . . . . . . . . . . . . . . . . . . . 60

3.2.3 Array item selectio n and ma nipulatio n . . . . . . . . . . . . . 62

3.2.4 Array calculation . . . . . . . . . . . . . . . . . . . . . . . . . 66

3.3 Array Special Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 72

3.3.1 Methods for standa rd library functions . . . . . . . . . . . . . 72

3.3.2 Basic customization . . . . . . . . . . . . . . . . . . . . . . . 73

3.3.3 Container customization . . . . . . . . . . . . . . . . . . . . . 75

3.3.4 Arithmetic customization . . . . . . . . . . . . . . . . . . . . 76

3.3.4.1 Binary . . . . . . . . . . . . . . . . . . . . . . . . . 76

3.3.4.2 In-place . . . . . . . . . . . . . . . . . . . . . . . . . 78

3.4.3 Flat Iterator indexing . . . . . . . . . . . . . . . . . . . . . . 85

4 Basic Routines 86

4.1 Creating arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

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

4.3 Printing a rrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

4.4 Functions r e dundant with methods . . . . . . . . . . . . . . . . . . 95

4.5 Dealing with data types . . . . . . . . . . . . . . . . . . . . . . . . . 96

5 Additional Convenience Routine s 98

5.1 Shap e functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

5.2 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

3

6.1 Attributes of array sca lars . . . . . . . . . . . . . . . . . . . . . . . . 129

6.2 Methods of array scalars . . . . . . . . . . . . . . . . . . . . . . . . . 131

6.3 Defining New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

7 Data-type (dtype) Objects 133

7.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

7.2 Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

7.3 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

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

8.7 Standard container class . . . . . . . . . . . . . . . . . . . . . . . . . 152

8.8 Array Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

8.8.1 Default iteration . . . . . . . . . . . . . . . . . . . . . . . . . 153

9.1.2 Output type deter mina tion . . . . . . . . . . . . . . . . . . . 157

9.1.3 Use of internal buffers . . . . . . . . . . . . . . . . . . . . . . 158

9.1.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . 158

9.1.5 Optional keyword arguments . . . . . . . . . . . . . . . . . . 159

9.2 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

9.3 Casting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

4

9.4.4 Outer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

9.5 Available ufuncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

9.5.1 Math operatio ns . . . . . . . . . . . . . . . . . . . . . . . . . 167

9.5.2 Trigonometric functions . . . . . . . . . . . . . . . . . . . . . 170

9.5.3 Bit-twiddling functions . . . . . . . . . . . . . . . . . . . . . . 171

9.5.4 Comparison functions . . . . . . . . . . . . . . . . . . . . . . 172

9.5.5 Floating functions . . . . . . . . . . . . . . . . . . . . . . . . 174

10 Basic Modules 177

10.1 Linear Algebra (linalg) . . . . . . . . . . . . . . . . . . . . . . . . 1 77

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

11 Testing and Packaging 196

11.1 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

11.2 NumPy Distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

11.2.1 misc util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

11.2.2 Other modules . . . . . . . . . . . . . . . . . . . . . . . . . . 206

11.3 Conversion of .src files . . . . . . . . . . . . . . . . . . . . . . . . . . 208

11.3.1 Fortran files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

11.3.1.1 Named r e peat rule . . . . . . . . . . . . . . . . . . . 208

11.3.1.2 Short repeat rule . . . . . . . . . . . . . . . . . . . . 208

11.3.1.3 Pre-defined na mes . . . . . . . . . . . . . . . . . . . 209

II C-API 211