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:
This manual contains:
numarray.stringsmodule that provides support for arrays of fixed length strings.
numarray.recordsmodule that supports arrays of fixed length records of string or numerical data.
numarray.objectsmodule that supports arrays of Python objects.