Numerical Python

David Ascher
Paul F. Dubois
Konrad Hinsen
Jim Hugunin
Travis Oliphant

with contributions from the Numerical Python community.

September 7, 2001

Lawrence Livermore National Laboratory, Livermore, CA 94566

UCRL-MA-128569

Legal Notice

 

Please see file Legal.html in the source distribution.

This open source project has been contributed to by many people, including personnel of the Lawrence Livermore National Laboratory. The following notice covers those contributions including this manual.

 

Copyright (c) 1999, 2000, 2001. 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.

This 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 any warranty, 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 not infringe privately-owned rights. Reference herein to any specific commercial products, process, or service by trade 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 and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes.

 

 

Table Of Contents

Numerical Python 1

Introduction 2

Where to get information and code 3

Acknowledgments 4

Installing NumPy 5

Testing the Python installation 5

Testing the Numeric Python Extension Installation 5

Installing NumPy 5

Installing on Windows 6

Installing on Unix 6

At the SourceForge... 6

The NumTut package 8

Testing the NumTut package 8

Possible reasons for failure 8

Win32 9

Unix 9

High-Level Overview 10

Array Objects 10

Universal Functions 11

Convenience Functions 11

Array Basics 13

Basics 13

Creating arrays from scratch 13

array() and typecodes 13

Multidimensional Arrays 15

resize 17

