WIXLIB

Numerical PythonDavid AscherPaul F. DuboisKonrad HinsenJim HuguninTravis Oliphant

Legal NoticeNumerical Python and this manual are an Open Source software project. This manual was originally written under the sponsorship of Lawrence Livermore National Laboratory. Numerical Python was written by a wide variety of people, principally Jim Hugunin when he was a student at MIT. LLNL has released this manual and itscontributions to Numerical Python under the following terms. Numerical Python is generally released under theterms of the Python license.Copyright (c) 1999. The Regents of the University of California. All rights reserved.Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted,provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.This work was produced at the University of California, Lawrence Livermore National Laboratory under contract no. W-7405-ENG-48 between the U.S. Department of Energy and The Regents of the University of California for the operation of UC LLNL.DISCLAIMERThis software was prepared as an account of work sponsored by an agency of the United States Government.Neither the United States Government nor the University of California nor any of their employees, makes anywarranty, express or implied, or assumes any liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would notinfringe privately-owned rights. Reference herein to any specific commercial products, process, or service bytrade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement,recommendation, or favoring by the United States Government or the University of California. The views andopinions of authors expressed herein do not necessarily state or reflect those of the United States Governmentor the University of California, and shall not be used for advertising or product endorsement purposes.ii

Table of Contents1. Introduction. 9Where to get information and code .10Acknowledgments .102. Installing NumPy. 12Testing the Python installation .12Testing the Numeric Python Extension Installation.12Installing NumPy .133. The NumTut package . 14Testing the NumTut package .14Possible reasons for failure:.14Win32 .14Unix .154. High-Level Overview . 16Array Objects .16Universal Functions.17Convenience Functions.17RandomArray .18FFT.18LinearAlgebra.195. Array Basics. 20Basics.20Creating arrays from scratch.21array() and typecodes .21Multidimensional Arrays .22Creating arrays with values specified on-the-fly'.26zeros() and ones() .26arrayrange().26Creating an array from a function: fromfunction().27identity().29

Coercion and Casting.29Automatic Coercions and Binary Operations .29Deliberate up-casting: The asarray function.30The typecode value table .30Consequences of silent upcasting.31Deliberate casts (potentially down): the astype method .31Operating on Arrays .32Simple operations.32Getting and Setting array values.33Slicing Arrays .346. Ufuncs . 36What are Ufuncs? .36Ufuncs can operate on any Python sequence.37Ufuncs can take output arguments.37Ufuncs have special methods .37The reduce ufunc method . 37The accumulate ufunc method . 38The outer ufunc method . 38The reduceat ufunc method . 39Ufuncs always return new arrays .39Which are the Ufuncs?.39Unary Mathematical Ufuncs (take only one argument) .39Binary Mathematical Ufuncs.39Logical Ufuncs.39Ufunc shorthands .407. Pseudo Indices . 428. Array Functions . 44take(a, indices, axis 0) .44transpose(a, axes None).45repeat(a, repeats, axis 0) .46choose(a, (b0, ., bn)).46ravel(a) .46nonzero(a).46where(condition, x, y) .47compress(condition, a, axis 0) .47diagonal(a, k 0) .47trace(a, k 0) .47searchsorted(a, values).47sort(a, axis -1) .48argsort(a, axis -1) .48argmax(a, axis -1), argmin(a, axis -1) .49fromstring(string, typecode) .49dot(m1, m2).49matrixmultiply(m1, m2).49clip(m, m min, m max).49indices(shape, typecode None).50swapaxes(a, axis1, axis2) .50concatenate((a0, a1, . , an), axis 0) .51innerproduct(a, b).51iv

array repr() .51array str().51resize(a, new shape).51diagonal(a, offset 0, axis1 -2, axis2 -1).52repeat . (a, counts, axis 0)52convolve (a, v, mode 0).52cross correlate (a, v, mode 0) .53where (condition, x, y) .53identity(n) .53sum(a, index 0) .53cumsum(a, index 0) .53product(a, index 0) .54cumproduct(a, index 0) .54alltrue(a, index 0) .54sometrue(a, index 0) .549. Array Methods. 55itemsize().55iscontiguous().55typecode() .55byteswapped().55tostring() .55tolist() .5610. Array Attributes . 57flat .57real and imaginary.5711. Special Topics. 59Subclassing.59Code Organization .59Numeric.py and friends .59UserArray.py .60Matrix.py.60Precision.py.60ArrayPrinter.py .60Mlab.py.60bartlett(M) . 60blackman(M) . 60corrcoef(x, y None) . 60cov(m,y None). 60cumprod(m) . 60cumsum(m). 60diag(v, k 0) . 60diff(x, n 1) . 61eig(m) . 61eye(N, M N, k 0, typecode None). 61fliplr(m) . 61flipud(m). 61hamming(M). 61hanning(M). 61kaiser(M, beta). 61v

