1. Introduction

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

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-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, 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 this text.

Why are these extensions needed? The core reason is a very prosaic one, and that is that 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. Anything which we can do in NumPy we can do in standard Python - we just may not be alive to see the program finish. 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 developed similarly in many array 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 way to be a good one, in a variety of contexts. The languages which were used to guide the development of NumPy include 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 working knowledge of the standard Python language.

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

All users of NumPy, whether interested in image processing or not, are encouraged to follow the tutorial with a 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 of this tutorial is to guide you along this "doing."

Here is what the rest of this part contains:

Installing NumPy provides information on testing Python, NumPy, and compiling and installing NumPy if necessary.

The NumTut package provides information on testing and installing the NumTut package, which allows easy visualization of arrays.

High-Level Overview gives a high-level overview of the components of the NumPy system as a whole.

Array Basics provides a detailed step-by-step introduction to the most important aspect of NumPy, the multidimensional array objects.

Ufuncs provides information on universal functions, the mathematical functions which operate on arrays and other sequences elementwise.

Pseudo Indices covers syntax for some special indexing operators.

Array Functions is a catalog of each of the utility functions which allow easy algorithmic processing of arrays.

Array Methods discusses the methods of array objects.

Array Attributes presents the attributes of array objects.

Special Topics is a collection of special topics, from the organization of the codebase to the mechanisms for customizing printing.

Writing a C extension to NumPy is an tutorial on how to write a C extension which uses NumPy arrays.

C API Reference is a reference for the C API to NumPy objects (both PyArrayObjects and UFuncObjects).

Glossary is a glossary of terms.

Reference material for the optional packages distributed with Numeric Python are described in the next part, Optional Packages.

Where to get information and code

Numerical Python and its documentation are available at SourceForge (sourceforge.net; SourceForge addresses can also be abbreviated as "sf.net"). The main web site is:

http://numpy.sourceforge.net

Downloads, bug reports, and patch facility, and releases are at the main project page, reachable from the above site or directly at: http://sourceforge.net/projects/numpy

The Python web sites is www.python.org.

Many packages are available from third parties that use Numeric to interface to a variety of mathematical and statistical software.

Acknowledgments

Numerical Python is the outgrowth of a long collaborative design process carried out by the Matrix SIG of the Python Software Activity (PSA). Jim Hugunin, while a graduate student at MIT, wrote most of the code and initial documentation. When Jim joined CNRI and began working on JPython, he didn't have the time to maintain Numerical Python so Paul Dubois at LLNL agreed to become the maintainer of Numerical Python. David Ascher, working as a consultant to LLNL, wrote most of this document, incorporating contributions from Konrad Hinsen and Travis Oliphant, both of whom are major contributors to Numerical Python.

Since the source was moved to SourceForge, the Numeric user community has become a significant part of the process. Numerical Python illustrates the power of the open source software concept.

Please send comments and corrections to this manual to paul@pfdubois.com, or to Paul F. Dubois, L-264, Lawrence Livermore National Laboratory, Livermore, CA 94566, U.S.A.

Go to Main Go to Previous Go to Next