Creating arrays with values specified `on-the-fly' 18

zeros() and ones() 18

arrayrange() 18

Creating an array from a function: fromfunction() 20

identity() 21

Coercion and Casting 21

Automatic Coercions and Binary Operations 21

Deliberate up-casting: The asarray function 22

The typecode value table 22

Consequences of silent upcasting 23

Saving space 23

Deliberate casts (potentially down): the astype method 23

Operating on Arrays 24

Simple operations 24

In-place operations 25

Getting and Setting array values 25

Slicing Arrays 26

Ufuncs 28

What are Ufuncs? 28

Ufuncs can operate on any Python sequence 29

Ufuncs can take output arguments 29

Ufuncs have special methods 29

The reduce ufunc method 29

The accumulate ufunc method 30

The outer ufunc method 30

The reduceat ufunc method 31

Ufuncs always return new arrays 31

Which are the Ufuncs? 31

Unary Mathematical Ufuncs (take only one argument) 31

Binary Mathematical Ufuncs 31

Logical Ufuncs 31

Comparisons 32

The operators and the comparison functions are not exactly equivalent 32

Ufunc shorthands 33

Pseudo Indices 34

Array Functions 36

take(a, indices, axis=0) 36

put (a, indices, values) 37

putmask (a, mask, values) 38

transpose(a, axes=None) 38

repeat(a, repeats, axis=0) 38

choose(a, (b0, ..., bn)) 38

ravel(a) 39

nonzero(a) 39

where(condition, x, y) 39

compress(condition, a, axis=0) 39

diagonal(a, k=0, axis1=0, axis2 = 1) 39

trace(a, k=0) 40

searchsorted(a, values) 40

sort(a, axis=-1) 40

argsort(a, axis=-1) 41

argmax(a, axis=-1), argmin(a, axis=-1) 41

fromstring(string, typecode) 41

dot(m1, m2) 42

matrixmultiply(m1, m2) 42

clip(m, m_min, m_max) 42

indices(shape, typecode=None) 42

swapaxes(a, axis1, axis2) 43

concatenate((a0, a1, ... , an), axis=0) 43

innerproduct(a, b) 44

outerproduct(a,b) 44

array_repr() 44

array_str() 44

resize(a, new_shape) 44

diagonal(a, offset=0, axis1=0, axis2=1) 44

repeat (a, counts, axis=0) 44

convolve (a, v, mode=2) 45

cross_correlate (a, v, mode=0) 45

where (condition, x, y) 45

identity(n) 45

sum(a, index=0) 46

cumsum(a, index=0) 46

product(a, index=0) 46

cumproduct(a, index=0) 46

alltrue(a, index=0) 46

sometrue(a, index=0) 46

allclose (x, y, rtol = 1.e-5, atol = 1.e-8) 46

Array Methods 47

itemsize() 47

iscontiguous() 47

typecode() 47

byteswapped() 47

tostring() 47

tolist() 48

Array Attributes 49

flat 49

real and imaginary 49

Special Topics 51

Subclassing 51

Code Organization 51

Numeric.py and friends 51

UserArray.py 51

Matrix.py 51

Precision.py 51

ArrayPrinter.py 51

MLab.py 51

bartlett(M) 52

blackman(M) 52

corrcoef(x, y=None) 52

cov(m,y=None) 52

cumprod(m, axis=0) 52

cumsum(m, axis=0) 52

diag(v, k=0) 52

diff(x, n=1) 52

eig(m) 52

eye(N, M=N, k=0, typecode=None) 52

fliplr(m) 52

flipud(m) 52

hamming(M) 52

hanning(M) 52

kaiser(M, beta) 52

max(m, axis=0) 52

mean(m, axis=0) 53

median(m) 53

min(m, axis=0) 53

msort(m) 53

prod(m, axis=0) 53

ptp(m, axis = 0) 53

rand(d1, ..., dn) 53

rot90(m,k=1) 53

sinc(x) 53

squeeze(a) 53

std(m, axis = 0) 53

sum(m, axis=0) 53

svd(m) 53

trapz(y,x=None) 53

tri(N, M=N, k=0, typecode=None) 53

tril(m,k=0) 53

triu(m,k=0) 54

The multiarray object 54

Typecodes 54

Indexing in and out, slicing 55

Ellipses 56

NewAxis 56

Set-indexing and Broadcasting 56

Axis specifications 57

Textual representations of arrays 57

Comparisons 59

Storing arrays on disk 59

Dealing with floating point exceptions 59

Writing a C extension to NumPy 61

Introduction 61

Preparing an extension module for NumPy arrays 61

Accessing NumPy arrays from C 62

Types and Internal Structure 62

Element data types 62

Contiguous arrays 63

Zero-dimensional arrays 63

A simple example 63

Accepting input data from any sequence type 64

Creating NumPy arrays 65

Returning arrays from C functions 65

A less simple example 66

C API Reference 68

ArrayObject C Structure and API 68

Structures 68

The ArrayObject API 69

Notes 72

UfuncObject C Structure and API 72

C Structure 72

UfuncObject C API 74

Glossary 77

Optional Packages 79

License and disclaimer for packages MA, RNG, Properties 80

FFT Reference 81

Python Interface 81

fft(data, n=None, axis=-1) 81

inverse_fft(data, n=None, axis=-1) 81

real_fft(data, n=None, axis=-1) 81

inverse_real_fft(data, n=None, axis=-1) 82

fft2d(data, s=None, axes=(-2,-1)) 82

real_fft2d(data, s=None, axes=(-2,-1)) 82

C API 82

Compilation Notes 83

LinearAlgebra Reference 84

Python Interface 84

solve_linear_equations(a, b) 84

inverse(a) 84

eigenvalues(a) 84

eigenvectors(a) 85

singular_value_decomposition(a, full_matrices=0) 85

generalized_inverse(a, rcond=1e-10) 85

determinant(a) 85

linear_least_squares(a, b, rcond=e-10) 85

cholesky_decomposition(a) 85

Heigenvalues(a) 85

Heigenvectors(a) 86

Compilation Notes 86

RandomArray Reference 87

Python Interface 87

seed(x=0, y=0) 87

get_seed() 87

random(shape= ReturnFloat ) 87

uniform(minimum, maximum, shape=ReturnFloat) 87

randint(minimum, maximum, shape=ReturnFloat) 87

permutation(n) 87

Floating point random arrays 88

standard_normal (shape=ReturnFloat) 88

normal (mean, stddev, shape=ReturnFloat) 88

multivariate_normal (mean, covariance) or
multivariate_normal (mean, covariance, leadingAxesShape) 88

exponential (mean, shape=ReturnFloat) 88

beta (a, b, shape=ReturnFloat) 88

gamma (a, r, shape=ReturnFloat) 89

chi_square (df, shape=ReturnFloat) 89

noncentral_chi_square (df, nonc, shape=ReturnFloat) 89

F (dfn, dfd, shape=ReturnFloat) 89

noncentral_F (dfn, dfd, nconc, shape=ReturnFloat) 89

Integer random arrays 89

binomial (trials, prob, shape=ReturnInt) 89

negative_binomial (trials, prob, shape=ReturnInt) 89

poisson (mean, shape=ReturnInt) 89

multinomial (trials, probs) or multinomial (trials, probs, leadingAxesShape) 89

Examples 90

Independent Random Streams 92

Background 92

Usage 92

Module RNG 92

Generator objects 92

Module ranf 92

Examples 93

Properties Reference 94

Defining a property 94

Evading the mechanism 94

Creating the class 94

Setting a property 95

Example: 95

Masked Arrays 97

Required Packages 97

Properties 97

What is a masked array? 97

Installing and using MA 97

Class MaskedArray 98

Attributes of masked arrays 98

Methods on masked arrays. 99

Constructing masked arrays 101

What are masks? 102

Working with masks 103

Operations 103

Copying or not? 103

Behaviors 104

Indexing and Slicing 104

Indexing in assignments 104

Operations that produce a scalar result 104

Assignment to elements and slices 104

Module MA: Attributes 104

Module MA: Functions 105

Unary functions 105

Binary functions 105

Comparison operators 105

Logical operators 105

Special array operators 105

Controlling the size of the string representations 107

Helper classes 107

MAError 107

The constant masked 107

The constant masked_print_option 108

Example of masked behavior 108

Class masked_unary_function 108

Class masked_binary_function 109

Class domained_binary_function 109

Examples of Using MA 109

Data with a given value representing missing data 109

Filling in the missing data 109

Numerical operations 110

Seeing the mask 110

Filling it your way 110

Ignoring extreme values 110

Averaging an entire multidimensional array 110

Index 113

Part I: Numerical Python

1. Introduction

2. Installing NumPy

3. The NumTut package

4. High-Level Overview

5. Array Basics

6. Ufuncs

7. Pseudo Indices

8. Array Functions

9. Array Methods

10. Array Attributes

11. Special Topics

12. Writing a C extension to NumPy

13. C API Reference

14. Glossary

Part II: Optional Packages

15. FFT Reference

16. LinearAlgebra Reference

17. RandomArray Reference

18. Independent Random Streams

19. Properties Reference

20. Masked Arrays