max(m) . 61mean(m). 61median(m) . 61min(m) . 61msort(m) . 61prod(m). 61ptp(m) . 61rand(d1, ., dn) . 62rot90(m,k 1). 62sinc(x). 62squeeze(a). 62std(m). 62sum(m). 62svd(m). 62trapz(y,x None) . 62tri(N, M N, k 0, typecode None). 62tril(m,k 0) . 62triu(m,k 0) . 62The multiarray object.62Typecodes.63Indexing in and out, slicing.64Ellipses.65NewAxis .65Set-indexing and Broadcasting .65Axis specifications.65Textual representations of arrays.66array2string(a, max line width None, precision None,suppress small None, separator ' ', array output 0):.66Comparisons .68Pickling and Unpickling -- storing arrays on disk.68Dealing with floating point exceptions .6812. Writing a C extension to NumPy . 69Introduction .69Preparing an extension module for NumPy arrays .69Accessing NumPy arrays from C .69Types and Internal Structure .69Element data types.70Contiguous arrays .71Zero-dimensional arrays.71A simple example.71Accepting input data from any sequence type .72Creating NumPy arrays.73Returning arrays from C functions .73A less simple example .7313. C API Reference. 75ArrayObject C Structure and API .75Structures .75The ArrayObject API .76Notes .79UfuncObject C Structure and API .79C Structure .79vi

UfuncObject C API .8114. FFT Reference. 84Python Interface .84fft(data, n None, axis -1).84inverse fft(data, n None, axis -1) .84real fft(data, n None, axis -1).84inverse real fft(data, n None, axis -1) .85fft2d(data, s None, axes (-2,-1)) .85real fft2d(data, s None, axes (-2,-1)) .85C API.85Compilation Notes.8615. LinearAlgebra Reference . 87Python Interface .87solve linear equations(a, b) .87inverse(a) .87eigenvalues(a).87eigenvectors(a).88singular value decomposition(a, full matrices 0) .88generalized inverse(a, rcond 1e-10) .88determinant(a) .88linear least squares(a, b, rcond e-10) .88C API.88Compilation Notes.8816. RandomArray Reference. 89Python Interface .89seed(x 0, y 0) .89get seed() .89random(shape ReturnFloat) .89uniform(minimum, maximum, shape ReturnFloat) .89randint(minimum, maximum, shape ReturnFloat) .89permutation(n) .89C API.9017. Glossary . 91.91vii

viii

Introduction1. IntroductionThis chapter introduces the Numeric Python extension and outlines the rest of thedocument.The Numeric Python extensions (NumPy henceforth) is a set of extensions to the Python programming language which allows Python programmers to efficiently manipulate large sets of objects organized in grid-likefashion. These sets of objects are called arrays, and they can have any number of dimensions: one dimensionalarrays are similar to standard Python sequences, two-dimensional arrays are similar to matrices from linear algebra. Note that one-dimensional arrays are also different from any other Python sequence, and that two-dimensional matrices are also different from the matrices of linear algebra, in ways which we will mention later in thistext.Why are these extensions needed? The core reason is a very prosaic one, and that is that manipulating a set ofa million numbers in Python with the standard data structures such as lists, tuples or classes is much too slowand uses too much space. Anything which we can do in NumPy we can do in standard Python – we just maynot be alive to see the program finish. A more subtle reason for these extensions however is that the kinds ofoperations that programmers typically want to do on arrays, while sometimes very complex, can often be decomposed into a set of fairly standard operations. This decomposition has been developed similarly in manyarray languages. In some ways, NumPy is simply the application of this experience to the Python language –thus many of the operations described in NumPy work the way they do because experience has shown that wayto be a good one, in a variety of contexts. The languages which were used to guide the development of NumPyinclude the infamous APL family of languages, Basis, MATLAB, FORTRAN, S and S , and others. This heritage will be obvious to users of NumPy who already have experience with these other languages. This tutorial,however, does not assume any such background, and all that is expected of the reader is a reasonable workingknowledge of the standard Python language.This document is the “official” documentation for NumPy. It is both a tutorial and the most authoritative sourceof information about NumPy with the exception of the source code. The tutorial material will walk you througha set of manipulations of simple, small, arrays of numbers, as well as image files. This choice was made because: Aconcrete data set makes explaining the behavior of some functions much easier to motivate than simplytalking about abstract operations on abstract data sets; Every reader will at least an intuition as to the meaning of the data and organization of image files, and The result of various manipulations can be displayed simply since the data set has a natural graphical representation.All users of NumPy, whether interested in image processing or not, are encouraged to follow the tutorial witha working NumPy installation at their side, testing the examples, and, more importantly, transferring the understanding gained by working on images to their specific domain. The best way to learn is by doing – the aim ofthis tutorial is to guide you along this “doing.”9