1. Introduction

This chapter introduces the numarray Python extension and outlines the rest of the document.

Numarray is a set of extensions to the Python programming language which allows Python programmers to efficiently manipulate large sets of objects organized in grid-like fashion. These sets of objects are called arrays, and they can have any number of dimensions. One-dimensional arrays are similar to standard Python sequences, and 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. One significant difference is that numarray objects must contain elements of homogeneous type, while standard Python sequences can contain elements of mixed type. Two-dimensional arrays differ from matrices primarily in the way multiplication is performed; 2-D arrays are multiplied element-by-element.

This is a reimplementation of the earlier Numeric module (aka numpy). For the most part, the syntax of numarray is identical to that of Numeric, although there are significant differences. The differences are primarily in new features. For Python 2.2 and later, the syntax is completely backwards compatible. See the High-Level Overview (chapter 3) for incompatibilities for earlier versions of Python. The reasons for rewriting Numeric and a comparison between Numeric and numarray are also described in chapter 3. Portions of the present document are almost word-for-word identical to the Numeric manual. It has been updated to reflect the syntax and behavior of numarray, and there is a new section ( 3.4) on differences between Numeric and numarray.

Why are these extensions needed? The core reason is a very prosaic one: manipulating a set of a million numbers in Python with the standard data structures such as lists, tuples or classes is much too slow and uses too much space. A more subtle reason for these extensions, however, is that the kinds of operations 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 similarly developed in many array languages. In some ways, numarray is simply the application of this experience to the Python language. Thus many of the operations described in numarray work the way they do because experience has shown that way to be a good one, in a variety of contexts. The languages which were used to guide the development of numarray include the infamous APL family of languages, Basis, MATLAB, FORTRAN, S and S+, and others. This heritage will be obvious to users of numarray who already have experience with these other languages. This manual, however, does not assume any such background, and all that is expected of the reader is a reasonable working knowledge of the standard Python language.

This document is the ``official'' documentation for numarray. It is both a tutorial and the most authoritative source of information about numarray with the exception of the source code. The tutorial material will walk you through a set of manipulations of simple, small arrays of numbers. This choice was made because:

- A concrete data set makes explaining the behavior of some functions much easier to motivate than simply talking about abstract operations on abstract data sets.
- Every reader will have at least an intuition as to the meaning of the data and organization of image files.

This manual contains:

**Installing numarray**- Chapter 2 provides information on testing Python, numarray, and compiling and installing numarray if necessary.
**High-Level Overview**- Chapter 3 gives a high-level overview of the components of the numarray system as a whole.
**Array Basics**- Chapter 4 provides a detailed step-by-step introduction to the most important aspect of numarray, the multidimensional array objects.
**Ufuncs**- Chapter 7 provides information on universal functions, the mathematical functions which operate on arrays and other sequences elementwise.
**Pseudo Indices**- Chapter
covers syntax for some special indexing operators. **Array Functions**- Chapter 8 is a catalog of each of the utility functions which allow easy algorithmic processing of arrays.
**Array Methods**- Chapter 9 discusses the methods of array objects.
**Array Attributes**- Chapter 10 presents the attributes of array objects.
**Character Array**- Chapter 11 describes the
`numarray.strings`

module that provides support for arrays of fixed length strings. **Record Array**- Chapter 12 describes the
`numarray.records`

module that supports arrays of fixed length records of string or numerical data. **Object Array**- Chapter 13 describes the
`numarray.objects`

module that supports arrays of Python objects. **C extension API**- Chapter 14 describes the C-APIs provided
for
`numarray`based extension modules. **Convolution**- Chapter 15 describes the
`numarray.convolve`module for computing one-D and two-D convolutions and correlations of`numarray`objects. **Fast-Fourier-Transform**- Chapter 16 describes the
`numarray.fft`module for computing Fast-Fourier-Transforms (FFT) and Inverse FFTs over`numarray`objects in one- or two-dimensional manner. Ported from Numeric. **Linear Algebra**- Chapter 17 describes the
`numarray.linear_algebra`module which provides a simple interface to some commonly used linear algebra routines;**LAPACK**. Ported from Numeric. **Masked Arrays**- Chapter 18 describes the
`numarray.ma`module which supports Masked Arrays: arrays which potentially have missing or invalid elements. Ported from Numeric. **Random Numbers**- Chapter 20 describes the
`numarray.random_array`module which supports generation of arrays of random numbers. Ported from Numeric. **Multidimentional image analysis functions**- Chapter 21
describes the
`numarray.ndimage`module which provides functions for multidimensional image analysis such as filtering, morphology or interpolation. **Glossary**- Appendix A gives a glossary of terms.

Send comments to the NumArray community.