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.trelgol.com) 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 incon- venient 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 ac- knowledgement 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 12.1 New Python Types Defined ....................... 208 12.1.1 PyArray Type .......................... 209 12.1.2 PyArrayDescr Type ....................... 210 12.1.3 PyUFunc Type .......................... 218 12.1.4 PyArrayIter Type ........................ 220 12.1.5 PyArrayMultiIter Type ..................... 222 12.1.6 PyArrayFlags Type ....................... 223 12.1.7 ScalarArrayTypes ........................ 223 12.2 Other C-Structures ............................ 224 12.2.1 PyArray Dims .......................... 224 12.2.2 PyArray Chunk .......................... 224 12.2.3 PyArrayInterface ......................... 225 12.2.4 Internally used structures .................... 226 12.2.4.1 PyUFuncLoopObject ................. 227 12.2.4.2 PyUFuncReduceObject ................ 227 12.2.4.3 PyUFunc Loop1d ................... 227 12.2.4.4 PyArrayMapIter Type ................ 227 13 Complete API 228 13.1 Configuration defines ........................... 228 13.1.1 Guaranteed to be defined .................... 228 13.1.2 Possible defines .......................... 229 13.2 Array Data Types ............................ 229 13.2.1 Enumerated Types ........................ 230 13.2.2 Defines .............................. 231 13.2.2.1 Max and min values for integers ........... 231 13.2.2.2 Number of bits in data types ............. 231 13.2.2.3 Bit-width references to enumerated typenums . 231 13.2.2.4 Integer that can hold a pointer ............ 232 13.2.3 C-type names ........................... 232 13.2.3.1 Boolean ......................... 232 13.2.3.2 (Un)Signed Integer .................. 232 13.2.3.3 (Complex) Floating point ............... 233 13.2.3.4 Bit-width names .................... 233 13.2.4 Printf Formatting ........................ 233 13.3 Array API .................................233 13.3.1 Array structure and data access ................ 233 6 13.3.1.1 Data access ....................... 235 13.3.2 Creating arrays .......................... 236 13.3.2.1