path: root/doc/numpybook/numpybook.lyx

#LyX 1.5.1 created this file. For more info see http://www.lyx.org/
\lyxformat 276
\begin_document
\begin_header
\textclass mybook
\begin_preamble



\usepackage{array}

% This gives us a better font in URL links (otherwise the default
% MonoSpace font is bitmapped, and it looks horrible in PDF)
\usepackage{courier}

\usepackage{fullpage}

\usepackage{color}  % so we can use red for the fixme warnings

% The hyperref package gives us a pdf with properly built
% internal navigation ('pdf bookmarks' for the table of contents,
% internal cross-reference links, web links for URLs, etc.)

% A few colors to replace the defaults for certain link types
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}

\usepackage[
  %pdftex,  % needed for pdflatex
  breaklinks=true,  % so long urls are correctly broken across lines
  colorlinks=true,
  urlcolor=blue,
  linkcolor=darkorange,
  citecolor=darkgreen,
  ]{hyperref}

% This helps prevent overly long lines that stretch beyond the margins
\sloppy

% Define a \fixme command to mark visually things needing fixing in the draft.
% For final printing or to simply disable these bright warnings, simply
% uncomment the \renewcommand redefinition below

\newcommand{\fixme}[1] {
\textcolor{red}{
{\fbox{ {\bf FIX}
\ensuremath{\blacktriangleright \blacktriangleright \blacktriangleright}}
{\bf #1}
\fbox{\ensuremath{ \blacktriangleleft \blacktriangleleft \blacktriangleleft }
} } }
}
% Uncomment the next line to make the \fixme command be a no-op
%\renewcommand{\fixme}[1]{}

%%% If you also want to use the listings package for nicely formatted
%%% Python source code, this configuration produces good on-paper and
%%% on-screen results:

\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
% Use and configure listings package for nicely formatted code
\usepackage{listings}
\lstset{
  language=Python,
  basicstyle=\small\ttfamily,
  commentstyle=\ttfamily\color{blue},
  stringstyle=\ttfamily\color{orange},
  showstringspaces=false,
  breaklines=true,
  postbreak = \space\dots
}
\end_preamble
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\paperfontsize 10
\spacing onehalf
\papersize custom
\use_geometry true
\use_amsmath 2
\use_esint 0
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\paperwidth 7in
\paperheight 9in
\leftmargin 1in
\topmargin 1in
\rightmargin 1in
\bottommargin 1in
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle headings
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Standard
\begin_inset VSpace 2in*
\end_inset


\end_layout

\begin_layout Standard
\align center

\family sans
\series bold
\size giant
Guide to NumPy
\end_layout

\begin_layout Standard
\align center

\family sans
\size larger
Travis E.
 Oliphant, PhD 
\newline
August 21, 2008
\end_layout

\begin_layout Standard
\begin_inset VSpace vfill
\end_inset

This book was released from a restricted distribution using a Market-Determined,
 Temporary, Distribution-Restriction (MDTDR) system (see http://www.trelgol.com)
 on August 21, 2008.
 It is now released to the public domain and can be used as source material
 for other works.
 
\end_layout

\begin_layout Standard
\begin_inset LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Standard
\begin_inset FloatList table

\end_inset


\end_layout

\begin_layout Part
NumPy from Python
\end_layout

\begin_layout Chapter
Origins of NumPy
\end_layout

\begin_layout Quotation
A complex system that works is invariably found to have evolved from a simple
 system that worked
\end_layout

\begin_layout Right Address
---
\emph on
John Gall
\end_layout

\begin_layout Quotation
Copy from one, it's plagiarism; copy from two, it's research.
\end_layout

\begin_layout Right Address
---
\emph on
Wilson Mizner
\end_layout

\begin_layout Standard
NumPy builds on (and is a successor to) the successful Numeric array object.
 Its goal is to create the corner-stone for a useful environment for scientific
 computing.
 In order to better understand the people surrounding NumPy and (its library-pac
kage) SciPy, I will explain a little about how SciPy and (current) NumPy
 originated.
 In 1998, as a graduate student studying biomedical imaging at the Mayo
 Clinic in Rochester, MN, I came across Python and its numerical extension
 (Numeric) while I was looking for ways to analyze large data sets for Magnetic
 Resonance Imaging and Ultrasound using a high-level language.
 I quickly fell in love with Python programming which is a remarkable statement
 to make about a programming language.
 If I had not seen others with the same view, I might have seriously doubted
 my sanity.
 I became rather involved in the Numeric Python community, adding the C-API
 chapter to the Numeric documentation (for which Paul Dubois graciously
 made me a co-author).
 
\end_layout

\begin_layout Standard
As I progressed with my thesis work, programming in Python was so enjoyable
 that I felt inhibited when I worked with other programming frameworks.
 As a result, when a task I needed to perform was not available in the core
 language, or in the Numeric extension, I looked around and found C or Fortran
 code that performed the needed task, wrapped it into Python (either by
 hand or using SWIG), and used the new functionality in my programs.
 
\end_layout

\begin_layout Standard
Along the way, I learned a great deal about the underlying structure of
 Numeric and grew to admire it's simple but elegant structures that grew
 out of the mechanism by which Python allows itself to be extended.
 
\end_layout

\begin_layout Note
Numeric was originally written in 1995 based off of an earlier Matrix Object
 design by Jim Fulton which was released in 1994.
 Most of the code was written by Jim Hugunin while he was a graduate student
 at MIT.
 He received help from many people including Jim Fulton, David Ascher, Paul
 Dubois, and Konrad Hinsen.
 These individuals and many others added comments, criticisms, and code
 which helped the Numeric extension reach stability.
 Jim Hugunin did not stay long as an active member of the community ---
 moving on to write Jython and, later, Iron Python.
\end_layout

\begin_layout Standard
By operating in this need-it-make-it fashion I ended up with a substantial
 library of extension modules that helped Python + Numeric become easier
 to use in a scientific setting.
 These early modules included raw input-output functions, a special function
 library, an integration library, an ordinary differential equation solver,
 some least-squares optimizers, and sparse matrix solvers.
 While I was doing this laborious work, Pearu Peterson noticed that a lot
 of the routines I was wrapping were written in Fortran, and there was no
 simplified wrapping mechanism for Fortran subroutines (like SWIG for C).
 He began the task of writing f2py which made it possible to easily wrap
 Fortran programs into Python.
 I helped him a little bit, mostly with testing and contributing early function-
call-back code, but he put forth the brunt of the work.
 His result was simply amazing to me.
 I've always been impressed with f2py, especially because I knew how much
 effort writing and maintaining extension modules could be.
 Anybody serious about scientific computing with Python will appreciate
 that f2py is distributed along with NumPy.
\end_layout

\begin_layout Standard
When I finished my Ph.D.
 in 2001, Eric Jones (who had recently completed his Ph.D.
 at Duke) contacted me because he had a collection of Python modules he
 had developed as part of his thesis work as well.
 He wanted to combine his modules with mine into one super package.
 Together with Pearu Peterson we joined our efforts, and SciPy was born
 in 2001.
 Since then, many people have contributed module code to SciPy including
 Ed Schofield, Robert Cimrman, David M.
 Cooke, Charles (Chuck) Harris, Prabhu Ramachandran, Gary Strangman, Jean-Sebast
ien Roy, and Fernando Perez.
 Others such as Travis Vaught, David Morrill, Jeff Whitaker, and Louis Luangkeso
rn have contributed testing and build support.
 
\end_layout

\begin_layout Standard
At the start of 2005, SciPy was at release 0.3 and relatively stable for
 an early version number.
 Part of the reason it was difficult to stabilize SciPy was that the array
 object upon which SciPy builds was undergoing a bit of an upheaval.
 At about the same time as SciPy was being built, some Numeric users were
 hitting up against the limited capabilities of Numeric.
 In particular, the ability to deal with memory mapped files (and associated
 alignment and swapping issues), record arrays, and altered error checking
 modes were important but limited or non-existent in Numeric.
 As a result, numarray was created by Perry Greenfield, Todd Miller, and
 Rick White at the Space Science Telescope Institute as a replacement for
 Numeric.
 Numarray used a very different implementation scheme as a mix of Python
 classes and C code (which led to slow downs in certain common uses).
 While improving some capabilities, it was slow to pick up on the more advanced
 features of Numeric's universal functions (ufuncs) --- never re-creating
 the C-API that SciPy depended on.
 This made it difficult for SciPy to 
\begin_inset Quotes eld
\end_inset

convert
\begin_inset Quotes erd
\end_inset

 to numarray.
 
\end_layout

\begin_layout Standard
Many newcomers to scientific computing with Python were told that numarray
 was the future and started developing for it.
 Very useful tools were developed that could not be used with Numeric (because
 of numarray's change in C-API), and therefore could not be used easily
 in SciPy.
 This state of affairs was very discouraging for me personally as it left
 the community fragmented.
 Some developed for numarray, others developed as part of SciPy.
 A few people even rejected adopting Python for scientific computing entirely
 because of the split.
 In addition, I estimate that quite a few Python users simply stayed away
 from both SciPy and numarray, leaving the community smaller than it could
 have been given the number of people that use Python for science and engineerin
g purposes.
 
\end_layout

\begin_layout Standard
It should be recognized that the split was not intentional, but simply an
 outgrowth of the different and exacting demands of scientific computing
 users.
 My describing these events should not be construed as assigning blame to
 anyone.
 I very much admire and appreciate everyone I've met who is involved with
 scientific computing and Python.
 Using a stretched biological metaphor, it is only through the process of
 dividing and merging that better results are born.
 I think this concept applies to NumPy.
\end_layout

\begin_layout Standard
In early 2005, I decided to begin an effort to help bring the diverging
 community together under a common framework if it were possible.
 I first looked at numarray to see what could be done to add the missing
 features to make SciPy work with it as a core array object.
 After a couple of days of studying numarray, I was not enthusiastic about
 this approach.
 My familiarity with the Numeric code base no doubt biased my opinion, but
 it seemed to me that the features of Numarray could be added back to Numeric
 with a few fundamental changes to the core object.
 This would make the transition of SciPy to a more enhanced array object
 much easier in my mind.
 
\end_layout

\begin_layout Standard
Therefore, I began to construct this hybrid array object complete with an
 enhanced set of universal (broadcasting) functions that could deal with
 it.
 Along the way, quite a few new features and significant enhancements were
 added to the array object and its surrounding infrastructure.
 This book describes the result of that year-and-a-half-long effort which
 culminated with the release of NumPy 0.9.2 in early 2006 and NumPy 1.0 in
 late 2006.
 I first named the new package, SciPy Core, and used the scipy namespace.
 However, after a few months of testing under that name, it became clear
 that a separate namespace was needed for the new package.
 As a result, a rapid search for a new name resulted in actually coming
 back to the NumPy name which was the unofficial name of Numerical Python
 but never the actual namespace.
 Because the new package builds on the code-base of and is a successor to
 Numeric, I think the NumPy name is fitting and hopefully not too confusing
 to new users.
\end_layout

\begin_layout Standard
This book only briefly outlines some of the infrastructure that surrounds
 the basic objects in NumPy to provide the additional functionality contained
 in the older Numeric package (
\emph on
i.e.

\emph default
 LinearAlgebra, RandomArray, FFT).
 This infrastructure in NumPy includes basic linear algebra routines, Fourier
 transform capabilities, and random number generators.
 In addition, the f2py module is described in its own documentation, and
 so is only briefly mentioned in the second part of the book.
 There are also extensions to the standard Python distutils and testing
 frameworks included with NumPy that are useful in constructing your own
 packages built on top of NumPy.
 The central purpose of this book, however, is to describe and document
 the basic NumPy system that is available under the numpy namespace.
\end_layout

\begin_layout Note
The numpy namespace includes all names under the numpy.core and numpy.lib
 namespaces as well.
 Thus, 
\family typewriter
import numpy
\family default
 will also import the names from numpy.core and numpy.lib.
 This is the recommended way to use numpy.
\end_layout

\begin_layout Standard
The following table gives a brief outline of the sub-packages contained
 in numpy package.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="9" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="1in">
<column alignment="center" valignment="top" leftline="true" width="2in">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="2in">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Package
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Purpose
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Comments
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
core
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
basic objects
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
all names exported to numpy
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
lib
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
additional utilities
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
all names exported to numpy
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
linalg
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
basic linear algebra
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
old LinearAlgebra from Numeric
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
fft
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
discrete Fourier transforms
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
old FFT from Numeric
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
random
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
random number generators
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
old RandomArray from Numeric
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
distutils
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
enhanced build and distribution
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
improvements built on standard distutils
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
testing
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
unit-testing
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
utility functions useful for testing
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
f2py
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
automatic wrapping of Fortran code
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
a useful utility needed by SciPy
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Chapter
Object Essentials
\end_layout

\begin_layout Quotation
Our programs last longer if we manage to build simple abstractions for ourselves...
\end_layout

\begin_layout Right Address
---
\emph on
Ron Jeffries
\end_layout

\begin_layout Quotation
I will tell you the truth as soon as I figure it out.
\end_layout

\begin_layout Right Address
---
\emph on
Wayne Birmingham
\end_layout

\begin_layout Standard
NumPy provides two fundamental objects: an N-dimensional array object (
\family typewriter
ndarray
\family default
) and a universal function object (
\family typewriter
ufunc
\family default
).
 In addition, there are other objects that build on top of these which you
 may find useful in your work, and these will be discussed later.
 The current chapter will provide background information on just the 
\family typewriter
ndarray
\family default
 and the 
\family typewriter
ufunc
\family default
 that will be important for understanding the attributes and methods to
 be discussed later.
 
\end_layout

\begin_layout Standard
An N-dimensional array is a homogeneous collection of 
\begin_inset Quotes eld
\end_inset

items
\begin_inset Quotes erd
\end_inset

 indexed using 
\begin_inset Formula $N$
\end_inset

 integers.
 There are two essential pieces of information that define an 
\begin_inset Formula $N$
\end_inset

-dimensional array: 1) the shape of the array, and 2) the kind of item the
 array is composed of.
 The shape of the array is a tuple of 
\begin_inset Formula $N$
\end_inset

 integers (one for each dimension) that provides information on how far
 the index can vary along that dimension.
 The other important information describing an array is the kind of item
 the array is composed of.
 Because every 
\family typewriter
ndarray
\family default
 is a homogeneous collection of exactly the same data-type, every item takes
 up the same size block of memory, and each block of memory in the array
 is interpreted in exactly the same way
\begin_inset Foot
status open

\begin_layout Standard
By using OBJECT arrays, one can effectively have heterogeneous arrays, but
 the system still sees each element of the array as exactly the same thing
 (a reference to a Python object).
\end_layout

\end_inset

.
\end_layout

\begin_layout Tip
All arrays in NumPy are indexed starting at 0 and ending at M-1 following
 the Python convention.
\end_layout

\begin_layout Standard
For example, consider the following piece of code:
\end_layout

\begin_layout MyCode
>>> a = array([[1,2,3],[4,5,6]])
\newline
>>> a.shape
\newline
(2, 3)
\newline
>>> a.dtype
\newline
dtype('int32')
\end_layout

\begin_layout Note
for all code in this book it is assumed that you have first entered 
\family typewriter
from numpy import *
\family default
.
 In addition, any previously defined arrays are still defined for subsequent
 examples.
\end_layout

\begin_layout Standard
This code defines an array of size 
\begin_inset Formula $2\times3$
\end_inset

 composed of 4-byte (little-endian) integer elements (on my 32-bit platform).
 We can index into this two-dimensional array using two integers: the first
 integer running from 0 to 1 inclusive and the second from 0 to 2 inclusive.
 For example, index 
\begin_inset Formula $\left(1,1\right)$
\end_inset

 selects the element with value 5: 
\end_layout

\begin_layout MyCode
>>> a[1,1]
\newline
5
\end_layout

\begin_layout Standard
All code shown in the shaded-boxes in this book has been (automatically)
 executed on a particular version of NumPy.
 The output of the code shown below shows which version of NumPy was used
 to create all of the output in your copy of this book.
\end_layout

\begin_layout MyCode
>>> import numpy; print numpy.__version__
\newline
1.0.2.dev3478
\end_layout

\begin_layout Section
Data-Type Descriptors
\end_layout

\begin_layout Standard
In NumPy, an ndarray is an 
\begin_inset Formula $N$
\end_inset

-dimensional array of items where each item takes up a fixed number of bytes.
 Typically, this fixed number of bytes represents a number (
\emph on
e.g.

\emph default
 integer or floating-point).
 However, this fixed number of bytes could also represent an arbitrary record
 made up of any collection of other data types.
 NumPy achieves this flexibility through the use of a data-type (dtype)
 object.
 Every array has an associated dtype object which describes the layout of
 the array data.
 Every dtype
\begin_inset LatexCommand index
name "dtype"

\end_inset

 object, in turn, has an associated Python type-object that determines exactly
 what type of Python object is returned when an element of the array is
 accessed.
 The dtype objects are flexible enough to contain references to arrays of
 other dtype objects and, therefore, can be used to define nested records.
 This advanced functionality will be described in better detail later as
 it is mainly useful for the recarray (record array) subclass that will
 also be defined later.
 However, all ndarrays can enjoy the flexibility provided by the dtype objects.
 Figure 
\begin_inset LatexCommand ref
reference "cap:Conceptual-diagram-showing"

\end_inset

 provides a conceptual diagram showing the relationship between the ndarray,
 its associated data-type object, and an array-scalar that is returned when
 a single-element of the array is accessed.
 Note that the data-type points to the type-object of the array scalar
\begin_inset LatexCommand index
name "array scalars"

\end_inset

.
 An array scalar is returned using the type-object and a particular element
 of the ndarray.
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\align center
\begin_inset Graphics
	filename Figures/threefundamental.eps
	width 90text%
	keepAspectRatio

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Conceptual-diagram-showing"

\end_inset

Conceptual diagram showing the relationship between the three fundamental
 objects used to describe the data in an array: 1) the ndarray itself, 2)
 the data-type object that describes the layout of a single fixed-size element
 of the array, 3) the array-scalar Python object that is returned when a
 single element of the array is accessed.
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Every dtype object is based on one of 21 built-in dtype objects.
 These built-in objects allow numeric operations on a wide-variety of integer,
 floating-point, and complex data types.
 Associated with each data-type is a Python type object whose instances
 are array scalars.
 This type-object can be obtained using the 
\family typewriter
type
\family default
 attribute of the dtype object.
 Python typically defines only one data-type of a particular data class
 (one integer type, one floating-point type, etc.).
 This can be convenient for some applications that don't need to be concerned
 with all the ways data can be represented in a computer.
 For scientific applications, however, this is not always true.
 As a result, in NumPy, their are 21 different fundamental Python data-type-desc
riptor objects built-in.
 These descriptors are mostly based on the types available in the C language
 that CPython is written in.
 However, there are a few types that are extremely flexible, such as 
\family typewriter
str_
\family default
, 
\family typewriter
unicode_
\family default
, and 
\family typewriter
void
\family default
.
\end_layout

\begin_layout Standard
The fundamental data-types are shown in Table 
\begin_inset LatexCommand ref
reference "cap:Fundamental-Data-Types"

\end_inset

.
 Along with their (mostly) C-derived names, the integer, float, and complex
 data-types are also available using a bit-width convention so that an array
 of the right size can always be ensured (
\emph on
e.g.

\emph default
 int8, float64, complex128).
 The C-like names are also accessible using a character code which is also
 shown in the table (use of the character codes, however, is discouraged).
 Names for the data types that would clash with standard Python object names
 are followed by a trailing underscore, '_'.
 These data types are so named because they use the same underlying precision
 as the corresponding Python data types.
 Most scientific users should be able to use the array-enhanced scalar objects
 in place of the Python objects.
 The array-enhanced scalars inherit from the Python objects they can replace
 and should act like them under all circumstances (except for how errors
 are handled in math computations).
 
\end_layout

\begin_layout Tip
The array types 
\series bold
bool
\series default
_, 
\series bold
int
\series default
_, 
\series bold
complex
\series default
_, 
\series bold
float
\series default
_, 
\series bold
object
\series default
_, 
\series bold
unicode
\series default
_, and 
\series bold
str_
\series default
 are enhanced-scalars.
 They are very similar to the standard Python types (without the trailing
 underscore) and inherit from them (except for bool_ and object_).
 They can be used in place of the standard Python types whenever desired.
 Whenever a data type is required, as an argument, the standard Python types
 are recognized as well.
\end_layout

\begin_layout Standard
Three of the data types are flexible in that they can have items that are
 of an arbitrary size: the 
\family typewriter
str_
\family default
 type, the 
\family typewriter
unicode_
\family default
 type, and the 
\family typewriter
void
\family default
 type.
 While, you can specify an arbitrary size for these types, every item in
 an array is still of that specified size.
 The void type, for example, allows for arbitrary records to be defined
 as elements of the array, and can be used to define exotic types built
 on top of the basic 
\family typewriter
ndarray
\family default
.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Fundamental-Data-Types"

\end_inset

Built-in array-scalar types corresponding to data-types for an ndarray.
 The bold-face types correspond to standard Python types.
 The object_ type is special because arrays with dtype='O' do not return
 an array scalar on item access but instead return the actual object referenced
 in the array.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="24" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Bit-Width
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Character
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
bool_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
boolXX
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'?'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
byte
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
intXX
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'b'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
short
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'h'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
intc
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'i'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
int_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'l'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
longlong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'q'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
intp
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'p'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ubyte
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
uintXX
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'B'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ushort
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'H'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
uintc
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'I'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
uint
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'L'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ulonglong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'Q'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
uintp
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'P'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
single
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
floatXX
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'f'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
float_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'd'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
longfloat
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'g'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
csingle
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
complexXX
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'F'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
complex_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'D'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
clongfloat
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'G'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
object_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'O'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
str_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'S#'
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
unicode_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'U#'
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
void
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
'V#'
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Note
The two types 
\family typewriter
intp
\family default
 and 
\family typewriter
uintp
\family default
 are not separate types.
 They are names bound to a specific integer type just large enough to hold
 a memory address (a pointer) on the platform.
\end_layout

\begin_layout Warning
Numeric Compatibility: If you used old typecode characters in your Numeric
 code (which was never recommended), you will need to change some of them
 to the new characters.
 In particular, the needed changes are 'c->'S1', 'b'->'B', '1'->'b', 's'->'h',
 'w'->'H', and 'u'->'I'.
 These changes make the typecharacter convention more consistent with other
 Python modules such as the struct module.
\end_layout

\begin_layout Standard
The fundamental data-types are arranged into a hierarchy of Python type-objects
 shown in Figure 
\begin_inset LatexCommand ref
reference "cap:Hierarchy-of-type"

\end_inset

.
 Each of the leaves on this hierarchy correspond to actual data-types that
 arrays can have (in other words, there is a built in dtype object associated
 with each of these new types).
 They also correspond to new Python objects that can be created.
 These new objects are 
\begin_inset Quotes eld
\end_inset

scalar
\begin_inset Quotes erd
\end_inset

 types corresponding to each fundamental data-type.
 Their purpose is to smooth out the rough edges that result when mixing
 scalar and array operations.
 These scalar objects will be discussed in more detail in Chapter 
\begin_inset LatexCommand ref
reference "cha:Scalar-objects"

\end_inset

.
 The other types in the hierarchy define particular categories of types.
 These categories can be useful for testing whether or not the object returned
 by 
\family typewriter
self.dtype.type
\family default
 is of a particular class (using 
\family typewriter
issubclass
\family default
).
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\align center
\begin_inset Graphics
	filename Figures/hierarchy.eps
	lyxscale 75
	width 95text%
	keepAspectRatio

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Hierarchy-of-type"

\end_inset

Hierarchy of type objects representing the array data types.
 Not shown are the two integer types 
\family typewriter
intp
\family default
 and 
\family typewriter
uintp
\family default
 which just point to the integer type that holds a pointer for the platform.
 All the number types can be obtained using bit-width names as well.
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Basic indexing (slicing)
\end_layout

\begin_layout Standard
Indexing
\begin_inset LatexCommand index
name "indexing"

\end_inset

 is a powerful tool in Python and NumPy takes full advantage of this power.
 In fact, some of capabilities of Python's indexing were first established
 by the needs of Numeric users.
\begin_inset Foot
status open

\begin_layout Standard
For example, the ability to index with a comma separated list of objects
 and have it correspond to indexing with a tuple is a feature added to Python
 at the request of the NumPy community.
 The Ellipsis object was also added to Python explicitly for the NumPy community.
 Extended slicing (wherein a step can be provided) was also a feature added
 to Python because of Numeric.
\end_layout

\end_inset

 Indexing is also sometimes called slicing in Python, and slicing for an
 
\family typewriter
ndarray
\family default
 works very similarly as it does for other Python sequences.
 There are three big differences: 1) slicing can be done over multiple dimension
s, 2) exactly one ellipsis object can be used to indicate several dimensions
 at once, 3) slicing cannot be used to expand the size of an array (unlike
 lists).
\end_layout

\begin_layout Standard
A few examples should make slicing more clear.
 Suppose 
\begin_inset Formula $A$
\end_inset

 is a 
\begin_inset Formula $10\times20$
\end_inset

 array, then 
\begin_inset Formula $A[3]$
\end_inset

 is the same as 
\begin_inset Formula $A[3,:]$
\end_inset

 and represents the 4th length-20 
\begin_inset Quotes eld
\end_inset

row
\begin_inset Quotes erd
\end_inset

 of the array.
 On the other hand, 
\begin_inset Formula $A[:,3]$
\end_inset

 represents the 4th length-10 
\begin_inset Quotes eld
\end_inset

column
\begin_inset Quotes erd
\end_inset

 of the array.
 Every third element of the 4th column can be selected as 
\begin_inset Formula $A[::3,3]$
\end_inset

.
 Ellipses can be used to replace zero or more 
\begin_inset Quotes eld
\end_inset

:
\begin_inset Quotes erd
\end_inset

 terms.
 In other words, an Ellipsis
\begin_inset LatexCommand index
name "Ellipsis"

\end_inset

 object expands to zero or more full slice objects (
\begin_inset Quotes eld
\end_inset

:
\begin_inset Quotes erd
\end_inset

) so that the total number of dimensions in the slicing tuple matches the
 number of dimensions in the array.
 Thus, if 
\begin_inset Formula $A$
\end_inset

 is 
\begin_inset Formula $10\times20\times30\times40$
\end_inset

, then 
\begin_inset Formula $A[3:,...,4]$
\end_inset

 is equivalent to 
\begin_inset Formula $A[3:,:,:,4]$
\end_inset

 while 
\begin_inset Formula $A[...,3]$
\end_inset

 is equivalent to 
\begin_inset Formula $A[:,:,:,3].$
\end_inset

 
\end_layout

\begin_layout Standard
The following code illustrates some of these concepts:
\end_layout

\begin_layout MyCode
>>> a = arange(60).reshape(3,4,5); print a
\newline
[[[ 0  1  2  3  4]
\newline
  [ 5  6  7 
 8  9]
\newline
  [10 11 12 13 14]
\newline
  [15 16 17 18 19]]
\newline

\newline
 [[20 21 22 23 24]
\newline
  [25 26 27
 28 29]
\newline
  [30 31 32 33 34]
\newline
  [35 36 37 38 39]]
\newline

\newline
 [[40 41 42 43 44]
\newline
  [45 46 47
 48 49]
\newline
  [50 51 52 53 54]
\newline
  [55 56 57 58 59]]]
\end_layout

\begin_layout Standard
\InsetSpace ~

\end_layout

\begin_layout MyCode
>>> print a[...,3]
\newline
[[ 3  8 13 18]
\newline
 [23 28 33 38]
\newline
 [43 48 53 58]]
\newline
>>> print a[1,...,3]
\newline
[23
 28 33 38]
\newline
>>> print a[:,:,2]
\newline
[[ 2  7 12 17]
\newline
 [22 27 32 37]
\newline
 [42 47 52 57]]
\newline
>>>
 print a[0,::2,::2]
\newline
[[ 0  2  4]
\newline
 [10 12 14]]
\end_layout

\begin_layout Section
Memory Layout of 
\family typewriter
ndarray
\end_layout

\begin_layout Standard
On a fundamental level, an 
\begin_inset Formula $N$
\end_inset

-dimensional array object is just a one-dimensional sequence of memory with
 fancy indexing code that maps an 
\begin_inset Formula $N$
\end_inset

-dimensional index into a one-dimensional index.
 The one-dimensional index is necessary on some level because that is how
 memory is addressed in a computer.
 The fancy indexing, however, can be very helpful for translating our ideas
 into computer code.
 This is because many concepts we wish to model on a computer have a natural
 representation as an 
\begin_inset Formula $N$
\end_inset

-dimensional array.
 While this is especially true in science and engineering, it is also applicable
 to many other arenas which can be appreciated by considering the popularity
 of the spreadsheet as well as 
\begin_inset Quotes eld
\end_inset

image processing
\begin_inset Quotes erd
\end_inset

 applications.
\end_layout

\begin_layout Warning
Some high-level languages give pre-eminence to a particular use of 2-dimensional
 arrays as Matrices.
 In NumPy, however, the core object is the more general 
\begin_inset Formula $N$
\end_inset

-dimensional array.
 NumPy defines a matrix object as a sub-class of the N-dimensional array.
 
\end_layout

\begin_layout Standard
In order to more fully understand the array object along with its attributes
 and methods it is important to learn more about how an 
\begin_inset Formula $N$
\end_inset

-dimensional array is represented in the computer's memory.
 A complete understanding of this layout is only essential for optimizing
 algorithms operating on general purpose arrays.
 But, even for the casual user, a general understanding of memory layout
 will help to explain the use of certain array attributes that may otherwise
 be mysterious.
 
\end_layout

\begin_layout Subsection
Contiguous Memory Layout
\end_layout

\begin_layout Standard
There is a fundamental ambiguity in how the mapping to a one-dimensional
 index can take place which is illustrated for a 2-dimensional array in
 Figure 
\begin_inset LatexCommand ref
reference "cap:Options-for-memory"

\end_inset

.
 In that figure, each block represents a chunk of memory that is needed
 for representing the underlying array element.
 For example, each block could represent the 8 bytes needed to represent
 a double-precision floating point number.
 
\end_layout

\begin_layout Standard
In the figure, two arrays are shown, a 
\begin_inset Formula $4x3$
\end_inset

 array and a 
\begin_inset Formula $3x4$
\end_inset

 array.
 Each of these arrays takes 12 blocks of memory shown as a single, contiguous
 segment.
 How this memory is used to form the abstract 2-dimensional array can vary,
 however, and the 
\family typewriter
ndarray
\family default
 object supports both styles.
 Which style is in use can be interrogated by the use of the flags attribute
 which returns a dictionary of the state of array flags.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\align center
\begin_inset Graphics
	filename Figures/contiguous.eps
	width 85text%
	keepAspectRatio

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Options-for-memory"

\end_inset

Options for memory layout of a 2-dimensional array.
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
In the C-style of 
\begin_inset Formula $N$
\end_inset

-dimensional indexing shown on the left of Figure 
\begin_inset LatexCommand ref
reference "cap:Options-for-memory"

\end_inset

 the last 
\begin_inset Formula $N$
\end_inset

-dimensional index 
\begin_inset Quotes eld
\end_inset

varies the fastest.
\begin_inset Quotes erd
\end_inset

 In other words, to move through computer memory sequentially, the last
 index is incremented first, followed by the second-to-last index and so
 forth.
 Some of the algorithms in NumPy that deal with 
\begin_inset Formula $N$
\end_inset

-dimensional arrays work best with this kind of data.
 
\end_layout

\begin_layout Standard
In the Fortran-style of 
\begin_inset Formula $N$
\end_inset

-dimensional indexing shown on the right of Figure 
\begin_inset LatexCommand ref
reference "cap:Options-for-memory"

\end_inset

, the first 
\begin_inset Formula $N$
\end_inset

-dimensional index 
\begin_inset Quotes eld
\end_inset

varies the fastest.
\begin_inset Quotes erd
\end_inset

 Thus, to move through computer memory sequentially, the first index is
 incremented first until it reaches the limit in that dimension, then the
 second index is incremented and the first index is reset to zero.
 While NumPy can be compiled without the use of a Fortran compiler, several
 modules of SciPy (available separately) rely on underlying algorithms written
 in Fortran.
 Algorithms that work on 
\begin_inset Formula $N$
\end_inset

-dimensional arrays that are written in Fortran typically expect Fortran-style
 arrays.
 
\end_layout

\begin_layout Standard
The two-styles of memory layout for arrays are connected through the transpose
 operation.
 Thus, if 
\begin_inset Formula $A$
\end_inset

 is a (contiguous) C-style array, then the same block of memory can be used
 to represent 
\begin_inset Formula $A^{T}$
\end_inset

 as a (contiguous) Fortran-style array.
 This kind of understanding can be useful when trying to optimize the wrapping
 of Fortran subroutines, or if a more detailed understanding of how to write
 algorithms for generally-indexed arrays is desired.
 But, fortunately, the casual user who does not care if an array is copied
 occasionally to get it into the right orientation needed for a particular
 algorithm can forget about how the array is stored in memory and just visualize
 it as an 
\begin_inset Formula $N$
\end_inset

-dimensional array (that is, after all, the whole point of creating the
 
\family typewriter
ndarray
\family default
 object in the first place).
 
\end_layout

\begin_layout Subsection
Non-contiguous memory layout
\end_layout

\begin_layout Standard
Both of the examples presented above are 
\emph on
single-segment
\begin_inset LatexCommand index
name "single-segment"

\end_inset


\emph default
 arrays where the entire array is visited by sequentially marching through
 memory one element at a time.
 When an algorithm in C or Fortran expects an N-dimensional array, this
 single segment (of a certain fundamental type) is usually what is expected
 along with the shape 
\begin_inset Formula $N$
\end_inset

-tuple.
 With a single-segment of memory representing the array, the one-dimensional
 index into computer memory can always be computed from the 
\begin_inset Formula $N$
\end_inset

-dimensional index.
 This concept is explored further in the following paragraphs.
\end_layout

\begin_layout Standard
Let 
\begin_inset Formula $n_{i}$
\end_inset

 be the value of the 
\begin_inset Formula $i^{\textrm{th}}$
\end_inset

 index into an array whose shape is represented by the 
\begin_inset Formula $N$
\end_inset

 integers 
\begin_inset Formula $d_{i}$
\end_inset

 (
\begin_inset Formula $i=0\ldots N-1).$
\end_inset

 Then, the one-dimensional index into a C-style contiguous array is 
\begin_inset Formula \[
n^{C}=\sum_{i=0}^{N-1}n_{i}\prod_{j=i+1}^{N-1}d_{j}\]

\end_inset

 while the one-dimensional index into a Fortran-style contiguous array is
 
\begin_inset Formula \[
n^{F}=\sum_{i=0}^{N-1}n_{i}\prod_{j=0}^{i-1}d_{j}.\]

\end_inset

 In these formulas we are assuming that 
\begin_inset Formula \[
\prod_{j=k}^{m}d_{j}=d_{k}d_{k+1}\cdots d_{m-1}d_{m}\]

\end_inset

so that if 
\begin_inset Formula $m<k,$
\end_inset

 the product is 
\begin_inset Formula $1.$
\end_inset

 While perfectly general, these formulas may be a bit confusing at first
 glimpse.
 Let's see how they expand out for determining the one-dimensional index
 corresponding to the element 
\begin_inset Formula $\left(1,3,2\right)$
\end_inset

 of a 
\begin_inset Formula $4\times5\times6$
\end_inset

 array.
 If the array is stored as Fortran contiguous, then 
\begin_inset Formula \begin{eqnarray*}
n^{F} & = & n_{0}\cdot\left(1\right)+n_{1}\cdot(4)+n_{2}\cdot\left(4\cdot5\right)\\
 & = & 1+3\cdot4+2\cdot20=53.\end{eqnarray*}

\end_inset

 On the other hand, if the array is stored as C contiguous, then 
\begin_inset Formula \begin{eqnarray*}
n^{C} & = & n_{0}\cdot\left(5\cdot6\right)+n_{1}\cdot\left(6\right)+n_{2}\cdot\left(1\right)\\
 & = & 1\cdot30+3\cdot6+2\cdot1=50.\end{eqnarray*}

\end_inset

 The general pattern should be more clear from these examples.
 
\end_layout

\begin_layout Standard
The formulas for the one-dimensional index of the N-dimensional arrays reveal
 what results in an important generalization for memory layout.
 Notice that each formula can be written as 
\begin_inset Formula \[
n^{X}=\sum_{i=0}^{N-1}n_{i}s_{i}^{X}\]

\end_inset

 where 
\begin_inset Formula $s_{i}^{X}$
\end_inset

 gives the 
\emph on
stride
\begin_inset LatexCommand index
name "stride"

\end_inset


\emph default
 for dimension 
\begin_inset Formula $i$
\end_inset

.
\begin_inset Foot
status open

\begin_layout Standard
Our definition of stride here is an element-based stride, while the strides
 attribute returns a byte-based stride.
 The byte-based stride is the element itemsize multiplied by the element-based
 stride.
\end_layout

\end_inset

 Thus, for C and Fortran contiguous arrays respectively we have 
\begin_inset Formula \begin{eqnarray*}
s_{i}^{C} & = & \prod_{j=i+1}^{N-1}d_{j}=d_{i+1}d_{i+2}\cdots d_{N-1},\\
s_{i}^{F} & = & \prod_{j=0}^{i-1}d_{j}=d_{0}d_{1}\cdots d_{i-1}.\end{eqnarray*}

\end_inset


\end_layout

\begin_layout Standard
The stride is how many elements in the underlying one-dimensional layout
 of the array one must jump in order to get to the next array element of
 a specific dimension in the N-dimensional layout.
 Thus, in a C-style 
\begin_inset Formula $4\times5\times6$
\end_inset

 array one must jump over 30 elements to increment the first index by one,
 so 30 is the stride for the first dimension (
\begin_inset Formula $s_{0}^{C}=30$
\end_inset

).
 If, for each array, we define a strides tuple with 
\begin_inset Formula $N$
\end_inset

 integers, then we have pre-computed and stored an important piece of how
 to map the 
\begin_inset Formula $N$
\end_inset

-dimensional index to the one-dimensional one used by the computer.
 
\end_layout

\begin_layout Standard
In addition to providing a pre-computed table for index mapping, by allowing
 the strides tuple to consist of arbitrary integers we have provided a more
 general layout for the 
\begin_inset Formula $N$
\end_inset

-dimensional array.
 As long as we always use the stride information to move around in the 
\begin_inset Formula $N$
\end_inset

-dimensional array, we can use any convenient layout we wish for the underlying
 representation as long as it is regular enough to be defined by constant
 jumps in each dimension.
 The 
\family typewriter
ndarray
\family default
 object of NumPy uses this stride information and therefore the underlying
 memory of an 
\family typewriter
ndarray
\family default
 can be laid out dis-contiguously.
 
\end_layout

\begin_layout Note
Several algorithms in NumPy work on arbitrarily strided arrays.
 However, some algorithms require single-segment arrays.
 When an irregularly strided array is passed in to such algorithms, a copy
 is automatically made.
 
\end_layout

\begin_layout Standard
An important situation where irregularly strided arrays occur is array indexing.
 Consider again Figure 
\begin_inset LatexCommand ref
reference "cap:Options-for-memory"

\end_inset

.
 In that figure a high-lighted sub-array is shown.
 Define 
\begin_inset Formula $C$
\end_inset

 to be the 
\begin_inset Formula $4\times3$
\end_inset

 C contiguous array and 
\begin_inset Formula $F$
\end_inset

 to be the 
\begin_inset Formula $3\times4$
\end_inset

 Fortran contiguous array.
 The highlighted areas can be written respectively as 
\begin_inset Formula $C$
\end_inset

[1:3,1:3] and 
\begin_inset Formula $F$
\end_inset

[1:3,1:3].
 As evidenced by the corresponding highlighted region in the one-dimensional
 view of the memory, these sub-arrays are neither C contiguous nor Fortran
 contiguous.
 However, they can still be represented by an 
\family typewriter
ndarray
\family default
 object using the same striding tuple as the original array used.
 Therefore, a regular indexing expression on an 
\family typewriter
ndarray
\family default
 can always produce an 
\family typewriter
ndarray
\family default
 object 
\emph on
without
\emph default
 copying any data.
 This is sometimes referred to as the 
\begin_inset Quotes eld
\end_inset

view
\begin_inset Quotes erd
\end_inset

 feature of array indexing, and one can see that it is enabled by the use
 of striding information in the underlying 
\family typewriter
ndarray
\family default
 object.
 The greatest benefit of this feature is that it allows indexing to be done
 very rapidly and without exploding memory usage (because no copies of the
 data are made).
\end_layout

\begin_layout Section
Universal Functions for arrays
\end_layout

\begin_layout Standard
NumPy provides a wealth of mathematical functions that operate on then ndarray
 object.
 From algebraic functions such as addition and multiplication to trigonometric
 functions such as 
\begin_inset Formula $\sin,$
\end_inset

 and 
\begin_inset Formula $\cos$
\end_inset

.
 Each universal function
\begin_inset LatexCommand index
name "universal function"

\end_inset

 (
\family typewriter
ufunc
\family default

\begin_inset LatexCommand index
name "ufunc"

\end_inset

) is an instance of a general class so that function behavior is the same.
 All ufuncs perform element-by-element operations over an array or a set
 of arrays (for multi-input functions).
 The ufuncs themselves and their methods are documented in Part 
\begin_inset LatexCommand ref
reference "par:The-Ufunc-Object"

\end_inset

.
 
\end_layout

\begin_layout Standard
One important aspect of ufunc behavior that should be introduced early,
 however, is the idea of 
\emph on

\begin_inset LatexCommand index
name "broadcasting"

\end_inset

broadcasting
\emph default
.
 Broadcasting is used in several places throughout NumPy and is therefore
 worth early exposure.
 To understand the idea of broadcasting, you first have to be conscious
 of the fact that all ufuncs are always element-by-element operations.
 In other words, suppose we have a ufunc with two inputs and one output
 (
\emph on
e.g.

\emph default
 addition) and the inputs are both arrays of shape 
\begin_inset Formula $4\times6\times5$
\end_inset

.
 Then, the output is going to be 
\begin_inset Formula $4\times6\times5$
\end_inset

, and will be the result of applying the underlying function (
\emph on
e.g.

\emph default
 
\begin_inset Formula $+$
\end_inset

) to each pair of inputs to produce the output at the corresponding 
\begin_inset Formula $N$
\end_inset

-dimensional location.
 
\end_layout

\begin_layout Standard
Broadcasting allows ufuncs to deal in a meaningful way with inputs that
 do not have exactly the same shape.
 In particular, the first rule of broadcasting is that if all input arrays
 do not have the same number of dimensions, then a 
\begin_inset Quotes eld
\end_inset


\begin_inset Formula $1$
\end_inset


\begin_inset Quotes erd
\end_inset

 will be repeatedly pre-pended to the shapes of the smaller arrays until
 all the arrays have the same number of dimensions.
 The second rule of broadcasting ensures that arrays with a size of 1 along
 a particular dimension act as if they had the size of the array with the
 largest shape along that dimension.
 The value of the array element is assumed to be the same along that dimension
 for the 
\begin_inset Quotes eld
\end_inset

broadcasted
\begin_inset Quotes erd
\end_inset

 array.
 After application of the broadcasting rules, the sizes of all arrays must
 match.
\end_layout

\begin_layout Standard
While a little tedious to explain, the broadcasting rules are easy to pick
 up by looking at a couple of examples.
 Suppose there is a 
\family typewriter
ufunc
\family default
 with two inputs, 
\begin_inset Formula $A$
\end_inset

 and 
\begin_inset Formula $B$
\end_inset

.
 Now supposed that 
\begin_inset Formula $A$
\end_inset

 has shape 
\begin_inset Formula $4\times6\times5$
\end_inset

 while 
\begin_inset Formula $B$
\end_inset

 has shape 
\begin_inset Formula $4\times6\times1$
\end_inset

.
 The ufunc will proceed to compute the 
\begin_inset Formula $4\times6\times5$
\end_inset

 output as if 
\begin_inset Formula $B$
\end_inset

 had been 
\begin_inset Formula $4\times6\times5$
\end_inset

 by assuming that 
\begin_inset Formula $B[...,k]=B[...,0]$
\end_inset

 for 
\begin_inset Formula $k=1,2,3,4$
\end_inset

.
 
\end_layout

\begin_layout Standard
Another example illustrates the idea of adding 
\begin_inset Formula $1$
\end_inset

's to the beginning of the array shape-tuple.
 Suppose 
\begin_inset Formula $A$
\end_inset

 is the same as above, but 
\begin_inset Formula $B$
\end_inset

 is a length 
\begin_inset Formula $5$
\end_inset

 array.
 Because of the first rule, 
\begin_inset Formula $B$
\end_inset

 will be interpreted as a 
\begin_inset Formula $1\times1\times5$
\end_inset

 array, and then because of the second rule 
\begin_inset Formula $B$
\end_inset

 will be interpreted as a 
\begin_inset Formula $4\times6\times5$
\end_inset

 array by repeating the elements of 
\begin_inset Formula $B$
\end_inset

 in the obvious way.
 
\end_layout

\begin_layout Standard
The most common alteration needed is to route-around the automatic pre-pending
 of 1's to the shape of the array.
 If it is desired, to add 
\begin_inset Formula $1$
\end_inset

's to the end of the array shape, then dimensions can always be added using
 the 
\family typewriter
newaxis
\family default
 name in NumPy: 
\begin_inset Formula $B[...,\textrm{newaxis, newaxis}]$
\end_inset

 returns an array with 2 additional 1's appended to the shape of 
\begin_inset Formula $B.$
\end_inset

 
\end_layout

\begin_layout Standard
One important aspect of broadcasting is the calculation of functions on
 regularly spaced grids.
 For example, suppose it is desired to show a portion of the multiplication
 table by computing the function 
\begin_inset Formula $a*b$
\end_inset

 on a grid with 
\begin_inset Formula $a$
\end_inset

 running from 6 to 9 and 
\begin_inset Formula $b$
\end_inset

 running from 12 to 16.
 The following code illustrates how this could be done using ufuncs and
 broadcasting.
 
\end_layout

\begin_layout MyCode
>>> a = arange(6, 10); print a
\newline
[6 7 8 9]
\newline
>>> b = arange(12, 17); print b
\newline
[12
 13 14 15 16]
\newline
>>> table = a[:,newaxis] * b
\newline
>>> print table
\newline
[[ 72  78  84  90
  96]
\newline
 [ 84  91  98 105 112]
\newline
 [ 96 104 112 120 128]
\newline
 [108 117 126 135 144]]
\end_layout

\begin_layout Section
Summary of new features 
\end_layout

\begin_layout Standard
More information about using arrays in Python can be found in the old Numeric
 documentation at 
\begin_inset LatexCommand htmlurl
name "http://numeric.scipy.org"
target "http://numeric.scipy.org"

\end_inset

.
 Quite a bit of that documentation is still accurate, especially in the
 discussion of array basics.
 There are significant differences, however, and this book seeks to explain
 them in detail.
 The following list tries to summarize the significant new features (over
 Numeric) available in the 
\family typewriter
ndarray
\family default
 and 
\family typewriter
ufunc
\family default
 objects of NumPy: 
\end_layout

\begin_layout Enumerate
more data types (all standard C-data types plus complex floats, Boolean,
 string, unicode, and void *);
\end_layout

\begin_layout Enumerate
flexible data types where each array can have a different itemsize (but
 all elements of the same array still have the same itemsize);
\end_layout

\begin_layout Enumerate
there is a true Python scalar type (contained in a hierarchy of types) for
 every data-type an array can have;
\end_layout

\begin_layout Enumerate
data-type objects define the data-type with support for data-type objects
 with fields and subarrays which allow record arrays with nested records;
\end_layout

\begin_layout Enumerate
many more array methods in addition to functional counterparts;
\end_layout

\begin_layout Enumerate
attributes more clearly distinguished from methods (attributes are intrinsic
 parts of an array so that setting them changes the array itself);
\end_layout

\begin_layout Enumerate
array scalars covering all data types which inherit from Python scalars
 when appropriate;
\end_layout

\begin_layout Enumerate
arrays can be misaligned, swapped, and in Fortran order in memory (facilitates
 memory-mapped arrays);
\end_layout

\begin_layout Enumerate
arrays can be more easily read from text files and created from buffers
 and iterators;
\end_layout

\begin_layout Enumerate
arrays can be quickly written to files in text and/or binary mode;
\end_layout

\begin_layout Enumerate
arrays support the removal of the 64-bit memory limitation as long as you
 have Python 2.5 or later;
\end_layout

\begin_layout Enumerate
fancy indexing can be done on arrays using integer sequences and Boolean
 masks;
\end_layout

\begin_layout Enumerate
coercion rules are altered for mixed scalar / array operations so that scalars
 (anything that produces a 0-dimensional array internally) will not determine
 the output type in such cases.
\end_layout

\begin_layout Enumerate
when coercion is needed, temporary buffer-memory allocation is limited to
 a user-adjustable size;
\end_layout

\begin_layout Enumerate
errors are handled through the IEEE floating point status flags and there
 is flexibility on a per-thread level for handling these errors;
\end_layout

\begin_layout Enumerate
one can register an error callback function in Python to handle errors are
 set to 'call' for their error handling;
\end_layout

\begin_layout Enumerate
ufunc reduce, accumulate, and reduceat can take place using a different
 type then the array type if desired (without copying the entire array);
\end_layout

\begin_layout Enumerate
ufunc output arrays passed in can be a different type than expected from
 the calculation;
\end_layout

\begin_layout Enumerate
ufuncs take keyword arguments which can specify 1) the error handling explicitly
 and 2) the specific 1-d loop to use by-passing the type-coercion detection.
 
\end_layout

\begin_layout Enumerate
arbitrary classes can be passed through ufuncs (__array_wrap__ and __array_prior
ity__ expand previous __array__ method);
\end_layout

\begin_layout Enumerate
ufuncs can be easily created from Python functions;
\end_layout

\begin_layout Enumerate
ufuncs have attributes to detail their behavior, including a dynamic doc
 string that automatically generates the calling signature;
\end_layout

\begin_layout Enumerate
several new ufuncs (frexp, modf, ldexp, isnan, isfinite, isinf, signbit);
\end_layout

\begin_layout Enumerate
new types can be registered with the system so that specialized ufunc loops
 can be written over new type objects;
\end_layout

\begin_layout Enumerate
new types can also register casting functions and rules for fitting into
 the 
\begin_inset Quotes eld
\end_inset

can-cast
\begin_inset Quotes erd
\end_inset

 hierarchy;
\end_layout

\begin_layout Enumerate
C-API enhanced so that more of the functionality is available from compiled
 code;
\end_layout

\begin_layout Enumerate
C-API enhanced so array structure access can take place through macros;
\end_layout

\begin_layout Enumerate
new iterator objects created for easy handling in C of non-contiguous arrays;
\end_layout

\begin_layout Enumerate
new multi-iterator object created for easy handling in C of broadcasting;
\end_layout

\begin_layout Enumerate
types have more functions associated with them (no magic function lists
 in the C-code).
 Any function needed is part of the type structure.
\end_layout

\begin_layout Standard
All of these enhancements will be documented more thoroughly in the remaining
 portions of this book.
\end_layout

\begin_layout Section
Summary of differences with Numeric
\end_layout

\begin_layout Standard
An effort was made to retain backwards compatibility with Numeric all the
 way to the C-level.
 This was mostly accomplished, with a few changes that needed to be made
 for consistency of the new system.
 If you are just starting out with NumPy, then this section may be skipped.
\end_layout

\begin_layout Standard
There are two steps (one required and one optional) to converting code that
 works with Numeric to work fully with NumPy The first step uses a compatibility
 layer and requires only small changes which can be handled by the numpy.oldnumer
ic.alter_code1 module.
 Code written to the compatibility layer will work and be supported.
 The purpose of the compatibility layer is to make it easy to convert to
 NumPy and many codes may only take this first step and work fine with NumPy.
 The second step is optional as it removes dependency on the compatibility
 layer and therefore requires a few more extensive changes.
 Many of these changes can be performed by the numpy.oldnumeric.alter_code2
 module, but you may still need to do some final tweaking by hand.
 Because many users will probably be content to only use the first step,
 the alter_code2 module for second-stage migration may not be as complete
 as it otherwise could be.
 
\end_layout

\begin_layout Subsection
First-step changes
\end_layout

\begin_layout Standard
In order to use the compatibility layer there are still a few changes that
 need to be made to your code.
 Many of these changes can be made by running the alter_code1 module with
 your code as input.
 
\end_layout

\begin_layout Enumerate
Importing (the alter_code1 module handles all these changes)
\end_layout

\begin_deeper
\begin_layout Enumerate
import Numeric --> import numpy.oldnumeric as Numeric
\end_layout

\begin_layout Enumerate
import Numeric as XX --> import numpy.oldnumeric as XX
\end_layout

\begin_layout Enumerate
from Numeric import <name1>,...<nameN> --> from numpy.oldnumeric import <name1>,...,<na
meN>
\end_layout

\begin_layout Enumerate
from Numeric import * --> from numpy.oldnumeric import * 
\end_layout

\begin_layout Enumerate
Similar name changes need to be made for Matrix, MLab, UserArray, LinearAlgebra,
 RandomArray RNG, RNG.Statistics, and FFT.
 The new names are numpy.oldnumeric.<pkg> where <pkg> is matrix, mlab, user_array,
 linear_algebra, random_array, rng, rng_stats, and fft.
 
\end_layout

\begin_layout Enumerate
multiarray and umath (if you used them directly) are now numpy.core.multiarray
 and numpy.core.umath, but it is more future proof to replace usages of these
 internal modules with numpy.oldnumeric.
\end_layout

\end_deeper
\begin_layout Enumerate
Method name changes and methods converted to attributes.
 The alter_code1 module handles all these changes.
 
\end_layout

\begin_deeper
\begin_layout Enumerate

\emph on
arr
\emph default
.typecode() --> 
\emph on
arr
\emph default
.dtype.char
\end_layout

\begin_layout Enumerate

\emph on
arr
\emph default
.iscontiguous() --> 
\emph on
arr
\emph default
.flags.contiguous
\end_layout

\begin_layout Enumerate

\emph on
arr
\emph default
.byteswapped() --> 
\emph on
arr
\emph default
.byteswap()
\end_layout

\begin_layout Enumerate

\emph on
arr
\emph default
.toscalar() --> 
\emph on
arr
\emph default
.item()
\end_layout

\begin_layout Enumerate

\emph on
arr
\emph default
.itemsize() --> 
\emph on
arr
\emph default
.itemsize
\end_layout

\begin_layout Enumerate

\emph on
arr
\emph default
.spacesaver() eliminated 
\end_layout

\begin_layout Enumerate

\emph on
arr
\emph default
.savespace() eliminated 
\end_layout

\end_deeper
\begin_layout Enumerate
Some of the typecode characters have changed to be more consistent with
 other Python modules (array and struct).
 You should only notice this change if you used the actual typecode characters
 (instead of the named constants).
 
\newline
The alter_code1 module will change uses of 'b' to 'B' for internal Numeric
 functions that it knows about because NumPy will interpret 'b' to mean
 a signed byte type (instead of the old unsigned).
 It will also change the character codes when they are used explicitly in
 the .astype method.
 In the compatibility layer (and only in the compatibility layer), typecode-requ
iring function calls (
\emph on
e.g.

\emph default
 zeros, array) understand the old typecode characters.
 
\newline
The changes are (Numeric --> NumPy): 
\end_layout

\begin_deeper
\begin_layout Enumerate
'b' --> 'B' 
\end_layout

\begin_layout Enumerate
'1' --> 'b'
\end_layout

\begin_layout Enumerate
's' --> 'h'
\end_layout

\begin_layout Enumerate
'w' --> 'H'
\end_layout

\begin_layout Enumerate
'u' --> 'I'
\end_layout

\end_deeper
\begin_layout Enumerate

\emph on
arr.
\emph default
flat now returns an indexable 1-D iterator.
 This behaves correctly when passed to a function, but if you expected methods
 or attributes on 
\emph on
arr.
\emph default
flat --- besides .copy() --- then you will need to replace 
\emph on
arr
\emph default
.flat with 
\emph on
arr.
\emph default
ravel() (copies only when necessary) or 
\emph on
arr.
\emph default
flatten() (always copies).
 The alter_code1 module will change 
\emph on
arr
\emph default
.flat to 
\emph on
arr
\emph default
.ravel() unless you used the construct 
\emph on
arr
\emph default
.flat = obj or 
\emph on
arr
\emph default
.flat[ind].
\end_layout

\begin_layout Enumerate
If you used type-equality testing on the objects returned from arrays, then
 you need to change this to isinstance testing.
 Thus type(a[0]) is float or type(a[0]) == float should be changed to isinstance
(a[0], float).
 This is because array scalar objects are now returned from arrays.
 These inherit from the Python scalars where they can, but define their
 own methods and attributes.
 This conversion is done by alter_code1 for the types (float, int, complex,
 and ArrayType)
\end_layout

\begin_layout Enumerate
If your code should produce 0-d arrays.
 These no-longer have a length as they should be interpreted similarly to
 real scalars which don't have a length.
 
\end_layout

\begin_layout Enumerate
Arrays cannot be tested for truth value unless they are empty (returns False)
 or have only one element.
 This means that if Z: where Z is an array will fail (unless Z is empty
 or has only one element).
 Also the 'and' and 'or' operations (which test for object truth value)
 will also fail on arrays of more than one element.
 Use the .any() and .all() methods to test for truth value of an array.
 
\end_layout

\begin_layout Enumerate
Masked arrays return a special nomask object instead of None when there
 is no mask on the array for the functions getmask and attribute access
 
\emph on
arr
\emph default
.mask
\end_layout

\begin_layout Enumerate
Masked array functions have a default axis of None (meaning ravel), make
 sure to specify an axis if your masked arrays are larger than 1-d.
 
\end_layout

\begin_layout Enumerate
If you used the construct 
\family typewriter
arr.shape=<tuple>
\family default
, this will not work for array scalars (which can be returned from array
 operations).
 You cannot set the shape of an array-scalar (you can read it though).
 As a result, for more general code you should use 
\family typewriter
arr=arr.reshape(<tuple>)
\family default
 which works for both array-scalars and arrays.
 
\end_layout

\begin_layout Standard
The alter_code1 script should handle the changes outlined in steps 1-5 above.
 The final incompatibilities in 6-9 are less common and must be modified
 by hand if necessary.
 
\end_layout

\begin_layout Subsection
Second-step changes
\end_layout

\begin_layout Standard
During the second phase of migration (should it be necessary) the compatibility
 layer is dropped.
 This phase requires additional changes to your code.
 There is another conversion module (alter_code2) which can help but it
 is not complete.
 The changes required to drop dependency on the compatibility layer are
\end_layout

\begin_layout Enumerate
Importing 
\end_layout

\begin_deeper
\begin_layout Enumerate
numpy.oldnumeric --> numpy
\end_layout

\begin_layout Enumerate
from numpy.oldnumeric import * --> from numpy import * (this may clobber
 more names and therefore require further fixes to your code but then you
 didn't do this regularly anyway did you).
 The recommended procedure if this replacement causes problems is to fix
 the use of from numpy.oldnumeric import * to extract only the required names
 and then continue.
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.mlab --> None, the functions come from other places.
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.linear_algebra --> numpy.lilnalg with name changes to the
 functions (made lower case and shorter).
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.random_array --> numpy.random with some name changes to the
 functions.
\end_layout

\begin_layout Enumerate
numpy.oldnumeic.fft --> numpy.fft with some name changes to the functions.
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.rng --> None
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.rng_stats --> None
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.user_array --> numpy.lib.user_array
\end_layout

\begin_layout Enumerate
numpy.oldnumeric.matrix --> numpy
\end_layout

\end_deeper
\begin_layout Enumerate
The typecode names are all lower-case and refer to type-objects corresponding
 to array scalars.
 The character codes are understood by array-creation functions but are
 not given names.
 All named type constants should be replaced with their lower-case equivalents.
 Also, the old character codes '1', 's', 'w', and 'u' are not understood
 as data-types.
 It is probably easiest to manually replace these with Int8, Int16, UInt16,
 and UInt32 and let the alter_code2 script convert the names to lower-case
 typeobjects.
 
\end_layout

\begin_layout Enumerate
Keyword and argument changes
\end_layout

\begin_deeper
\begin_layout Enumerate
All 
\family typewriter
typecode=
\family default
 keywords must be changed to 
\family typewriter
dtype=
\family default
.
 
\end_layout

\begin_layout Enumerate
The 
\family typewriter
savespace
\family default
 keyword argument has been removed from all functions where it was present
 (array, sarray, asarray, ones, and zeros).
 The sarray function is equivalent to asarray.
\end_layout

\end_deeper
\begin_layout Enumerate
The default data-type in NumPy is float unlike in Numeric (and numpy.oldnumeric)
 where it was int.
 There are several functions affected by this so that if your code was relying
 on the default data-type, then it must be changed to explicitly add dtype=int.
\end_layout

\begin_layout Enumerate
The nonzero function in NumPy returns a tuple of index arrays just like
 the corresponding method.
 There is a flatnonzero function that first ravels the array and then returns
 a single index array.
 This function should be interchangeable with the old use of nonzero.
 
\end_layout

\begin_layout Enumerate
The default axis is None (instead of 0) to match the methods for the functions
 take, repeat, sum, average, product, sometrue, alltrue, cumsum, and cumproduct
 (from Numeric) and also for the functions average, max, min, ptp, prod,
 std, and mean (from MLab).
\end_layout

\begin_layout Enumerate
The default axis is None (instead of -1) to match the methods for the functions
 argmin, argmax, compress
\end_layout

\begin_layout Subsection
Updating code that uses Numeric using alter_codeN
\end_layout

\begin_layout Standard
Despite the long list of changes that might be needed given above, it is
 likely that your code does not use any of the incompatible corners and
 it should not be too difficult to convert from Numeric to NumPy.
 For example all of SciPy was converted in about 2-3 days.
 The needed changes are largely search-and replace type changes, and the
 alter_codeN modules can help.
 The modules have two functions which help the process:
\end_layout

\begin_layout Description
convertfile (filename, orig=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Convert the file with the given filename to use NumPy.
 If orig is True, then a backup is first made and given the name filename.orig.
 Then, the file is converted and the updated code written over the top of
 the old file.
 
\end_layout

\begin_layout Description
convertall (direc=os.path.curdir, orig=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Converts all the 
\begin_inset Quotes eld
\end_inset

.py
\begin_inset Quotes erd
\end_inset

 files in the given directory to use NumPy.
 Backups of all the files are first made if orig is True as explained for
 the convertfile function.
 
\end_layout

\begin_layout Description
convertsrc (direc=os.path.curdir, ext=None, orig=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Replace 
\family typewriter
''Numeric/arrayobject.h
\begin_inset Quotes erd
\end_inset


\family default
 with 
\family typewriter
''numpy/oldnumeric.h
\begin_inset Quotes erd
\end_inset


\family default
 in all files ending in the list of extensions given by ext (if ext is None,
 then all files are updated).
 If orig is True, then first make a backup file with 
\begin_inset Quotes eld
\end_inset

.orig
\begin_inset Quotes erd
\end_inset

 as the extension.
\end_layout

\begin_layout Description
converttree (direc=os.path.curdir)
\end_layout

\begin_layout Description
\InsetSpace ~
 Walks the tree pointed to by direc and converts all 
\begin_inset Quotes eld
\end_inset

.py
\begin_inset Quotes erd
\end_inset

 modules in each sub-directory to use NumPy.
 No backups of the files are made.
 Also, converts all .h and .c files to replace 
\family typewriter
''Numeric/arrayobject.h
\begin_inset Quotes erd
\end_inset


\family default
 with 
\family typewriter
''numpy/oldnumeric.h
\begin_inset Quotes erd
\end_inset


\family default
 so that NumPy is used.
 
\end_layout

\begin_layout Subsection
Changes to think about 
\end_layout

\begin_layout Standard
Even if you don't make changes to your old code.
 If you are used to coding in Numeric, then you may need to adjust your
 coding style a bit.
 This list provides some helpful things to remember.
 
\end_layout

\begin_layout Enumerate
Switch from using typecode characters to bitwidth type names or c-type names
 
\end_layout

\begin_layout Enumerate
Convert use of uppercase type-names Int32, Float, etc., to lower case int32,
 float, etc.
\end_layout

\begin_layout Enumerate
Convert use of functions to method calls where appropriate but explicitly
 specify any axis arguments for arrays greater than 1-d.
 
\end_layout

\begin_layout Enumerate
The names for standard computations like Fourier transforms, linear algebra,
 and random-number generation have changed to conform to the standard of
 lower-case names possibly separated by an underscore.
\end_layout

\begin_layout Enumerate
Look for ways to take advantage of advanced slicing, but remember it always
 returns a copy and may be slower at times.
\end_layout

\begin_layout Enumerate
Remove any kludges you inserted to eliminate problems with Numeric that
 are now gone.
 
\end_layout

\begin_layout Enumerate
Look for ways to take advantage of new features like expanded data-types
 (record-arrays).
 
\end_layout

\begin_layout Enumerate
See if you can inherit from the ndarray directly, rather than using user_array.co
ntainer (UserArray).
 However, if you were using UserArray in a multiple-inheritance hierarchy
 this is going to be more difficult and you can continue to use the standard
 container class in user_array (but notice the name change).
 
\end_layout

\begin_layout Enumerate
Watch your usage of scalars extracted from arrays.
 Treating Numeric arrays like lists and then doing math on the elements
 1 by 1 was always about 2x slower than using real lists in Python.
 This can now be 3x-6x slower than using lists in NumPy because of the increased
 complexity of both the indexing of ndarrays and the math of array scalars.
 If you must select individual scalars from NumPy, you can get some speed
 increases by using the item method to get a standard Python scalar from
 an N-d array and by using the itemset method to place a scalar into a particula
r location in the N-d array.
 This complicates the appearance of the code, however.
 Also, when using these methods inside a loop, be sure to assign the methods
 to a local variable to avoid the attribute look-up at each loop iteration.
 
\end_layout

\begin_layout Standard
Throughout this book, warnings are inserted when compatibility issues with
 old Numeric are raised.
 While you may not need to make any changes to get code to run with the
 ndarray object, you will likely want to make changes to take advantage
 of the new features of NumPy.
 If you get into a jam during the conversion process, you should be aware
 that Numeric and NumPy can both be used together and they will not interfere
 with each other.
 In addition, if you have Numeric 24.0 or newer, they can even share the
 same memory.
 This makes it easy to use NumPy as well as third-party tools that have
 not made the switch from Numeric yet.
\end_layout

\begin_layout Section
Summary of differences with Numarray
\end_layout

\begin_layout Standard
Conversion from Numarray can also be relatively painless, depending on how
 dependent your code is on the specific structure of the Numarray ufuncs,
 cfuncs, and various array-like objects.
 The internals of Numarray can be quite different and so depending on how
 intimately you used those internals adapting to NumPy can be more or less
 difficult.
 C-code that used the Numarray C-API can be easily adapted because NumPy
 includes a Numarray-compatible C-API module.
 All you need to do is replace usage of 
\begin_inset Quotes eld
\end_inset

numarray/libnumarray.h
\begin_inset Quotes erd
\end_inset

 with 
\begin_inset Quotes eld
\end_inset

numpy/libnumarray.h
\begin_inset Quotes erd
\end_inset

 and be sure the directory returned from the Python command numpy.get_numarray_in
clude() is included in the list of directories used for compilation.
\end_layout

\begin_layout Standard
On the Python-side the largest number of differences are in the methods
 and attributes of the array and the way array data-types are represented.
 In addition, arrays containing Python Objects, strings, and records are
 an integral part of the array object and not handled using a separate class
 (although enhanced separate classes do exist for the case of character
 arrays and record arrays).
 
\end_layout

\begin_layout Standard
As is the case with Numeric, there is a two-step process available for migrating
 code written for Numarray to work with NumPy.
 This process involves running functions in the modules alter_code1 and
 alter_code2 located in the numarray sub-package of NumPy.
 These modules have interfaces identical to the ones that convert Numeric
 code, but they work to convert code written for numarray.
 The first module will convert your code to use the numarray compatibility
 module (numpy.numarray), while the second will try and help convert code
 to move away from dependency on the compatibility module.
 Because many users will probably be content to only use the first step,
 the alter_code2 module for second-stage migration may not be as complete
 as it otherwise could be.
 
\end_layout

\begin_layout Standard
Also, the alter_code1 module is not guaranteed to convert every piece of
 working numarray code to use NumPy.
 If your code relied on the internal module structure of numarray or on
 how the class hierarchy was laid out, then it will need to be changed manually
 to run with NumPy.
 Of course you can still use your code with Numarray installed side-by-side
 and the two array objects should be able to exchange data without copying.
 
\end_layout

\begin_layout Subsection
First-step changes
\end_layout

\begin_layout Standard
The alter_code1 script makes the following import and attribute/method changes
\end_layout

\begin_layout Subsubsection
Import changes
\end_layout

\begin_layout Itemize
import numarray --> import numpy.numarray as numarray
\end_layout

\begin_layout Itemize
import numarray.package --> import numpy.numarray.package as numarray_package
 with all usages of numarray.package in the code replaced by numarray_package
\end_layout

\begin_layout Itemize
import numarray as <name> --> import numpy.numarray s <name>
\end_layout

\begin_layout Itemize
import numarray.package as <name> --> import numpy.numarray.package as <name>
\end_layout

\begin_layout Itemize
from numarray import <names> --> from numpy.numarray import <names>
\end_layout

\begin_layout Itemize
from numarray.package import <names> --> from numpy.numarray.package import
 <names>
\end_layout

\begin_layout Subsubsection
Attribute and method changes
\end_layout

\begin_layout Itemize
.imaginary --> .imag
\end_layout

\begin_layout Itemize
.flat --> probably .ravel() (Many usages will still work correctly because
 you can index and assign to self.flat)
\end_layout

\begin_layout Itemize
.byteswapped() --> .byteswap(False)
\end_layout

\begin_layout Itemize
.byteswap() --> .byteswap(True) (Returns a reference to self instead of None).
 
\end_layout

\begin_layout Itemize
self.info() --> numarray.info(self)
\end_layout

\begin_layout Itemize
.isaligned() --> .flags.aligned
\end_layout

\begin_layout Itemize
.isbyteswapped() --> not .dtype.isnative (the byte-order is a property of the
 data-type object not the array itself in NumPy).
 
\end_layout

\begin_layout Itemize
.iscontiguous() --> .flags.c_contiguous
\end_layout

\begin_layout Itemize
.is_c_array() --> .dtype.isnative and .flags.carray
\end_layout

\begin_layout Itemize
.is_fortran_contiguous() --> .flags.f_contiguous
\end_layout

\begin_layout Itemize
.is_f_array() --> .dtype.isnative and .flags.farray
\end_layout

\begin_layout Itemize
.itemsize() --> .itemsize
\end_layout

\begin_layout Itemize
.nelements() --> .size
\end_layout

\begin_layout Itemize
self.new(type) --> numarray.newobj(self, type)
\end_layout

\begin_layout Itemize
.repeat(r) --> .repeat(r, axis=0)
\end_layout

\begin_layout Itemize
.size() --> .size
\end_layout

\begin_layout Itemize
.type() --> numarray.typefrom(self) 
\end_layout

\begin_layout Itemize
.typecode() --> .dtype.char
\end_layout

\begin_layout Itemize
.stddev() --> .std()
\end_layout

\begin_layout Itemize
.togglebyteorder() --> numarray.togglebyteorder(self)
\end_layout

\begin_layout Itemize
.getshape() --> .shape
\end_layout

\begin_layout Itemize
.setshape(obj) --> .shape = obj
\end_layout

\begin_layout Itemize
.getflat() --> .ravel()
\end_layout

\begin_layout Itemize
.getreal() --> .real
\end_layout

\begin_layout Itemize
.setreal(obj) --> .real = obj
\end_layout

\begin_layout Itemize
.getimag() --> .imag
\end_layout

\begin_layout Itemize
.setimag(obj) --> .imag = obj
\end_layout

\begin_layout Itemize
.getimaginary() --> .imag
\end_layout

\begin_layout Itemize
.setimaginary(obj) --> .imag = obj
\end_layout

\begin_layout Subsection
Second-step changes
\end_layout

\begin_layout Standard
One of the notable differences is that several functions (array, arange,
 fromfile, and fromstring) do not take the shape= keyword argument.
 Instead you simply reshape the result using the reshape method.
 Another notable difference is that instead of allowing typecode=, type=,
 and dtype= variants for specifying the data-types, you must use the dtype=
 keyword.
 Other differences include
\end_layout

\begin_layout Itemize
matrixmultiply(a,b) --> dot(a,b)
\end_layout

\begin_layout Itemize
innerproduct(a,b) --> inner(a,b)
\end_layout

\begin_layout Itemize
outerproduct(a,b) --> outer(a,b)
\end_layout

\begin_layout Itemize
kroneckerproduct(a,b) --> kron(a,b)
\end_layout

\begin_layout Itemize
tensormultiply(a,b) --> None
\end_layout

\begin_layout Subsection
Additional Extension modules
\end_layout

\begin_layout Standard
There are three extension packages that come included with numarray which
 are now downloaded separately.
 Stubs for these packages exist in numpy.numarray but they try and find the
 actual code by looking at what is currently installed.
 These packages are available in SciPy but can be installed separately as
 well:
\end_layout

\begin_layout Itemize
nd_image --> scipy.ndimage
\end_layout

\begin_layout Itemize
convolve --> scipy.stsci.convolve
\end_layout

\begin_layout Itemize
image --> scipy.stsci.image
\end_layout

\begin_layout Standard
If you don't want to install all of scipy, you can grab just these packages
 from SVN using
\end_layout

\begin_layout LyX-Code
svn co http://svn.scipy.org/svn/scipy/trunk/Lib/ndimage ndimage
\end_layout

\begin_layout LyX-Code
svn co http://svn.scipy.org/svn/scipy/trunk/Lib/stsci stsci
\end_layout

\begin_layout Standard
and then run
\end_layout

\begin_layout LyX-Code
cd ndimage; sudo python setup.py install
\end_layout

\begin_layout LyX-Code
cd stsci; sudo python setup.py install
\end_layout

\begin_layout Standard
On a Windows system, you can use the Tortoise SVN client which is integrated
 into the Windows Explorer.
 It can be downloaded from http://tortoisesvn.tigris.org.
 Instructions on how to use it are also provided on that site.
 After downloading the packages from SVN, installation will still require
 a C-compiler (the mingw32 compiler works fine even with MSVC-compiled Python
 as long as you specify --compiler=mingw32).
 Alternatively you can download binary releases of scipy from http://www.scipy.org
 to get the needed functionality or use the Enthon edition of Python.
\end_layout

\begin_layout Chapter
The Array Object
\end_layout

\begin_layout Quotation
Don't worry about people stealing your ideas.
 If your ideas are any good, you'll have to ram them down people's throats.
\end_layout

\begin_layout Right Address
---
\emph on
Howard Aiken, IBM engineer
\end_layout

\begin_layout Quotation
No idea is so antiquated that it was not once modern; no idea is so modern
 that it will not someday be antiquated.
\end_layout

\begin_layout Right Address
---
\emph on
Ellen Glasgow
\end_layout

\begin_layout Section

\family typewriter
ndarray
\family default
 Attributes
\end_layout

\begin_layout Standard
Array
\begin_inset LatexCommand index
name "ndarray|("

\end_inset

 attributes reflect information that is intrinsic to the array itself.
 Generally, accessing an array through its attributes allows you to get
 and sometimes set intrinsic properties of the array without creating a
 new array.
 The exposed attributes are the core parts of an array and only some of
 them can be reset meaningfully without creating a new array.
 Table 
\begin_inset LatexCommand ref
reference "cap:ndarray-attributes"

\end_inset

 shows all the attributes
\begin_inset LatexCommand index
name "ndarray!attributes|("

\end_inset

 with a brief description.
 Detailed information on each attribute is given below.
\end_layout

\begin_layout Warning
Numeric Compatibility: you should check your old use of the .flat attribute.
 This attribute now returns an iterator object which acts like a 1-d array
 in terms of indexing.
 while it does not share all the attributes or methods of an array, it will
 be interpreted as an array in functions that take objects and convert them
 to arrays.
 Furthermore, Any changes in an array converted from a 1-d iterator will
 be reflected back in the original array when the converted array is deleted.
 
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:ndarray-attributes"

\end_inset

Attributes of the 
\family typewriter
ndarray
\family default
.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
vspace*{-0.2in}
\backslash
setlength{
\backslash
extrarowheight}{0.25eM}
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="18" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="1in">
<column alignment="center" valignment="top" leftline="true" width="1in">
<column alignment="block" valignment="top" leftline="true" rightline="true" width="3in">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Attribute
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Settable
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Description
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
flags
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
special array-connected dictionary-like object with attributes showing the
 state of flags in this array; only the flags WRITEABLE, ALIGNED, and UPDATEIFCO
PY can be modified by setting attributes of this object
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
shape
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
tuple showing the array shape; setting this attribute re-shapes the array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
strides
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
tuple showing how many 
\emph on
bytes
\emph default
 must be jumped in the data segment to get from one entry to the next
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
ndim
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
number of dimensions in array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
data
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
buffer object loosely wrapping the array data (only works for single-segment
 arrays)
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
size
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
total number of elements 
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
itemsize
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
size (in bytes) of each element 
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
nbytes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
total number of bytes used
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
base
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
object this array is using for its data buffer, or None if it owns its own
 memory
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
dtype
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
data-type object for this array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
real
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
real part of the array; setting copies data to real part of current array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
imag
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
imaginary part, or read-only zero array if type is not complex; setting
 works only if type is complex
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
flat
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
one-dimensional, indexable iterator object that acts somewhat like a 1-d
 array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
ctypes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
object to simplify the interaction of this array with the ctypes module
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
__array_interface__
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
dictionary with keys (data, typestr, descr, shape, strides) for compliance
 with Python side of array protocol
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
__array_struct__
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
array interface on C-level
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
__array_priority__
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
always 0.0 for base type 
\family typewriter
ndarray
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset

 
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Memory Layout attributes
\end_layout

\begin_layout Description
flags
\begin_inset LatexCommand index
name "ndarray!attributes!flags"

\end_inset

 
\end_layout

\begin_layout Description
\InsetSpace ~
 Array flags
\begin_inset LatexCommand index
name "ndarray!flags|("

\end_inset

 provide information about how the memory area used for the array is to
 be interpreted.
 There are 6 Boolean flags in use which govern whether or not:
\end_layout

\begin_deeper
\begin_layout Description
C_CONTIGUOUS\InsetSpace ~
(C) the data is in a single, C-style contiguous segment;
\end_layout

\begin_layout Description
F_CONTIGUOUS\InsetSpace ~
(F) the data is in a single, Fortran-style contiguous segment;
\end_layout

\begin_layout Description
OWNDATA\InsetSpace ~
(O) the array owns the memory it uses or if it borrows it from another
 object (if this is False, the base attribute retrieves a reference to the
 object this array obtained its data from);
\end_layout

\begin_layout Description
WRITEABLE\InsetSpace ~
(W) the data area can be written to;
\end_layout

\begin_layout Description
ALIGNED\InsetSpace ~
(A) the data and strides are aligned appropriately for the hardware
 (as determined by the compiler);
\end_layout

\begin_layout Description
UPDATEIFCOPY\InsetSpace ~
(U) this array is a copy of some other array (referenced by
 
\family typewriter
.base
\family default
).
 When this array is deallocated, the base array will be updated with the
 contents of this array.
\end_layout

\end_deeper
\begin_layout Description
\InsetSpace ~
 Only the 
\series bold
UPDATEIFCOPY
\series default
, 
\series bold
WRITEABLE
\series default
, and 
\series bold
ALIGNED
\series default
 flags can be changed by the user.
 This can be done using the special array-connected, dictionary-like object
 that the flags attribute returns.
 By setting elements in this dictionary, the underlying array obect's flags
 are altered.
 Flags can also be changed using the method 
\family typewriter
setflags
\family default
(...).
 All flags in the dictionary can be accessed using their first (upper case)
 letter as well as the full name.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 Certain logical combinations of flags can also be read using named keys
 to the special flags dictionary.
 These combinations are
\end_layout

\begin_deeper
\begin_layout Description
FNC Returns F_CONTIGUOUS and not C_CONTIGUOUS
\end_layout

\begin_layout Description
FORC Returns F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
\end_layout

\begin_layout Description
BEHAVED\InsetSpace ~
(B) Returns ALIGNED and WRITEABLE 
\end_layout

\begin_layout Description
CARRAY\InsetSpace ~
(CA) Returns BEHAVED and C_CONTIGUOUS
\end_layout

\begin_layout Description
FARRAY_(FA) Returns BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS
\end_layout

\end_deeper
\begin_layout Note
The array flags cannot be set arbitrarily.
 UPDATEIFCOPY can only be set False.
 the ALIGNED flag can only be set True if the data is truly aligned.
 The flag WRITEABLE can only be set True if the array owns its own memory
 or the ultimate owner of the memory exposes a writeable buffer interface
 (or is a string).
 The exception for string is made so that unpickling can be done without
 copying memory.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 Flags can also be set and read using attribute access with the lower-case
 key equivalent (without first letter support).
 Thus, for example, self.flags.c_contiguous returns whether or not the array
 is C-style contiguous, and self.flags.writeable=True changes the array to
 be writeable (if possible)
\begin_inset LatexCommand index
name "ndarray!flags|)"

\end_inset

.
\end_layout

\begin_layout Description
shape
\begin_inset LatexCommand index
name "ndarray!attributes!shape"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The shape of the array is a tuple giving the number of elements in each
 dimension.
 The shape can be reset for single-segment arrays by setting this attribute
 to another tuple.
 The total number of elements cannot change.
 However, a -1 may be used in a dimension entry to indicate that the array
 length in that dimension should be computed so that the total number of
 elements does not change.
 
\family typewriter
a.shape=x
\family default
 is equivalent to 
\family typewriter
a=a.reshape(x)
\family default
 except the latter can be used even if the array is not single-segment and
 even if 
\begin_inset Formula $a$
\end_inset

 is an array scalar.
 
\end_layout

\begin_layout Note
Setting the shape attribute to () for a 1-element array will turn self into
 a 0-dimensional array.
 This is one of the few ways to get a 0-dimensional array in Python.
 Most other operations will return an array scalar.
 Other ways to get a 0-dimensional array in Python include calling array
 with a scalar argument and calling the squeeze method of an array whose
 shape is all 1's.
 
\end_layout

\begin_layout Description
strides
\begin_inset LatexCommand index
name "ndarray!attributes!strides"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The strides of an array is a tuple showing for each dimension how many
 
\emph on
bytes
\emph default
 must be skipped to get to the next element in that dimension.
 Setting this attribute to another tuple will change the way the memory
 is viewed.
 This attribute can only be set to a tuple that will not cause the array
 to access unavailable memory.
 If an attempt is made to do so, ValueError is raised.
\end_layout

\begin_layout Description
ndim
\begin_inset LatexCommand index
name "ndarray!attributes!ndim"

\end_inset

 
\end_layout

\begin_layout Description
\InsetSpace ~
 The number of dimensions of an array is sometimes called the rank of the
 array.
 Getting this attribute reveals the length of the shape tuple and the strides
 tuple.
 
\end_layout

\begin_layout Description
data
\begin_inset LatexCommand index
name "ndarray!attributes!data"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 A buffer object referencing the actual data for this array if this array
 is single-segment.
 If the array is not single-segment, then an AttributeError is raised.
 The buffer object is writeable depending on the status of self.flags.writeable.
\end_layout

\begin_layout Description
size
\begin_inset LatexCommand index
name "ndarray!attributes!size"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The total number of elements in the array.
\end_layout

\begin_layout Description
itemsize
\begin_inset LatexCommand index
name "ndarray!attributes!itemsize"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The number of bytes each element of the array requires.
 
\end_layout

\begin_layout Description
nbytes
\begin_inset LatexCommand index
name "ndarray!attributes!nbytes"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The total number of bytes used by the array.
 This is equal to 
\family typewriter
self.itemsize*self.size
\family default
.
\end_layout

\begin_layout Description
base
\begin_inset LatexCommand index
name "ndarray!attributes!base"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 If the array does not own its own memory, then this attribute returns the
 object whose memory this array is referencing.
 The returned object may not be the original allocator of the memory, but
 may be borrowing it from still another object.
 If this array does own its own memory, then None is returned unless the
 UPDATEIFCOPY flag is True in which case self.base is the array that will
 be updated when self is deleted.
 UPDATEIFCOPY gets set for an array that is created as a behaved copy of
 a general array.
 The intent is for the misaligned array to get any changes that occur to
 the copy.
 
\end_layout

\begin_layout Subsection
Data Type attributes
\end_layout

\begin_layout Standard
There are several ways to specify the kind of data that the array is composed
 of.
 The fullest description that preserves field information is always obtained
 using an actual dtype object.
 See Chapter 
\begin_inset LatexCommand ref
reference "cha:Data-descriptor-objects"

\end_inset

 for more discussion on data-type objects and acceptable arguments to construct
 data-type objects.
 Three commonly-used attributes of the data-type object returned are also
 documented here.
\end_layout

\begin_layout Description
dtype
\begin_inset LatexCommand index
name "ndarray!attributes!dtype"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 A data-type object that fully describes (including any defined fields)
 each fixed-length item in the array.
 Whether or not the data is in machine byte-order is also determined by
 the data-type.
 The data-type attribute can be set to anything that can be interpreted
 as a data-type (see Chapter 
\begin_inset LatexCommand ref
reference "cha:Data-descriptor-objects"

\end_inset

 for more information).
 Setting this attribute allows you to change the interpretation of the data
 in the array.
 The new data-type must be compatible with the array's current data-type.
 The new data-type is compatible if it has the same itemsize as the current
 data-type descriptor, or (if the array is a single-segment array) if the
 the array with the new data-type fits in the memory already consumed by
 the array.
 
\end_layout

\begin_layout Description
dtype.type
\end_layout

\begin_layout Description
\InsetSpace ~
 A Python type object gives the typeobject whose instances represent elements
 of the array.
 This type object can be used to instantiate a scalar of that type.
 
\end_layout

\begin_layout Description
dtype.char
\end_layout

\begin_layout Description
\InsetSpace ~
 A typecode character unique to each of the 21 built-in types.
 
\end_layout

\begin_layout Description
dtype.str
\end_layout

\begin_layout Description
\InsetSpace ~
 This string consists of a required first character giving the 
\begin_inset Quotes eld
\end_inset

endianness
\begin_inset Quotes erd
\end_inset

 of the data (
\begin_inset Quotes eld
\end_inset

<
\begin_inset Quotes erd
\end_inset

 for little endian, 
\begin_inset Quotes eld
\end_inset

>
\begin_inset Quotes erd
\end_inset

 for big endian, and 
\begin_inset Quotes eld
\end_inset

|
\begin_inset Quotes erd
\end_inset

 for irrelevant), the second character is a code for the kind of data ('b'
 for Boolean, 'i' for signed integer, 'u' for unsigned integer, 'f' for
 floating-point, 'c' for complex floating point, 'O' for object, 'S' for
 ASCII string, 'U' for unicode, and 'V' for void), the final characters
 give the number of bytes each element uses.
\end_layout

\begin_layout Subsection
Other attributes
\end_layout

\begin_layout Description
T
\begin_inset LatexCommand index
name "ndarray!attributes!T"

\end_inset

 
\end_layout

\begin_layout Description
\InsetSpace ~
 Equivalent to self.transpose().
 For self.ndim < 2, it returns a view of self.
 
\end_layout

\begin_layout Warning
If arr is 0- or 1-dimensional, then arr.T will return a new ndarray which
 refers to the same data as arr.
 This is because transpose has the effect of reversing the shape attribute
 of an array (whose 0-d and 1-d equivalent is to return the same array).
 This may be surprising if you are thinking of your 1-d array as a 
\begin_inset Quotes eld
\end_inset

row
\begin_inset Quotes erd
\end_inset

 or a 
\begin_inset Quotes eld
\end_inset

column
\begin_inset Quotes erd
\end_inset

 vector and expected the .T attribute to return the other convention.
 
\end_layout

\begin_layout Description
real
\begin_inset LatexCommand index
name "ndarray!attributes!real"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The real part of an array.
 For arrays that are not complex this attribute returns the array itself.
 Setting this attribute allows setting just the real part of an array.
 If the array is already real then setting this attribute is equivalent
 to self[...] = values.
\end_layout

\begin_layout Description
imag
\begin_inset LatexCommand index
name "ndarray!attributes!imag"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 A view of the imaginary part of an array.
 For arrays that are not complex, this returns a read-only array of zeros.
 Setting this array allows in-place alteration of the complex part of an
 imaginary array.
 If the array is not complex, then trying to set this attribute raises an
 Error.
 
\end_layout

\begin_layout Description
flat
\begin_inset LatexCommand index
name "ndarray!attributes!flat"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Return an iterator object (numpy.flatiter) that acts like a 1-d version
 of the array.
 1-d indexing works on this array and it can be passed in to most routines
 as an array wherein a 1-d array will be constructed from it.
 The new 1-d array will reference this array's data if this array is C-style
 contiguous, otherwise, new memory will be allocated for the 1-d array,
 the UPDATEIFCOPY flag will be set for the new array, and this array will
 have its WRITEABLE flag set FALSE until the the last reference to the new
 array disappears.
 When the last reference to the new 1-d array disappears, the data will
 be copied over to this non-contiguous array.
 This is done so that a.flat effectively references the current array regardless
 of whether or not it is contiguous or non-contiguous.
 As an example, consider the following code:
\end_layout

\begin_layout MyCode
>>> a = zeros((4,5))
\newline
>>> b = ones(6)
\newline
>>> add(b,b,a[1:3,0:3].flat)
\newline
array([[ 2.,
  2.,  2.],
\newline
       [ 2.,  2.,  2.]])
\newline
>>> print a
\newline
[[ 0.
  0.
  0.
  0.
  0.]
\newline
 [ 2.
  2.
  2.
  0.
  0.]
\newline
 [ 2.
  2.
  2.
  0.
  0.]
\newline
 [ 0.
  0.
  0.
  0.
  0.]]
\end_layout

\begin_layout Description
\InsetSpace ~
 The numpy.flatiter object has two methods: 
\series bold
__array__()
\series default
 and 
\series bold
copy()
\series default
 and one attribute: 
\series bold
base
\series default
.
 The base attribute returns a reference to the underlying array.
 
\end_layout

\begin_layout Description
__array_priority__
\begin_inset LatexCommand index
name "ndarray!attributes!\\_\\_array\\_priority\\_\\_"

\end_inset

 
\end_layout

\begin_layout Description
\InsetSpace ~
 The array priority attribute is a floating point number useful in mixed
 operations involving two subtypes to decide which subtype is returned.
 The base ndarray object has priority 0.0 and 1.0 is the default subtype priority.
\end_layout

\begin_layout Subsection
Array Interface attributes
\end_layout

\begin_layout Standard
The array interface
\begin_inset LatexCommand index
name "array interface"

\end_inset

 (sometimes called array protocol) was created in 2005 as a means for array-like
 Python objects to re-use each other's data buffers intelligently whenever
 possible.
 The ndarray object supports both the Python-side and the C-side of the
 array interface.
 The system is able to consume objects that expose the array interface,
 and array objects can expose their inner workings to other objects that
 support the array interface.
 
\end_layout

\begin_layout Description
__array_interface__
\begin_inset LatexCommand index
name "ndarray!attributes!\\_\\_array\\_interface\\_\\_"

\end_inset

 
\end_layout

\begin_layout Description
\InsetSpace ~
 The python-side of the array interface.
 It is a dictionary with the following attributes:
\end_layout

\begin_deeper
\begin_layout Description
data A 2-tuple (dataptr, read-only flag).
 The dataptr is a string giving the address (in hexadecimal format) of the
 array data.
 The read-only flag is True if the array memory is read-only.
 
\end_layout

\begin_layout Description
strides The strides tuple.
 Same as 
\series bold
strides
\series default
 attribute except None is returned if the array is C-style contiguous.
\end_layout

\begin_layout Description
shape The shape tuple.
 Same as 
\series bold
shape
\series default
 attribute.
\end_layout

\begin_layout Description
typestr A string giving the format of the data.
 Same as 
\series bold
dtype.str
\series default
 attribute.
 
\end_layout

\begin_layout Description
descr A list of tuples providing the detailed description of this data type.
 This information is obtained from the arrdescr attribute of the dtypedescr
 object associated with each array.
 For arrays with fields, this will return a valid array-protocol descriptor
 list.
 For arrays without defined fields, this returns [('',typestr)].
\end_layout

\end_deeper
\begin_layout Description
__array_struct__
\begin_inset LatexCommand index
name "ndarray!attributes!\\_\\_array\\_struct\\_\\_"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 A PyCObject that wraps a pointer to a PyArrayInterface structure.
 This is only useful on the C-level for rapid implementation of the array
 interface, using a single attribute lookup.
\end_layout

\begin_layout Description
ctypes
\begin_inset LatexCommand index
name "ndarray!attributes!ctypes|("

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 This attribute creates an object that makes it easier to use arrays when
 calling out to shared libraries with the ctypes module.
 The returned object has data, shape, and strides attributes which return
 ctypes
\begin_inset LatexCommand index
name "ctypes"

\end_inset

 objects that can be used as arguments to a shared library.
 These attributes are:
\end_layout

\begin_deeper
\begin_layout Description
data A pointer to the memory area of the array as a Python integer.
 This memory area may contain data that is not aligned, or not in correct
 byte-order.
 The memory area may not even be writeable.
 The array flags and data-type of this array should be respected when passing
 this attribute to arbitrary C-code to avoid trouble that can include Python
 crashing.
 User Beware! The value of this attribute is exactly the same as 
\family typewriter
self.__array_interface__['data'][0]
\family default
.
\end_layout

\begin_layout Description
shape (c_intp*self.ndim) A ctypes array of length self.ndim where the base-type
 is the C-integer corresponding to dtype('p') on this platform.
 This base-type could be c_int, c_long, or c_longlong depending on the platform.
 The c_intp type is defined accordingly in numpy.ctypeslib.
 The ctypes array contains the shape of the underlying array.
\end_layout

\begin_layout Description
strides (c_intp*self.ndim) A ctypes array of length self.ndim where the base-type
 is the same as for the shape attribute.
 This ctypes array contains the strides information from the underlying
 array.
 This strides information is important for showing how many bytes must be
 jumped to get to the next element in the array.
 
\end_layout

\begin_layout Description
_as_parameter_ (c_void_p) Returns the data-pointer to the array as a ctypes
 object.
 Among other possible uses, this enables this ctypes object to be used directly
 in a ctypes-loaded call to an arbitrary function.
 Be sure to respect the flags on the array and the size and strides of the
 array so as not to use this memory in-appropriately (see the 
\series bold
ndpointer
\series default
 function for how to return a class that can be used with the argtypes attribute
 of ctypes functions).
 
\end_layout

\end_deeper
\begin_layout Warning
Be careful using the ctypes attribute --- especially on temporary arrays
 or arrays constructed on the fly.
 For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer
 to memory that is invalid because the array created as (a+b) is deallocated
 before the next Python statement.
 You can avoid this problem using either c=a+b or ct=(a+b).ctypes.
 In the latter case, ct will hold a reference to the array until ct is deleted
 or re-assigned.
\end_layout

\begin_layout Description
\InsetSpace ~
 The ctypes object also has several methods which can alter how the shape,
 strides, and data of the underlying object is returned.
 
\end_layout

\begin_deeper
\begin_layout Description
data_as (obj) Return the data pointer cast-to a particular c-types object.
 For example, calling 
\family typewriter
self._as_parameter_
\family default
 is equivalent to 
\family typewriter
self.data_as(ctypes.c_void_p)
\family default
.
 Perhaps you want to use the data as a pointer to a ctypes array of floating-poi
nt data: 
\family typewriter
self.data_as(ctypes.POINTER(ctypes.c_double))
\family default
.
 
\end_layout

\begin_layout Description
shape_as (obj) Return the shape tuple as an array of some other c-types
 type.
 For example: 
\family typewriter
self.shape_as(ctypes.c_short)
\family default
.
 
\end_layout

\begin_layout Description
strides_as (obj) Return the strides tuple as an array of some other c-types
 type.
 For example: 
\family typewriter
self.strides_as(ctypes.c_longlong)
\family default
.
\end_layout

\end_deeper
\begin_layout Description
\InsetSpace ~
 If the ctypes module is not available, then the ctypes attribute of array
 objects still returns something useful, but ctypes objects are not returned
 and errors may be raised instead.
 In particular, the object will still have the _as_parameter_ attribute
 which will return an integer equal to the data
\begin_inset LatexCommand index
name "ndarray!attributes!ctypes|)"

\end_inset

 attribute
\begin_inset LatexCommand index
name "ndarray!attributes|)"

\end_inset

.
 
\end_layout

\begin_layout Section

\family typewriter
ndarray
\family default
 Methods
\end_layout

\begin_layout Standard
In NumPy, the 
\family typewriter
ndarray
\family default
 object has many methods
\begin_inset LatexCommand index
name "ndarray!methods|("

\end_inset

 which operate on or with the array in some fashion, typically returning
 an array result.
 In Numeric, many of these methods were only library calls.
 These methods are explained in this chapter.
 Whenever the array whose method is being called needs to be referenced
 it will be referred to as 
\emph on
this array
\emph default
, or 
\emph on
self
\emph default
.
 Keyword arguments will be shown.
 Methods that only take one argument do not have keyword arguments.
 Default values for one argument methods will be shown in braces {default}.
 
\end_layout

\begin_layout Warning
If you are converting code from Numeric, then you will need to make the
 following (search and replace) conversions: 
\family typewriter
.typecode() --> .dtype.char
\family default
; 
\family typewriter
.iscontiguous() --> .flags.contiguous
\family default
; 
\family typewriter
.byteswapped() --> .byteswap()
\family default
; 
\family typewriter
.toscalar() --> .item()
\family default
; and 
\family typewriter
.itemsize() --> .itemsize
\family default
.
 The numpy.oldnumeric.alter_code1 module can automate this for you.
\end_layout

\begin_layout Subsection
Array conversion
\end_layout

\begin_layout Description
tolist
\begin_inset LatexCommand index
name "ndarray!methods!tolist"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 The contents of self as a nested list.
\end_layout

\begin_layout MyCode
>>> a = array([[1,2,3],[4,5,6]]); print a.tolist()
\newline
[[1, 2, 3], [4, 5, 6]]
\end_layout

\begin_layout Description
item
\begin_inset LatexCommand index
name "ndarray!methods!item"

\end_inset

 (*args)
\end_layout

\begin_layout Description
\InsetSpace ~
 If no arguments are passed in, then this method only works for arrays with
 one element (a.size == 1).
 In this case, it returns a standard Python scalar object (if possible)
 copied from the first element of self.
 When the data type of self is longdouble or clongdouble, this returns a
 scalar array object because there is no available Python scalar that would
 not lose information.
 Void arrays return a buffer object for item() unless fields are defined
 in which case a tuple is returned.
\end_layout

\begin_layout MyCode
>>> asc = a[0,0].item()
\newline
>>> type(asc)
\newline
<type 'int'>
\newline
>>> asc
\newline
1
\newline
>>> type(a[0,0])
\newline
<type
 'numpy.int32'>
\end_layout

\begin_layout Description
\InsetSpace ~
 If arguments are provided, then they indicate indices into the array (either
 a flat index or an nd-index).
 A standard Python scalar corresponding to the item at the given location
 is then returned.
 This is very similar to self[args] except instead of an array scalar, a
 standard Python scalar is returned.
 This can be useful for speeding up access to elements of the array and
 doing arithmetic on elements of the array using Python's optimized math.
 
\end_layout

\begin_layout Description
itemset
\begin_inset LatexCommand index
name "ndarray!methods!itemset"

\end_inset

 (*args)
\end_layout

\begin_layout Description
\InsetSpace ~
 There must be at least 1 argument and define the last argument as item.
 Then, this is equivalent to but faster than self[args] = item.
 The item should be a scalar value and args must select a single item in
 the array.
\end_layout

\begin_layout Description
tostring
\begin_inset LatexCommand index
name "ndarray!methods!tostring"

\end_inset

 (order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 A Python string showing a copy of the raw contents of data memory.
 The string can be produced in either 'C' or 'Fortran', or 'Any' order (the
 default is 'C'-order).
 'Any' order means C-order unless the F_CONTIGUOUS flag in the array is
 set, then 'Fortran' order.
 
\end_layout

\begin_layout Description
tofile
\begin_inset LatexCommand index
name "ndarray!methods!tofile"

\end_inset

 (file=, sep='', format='')
\end_layout

\begin_layout Description
\InsetSpace ~
 Write the contents of self to the open file object.
 If file is a string, then open a file of that name first.
 If sep is the empty string, then write the file in binary mode.
 If sep is any other string, write the array in simple text mode separating
 each element with the value of the sep string.
 When the file is written in text mode, the format string can be used to
 alter the appearance of each entry.
 If format is the empty string, then it is equivalent to 
\family typewriter

\begin_inset Quotes eld
\end_inset

%s
\begin_inset Quotes erd
\end_inset


\family default
.
 Each element of the array will be converted to a Python scalar, 
\family typewriter
o
\family default
, and written to the file as 
\family typewriter

\begin_inset Quotes eld
\end_inset

format
\begin_inset Quotes erd
\end_inset

 % o
\family default
.
 Note that writing an array to a file does not store any information about
 the shape, type, or endianness of an array.
 When written in binary mode, tofile is functionally equivalent to 
\family typewriter
fid.write(self.tostring())
\family default
.
\end_layout

\begin_layout MyCode
>>> a.tofile('myfile.txt',sep=':',format='%03d')
\end_layout

\begin_layout MyCode
Contents of myfile.txt
\end_layout

\begin_layout MyCode
001:002:003:004:005:006
\end_layout

\begin_layout Description
dump
\begin_inset LatexCommand index
name "ndarray!methods!dump"

\end_inset

 (file)
\end_layout

\begin_layout Description
\InsetSpace ~
 Pickle the contents of self to the file object represented by file.
 Equivalent to cPickle.dump(self, file, 2)
\end_layout

\begin_layout Description
dumps
\begin_inset LatexCommand index
name "ndarray!methods!dumps"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return pickled representation of self as a string.
 Equivalent to cPickle.dumps(self, 2)
\end_layout

\begin_layout Description
astype
\begin_inset LatexCommand index
name "ndarray!methods!astype"

\end_inset

 ({None})
\end_layout

\begin_layout Description
\InsetSpace ~
 Force conversion of this array to an array with the data type provided
 as the argument.
 If the argument is None, or equal to the data type of self, then return
 a copy of the array.
 
\end_layout

\begin_layout Description
byteswap
\begin_inset LatexCommand index
name "ndarray!methods!byteswap"

\end_inset

 ({False})
\end_layout

\begin_layout Description
\InsetSpace ~
 Byteswap the elements of the array and return the byteswapped array.
 If the argument is True, then byteswap in-place and return a reference
 to self.
 Otherwise, return a copy of the array with the elements byteswapped.
 The data-type descriptor is not changed so the array will have changed
 numbers.
\end_layout

\begin_layout Description
copy
\begin_inset LatexCommand index
name "ndarray!methods!copy"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a copy of the array (which is always single-segment, and ALIGNED).
 However, the data-type is preserved (including whether or not the data
 is byteswapped).
 
\end_layout

\begin_layout Description
view
\begin_inset LatexCommand index
name "ndarray!methods!view"

\end_inset

 ({None})
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new array using the same memory area as self.
 If the optional argument is given, it can be either a typeobject that is
 a sub-type of the ndarray or an object that can be converted to a data-type
 descriptor.
 If the argument is a typeobject then a new array of that Python type is
 returned that uses the information from self.
 If the argument is a data-type descriptor, then a new array of the same
 Python type as self is returned using the given data-type.
 
\end_layout

\begin_layout MyCode
>>> print a.view(single)
\newline
[[  1.40129846e-45   2.80259693e-45   4.20389539e-45]
\newline

 [  5.60519386e-45   7.00649232e-45   8.40779079e-45]]
\newline
>>> a.view(ubyte)
\newline
array([[1,
 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0],
\newline
       [4, 0, 0, 0, 5, 0, 0, 0, 6, 0,
 0, 0]], dtype=uint8)
\end_layout

\begin_layout Description
getfield
\begin_inset LatexCommand index
name "ndarray!methods!getfield"

\end_inset

 (dtype=, offset=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a 
\emph on
field
\emph default
 of the given array as an array of the given data type.
 A field is a view of the array's data at a certain byte offset interpreted
 as a given data type.
 The returned array is a reference into self, therefore changes made to
 the returned array will be reflected in self.
 This method is particularly useful for record arrays that use a void data
 type, but it can also be used to extract the low (high)-order bytes of
 other array types as well.
 For example, using getfield, you could extract fixed-length substrings
 from an array of strings.
 
\end_layout

\begin_layout MyCode
>>> a = array(['Hello','World','NumPy'])
\newline
>>> a.getfield('S2',1)
\newline
array(['el',
 'or', 'um'], 
\newline
      dtype='|S2')
\end_layout

\begin_layout Description
setflags
\begin_inset LatexCommand index
name "ndarray!methods!setflags"

\end_inset

 (write=None, align=None, uic=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
 The ALIGNED flag can only be set to True if the data is actually aligned
 according to the type.
 The UPDATEIFCOPY flag can never be set to True.
 The flag WRITEABLE can only be set True if the array owns its own memory
 or the ultimate owner of the memory exposes a writeable buffer interface
 (or is a string).
 The exception for string is made so that unpickling can be done without
 copying memory.
 
\end_layout

\begin_layout Description
fill
\begin_inset LatexCommand index
name "ndarray!methods!fill"

\end_inset

 (scalar)
\end_layout

\begin_layout Description
\InsetSpace ~
 Fill an array with the scalar value (appropriately converted to the type
 of self).
 If the scalar value is an array or a sequence, then only the first element
 is used.
 This method is usually faster than a[...]=scalar or self.flat=scalar, and always
 interprets its argument as a scalar.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Array conversion methods
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
setlength{
\backslash
extrarowheight}{0.1eM}
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="15" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" width="30text%">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Method
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Arguments
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Description
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
astype
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(dtype {None})
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Cast to another data type
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
byteswap
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(inplace {False})
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Byteswap array elements
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
copy
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Copy array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
dump
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(file)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Pickle to stream or file
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
dumps
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Get pickled string
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
fill
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(scalar)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Fill an array with scalar value
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
getfield
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(dtype=, offset=0)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Return a field of the array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
setflags
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(write=None, align=None, uic=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Set array flags
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
tofile
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(file=, sep='', format='')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Raw write to file
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
tolist
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Array as a nested list
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
item
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(*args)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Python scalar extraction
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
itemset
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(*args)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Insert scalar (last argument) into array
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
tostring
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(order='C')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
String of raw memory
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
view
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(obj)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
View as another data type or class
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Array shape manipulation
\end_layout

\begin_layout Standard
For reshape, resize, and transpose, the single tuple argument may be replaced
 with 
\begin_inset Formula $n$
\end_inset

 integers which will be interpreted as an 
\begin_inset Formula $n$
\end_inset

-tuple.
\end_layout

\begin_layout Description
reshape
\begin_inset LatexCommand index
name "ndarray!methods!reshape"

\end_inset

 (newshape, order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array that uses the same data as this array but has a new shape
 given by the newshape tuple (or a scalar to reshape as 1-d).
 The new shape must define an array with the same total number of elements.
 If one of the elements of the new shape tuple is -1, then that dimension
 will be determined such that the overall number of items in the array stays
 constant.
 If possible, the new array will reference the data of the old one.
 If the data must be moved in order to accomplish the reshape, then then
 the new array will contain a copy of the data in self.
 The order argument specifies how the array data should be viewed during
 the reshape (either in 'C' or 'FORTRAN' order).
 This order argument specifies both how the intrinsic raveling to a 1-d
 array should occur as well as how that 1-d array should be used to fill-up
 the new output array.
 
\end_layout

\begin_layout Description
resize
\begin_inset LatexCommand index
name "ndarray!methods!resize"

\end_inset

 (newshape, refcheck=1, order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Resize an array in-place.
 This changes self (in-place) to be an array with the new shape, reallocating
 space for the data area if necessary.
 If the data memory must be changed because the number of new elements is
 different than self.size, then an error will occur if this array does not
 own its data or if another object is referencing this one.
 Only a single-segment array can be resized.
 The method returns None.
 To bypass the reference count check, then set refcheck=0.
 The purpose of the reference count check is to make sure you don't use
 this array as a buffer for another Python object and then reallocate the
 memory.
 However, reference counts can increase in other ways so if you are sure
 that you have not shared the memory for this array to another Python object,
 then you may safely set refcheck=0.
 
\end_layout

\begin_layout Description
transpose
\begin_inset LatexCommand index
name "ndarray!methods!transpose"

\end_inset

 (<None>)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array view with the shape transposed according to the argument.
 An argument of None is equivalent to range(self.ndim)[::-1].
 The argument can either be a tuple or multiple integer arguments.
 This method returns a new array with permuted shape and strides attributes
 using the same data as self.
 
\end_layout

\begin_layout MyCode
>>> a = arange(40).reshape((2,4,5))
\newline
>>> b = a.transpose(2,0,1)
\newline
>>> print a.shape,
 b.shape
\newline
(2, 4, 5) (5, 2, 4)
\newline
>>> print a.strides, b.strides
\newline
(80, 20, 4) (4, 80,
 20)
\newline
>>> print a
\newline
[[[ 0  1  2  3  4]
\newline
  [ 5  6  7  8  9]
\newline
  [10 11 12 13 14]
\newline
  [15
 16 17 18 19]]
\newline

\newline
 [[20 21 22 23 24]
\newline
  [25 26 27 28 29]
\newline
  [30 31 32 33 34]
\newline
  [35
 36 37 38 39]]]
\newline
>>> print b
\newline
[[[ 0  5 10 15]
\newline
  [20 25 30 35]]
\newline

\newline
 [[ 1  6 11 16]
\newline

  [21 26 31 36]]
\newline

\newline
 [[ 2  7 12 17]
\newline
  [22 27 32 37]]
\newline

\newline
 [[ 3  8 13 18]
\newline
  [23 28 33
 38]]
\newline

\newline
 [[ 4  9 14 19]
\newline
  [24 29 34 39]]]
\end_layout

\begin_layout Description
swapaxes
\begin_inset LatexCommand index
name "ndarray!methods!swapaxes"

\end_inset

 (axis1, axis2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array view with axis1 and axis2 swapped.
 This is a special case of the transpose method with argument equal to arg=range
(self.ndim); arg[axis1], arg[axis2] = arg[axis2], arg[axis1].
 See the 
\series bold
rollaxis
\series default
 function for a routine that transposes the array with the axes rolled instead
 of swapped.
 
\end_layout

\begin_layout Description
flatten
\begin_inset LatexCommand index
name "ndarray!methods!flatten"

\end_inset

 (order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new 1-d array with data copied from self.
 Equivalent to but slightly faster then a.flat.copy().
 
\end_layout

\begin_layout Description
ravel
\begin_inset LatexCommand index
name "ndarray!methods!ravel"

\end_inset

 (order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a 1-d version of self.
 If self is single-segment, then the new array references self, otherwise,
 a copy is made.
\end_layout

\begin_layout Description
squeeze
\begin_inset LatexCommand index
name "ndarray!methods!squeeze"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array with all unit-length dimensions squeezed out.
\end_layout

\begin_layout Subsection
Array item selection and manipulation
\end_layout

\begin_layout Standard
For array methods that take an axis keyword, it defaults to None.
 If axis is None, then the array is treated as a 1-D array.
 Any other value for axis represents the dimension along which the operation
 should proceed.
 
\end_layout

\begin_layout Description
take
\begin_inset LatexCommand index
name "ndarray!methods!take"

\end_inset

 (indices=, axis=None, out=None, mode='raise')
\end_layout

\begin_layout Description
\InsetSpace ~
 The functionality of this method is available using the advanced indexing
 ability of the 
\family typewriter
ndarray
\family default
 object.
 However, for doing selection along a single axis it is usually faster to
 use take.
 If axis is not None, this method is equivalent to 
\family typewriter
self[indxobj]
\family default
 preceeded by 
\family typewriter
indxobj=[slice(None)]*self.ndim; indxobj[
\series bold
axis
\series default
] =
\family default
 
\family typewriter
\series bold
indices
\family default
\series default
.
 It returns the elements or sub-arrays from self indicated by the index
 numbers in indices.
 If axis is None, then this method is equivalent to 
\family typewriter
self.flat[indices]
\family default
.
 The out and mode arguments allow for specification of the output array
 and how out-of-bounds indices will be handled ('raise': raise an error,
 'wrap': wrap around, 'clip': clip to range)
\end_layout

\begin_layout Description
put
\begin_inset LatexCommand index
name "ndarray!methods!put"

\end_inset

 (indices=, values=, mode='raise')
\end_layout

\begin_layout Description
\InsetSpace ~
 Performs the equivalent of 
\end_layout

\begin_layout LyX-Code
for n in 
\series bold
indices
\series default
:
\end_layout

\begin_layout LyX-Code
    self.flat[n] = 
\series bold
values
\series default
[n]
\end_layout

\begin_layout Description
\InsetSpace ~
 Values is repeated if it is too short.
 The mode argument specifies what to do if n is too large.
 
\end_layout

\begin_layout Description
repeat
\begin_inset LatexCommand index
name "ndarray!methods!repeat"

\end_inset

 (repeats=, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Copy elements (or sub-arrays selected along axis) of self 
\series bold
repeats
\series default
 times.
 The repeats argument must be a sequence of length self.shape[axis] or a
 scalar.
 The repeats argument dictates how many times the element (or sub-array)
 will be repeated in the result array.
 
\end_layout

\begin_layout Description
choose
\begin_inset LatexCommand index
name "ndarray!methods!choose"

\end_inset

 (choices, out=None, mode='raise')
\end_layout

\begin_layout Description
\InsetSpace ~
 The array must be an integer (or bool) array with entries from 
\begin_inset Formula $0$
\end_inset

 to 
\begin_inset Formula $n$
\end_inset

.
 Choices is a tuple of 
\begin_inset Formula $n$
\end_inset

 choice arrays: 
\begin_inset Formula $b0,\, b1,\,\ldots\,,\, bn$
\end_inset

.
 (Alternatively, choices can be replaced with 
\begin_inset Formula $n$
\end_inset

 arguments where each argument is a choice array).
 The return array will be formed from the elements of the choice arrays
 according to the value of the elements of self.
 In other words, the output array will merge the choice arrays together
 by using the value of self at a particular position to select which choice
 array should be used for the output at a particular position.
 The out keyword allows specification of an output array and the clip keyword
 allows different behavior when self contains entries outside the number
 of choices.
 The acceptable arguments to mode are 'raise' (RAISE), 'wrap' (WRAP), and
 'clip' (CLIP) ('raise' produces an error, 'wrap' converts the number into
 range by periodic wrapping so that numbers <0 have 
\begin_inset Formula $n$
\end_inset

 repeatedly added and numbers >= 
\begin_inset Formula $n$
\end_inset

 have 
\begin_inset Formula $n$
\end_inset

 repeatedly subtracted, and 'clip' will clip all entries to be within the
 range [0,
\begin_inset Formula $n$
\end_inset

).
\end_layout

\begin_layout MyCode
>>> a = array([0,3,2,1])
\newline
>>> a.choose([0,1,2,3],[10,11,12,13],
\newline
...
 [20,21,22,23],[30,31,32,33])
\newline
array([ 0, 31, 22, 13])
\end_layout

\begin_layout Description
sort
\begin_inset LatexCommand index
name "ndarray!methods!sort"

\end_inset

 (axis=-1, kind='quick', order=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Sort the array in-place and return None.
 The sort takes place over the given axis using an underlying sort algorithm
 specified by kind.
 The sorting algorithms available are 'quick', 'heap', and 'merge'.
 For flexible types only the quicksort algorithm is available.
 For arrays with fields defined, the order keyword allows specification
 of the order in which to use the field names in the sort.
 If order is a string then it is the field name to use to define the sort.
 If order is a list (or tuple) of strings, then it specifies a lexicographic
 ordering so that the first listed field name is compared first if that
 results in equality, the second listed field name is used for the comparison
 and so on.
 If order is None, then arrays with fields use the first field for comparison.
 
\end_layout

\begin_layout MyCode
>>> a=array([[0.2,1.3,2.5],[1.5,0.1,1.4]]);
\newline
>>> b=a.copy(); b.sort(0); print b
\newline
[[
 0.2  0.1  1.4]
\newline
 [ 1.5  1.3  2.5]]
\newline
>>> b=a.copy(); b.sort(1); print b
\newline
[[ 0.2  1.3  2.5]
\newline

 [ 0.1  1.4  1.5]]
\end_layout

\begin_layout Description
argsort
\begin_inset LatexCommand index
name "ndarray!methods!argsort"

\end_inset

 (axis=-1, kind='quick', order=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an index array of the same size as self showing which indices along
 the given axis should be selected to sort self along that axis.
 Uses an underlying sort algorithm specified by kind.
 The sorting algorithms available are 'quick', 'heap', and 'merge'.
 For arrays with fields defined, the order keyword allows specification
 of the order in which to use the field names in the sort.
 If order is a string then it is the field name to use to define the sort.
 If order is a list (or tuple) of strings, then it specifies a lexicographic
 ordering so that the first listed field name is compared first if that
 results in equality, the second listed field name is used for the comparison
 and so on.
 If order is None, then arrays with fields use the first field for comparison.
 
\end_layout

\begin_layout MyCode
>>> b=a.copy(); print b.argsort(0)
\newline
[[0 1 1]
\newline
 [1 0 0]]
\newline
>>> b=a.copy(); print b.argsort(1
)
\newline
[[0 1 2]
\newline
 [1 2 0]]
\end_layout

\begin_layout Tip
Complex valued arrays sort lexicographically by comparing first the real
 parts and then the imaginary parts if the real parts are the same.
\end_layout

\begin_layout Description
searchsorted
\begin_inset LatexCommand index
name "ndarray!methods!searchsorted"

\end_inset

 (values, side='left')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an index array (dtype=intp) of the same shape as values showing
 the index where the value would fit in self.
 The index is such that self[index-1] 
\begin_inset Formula $<$
\end_inset

 value 
\begin_inset Formula $\le$
\end_inset

 self[index] when side is 'left'.
 In this formula self[self.size]=
\begin_inset Formula $\infty$
\end_inset

 and self[-1]=
\begin_inset Formula $-\infty$
\end_inset

.
 Therefore, if value is larger than all elements of self, then index is
 self.size.
 If value is smaller than all elements of self, then index is 0.
 Self must be a sorted 1-d array.
 If elements of self are repeated, the index of the first occurrence is
 used.
 If side is 'right', then the search rule is switched so that the 
\begin_inset Formula $<$
\end_inset

 sign is on the 
\begin_inset Quotes eld
\end_inset

right
\begin_inset Quotes erd
\end_inset

 instead of the left in the search rule.
 In other words, the index returned is such that self[index-1] 
\begin_inset Formula $\le$
\end_inset

value 
\begin_inset Formula $<$
\end_inset

 self[index].
\end_layout

\begin_layout MyCode
>>> b=a.ravel(); b.sort()
\newline
>>> b.searchsorted([0.0, 1.35, 2.0, 3.0])
\newline
array([0, 3,
 5, 6])
\end_layout

\begin_layout Description
nonzero
\begin_inset LatexCommand index
name "ndarray!methods!nonzero"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the 
\begin_inset Formula $n$
\end_inset

-dimensional indices for elements of the 
\begin_inset Formula $n$
\end_inset

-dimensional array self that are nonzero into an 
\begin_inset Formula $n$
\end_inset

-tuple of equal-length index arrays.
 In particular, notice that a 0-dimensional array always returns an empty
 tuple.
 
\end_layout

\begin_layout MyCode
>>> x = arange(15); y=x.reshape(3,5)
\newline
>>> (x>8).nonzero()
\newline
(array([ 9, 10, 11,
 12, 13, 14]),)
\newline
>>> (y>8).nonzero()
\newline
(array([1, 2, 2, 2, 2, 2]), array([4, 0,
 1, 2, 3, 4]))
\end_layout

\begin_layout Description
compress
\begin_inset LatexCommand index
name "ndarray!methods!compress"

\end_inset

 (condition=, axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This method expects condition to be a one-dimensional mask array of the
 same length as self.shape[axis].
 If the array is less than self.shape[axis], then False is assumed for the
 missing elements.
 The method returns the elements (or sub-arrays along the given axis) of
 self where condition is true.
 The shape of the return array is self.shape with the axis dimension replaced
 by the number of True elements of condition.
 The same effect can often be accomplished using array indexing.
\end_layout

\begin_layout MyCode
>>> x=array([0,1,2,3])
\newline
>>> x.compress(x > 2)
\newline
array([3])
\newline
>>> x[x>2]
\newline
array([3])
\end_layout

\begin_layout Description
diagonal
\begin_inset LatexCommand index
name "ndarray!methods!diagonal"

\end_inset

 (offset=0, axis1=0, axis2=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 If self is 2-d, return the 
\series bold
offset
\series default
 (from the main diagonal) diagonal of self.
 If self is larger than 2-d, then return an array constructed from all the
 diagonals created from all the 2-d sub-arrays formed using all of axis1
 and axis2.
 The offset parameter is with respect to axis2.
 The shape of the returned array is found by removing the axis1 and axis2
 entries from self.shape and then appending the length of the offset diagonal
 of each 2-d sub-array.
\end_layout

\begin_layout MyCode
>>> a=arange(25).reshape(5,5); print a
\newline
[[ 0  1  2  3  4]
\newline
 [ 5  6  7  8  9]
\newline

 [10 11 12 13 14]
\newline
 [15 16 17 18 19]
\newline
 [20 21 22 23 24]]
\newline
>>> print a.diagonal()
\newline
[
 0  6 12 18 24]
\newline
>>> print a.diagonal(1)
\newline
[ 1  7 13 19]
\newline
>>> print a.diagonal(-1)
\newline
[
 5 11 17 23]
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Array item selection and shape manipulation methods.
 If axis is an argument, then the calculation is performed along that axis.
 An axis value of None means the array is flattened before calculation proceeds.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
setlength{
\backslash
extrarowheight}{0.25eM}
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="18" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" width="50text%">
<column alignment="block" valignment="top" leftline="true" rightline="true" width="30text%">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Method
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Arguments
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Description
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
argsort
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
argsort (axis=None, kind='quick')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Indices showing how to sort array.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
choose
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
choose (c0, c1 , ..., cn, out=None, clip='raise')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Choose from different arrays based on value of self.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
compress
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(condition=, axis=None, out=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Elements of self where condition is true.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
diagonal
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(offset=0, axis1=0, axis2=1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Return a diagonal from self.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
flatten
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(order='C')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
A 1-d copy of self.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
nonzero
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
True where self is not zero.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
put
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(indices=, values=, mode='raise')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Place values at 1-d index locations of self.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
ravel
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(order='C')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
1-d version of self (no data copy if self is C-style contiguous).
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
repeat
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(repeats=, axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Repeat elements of self.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
reshape
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(d1,d2,...,dn, order='C')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Return reshaped version of self.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
resize
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(d1,d2,...,dn, refcheck=1, order='Any')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Resize self in-place.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
searchsorted
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(values)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Show where values would be placed in self (assumed sorted).
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
sort
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, kind='quick')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Copy of self sorted along axis.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
squeeze
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Squeeze out all length-1 dimensions.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
swapaxes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis1, axis2)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Swap two dimensions of self.
 
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
take
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(indices=, axis=None, out=None, mode='raise')
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Select elements of self along axis according to indices.
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
transpose
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(permute <None>)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Rearrange shape of self according to permute.
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Array calculation
\end_layout

\begin_layout Standard
Many of these methods take an argument named axis.
 In such cases, if axis is None (the default), the array is treated as a
 1-d array and the operation is performed over the entire array.
 This behavior is also the default if self is a 0-dimensional array or array
 scalar.
 If axis is an integer, then the operation is done over the given axis (for
 each 1-d subarray that can be created along the given axis).
 The parameter dtype specifies the data type over which a reduction operation
 (like summing) should take place.
 The default reduce data type is the same as the data type of self.
 To avoid overflow, it can be useful to perform the reduction using a larger
 data type.
 For several methods, an optional out argument can be provided and the result
 will be placed into the output array given.
 The out argument must be an ndarray and have the same number of elements.
 It can be of a different type in which case casting will be performed.
 
\end_layout

\begin_layout Description
max
\begin_inset LatexCommand index
name "ndarray!methods!max"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the largest value in self.
 This is a better way to compute the maximum over an array, than using max(self).
 The latter uses the generic sequence interface to self.
 This will be slower, and will try to get an answer by comparing whole sub-array
s of self.
 This will be incorrect for arrays larger than 1-d.
\end_layout

\begin_layout Description
argmax
\begin_inset LatexCommand index
name "ndarray!methods!argmax"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (first, 1-d) index of the largest value in self.
\end_layout

\begin_layout Description
min
\begin_inset LatexCommand index
name "ndarray!methods!min"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the smallest value in self.
 This is a better way to compute the minimum over an array, than using min(self).
 The latter uses the generic sequence interface to self.
 This will be slower, and will try to get an answer by comparing whole sub-array
s of self.
 This will be incorrect for arrays larger than 1-d.
\end_layout

\begin_layout Description
argmin
\begin_inset LatexCommand index
name "ndarray!methods!argmin"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (first, 1-d) index of the smallest value in self.
\end_layout

\begin_layout Description
ptp
\begin_inset LatexCommand index
name "ndarray!methods!ptp"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the difference of the largest to the smallest value in self.
 Equivalent to self.max(axis) - self.min(axis)
\end_layout

\begin_layout Description
clip
\begin_inset LatexCommand index
name "ndarray!methods!clip"

\end_inset

 (min=,max=, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new array where any element in self less than min is set to min
 and any element less than max is set to max.
 Equivalent to self[self<min]=min; self[self>max]=max.
\end_layout

\begin_layout Description
conj
\begin_inset LatexCommand index
name "ndarray!methods!conj"

\end_inset

 (out=None)
\end_layout

\begin_layout Description
conjugate
\begin_inset LatexCommand index
name "ndarray!methods!conjugate"

\end_inset

 (out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the conjugate of elements of the array.
\end_layout

\begin_layout Description
round
\begin_inset LatexCommand index
name "ndarray!methods!round"

\end_inset

 (decimals=0, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Round the elements of the array to the nearest decimal.
 For decimals < 0, the rounding is done to the nearest tens, hundreds, etc.
 Rounding of exactly the half-interval is to the nearest even integer.
 This is the only difference with standard Python rounding.
\end_layout

\begin_layout Description
trace
\begin_inset LatexCommand index
name "ndarray!methods!trace"

\end_inset

 (offset=0, axis1=0, axis2=1, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Perform a summation along each diagonal specified by offset, axis1, and
 axis2.
 Equivalent to diagonal(offset,axis1,axis2).sum(axis=-1, dtype=dtype)
\end_layout

\begin_layout Description
sum
\begin_inset LatexCommand index
name "ndarray!methods!sum"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the sum 
\begin_inset Formula \[
\sum_{i=0}^{N-1}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]\]

\end_inset

 where axis ':' objects are placed before the 
\begin_inset Formula $i.$
\end_inset

 
\end_layout

\begin_layout Description
cumsum
\begin_inset LatexCommand index
name "ndarray!methods!cumsum"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the cumulative sum.
 If ret is the return array of the same shape as 
\begin_inset Formula $\textrm{self},$
\end_inset

 then 
\begin_inset Formula \[
\textrm{ret}[\underbrace{:,\ldots,:}_{\textrm{axis}},j]=\sum_{i=0}^{j}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i].\]

\end_inset


\end_layout

\begin_layout Description
mean
\begin_inset LatexCommand index
name "ndarray!methods!mean"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the average value caculated as
\begin_inset Formula \[
\frac{1}{N}\sum_{i=0}^{N-1}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]\]

\end_inset

 where 
\begin_inset Formula $N$
\end_inset

 is self.shape[axis] and axis ':' objects are placed before the 
\begin_inset Formula $i.$
\end_inset

 The sum is done in the data-type of self unless self is an integer or Boolean
 data-type and then it is done over the float data-type.
 
\end_layout

\begin_layout Description
var
\begin_inset LatexCommand index
name "ndarray!methods!var"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the variance of the data calculated as 
\begin_inset Formula \[
\frac{1}{N}\sum_{i=0}^{N-1}\left(\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]-\mu\right)^{2}\]

\end_inset

 where 
\begin_inset Formula $N$
\end_inset

 is self.shape[axis] and 
\begin_inset Formula $\mu$
\end_inset

 is the mean (restored to the same number of dimensions as self with 
\begin_inset Formula $\mu$
\end_inset

 copied along the axis dimension).
 This is equivalent to (self**2).mean - self.mean()**2 and ((self-self.mean())**2).m
ean().
 The value of 
\begin_inset Formula $N-1$
\end_inset

 was not chosen for normalization because while it gives an 
\begin_inset Quotes eld
\end_inset

unbiased
\begin_inset Quotes erd
\end_inset

 estimate, it is not always prudent to return unbiased estimates as they
 may have larger mean-square error.
 The sum is done using a float data-type if self has integer or Boolean
 data-type, otherwise it is done using the same data-type as self.
 
\end_layout

\begin_layout Description
std
\begin_inset LatexCommand index
name "ndarray!methods!std"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the standard deviation calculated as 
\begin_inset Formula \[
\sqrt{\frac{1}{N}\sum_{i=0}^{N-1}\left(\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]-\mu\right)^{2}}\]

\end_inset

 where 
\begin_inset Formula $N$
\end_inset

 is self.shape[axis] and 
\begin_inset Formula $\mu$
\end_inset

 is the mean (restored to the same number of dimensions as self with 
\begin_inset Formula $\mu$
\end_inset

 copied along the axis dimension).
 The sum is done using the same data-type as self unless self is an integer
 or Boolean data-type and then it is done using a float data-type.
 
\end_layout

\begin_layout Description
prod
\begin_inset LatexCommand index
name "ndarray!methods!prod"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the product calculated as 
\begin_inset Formula \[
\prod_{i=0}^{N-1}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i].\]

\end_inset


\end_layout

\begin_layout Description
cumprod
\begin_inset LatexCommand index
name "ndarray!methods!cumprod"

\end_inset

 (axis=None, dtype=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the cumulative product so that the return array, ret, is the same
 shape as self and 
\begin_inset Formula \[
\textrm{ret}[\underbrace{:,\ldots,:}_{\textrm{axis}},j]=\prod_{i=0}^{j}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i].\]

\end_inset


\end_layout

\begin_layout Description
all
\begin_inset LatexCommand index
name "ndarray!methods!all"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return True if all entries along axis evaluate True, otherwise return False.
\end_layout

\begin_layout Description
any
\begin_inset LatexCommand index
name "ndarray!methods!any"

\end_inset

 (axis=None, out=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return True if any entries along axis evaluate True, otherwise return False
\begin_inset LatexCommand index
name "ndarray!methods|)"

\end_inset

.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Array object calculation methods.
 If axis is an argument, then the calculation is performed along that axis.
 An axis value of None means the array is flattened before calculation proceeds.
 All of these methods can take an optional out= argument which can specify
 the output array to write the results into.
 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
setlength{
\backslash
extrarowheight}{0.5eM}
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="18" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" width="30text%">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Method
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Arguments
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family sans
\series bold
\size large
Description
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
all
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
true if all entries are true.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
any
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
true if any entries are true.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
argmax
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
index of largest value.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
argmin
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
index of smallest value.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
clip
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(min=, max=)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
self[self>max]=max; self[self<min]=min
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
conj
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
complex conjugate
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
cumprod
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
cumulative product
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
cumsum
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None) 
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
cumulative sum
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
max
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
maximum of self
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
mean
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
mean of self
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
min
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
minimum of self
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
prod
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
multiply elements of self together
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
ptp
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
self.max(axis)-self.min(axis)
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
var
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
variance of self
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
std
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
standard deviation of self
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
sum
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(axis=None, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
add elements of self together
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\series bold
trace
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
(offset, axis1=0, axis2=0, dtype=None)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
sum along a diagonal
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Array Special Methods
\end_layout

\begin_layout Standard
Methods
\begin_inset LatexCommand index
name "ndarray!special methods|("

\end_inset

 in this chapter are not generally meant to be called directly by the user.
 They are called by Python and are used to customize behavior of the ndarray
 object as it interacts with the Python language and standard library.
 
\end_layout

\begin_layout Subsection
Methods for standard library functions
\end_layout

\begin_layout Description
__copy__
\begin_inset LatexCommand index
name "ndarray!special methods!copy"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 To allow copy.copy(a) to perform a shallow copy of an array.
 Exactly the same as self.copy() (contents of object arrays are not copied).
 
\end_layout

\begin_layout Description
__deepcopy__
\begin_inset LatexCommand index
name "ndarray!special methods!deepcopy"

\end_inset

 (memodict)
\end_layout

\begin_layout Description
\InsetSpace ~
 To allow copy.deepcopy(a) to perform a deep copy.
 This is the same as a shallow copy unless self is an object array.
 Then, after the shallow copy is made, a copy.deepcopy(item) is called for
 every item in the object array.
 
\end_layout

\begin_layout Description
__reduce__
\begin_inset LatexCommand index
name "ndarray!special methods!reduce"

\end_inset

 ()
\end_layout

\begin_layout Description
__setstate__
\begin_inset LatexCommand index
name "ndarray!special methods!setstate"

\end_inset

 (shape, typestr, isfortran, data)
\end_layout

\begin_layout Description
\InsetSpace ~
 Pickling support for arrays is provided by these two methods.
 When an array needs to be pickled, the __reduce__() method is called to
 provide a 3-tuple of already-pickleable objects.
 To construct a new object from the pickle, the first two elements of the
 3-tuple are used to construct a new (0-length) array of the correct type
 and the last element of the 3-tuple, which is itself a 4-tuple of (shape,
 typestr, isfortran, data) is passed to the __setstate__ method of the newly
 created array to restore its contents.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 The reduce method returns a 3-tuple consisting of (callable, args, state)
 where callable is a simple constructor function that handles subclasses
 of the ndarray.
 Also, args is a 3-tuple of arguments to pass to this constructor function
 (type(self), (0,), self.dtypechar), and state is a 4-tuple of information
 giving the object's state (self.shape, self.dtypedescr, isfortran, string_or_list
).
 In this tuple, isfortran is a Bool stating whether the following flattened
 data is in Fortran order or not, and string_or_list is a string formed
 by self.tostring() if the data type is not object.
 If the data type of self is an object array, then string_or_list is a flat
 list equivalent to self.ravel().tolist().
 
\end_layout

\begin_layout Description
\InsetSpace ~
 On load from a pickle, the pickling code uses the first two elements from
 the tuple returned by reduce to construct an empty 0-dimensional subclass
 of the correct type.
 The last element is then passed to the __setstate__ method of the newly
 created array to restore its contents.
 
\end_layout

\begin_layout Note
When data is a string, the __setstate__ method will directly use the string
 memory as the array memory (new.base will point to the string).
 The typestr contains enough information to decode how the memory should
 be interpreted.
\end_layout

\begin_layout Subsection
Basic customization
\end_layout

\begin_layout Description
__new__
\begin_inset LatexCommand index
name "ndarray!special methods!new"

\end_inset

 (subtype, shape=, dtype=long_, buffer=None, offset=0, strides=None, order=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This method creates a new ndarray.
 It is typically only used in the __new__ method of a subclass.
 This method is called to construct a new array whenever the object name
 is called, 
\family typewriter
a=ndarray(...)
\family default
.
 It supports two basic modes of array creation: 
\end_layout

\begin_layout Enumerate
a single-segment array of the specified shape and data-type from newly allocated
 memory;
\end_layout

\begin_deeper
\begin_layout Enumerate
uses shape, dtype, strides, and order arguments; others are ignored;
\end_layout

\begin_layout Enumerate
The order argument allows specification of a Fortran-style contiguous memory
 segment (order='Fortran');
\end_layout

\begin_layout Enumerate
If strides is given, then it specifies the new strides of the array (and
 the order keyword is ignored).
 The strides will be checked for consistency with the dimension size so
 that steps outside of the memory won't occur.
\end_layout

\end_deeper
\begin_layout Enumerate
an array of the given shape and data type using the provided object, buffer,
 which must export the buffer interface.
 
\end_layout

\begin_deeper
\begin_layout Enumerate
all arguments can be used;
\end_layout

\begin_layout Enumerate
strides can be given and will be checked for consistency with the shape,
 data type, and available memory in buffer;
\end_layout

\begin_layout Enumerate
order indicates whether the data buffer should be interpreted as Fortran-style
 contiguous (order='Fortran') or not;
\end_layout

\begin_layout Enumerate
offset can be used to start the array data at some offset in the buffer.
 
\end_layout

\end_deeper
\begin_layout Note
The ndarray uses the default no-op __init__
\begin_inset LatexCommand index
name "ndarray!special methods!init"

\end_inset

 function because the array is completely initialized after __new__ is called.
\end_layout

\begin_layout Description
__array__
\begin_inset LatexCommand index
name "ndarray!special methods!array"

\end_inset

 (dtype {None})
\end_layout

\begin_layout Description
\InsetSpace ~
 This is a special method that should always return an object of type ndarray.
 Useful for subclasses that need to get to the ndarray object.
 
\end_layout

\begin_layout Description
__array_wrap__
\begin_inset LatexCommand index
name "ndarray!special methods!array\\_wrap"

\end_inset

 (arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 This is a special method that always returns an object of the same Python
 type as self using the array passed as an argument.
 This is mainly useful for subclasses as it is an easy way to get the subclass
 back from an ndarray.
\end_layout

\begin_layout Description
__lt__
\begin_inset LatexCommand index
name "ndarray!special methods!lt"

\end_inset

 (other) 
\end_layout

\begin_layout Description
__le__
\begin_inset LatexCommand index
name "ndarray!special methods!le"

\end_inset

 (other)
\end_layout

\begin_layout Description
__gt__
\begin_inset LatexCommand index
name "ndarray!special methods!gt"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ge__
\begin_inset LatexCommand index
name "ndarray!special methods!ge"

\end_inset

 (other)
\end_layout

\begin_layout Description
__eq__
\begin_inset LatexCommand index
name "ndarray!special methods!eq"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ne__
\begin_inset LatexCommand index
name "ndarray!special methods!ne"

\end_inset

 (other)
\end_layout

\begin_layout Description
\InsetSpace ~
 Defined to support rich comparisons (<, <=, >, >=, ==, !=) on ndarrays
 using universal functions.
 
\end_layout

\begin_layout Description
__str__
\begin_inset LatexCommand index
name "ndarray!special methods!str"

\end_inset

 ()
\end_layout

\begin_layout Description
__repr__
\begin_inset LatexCommand index
name "ndarray!special methods!repr"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 These functions print the array when called by str(self) and repr(self)
 respectively.
 Array printing can be changed using set_string_function(..).
 Default array printing has been borrowed from numarray whose printing code
 was written by Perry Greenfield and J.
 Todd Miller.
 By default, arrays print such that
\end_layout

\begin_layout Enumerate
The last axis is always printed left to right.
\end_layout

\begin_layout Enumerate
The next-to-last axis is printed top to bottom.
\end_layout

\begin_layout Enumerate
Remaining axes are printed top to bottom with increasing numbers of separators.
\end_layout

\begin_layout Description
\InsetSpace ~
 Five parameters of the printing can be set using keyword arguments with
 
\family typewriter
set_printoptions(...)
\family default
.
 The parameters
\begin_inset LatexCommand index
name "set\\_printoptions"

\end_inset

 can all be retrieved using 
\family typewriter
get_printoptions()
\family default
.
 These printing options
\begin_inset LatexCommand index
name "get\\_printoptions"

\end_inset

 are
\end_layout

\begin_deeper
\begin_layout Description
precision the number of digits of precision for floating point output (default
 8);
\end_layout

\begin_layout Description
threshold total number of array elements which triggers summarization rather
 than full representation (default 1000);
\end_layout

\begin_layout Description
edgeitems number of array items in summary at beginning an end of each dimension
 (default 3);
\end_layout

\begin_layout Description
linewidth the number of characters per line for the purpose of inserting
 line breaks (default 71);
\end_layout

\begin_layout Description
suppress Boolean indicating whether or not to suppress printing of small
 floating point values using scientific notation (default False).
 
\end_layout

\end_deeper
\begin_layout Description
__nonzero__
\begin_inset LatexCommand index
name "ndarray!special methods!nonzero"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Truth-value testing for the array as a whole.
 It is called whenever the truth value of the ndarray as a whole object
 is required.
 This raises an error if the number of elements in the the array is larger
 than 1 because the truth value of such arrays is ambiguous.
 Use .any() and .all() instead to be clear about what is meant in such cases.
 If the number of elements is 0 then False is returned.
 If there is one element in the array, then the truth-value of this element
 is returned.
\end_layout

\begin_layout Subsection
Container customization
\end_layout

\begin_layout Description
__len__
\begin_inset LatexCommand index
name "ndarray!special methods!len"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns self.shape[0].
 It is called in response to len(self).
 Use self.size to get the total number of elements in the array.
\end_layout

\begin_layout Description
\InsetSpace ~
 Notice that the default Python iterator for sequences is used when arrays
 are used in places that expect an iterator.
 This iterator returns successively self[0], self[1], ..., self[self.__len__()].
 Use self.flat to get an iterator that walks through the entire array one
 element at a time.
\end_layout

\begin_layout Description
__getitem__
\begin_inset LatexCommand index
name "ndarray!special methods!getitem"

\end_inset

 (key)
\end_layout

\begin_layout Description
\InsetSpace ~
 Called when evaluating self[key] construct.
 Items from the array can be selected using this customization.
 This construct has both standard and extended indexing abilities which
 are explained in Section 
\begin_inset LatexCommand ref
reference "sec:Array-indexing"

\end_inset

.
 A named field can be retrieved if key is a string and fields are defined
 in the dtypedescr object associated with this array.
 
\end_layout

\begin_layout Description
__setitem__
\begin_inset LatexCommand index
name "ndarray!special methods!setitem"

\end_inset

 (key, value)
\end_layout

\begin_layout Description
\InsetSpace ~
 Called when evaluating self[key]=value.
 Items in the array can be set using this construct.
 This construct is explained in Section 
\begin_inset LatexCommand ref
reference "sec:Array-indexing"

\end_inset

.
 A named field can be set if key is a string and fields are defined in the
 dtypedescr object associated with this array.
 
\end_layout

\begin_layout Description
__getslice__
\begin_inset LatexCommand index
name "ndarray!special methods!getslice"

\end_inset

 (i, j)
\end_layout

\begin_layout Description
\InsetSpace ~
 Equivalent to self.__getitem__(slice(i,j)) but defined mainly so that C
 code can use the sequence interface.
 Called to evaluate self[i:j] 
\end_layout

\begin_layout Description
__setslice__
\begin_inset LatexCommand index
name "ndarray!special methods!setslice"

\end_inset

 (i, j, value)
\end_layout

\begin_layout Description
\InsetSpace ~
 Equivalent to self.__setitem__(slice(i,j), value) but defined mainly so
 C code can use the sequence interface.
 Called to evaluate self[i:j] = value.
\end_layout

\begin_layout Description
__contains__
\begin_inset LatexCommand index
name "ndarray!special methods!contains"

\end_inset

 (item)
\end_layout

\begin_layout Description
\InsetSpace ~
 Called to determine truth value of the 
\family typewriter
item in self
\family default
 construct.
 Returns the equivalent of (self==item).any()
\end_layout

\begin_layout Subsection
Arithmetic customization
\end_layout

\begin_layout Subsubsection
Binary
\end_layout

\begin_layout Description
__add__
\begin_inset LatexCommand index
name "ndarray!special methods!add"

\end_inset

 (other) 
\end_layout

\begin_layout Description
__sub__
\begin_inset LatexCommand index
name "ndarray!special methods!sub"

\end_inset

 (other) 
\end_layout

\begin_layout Description
__mul__
\begin_inset LatexCommand index
name "ndarray!special methods!mul"

\end_inset

 (self, other)
\end_layout

\begin_layout Description
__div__
\begin_inset LatexCommand index
name "ndarray!special methods!div"

\end_inset

 (other)
\end_layout

\begin_layout Description
__truediv__
\begin_inset LatexCommand index
name "ndarray!special methods!truediv"

\end_inset

 (other)
\end_layout

\begin_layout Description
__floordiv__
\begin_inset LatexCommand index
name "ndarray!special methods!floordiv"

\end_inset

 (other)
\end_layout

\begin_layout Description
__mod__
\begin_inset LatexCommand index
name "ndarray!special methods!mod"

\end_inset

 (other)
\end_layout

\begin_layout Description
__divmod__
\begin_inset LatexCommand index
name "ndarray!special methods!divmod"

\end_inset

 (other)
\end_layout

\begin_layout Description
__pow__
\begin_inset LatexCommand index
name "ndarray!special methods!pow"

\end_inset

 (other[,modulo])
\end_layout

\begin_layout Description
__lshift__
\begin_inset LatexCommand index
name "ndarray!special methods!lshift"

\end_inset

 (other)
\end_layout

\begin_layout Description
__rshift__
\begin_inset LatexCommand index
name "ndarray!special methods!rshift"

\end_inset

 (other)
\end_layout

\begin_layout Description
__and__
\begin_inset LatexCommand index
name "ndarray!special methods!and"

\end_inset

 (other)
\end_layout

\begin_layout Description
__or__
\begin_inset LatexCommand index
name "ndarray!special methods!or"

\end_inset

 (other)
\end_layout

\begin_layout Description
__xor__
\begin_inset LatexCommand index
name "ndarray!special methods!xor"

\end_inset

 (other)
\end_layout

\begin_layout Description
\InsetSpace ~
 These methods are defined for ndarrays to implement the operations (
\family typewriter
+
\family default
, 
\family typewriter
-
\family default
, 
\family typewriter
*
\family default
, 
\family typewriter
/,
\family default
 
\family typewriter
/,
\family default
 
\family typewriter
//
\family default
, 
\family typewriter
%
\family default
, 
\family typewriter
divmod()
\family default
, 
\family typewriter
**
\family default
 or 
\family typewriter
pow()
\family default
, 
\family typewriter
<<,
\family default
 
\family typewriter
>>
\family default
, 
\family typewriter
&
\family default
, 
\family typewriter
^
\family default
, 
\family typewriter
|
\family default
).
 This is done using calls to the corresponding universal function object
 (add, subtract, multiply, divide, true_divide, floor_divide, remainder,
 divide and remainder, power, left_shift, right_shift, bitwise_and, bitwise_xor,
 bitwise_or).
 These implement element-by-element operations for arrays that are broadcastable
 to the same shape.
 
\end_layout

\begin_layout Itemize
any third argument to 
\family typewriter
pow()
\family default
 is silently ignored as the underlying ufunc (power) only takes two arguments.
\end_layout

\begin_layout Itemize
the three division operators are all defined, div is active by default,
 truediv is active when __future__.division is in effect.
\end_layout

\begin_layout Note
Because it is a built-in type (written in C), the __r<op>__ special methods
 are not directly defined for the ndarray.
\end_layout

\begin_layout Subsubsection
In-place
\end_layout

\begin_layout Description
__iadd__
\begin_inset LatexCommand index
name "ndarray!special methods!iadd"

\end_inset

 (other)
\end_layout

\begin_layout Description
__isub__
\begin_inset LatexCommand index
name "ndarray!special methods!isub"

\end_inset

 (other)
\end_layout

\begin_layout Description
__imul__
\begin_inset LatexCommand index
name "ndarray!special methods!imul"

\end_inset

 (other)
\end_layout

\begin_layout Description
__idiv__
\begin_inset LatexCommand index
name "ndarray!special methods!idiv"

\end_inset

 (other)
\end_layout

\begin_layout Description
__itruediv__
\begin_inset LatexCommand index
name "ndarray!special methods!itruediv"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ifloordiv__
\begin_inset LatexCommand index
name "ndarray!special methods!ifloordiv"

\end_inset

 (other)
\end_layout

\begin_layout Description
__imod__
\begin_inset LatexCommand index
name "ndarray!special methods!imod"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ipow__
\begin_inset LatexCommand index
name "ndarray!special methods!ipow"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ilshift__
\begin_inset LatexCommand index
name "ndarray!special methods!ilshift"

\end_inset

 (other)
\end_layout

\begin_layout Description
__irshift__
\begin_inset LatexCommand index
name "ndarray!special methods!irshift"

\end_inset

 (other)
\end_layout

\begin_layout Description
__iand__
\begin_inset LatexCommand index
name "ndarray!special methods!iand"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ixor__
\begin_inset LatexCommand index
name "ndarray!special methods!ixor"

\end_inset

 (other)
\end_layout

\begin_layout Description
__ior__
\begin_inset LatexCommand index
name "ndarray!special methods!ior"

\end_inset

 (other)
\end_layout

\begin_layout Description
\InsetSpace ~
 These methods are implemented to handle the inplace operatiors (
\family typewriter
+=
\family default
, 
\family typewriter
-=
\family default
, 
\family typewriter
*=
\family default
, 
\family typewriter
/=
\family default
, 
\family typewriter
/=
\family default
, 
\family typewriter
//=
\family default
, 
\family typewriter
%=
\family default
, 
\family typewriter
**
\family default
=, 
\family typewriter
<<
\family default
=, 
\family typewriter
>>=
\family default
, 
\family typewriter
&=
\family default
, 
\family typewriter
^=
\family default
, 
\family typewriter
|=
\family default
).
 The inplace operators are implemented using the corresponding ufunc and
 its ability to take an output argument (which is set as self).
 Using inplace operations can save space and time and is therefore encouraged
 whenever appropriate.
 
\end_layout

\begin_layout Warning
In place operations will perform the calculation using the precision decided
 by the data type of the two operands, but will silently downcast the result
 (if necessary) so it can fit back into the array.
 Therefore, for mixed precision calculations, a <op>= B can be different
 than a = a <op> B.
 For example, suppose a=ones((3,3)).
 Then a+=3j is different than a=a+3j While they both perform the same computatio
n, a+=3j casts the result to fit back in a, while a=a+3j re-binds the name
 a to the result.
\end_layout

\begin_layout Subsubsection
Unary operations
\end_layout

\begin_layout Description
__neg__
\begin_inset LatexCommand index
name "ndarray!special methods!neg"

\end_inset

 (self)
\end_layout

\begin_layout Description
__pos__
\begin_inset LatexCommand index
name "ndarray!special methods!pos"

\end_inset

 (self)
\end_layout

\begin_layout Description
__abs__
\begin_inset LatexCommand index
name "ndarray!special methods!abs"

\end_inset

 (self)
\end_layout

\begin_layout Description
__invert__
\begin_inset LatexCommand index
name "ndarray!special methods!invert"

\end_inset

 (self)
\end_layout

\begin_layout Description
\InsetSpace ~
 These functions are called in response to the unary operations (
\family typewriter
-
\family default
, 
\family typewriter
+
\family default
, 
\family typewriter
abs()
\family default
, 
\family typewriter
~
\family default
).
 With the exception of __pos__, these are implemented using ufuncs (negative,
 absolute, invert).
 The unary 
\family typewriter
+
\family default
 operator, however simply calls self.copy(), and can therefore be used to
 get a copy of an array.
 
\end_layout

\begin_layout Description
__complex__
\begin_inset LatexCommand index
name "ndarray!special methods!complex"

\end_inset

 (self)
\end_layout

\begin_layout Description
__int__
\begin_inset LatexCommand index
name "ndarray!special methods!int"

\end_inset

 (self)
\end_layout

\begin_layout Description
__long__
\begin_inset LatexCommand index
name "ndarray!special methods!long"

\end_inset

 (self)
\end_layout

\begin_layout Description
__float__
\begin_inset LatexCommand index
name "ndarray!special methods!float"

\end_inset

 (self)
\end_layout

\begin_layout Description
__oct__
\begin_inset LatexCommand index
name "ndarray!special methods!oct"

\end_inset

 (self)
\end_layout

\begin_layout Description
__hex__
\begin_inset LatexCommand index
name "ndarray!special methods!hex"

\end_inset

 (self)
\end_layout

\begin_layout Description
\InsetSpace ~
 These functions are also defined for the 
\family typewriter
ndarray
\family default
 object to handle the operations 
\family typewriter
complex()
\family default
, 
\family typewriter
int()
\family default
, 
\family typewriter
long()
\family default
, 
\family typewriter
float()
\family default
, 
\family typewriter
oct()
\family default
, and 
\family typewriter
hex()
\family default
.
 They work only on arrays that have one element in them and return the appropria
te scalar
\begin_inset LatexCommand index
name "ndarray!special methods|)"

\end_inset

.
 
\end_layout

\begin_layout Tip
The function called to implement many arithmetic special methods for arrays
 can be modified using the function set_numeric_ops.
 This function is called with keyword arguments indicating which operation(s)
 to replace.
 A dictionary is returned containing showing the old functions.
 By default, these functions are set to the corresponding ufunc.
 
\end_layout

\begin_layout Section
Array indexing
\end_layout

\begin_layout Standard
\begin_inset LatexCommand label
name "sec:Array-indexing"

\end_inset


\end_layout

\begin_layout Standard
More powerful array
\begin_inset LatexCommand index
name "indexing|("

\end_inset

 indexing
\begin_inset LatexCommand index
name "ndarray!special methods!getitem"

\end_inset

 was an important extension introduced by numarray, and was therefore an
 important part of the development of NumPy.
 In particular, the desire to select arbitrary elements based on their position
 in the array, and according to a mask was desirable.
 
\end_layout

\begin_layout Standard
There are two kinds of indexing available using the 
\family typewriter
X[obj]
\family default
 syntax: basic slicing, and advanced indexing
\begin_inset LatexCommand index
name "ndarray!special methods!setitem"

\end_inset

.
 For the description of this syntax given below, X is the array to-be-sliced
 and obj is the 
\emph on
selection
\emph default
 object.
 Furthermore, define 
\begin_inset Formula $N\equiv$
\end_inset

X.ndim.
 These two methods of slicing have different behavior and are triggered
 depending on obj.
 Adding additional functionality yet remaining compatible with old uses
 of slicing complicated the rules a little.
 Hopefully, after studying this section, you will have a firm grasp of what
 kind of selection will be initiated depending on the selection object.
\end_layout

\begin_layout Tip
in Python X[(exp1, exp2, ..., expN)] is equivalent to X[exp1, exp2, ..., expN]
 as the latter is just syntactic sugar for the former.
\end_layout

\begin_layout Subsection
Basic Slicing
\end_layout

\begin_layout Standard
Basic slicing
\begin_inset LatexCommand index
name "ndarray!special methods!getslice"

\end_inset

 extends Python's basic concept of slicing
\begin_inset LatexCommand index
name "ndarray!special methods!setslice"

\end_inset

 to N dimensions.
 Basic slicing occurs when obj is a slice object (constructed by start:stop:step
 notation inside of brackets), an integer, or a tuple of slice objects and
 integers.
 Ellipsis and newaxis objects can be interspersed with these as well.
 In order to remain backward compatible with a common usage in Numeric,
 basic slicing is also initiated if the selection object is any sequence
 (such as a list) containing slice objects, the ellipsis
\begin_inset LatexCommand index
name "ellipsis"

\end_inset

 object, or the newaxis
\begin_inset LatexCommand index
name "newaxis"

\end_inset

 object, but no integer arrays or other embedded sequences.
 
\end_layout

\begin_layout Standard
The standard rules of sequence slicing apply to basic slicing on a per-dimension
 basis (including using a step index).
 Some useful concepts to remember include:
\end_layout

\begin_layout Itemize
The basic slice syntax is '
\begin_inset Formula $i:j:k$
\end_inset

' where 
\begin_inset Formula $i$
\end_inset

 is the starting index, 
\begin_inset Formula $j$
\end_inset

 is the stopping index, and 
\begin_inset Formula $k$
\end_inset

 is the step (
\begin_inset Formula $k\neq0$
\end_inset

).
 This selects the 
\begin_inset Formula $m$
\end_inset

 elements (in the corresponding dimension) with index values 
\begin_inset Formula $i,\, i+k,\,\ldots,\, i+(m-1)k$
\end_inset

 where 
\begin_inset Formula $m=q+(r\neq0)$
\end_inset

 where 
\begin_inset Formula $q$
\end_inset

 and 
\begin_inset Formula $r$
\end_inset

 are the quotient and remainder obtained by dividing 
\begin_inset Formula $j-i$
\end_inset

 by 
\begin_inset Formula $k$
\end_inset

: 
\begin_inset Formula $j-i=qk+r$
\end_inset

, so that 
\begin_inset Formula $i+\left(m-1\right)k<j.$
\end_inset


\end_layout

\begin_layout Itemize
Assume 
\begin_inset Formula $n$
\end_inset

 is the number of elements in the dimension being sliced.
 Then, if 
\begin_inset Formula $i$
\end_inset

 is not given it defaults to 0 for 
\begin_inset Formula $k>0$
\end_inset

 and 
\begin_inset Formula $n$
\end_inset

 for 
\begin_inset Formula $k<0$
\end_inset

.
 If 
\begin_inset Formula $j$
\end_inset

 is not given it defaults to 
\begin_inset Formula $n$
\end_inset

 for 
\begin_inset Formula $k>0$
\end_inset

 and 
\begin_inset Formula $-1$
\end_inset

 for 
\begin_inset Formula $k<0$
\end_inset

.
 If 
\begin_inset Formula $k$
\end_inset

 is not given it defaults to 1.
 Note that '::' is the same as ':' and means select all indices along this
 axis.
 
\end_layout

\begin_layout Itemize
If the number of objects in the selection tuple is less than 
\begin_inset Formula $N$
\end_inset

, then ':' is assumed for any remaining dimensions.
\end_layout

\begin_layout Itemize
Ellipsis expand to the number of ':' objects needed to make a selection
 tuple of the same length as X.ndim.
 Only one ellipsis is expanded, any others are interpreted as more ':'
\end_layout

\begin_layout Itemize
Each newaxis object in the selection tuple serves to expand the dimensions
 of the resulting selection by one unit-length dimension.
 The added dimension is the position of the newaxis object in the selection
 tuple.
 
\end_layout

\begin_layout Itemize
An integer, 
\begin_inset Formula $i$
\end_inset

, returns the same values as 
\begin_inset Formula $i:i+1$
\end_inset

 
\series bold
except
\series default
 the dimensionality of the returned object is reduced by 1.
 In particular, a selection tuple with the 
\begin_inset Formula $p^{\textrm{th}}$
\end_inset

 element an integer (and all other entries ':') returns the corresponding
 sub-array with dimension 
\begin_inset Formula $N-1$
\end_inset

.
 If 
\begin_inset Formula $N=1,$
\end_inset

 then the returned object is an Array Scalar.
 These objects are explained in Chapter 
\begin_inset LatexCommand ref
reference "cha:Scalar-objects"

\end_inset

.
\end_layout

\begin_layout Itemize
If the selection tuple has all entries ':' except the 
\begin_inset Formula $p^{\textrm{th}}$
\end_inset

 entry which is a slice object 
\begin_inset Formula $i:j:k$
\end_inset

, then the returned array has dimension 
\begin_inset Formula $N$
\end_inset

 formed by concatenating the sub-arrays returned by integer indexing of
 elements 
\begin_inset Formula $i$
\end_inset

, 
\begin_inset Formula $i+k$
\end_inset

, 
\begin_inset Formula $i+(m-1)k<j$
\end_inset

, 
\end_layout

\begin_layout Itemize
Basic slicing with more than one non-':' entry in the slicing tuple, acts
 like repeated application of slicing using a single non-':' entry, where
 the non-':' entries are successively taken (with all other non-':' entries
 replaced by ':').
 Thus, X[ind1,...,ind2,:] acts like X[ind1][...,ind2,:] under basic slicing.
 Note this is NOT true for advanced slicing.
 
\end_layout

\begin_layout Itemize
You may use slicing to set values in the array, but (unlike lists) you can
 never grow the array.
 The size of the value to be set in X[obj] = value must be (broadcastable)
 to the same shape as X[obj].
 
\end_layout

\begin_layout Standard
Basic slicing always returns another 
\emph on
view
\begin_inset LatexCommand index
name "ndarray!view"

\end_inset


\emph default
 of the array.
 In other words, the returned array from a basic slicing operation uses
 the same data as the original array.
 This can be confusing at first, but it is faster and can save memory.
 A copy can always be obtained if needed using the unary + operator (which
 has lower precedence than slicing) or the .copy() method.
 
\end_layout

\begin_layout Tip
Remember that a slicing tuple can always be constructed as obj and used
 in the x[obj] notation.
 Slice objects can be used in the construction in place of the [start:stop:step]
 notation.
 For example, 
\family typewriter
x[1:10:5,::-1]
\family default
 can also be implemented as 
\family typewriter
obj=(slice(1,10,5), slice(None,None,-1)); X[obj]
\family default
.
 This can be useful for constructing generic code that works on arrays of
 arbitrary dimension.
\end_layout

\begin_layout Subsection
Advanced selection
\end_layout

\begin_layout Standard
Advanced selection is triggered when the selection object, obj, is a non-tuple
 sequence object, an ndarray (of data type integer or bool), or a tuple
 with at least one sequence object or ndarray (of data type integer or bool).
 There are two types of advanced indexing: integer and Boolean.
 Advanced selection always returns a copy of the data (contrast with basic
 slicing that returns a view).
 
\end_layout

\begin_layout Subsubsection
Integer
\end_layout

\begin_layout Standard
Integer indexing allows selection of arbitrary items in the array based
 on their 
\begin_inset Formula $N$
\end_inset

-dimensional index.
 This kind of selection occurs when advanced selection is triggered and
 the selection object is not an array of data type bool.
 For the discussion below, when the selection object is not a tuple, it
 will be referred to as if it had been promoted to a 1-tuple, which will
 be called the selection tuple.
 The rules of advanced integer-style indexing are:
\end_layout

\begin_layout Itemize
if the length of the selection tuple is larger than 
\begin_inset Formula $N$
\end_inset

(=X.ndim) an error is raised.
\end_layout

\begin_layout Itemize
all sequences and scalars in the selection tuple are converted to intp indexing
 arrays.
 
\end_layout

\begin_layout Itemize
all selection tuple objects must be convertible to intp arrays, or slice
 objects, or the Ellipsis (...) object.
\end_layout

\begin_layout Itemize
Exactly one Ellipsis object will be expanded, any other Ellipsis objects
 will be treated as full slice (':') objects.
 The Ellipsis object is replaced with as many full slice (':') objects as
 needed to make the length of the selection tuple 
\begin_inset Formula $N$
\end_inset

.
 
\end_layout

\begin_layout Itemize
If the selection tuple is smaller than 
\begin_inset Formula $N$
\end_inset

, then as many ':' objects as needed are added to the end of the selection
 tuple so that the modified selection tuple has length 
\begin_inset Formula $N$
\end_inset

.
\end_layout

\begin_layout Itemize
The shape of all the integer indexing arrays must be broadcastable to the
 same shape.
 Arrays are broadcastable if any of the following are satisfied 
\end_layout

\begin_deeper
\begin_layout Enumerate
The arrays all have exactly the same shape.
\end_layout

\begin_layout Enumerate
The arrays all have the same number of dimensions and the length of each
 dimensions is either a common length or 1.
\end_layout

\begin_layout Enumerate
The arrays that have too few dimensions can have their shapes pre-pended
 with a dimension of length 1 to satisfy property 2.
 
\end_layout

\end_deeper
\begin_layout Itemize
The shape of the output (or the needed shape of the object to be used for
 setting) is the broadcasted shape.
 
\end_layout

\begin_deeper
\begin_layout Description
Example: If a.shape is (5,1), b.shape is (1,6), c.shape is (6,) and d.shape
 is () so that d is a scalar, then a, b, c, and d are all broadcastable
 to dimension (5,6).
 The array 
\begin_inset Quotes eld
\end_inset

a
\begin_inset Quotes erd
\end_inset

 acts like a (5,6) array where a[:,0] is broadcast to the other columns,
 
\begin_inset Quotes eld
\end_inset

b
\begin_inset Quotes erd
\end_inset

 acts like a (5,6) array where b[0,:] is broadcast to the other rows, 
\begin_inset Quotes eld
\end_inset

c
\begin_inset Quotes erd
\end_inset

 acts like a (1,6) array and therefore a (5,6) where c[:] is broadcast to
 every row, and finally 
\begin_inset Quotes eld
\end_inset

d
\begin_inset Quotes erd
\end_inset

 acts like a (5,6) array where the single values is repeated.
 
\end_layout

\end_deeper
\begin_layout Itemize
After expanding any ellipses and filling out any missing (':') objects in
 the selection tuple, then let 
\begin_inset Formula $N_{t}$
\end_inset

 be the number of indexing arrays, and let 
\begin_inset Formula $N_{s}=N-N_{t}$
\end_inset

 be the number of slice objects.
 Note that 
\begin_inset Formula $N_{t}>0$
\end_inset

 (or we wouldn't be doing advanced integer indexing).
 
\end_layout

\begin_layout Itemize
If 
\begin_inset Formula $N_{s}=0$
\end_inset

 then the 
\begin_inset Formula $M$
\end_inset

-dimensional result is constructed by varying the index tuple 
\begin_inset Formula $\left(i_{1},\ldots,i_{M}\right)$
\end_inset

 over the range of the result shape and for each value of the index tuple
 setting:
\begin_inset Formula \[
\textrm{result[$i_{1},\ldots,i_{M}$]=X[ind$_{1}$[$i_{1},\ldots i_{M}$], ind$_{2}$[$i_{1},\ldots,i_{M}$], \, etc.,\, ind$_{N}$[$i_{1},\ldots,i_{M}$]}.\]

\end_inset


\end_layout

\begin_deeper
\begin_layout Description
Example: Suppose the shape of the broadcasted indexing arrays is 3-dimensional
 and 
\begin_inset Formula $N$
\end_inset

 is 2.
 Then the result is found by letting 
\begin_inset Formula $i,j,k$
\end_inset

 run over the shape found by broadcasting 
\begin_inset Formula $\textrm{ind}_{1},$
\end_inset

 and 
\begin_inset Formula $\textrm{ind}_{2},$
\end_inset

and for each 
\begin_inset Formula $i,j,k$
\end_inset

 setting result[
\begin_inset Formula $i,j,k$
\end_inset

] = X[
\begin_inset Formula $\textrm{ind}_{1}[i,j,k]$
\end_inset

, 
\begin_inset Formula $\textrm{ind}_{2}[i,j,k]$
\end_inset

].
 
\end_layout

\end_deeper
\begin_layout Itemize
If 
\begin_inset Formula $N_{s}>0$
\end_inset

, then partial indexing is done.
 This can be somewhat mind-boggling to understand, but if you think in terms
 of the shapes of the arrays involved, it can be easier to grasp what happens.
 In simple cases (
\emph on
i.e.

\emph default
 one indexing array and 
\begin_inset Formula $N-1$
\end_inset

 slice objects) it does exactly what you would expect (concatenation of
 repeated application of basic slicing).
 The rule for partial indexing is that the shape of the result (or the interpret
ed shape of the object to be used in setting) is the shape of X with the
 indexed subspace replaced with the broadcasted indexing subspace.
 If the index subspaces are right next to each other, then the broadcasted
 indexing space directly replaces all of the indexed subspaces in X.
 If the indexing subspaces are separated (by slice objects), then the broadcaste
d indexing space is first, followed by the sliced subspace of X.
 
\end_layout

\begin_deeper
\begin_layout Description
Example\InsetSpace ~
1: Suppose X.shape is (10,20,30) and ind is a (2,3,4) indexing intp
 array, then result=X[...,ind,:] has shape (10,2,3,4,30) because the (20,)-shaped
 subspace has been replaced with a (2,3,4)-shaped broadcasted indexing subspace.
 If we let 
\begin_inset Formula $i,j,k$
\end_inset

 loop over the (2,3,4)-shaped subspace then result[...,i,j,k,:] = X[...,ind[i,j,k],:].
 This example produces the same result as X.take(ind,axis=-2).
 
\end_layout

\begin_layout Description
Example\InsetSpace ~
2: Now let X.shape be (10,20,30,40,50) and suppose 
\begin_inset Formula $\textrm{ind}_{1}$
\end_inset

 and 
\begin_inset Formula $\textrm{ind}_{2}$
\end_inset

 are broadcastable to the shape (2,3,4).
 Then X[:,ind
\begin_inset Formula $_{1}$
\end_inset

,ind
\begin_inset Formula $_{2}$
\end_inset

] has shape (10,2,3,4,40,50) because the (20,30)-shaped subspace from X
 has been replaced with the (2,3,4) subspace from the indices.
 However, X[:,ind
\begin_inset Formula $_{1}$
\end_inset

,:,ind
\begin_inset Formula $_{2}$
\end_inset

,:] has shape (2,3,4,10,30,50) because there is no unambiguous place to
 drop in the indexing subspace, thus it is tacked-on to the beginning.
 It is always possible to use .transpose() to move the sups pace anywhere
 desired.
 This example cannot be replicated using take.
 
\end_layout

\end_deeper
\begin_layout Subsubsection
Boolean
\end_layout

\begin_layout Standard
This advanced selection occurs when obj is an array object of Boolean type
 (such as may be returned from comparison operators).
 It is always equivalent to (but faster than) X[obj.nonzero()] where as described
 above obj.nonzero() returns a tuple (of length obj.ndim) of integer index
 arrays showing the True elements of obj.
 
\end_layout

\begin_layout Standard
The special case when obj.ndim == X.ndim is worth mentioning.
 In this case X[obj] returns a 1-dimensional array filled with the elements
 of X corresponding to the True values of obj.
 It The search order will be C-style (last index varies the fastest).
 If obj has True values at entries that are outside of the bounds of X,
 then an index error will be raised.
\end_layout

\begin_layout Standard
You can also use Boolean arrays as element of the selection tuple.
 In such instances, they will always be interpreted as nonzero(obj) and
 the equivalent integer indexing will be done.
 In general you can think of indexing with Boolean arrays as indexing with
 nonzero(<Boolean>).
\end_layout

\begin_layout Warning
the definition of advanced selection means that X[(1,2,3),] is fundamentally
 different than X[(1,2,3)].
 The latter is equivalent to X[1,2,3] which will trigger basic selection
 while the former will trigger advanced selection.
 Be sure to understand why this is True.
 You should also recognize that x[[1,2,3]] will trigger advanced selection,
 but X[[1,2,slice(None)]] will trigger basic selection.
\end_layout

\begin_layout Subsection
Flat Iterator indexing
\end_layout

\begin_layout Standard
As mentioned previously, X.flat returns an iterator that will iterate over
 the entire array (in C-contiguous style with the last index varying the
 fastest).
 This iterator object can also be indexed using basic slicing or advanced
 indexing as long as the selection object is not a tuple.
 This should be clear from the fact that X.flat is a 1-dimensional view.
 X.flat can be used for integer indexing using 1-dimensional C-style-flat
 indices.
 The shape of any returned array is therefore the shape of the integer indexing
\begin_inset LatexCommand index
name "indexing|)"

\end_inset

 object
\begin_inset LatexCommand index
name "ndarray|)"

\end_inset

.
 
\end_layout

\begin_layout Chapter
Basic Routines 
\end_layout

\begin_layout Quotation
Do not pray for tasks equal to your powers; pray for powers equal to your
 tasks.
 Then the doing of your work shall be no miracle, but you shall be the miracle.
\end_layout

\begin_layout Right Address
---
\emph on
Phillips Brooks
\end_layout

\begin_layout Quote
Education isn't how much you have committed to memory, or even how much
 you know.
 It's being able to differentiate between what you do know and what you
 don't.
\end_layout

\begin_layout Right Address
---
\emph on
Anatole France
\end_layout

\begin_layout Section
Creating arrays
\end_layout

\begin_layout Description
array
\begin_inset LatexCommand index
name "array"

\end_inset

 (object=, dtype=None, copy=True, order=None, subok=False, ndmin=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Create a new ndarray of data type, dtype (or determined from object if
 dtype is None).
 The shape of the new array will be determined from object.
 If copy is True, then ensure a copy of the object is made.
 If copy is False, then the returned object is a copy of the array only
 if dtype is not equivalent to the data type of object.
 If order is 'Fortran' then the resulting array will be in Fortran order,
 otherwise it is in C order.
 If subok (subclasses are O.K.) is True then pass through subclasses of the
 array object if possible.
 If subok is False then only ndarray objects may be returned.
 The ndmin parameter specifies that the returned array must have at least
 the given number of dimensions.
 
\end_layout

\begin_layout Description
asarray
\begin_inset LatexCommand index
name "asarray"

\end_inset

 (object=, dtype=None, order=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Exactly the same as array(...) except the default copy argument is False,
 and subok is always False.
 Using this function always returns the base class ndarray.
 
\end_layout

\begin_layout Description
asanyarray
\begin_inset LatexCommand index
name "asanyarray"

\end_inset

 (object, dtype=None, order=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Thin wrapper around array(...) with subok=1.
 You should use this routine if you are only making use of the array attributes,
 and believe the calculations that will follow would work with any subclass
 of the array.
 Use of this routine increases the chance that array subclasses will interact
 seamlessly with your function --- returning the same subclasses.
 
\end_layout

\begin_layout Description
require
\begin_inset LatexCommand index
name "require"

\end_inset

 (object, dtype=None, requirements=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Require a Python object to be an ndarray (or a sub-class) of the given
 data-type if it can be cast safely, otherwise raise an error.
 The requirements, if given, are a sequence containing the requested combination
 of the flags 'C_CONTIGUOUS' ('C'), 'F_CONTIGUOUS' ('F'), 'ALIGNED' ('A'),
 'WRITEABLE' ('W'), 'OWNDATA' ('O'), and the special directive 'ENSUREARRAY'
 ('E').
 These strings dictate which flags should be set on the return array (note
 only one of 'F_CONTIGUOUS' or 'C_CONTIGUOUS' should be used and 'F_CONTIGUOUS'
 over-rides 'C_CONTIGUOUS').
 The special directive 'ENSUREARRAY' makes sure that a base-class ndarray
 is returned instead of allowing sub-classes to pass through.
 This function is particularly useful in a Python interface to C-code (say
 called using ctypes
\begin_inset LatexCommand index
name "ctypes"

\end_inset

).
 
\end_layout

\begin_layout Description
arange
\begin_inset LatexCommand index
name "arange"

\end_inset

 (start=, stop=None, step=1, dtype=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Function similar to Python's built-in range() function except it returns
 an ndarray object.
 Return a 1-d array of data type, dtype (or determined from the start, stop,
 and step objects if None), that starts at start, ends 
\emph on
before
\emph default
 stop and is incremented by step.
 The returned array has length 
\begin_inset Formula $n$
\end_inset

 where 
\begin_inset Formula \[
n=\left\lceil \frac{\textrm{stop}-\textrm{start}}{\textrm{step}}\right\rceil \]

\end_inset

 with element 
\begin_inset Formula $i$
\end_inset

 equal to 
\begin_inset Formula $\textrm{start}+i\cdot\textrm{step}.$
\end_inset

 If stop is None, then the first argument is interpreted as stop and start
 is 0.
 
\end_layout

\begin_layout Note
By definition of the ceiling function (denoted by 
\begin_inset Formula $\left\lceil x\right\rceil $
\end_inset

), we know that 
\begin_inset Formula $x\leq\left\lceil x\right\rceil <x+1$
\end_inset

, therefore this definition of the length of arange guarantees that 
\begin_inset Formula $\textrm{start}+n\cdot\textrm{step}\geq\textrm{stop}$
\end_inset

 as well as 
\begin_inset Formula $\textrm{start}+(n-1)\cdot\textrm{step}<\textrm{stop}$
\end_inset

.
 
\end_layout

\begin_layout Description
isfortran
\begin_inset LatexCommand index
name "isfortran"

\end_inset

 (arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Equivalent to 
\family typewriter
arr.flags.fnc
\family default
 and therefore returns True only if arr is Fortran-contiguous but not also
 C-contiguous.
\end_layout

\begin_layout Description
empty
\begin_inset LatexCommand index
name "empty"

\end_inset

 (shape=, dtype=int, order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an uninitialized array of data type, dtype, and given shape.
 The memory layout defaults to C-style contiguous, but can be made Fortran-style
 contiguous with a 'Fortran' order keyword.
\end_layout

\begin_layout Description
empty_like
\begin_inset LatexCommand index
name "empty\\_like"

\end_inset

 (arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Syntactic sugar for empty(a.shape, a.dtype, isfortran(arr))
\end_layout

\begin_layout Description
zeros
\begin_inset LatexCommand index
name "zeros"

\end_inset

 (shape=, dtype=int, order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array of data type dtype and given shape filled with zeros.
 The memory layout may be altered from the default C-style contiguous with
 the order keyword.
\end_layout

\begin_layout Description
zeros_like
\begin_inset LatexCommand index
name "zeros\\_like"

\end_inset

 (arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Syntactic sugar for zeros(a.shape, a.dtype, isfortran(arr))
\end_layout

\begin_layout Description
ones
\begin_inset LatexCommand index
name "ones"

\end_inset

 (shape=, dtype=int, order='C')
\end_layout

\begin_layout Description
\InsetSpace ~
 Syntactic sugar for a = zeros(shape, dtype, order); a+= 1.
 
\end_layout

\begin_layout Description
fromstring
\begin_inset LatexCommand index
name "fromstring"

\end_inset

 (string=,dtype=int, count=-1, sep='')
\end_layout

\begin_layout Description
\InsetSpace ~
 If sep is '', then return a new 1-d array with data-type descriptor given
 by dtype and with memory initialized (copied) from the raw binary data
 in string.
 If count is non-negative, the new array will have count elements (with
 a 
\family typewriter
ValueError
\family default
 raised if count requires more data than the string offers), otherwise the
 size of the string must be a multiple of the itemsize implied by dtype,
 and count will be the length of the string divided by the itemsize.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 If sep is not '', then interpret the string in ASCII mode with the provided
 separator and convert the string to an array of numbers.
 Any additional white-space will be ignored.
\end_layout

\begin_layout Description
fromfile
\begin_inset LatexCommand index
name "fromfile"

\end_inset

 (file=, dtype=int, count=-1, sep='')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a 1-d array of data type, dtype, from a file (open file object or
 string with the name of a file to read).
 The file will be read in binary mode if sep is the empty string.
 Otherwise, the file will be read in text mode with sep providing the separator
 string between the entries.
 If count is -1, then the size will be determined from the file, otherwise,
 up to count items will be read from the file.
 If fewer than count items are read, then a RunTimeWarning is issued indicating
 the number of items read.
\end_layout

\begin_layout Description
frombuffer
\begin_inset LatexCommand index
name "frombuffer"

\end_inset

 (buffer, dtype=intp, count=-1, offset=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Very similar to (binary-mode) fromstring in interpretation of the arguments,
 except buffer can be any object exposing the buffer interface (or any object
 with a __buffer__ attribute that returns a buffer exposing the buffer protocol).
 The new array shares memory with the buffer object.
 The new array will be read-only if the buffer does not expose a writeable
 buffer.
 
\end_layout

\begin_layout Description
fromiter
\begin_inset LatexCommand index
name "fromiter"

\end_inset

 (iterator_or_generator, dtype=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an array from an iterator or a generator.
 Only handles 1-dimensional cases.
 By default the data-type is determined from the objects returned from the
 iterator.
 
\end_layout

\begin_layout Description
load
\begin_inset LatexCommand index
name "load"

\end_inset

 (file)
\end_layout

\begin_layout Description
\InsetSpace ~
 Load a NumPy binary file (.npy), a NumPy binary zipfile (.npz), or a pickled
 Python object from an open file.
 If file is a string, then open a file with that name first.
 Which kind of file should be loaded is determined by the magic bytes at
 the front of the file (not by filename extension).
 See 
\shape italic
save
\shape default
 and 
\shape italic
savez
\shape default
 for functions which write .npy and .npz files from NumPy arrays.
 If file is a binary zipfile, then an instance of NpzObj is returned.
 This object is a simple wrapper around the zip-file which allows extraction
 of the arrays stored within it.
 The .files attribute of the NpzObj returns a list of all arrays in the archive.
 These arrays are accessible through a dictionary-like interface (obj['name'])
 or through attribute lookup through the .f attribute of the returned object
 (obj.f.name).
 If the file is a NumPy binary file (.npy), then the array itself is returned
 from this function.
 If the file contains a pickled object, then that object is returned.
 
\end_layout

\begin_layout Description
loads
\begin_inset LatexCommand index
name "loads"

\end_inset

 (str)
\end_layout

\begin_layout Description
\InsetSpace ~
 Load a pickled array from a string.
 Equivalent to cPickle.loads(str).
 This function will likely be deprecated in the future.
 Use cPickle instead.
\end_layout

\begin_layout Description
save
\begin_inset LatexCommand index
name "save"

\end_inset

 (file, arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Save the array into a file which can be a string or an open file-like object.
 If the file is given as a string, then it will have .npy appended if it
 does not already end with that extension.
 The .npy file format is NumPy-specific and is documented in the numpy.lib.format
 module.
 It only stores a single array.
 
\end_layout

\begin_layout Description
savez
\begin_inset LatexCommand index
name "savez"

\end_inset

 (file, *args, **kwds)
\end_layout

\begin_layout Description
\InsetSpace ~
 Save a sequence of arrays into a NumPy binary zipfile (.npz).
 An .npz file is a regular zip-file containing multiple .npy files.
 If keywords are given, then the keyword names are used as filenames (with
 the .npy extension added) in the zip-file with the corresponding values
 being converted to arrays and stored in the specified filename.
 Any non-keyword arguments that are passed in results in the names arr_0,
 arr_1, etc.
 being used in the zip-file (if a keyword by one of those names also exists,
 then a ValueError is raised).
 
\end_layout

\begin_layout Description
loadtxt
\end_layout

\begin_layout Description
savetxt
\end_layout

\begin_layout Description
DataSource
\end_layout

\begin_layout Description
indices
\begin_inset LatexCommand index
name "indices"

\end_inset

 (dimensions, dtype=intp)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array of dtype representing 
\begin_inset Formula $n$
\end_inset

(=len(dimensions)) grids of indices each with variation in a single direction.
 The returned array has shape (
\begin_inset Formula $n$
\end_inset

,)+dimensions.
 Compare with mgrid.
 
\end_layout

\begin_layout MyCode
>>> indices((2,3))
\newline
array([[[0, 0, 0],
\newline
        [1, 1, 1]],
\newline

\newline
       [[0, 1, 2],
\newline

        [0, 1, 2]]])
\end_layout

\begin_layout Description
fromfunction
\begin_inset LatexCommand index
name "fromfunction"

\end_inset

 (function, dimensions, **kwargs)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an array from a function called on a tuple of index grids.
 The function should be able to take array arguments and process them like
 ufuncs (use vectorize if it doesn't).
 The function should accept as many arguments as there are dimensions which
 is a sequence of numbers indicating the length of the desired output for
 each axis.
 Keyword arguments to function may also be passed in as keywords to fromfunction.
\end_layout

\begin_layout MyCode
>>> print fromfunction(lambda i,j: i+j, (2,3))
\newline
[[ 0.
  1.
  2.]
\newline
 [ 1.
  2.
  3.]]
\end_layout

\begin_layout Description
identity
\begin_inset LatexCommand index
name "identity"

\end_inset

 (n, dtype=intp)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a 2-d array of shape (n,n) and data type, dtype with ones along
 the main diagonal.
 
\end_layout

\begin_layout Description
where
\begin_inset LatexCommand index
name "where"

\end_inset

 (condition[, x, y])
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns an array shaped like condition, that has the elements of x and
 y respectively where condition is respectively true or false.
 If x and y are not given, then it is equivalent to nonzero(condition).
\end_layout

\begin_layout Description
flatnonzero
\begin_inset LatexCommand index
name "flatnonzero"

\end_inset

 (arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return indices that are non-zero in a flattened version of arr.
 Equivalent to a.ravel().nonzero()[0].
\end_layout

\begin_layout Description
putmask
\begin_inset LatexCommand index
name "putmask"

\end_inset

 (arr=, mask=, values=)
\end_layout

\begin_layout Description
\InsetSpace ~
 Performs the equivalent of 
\end_layout

\begin_layout LyX-Code
for n, obj in enumerate(
\series bold
mask
\series default
.flat):
\end_layout

\begin_layout LyX-Code
    if obj:
\end_layout

\begin_layout LyX-Code
        self.flat[n] = 
\series bold
values
\series default
[n]
\end_layout

\begin_layout Description
\InsetSpace ~
 The values array is repeated if it is too short.
 In particular, this means that indexing on the values array is modular
 it's length, which might be surprising you are expecting putmask to work
 the same as arr[mask]=values.
\end_layout

\begin_layout Description
lexsort
\begin_inset LatexCommand index
name "lexsort"

\end_inset

 (keys=, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array of indices similar to argsort except sorting is done using
 all of the provided keys.
 First a sort is computed using key[0], then the indices are further altered
 by sorting on key[1].
 This is repeated until sorting has been performed on all of the keys.
 This is a useful function for multiple-field sorting.
\end_layout

\begin_layout MyCode
>>> a = [1,2,1,3,1,5]; b = [0,4,5,6,2,3]
\newline
>>> ind = lexsort((b,a))
\newline
>>> print
 take(a,ind)
\newline
[1 1 1 2 3 5]
\newline
>>> print take(b,ind)
\newline
[0 2 5 4 6 3]
\end_layout

\begin_layout Description
\InsetSpace ~
 Notice the order the keys had to be used in order to get a lexicographical
 sorting order.
 To clarify, suppose three equal-length sequences are fields of an underlying
 data-type: (f1,f2,f3).
 If we want to sort first on f1 and then on f2 and then on f3, the indices
 that would accomplish that sort are obtained as lexsort((f3,f2,f1)).
\end_layout

\begin_layout Section
Operations on two or more arrays
\end_layout

\begin_layout Description
concatenate
\begin_inset LatexCommand index
name "concatenate"

\end_inset

 (seq=, axis=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a new array from elements of the sequence object seq concatenated
 along the given axis.
 The elements of the sequence object must have compatible types and be the
 same shape.
 If axis is None, then flatten each element of seq before concatenating
 together to construct a 1-d array.
\end_layout

\begin_layout Description
correlate
\begin_inset LatexCommand index
name "correlate"

\end_inset

 (x, y, mode='valid')
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the 1-d cross correlation of x and y keeping portions determined
 by mode which may be 'valid' (0), 'same' (1), or 'full' (2).
 The 'full' cross-correlation between two 1-d arrays is computed as 
\begin_inset Formula \[
z\left[n\right]=\sum_{i=\max\left(n-M,0\right)}^{\min\left(n,K\right)}x\left[i\right]y\left[n+i\right],\]

\end_inset

for 
\begin_inset Formula $n=0\ldots K+M$
\end_inset

 where 
\begin_inset Formula $K$
\end_inset

=len(
\begin_inset Formula $x$
\end_inset

)-1 and 
\begin_inset Formula $M$
\end_inset

=len(
\begin_inset Formula $y$
\end_inset

)-1, and we assume 
\begin_inset Formula $K\geq M$
\end_inset

 (without loss of generality because we can interchange the roles of 
\begin_inset Formula $x$
\end_inset

 and 
\begin_inset Formula $y$
\end_inset

 without effect).
 For this formula to work, we assume that 
\begin_inset Formula $x[i]=0$
\end_inset

 when 
\begin_inset Formula $i\notin\left[0,K-1\right]$
\end_inset

 and 
\begin_inset Formula $y[j]=0$
\end_inset

 when 
\begin_inset Formula $j\neq[0,M-1]$
\end_inset

.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 If mode is 'same' then only the 
\begin_inset Formula $K$
\end_inset

 middle values are returned starting at 
\begin_inset Formula $n=\left\lfloor \frac{M-1}{2}\right\rfloor $
\end_inset

.
 If the flag has a value of 'valid' then only the middle 
\begin_inset Formula $K-M+1=\left(K+1\right)-\left(M+1\right)+1$
\end_inset

 output values are returned starting at 
\begin_inset Formula $n=M.$
\end_inset

 
\end_layout

\begin_layout Description
convolve
\begin_inset LatexCommand index
name "convolve"

\end_inset

 (x, y, mode='valid')
\end_layout

\begin_layout Description
\InsetSpace ~
 Convolution is very similar to correlation except it is defined with one
 sequence reversed: 
\begin_inset Formula \[
z\left[n\right]=\sum_{i}x[i]y[n-i].\]

\end_inset

 The mode keyword has the same effect as it does for correlation.
 Convolution ('full') between two 1-d arrays implements polynomial multiplicatio
n where the array entries are viewed as coefficients for polynomials.
\end_layout

\begin_deeper
\begin_layout Description
Example: Consider that 
\begin_inset Formula $(x^{3}+4x^{2}+2)$
\end_inset


\begin_inset Formula $\left(x^{4}+3x+1\right)$
\end_inset

=
\begin_inset Formula $x^{7}+4x^{6}+5x^{4}+13x^{3}+4x^{2}+6x+2.$
\end_inset

 This can be determined by using the code 
\family typewriter
convolve([1,4,0,2], [1,0,0,3,1])
\family default
 which returns 
\family typewriter
[1,4,0,5,13,4,6,2].

\family default
 Notice the one-to-one alignment between the elements of the arrays and
 the coefficients on powers of 
\begin_inset Formula $x$
\end_inset

 in the polynomial.
 
\end_layout

\end_deeper
\begin_layout Description
outer
\begin_inset LatexCommand index
name "outer"

\end_inset

 (a, b)
\end_layout

\begin_layout Description
\InsetSpace ~
 compute an outerproduct which is syntactic sugar for a.ravel() [:,newaxis]
 * b.ravel() [newaxis,:] (after first converting a and b to ndarrays).
\end_layout

\begin_layout MyCode
>>> print outer([1,2,3],[10,100,1000])
\newline
[[  10  100 1000]
\newline
 [  20  200 2000]
\newline

 [  30  300 3000]]
\end_layout

\begin_layout Description
inner
\begin_inset LatexCommand index
name "inner"

\end_inset

 (a, b)
\end_layout

\begin_layout Description
\InsetSpace ~
 Computes the inner product between two arrays.
 This is an array that has shape a.shape[:-1] + b.shape[:-1] with elements
 computed as the sum of the product of the elements from the last dimensions
 of a and b.
 In particular, let 
\begin_inset Formula $I$
\end_inset

 and 
\begin_inset Formula $J$
\end_inset

 be the super
\begin_inset Foot
status open

\begin_layout Standard
A super index is 0 or more integer indices used to index into an N-dimensional
 array.
 How many indices a super index represents should be implied by context.
\end_layout

\end_inset

 indices selecting the 1-dimensional arrays 
\begin_inset Formula $a[I,:]$
\end_inset

 and 
\begin_inset Formula $b[J,:]$
\end_inset

, then the resulting array, 
\begin_inset Formula $r$
\end_inset

, is 
\begin_inset Formula \[
r[I,J]=\sum_{k}a[I,k]b[J,k].\]

\end_inset


\end_layout

\begin_layout Description
dot
\begin_inset LatexCommand index
name "dot"

\end_inset

 (a, b)
\end_layout

\begin_layout Description
\InsetSpace ~
 Computes the dot (matrix) product between two arrays.
 The product-sum is over the last dimension of 
\begin_inset Formula $a$
\end_inset

 and the second-to-last dimension of 
\begin_inset Formula $b$
\end_inset

.
 Specifically, if 
\begin_inset Formula $I$
\end_inset

 and 
\begin_inset Formula $J$
\end_inset

 are super indices for 
\begin_inset Formula $a[I,:]$
\end_inset

 and 
\begin_inset Formula $b[J,:,j]$
\end_inset

 so that 
\begin_inset Formula $j$
\end_inset

 is the index of the last dimension of 
\begin_inset Formula $b$
\end_inset

.
 Then, the shape of the resulting array is a.shape[:-1] + b.shape[:-2] + (b.shape[-
1],) with elements.
 
\begin_inset Formula \[
r[I,J,j]=\sum_{k}a[I,k]b[J,k,j],\]

\end_inset


\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "vdot"

\end_inset

vdot (a, b)
\end_layout

\begin_layout Description
\InsetSpace ~
 Computes the dot product between two arrays (flattened into one-dimensional
 vectors) after conjugating the first vector.
 This is an inner-product following the physicists convention of conjugating
 the first argument.
\begin_inset Formula \[
r=\sum_{k}\overline{\textrm{a.flat}[k]}\textrm{b.flat}[k].\]

\end_inset


\end_layout

\begin_layout Description
tensordot
\begin_inset LatexCommand index
name "tensordot"

\end_inset

 (a, b, axes=(-1,0))
\end_layout

\begin_layout Description
\InsetSpace ~
 Computes a dot-product between two arrays where the sum is taken over the
 axes specified by the 2-sequence which can have either scalar or sequence
 entries.
 The axes specified are summed over and the remaining axes are used to construct
 the result.
 So, for example, if 
\begin_inset Formula $a$
\end_inset

 is 
\begin_inset Formula $3\times4\times5$
\end_inset

 and 
\begin_inset Formula $b$
\end_inset

 is 
\begin_inset Formula $4\times3\times2$
\end_inset

 then if axes=([1,0],[0,1]) (or axes=([0,1],[1,0])) the result will be 
\begin_inset Formula $5\times2$
\end_inset

.
 Let 
\begin_inset Formula $I$
\end_inset

 represent the indices of the un-summed axes in 
\begin_inset Formula $a$
\end_inset

, let 
\begin_inset Formula $J$
\end_inset

 represent the indices of the un-summed axes in 
\begin_inset Formula $b$
\end_inset

 and let 
\begin_inset Formula $K$
\end_inset

 represent the the indices of the axes summed over in both 
\begin_inset Formula $a$
\end_inset

 and 
\begin_inset Formula $b$
\end_inset

.
 Also, let 
\begin_inset Formula $a_{t}$
\end_inset

 represent a transposed version of 
\begin_inset Formula $a$
\end_inset

 where the axes to be summed over are pushed to the end, and let 
\begin_inset Formula $b_{t}$
\end_inset

 represent a transposed version of 
\begin_inset Formula $b$
\end_inset

 where the axes to be summed over are pushed to the front.
 Then, using 
\begin_inset Formula $\sum_{K}$
\end_inset

 to represent a multi-index sum, the result can be written as 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
r[I,J]=\sum_{K}a_{t}[I,K]b_{t}[K,J]\]

\end_inset


\end_layout

\begin_layout Description
cross
\begin_inset LatexCommand index
name "cross"

\end_inset

 (a, b, axisa=-1, axisb=-1, axisc=-1, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the cross product of two (arrays of) vectors.
 The cross product is performed over the axes of the input arrays indicated
 by the axisa, and axisb arguments.
 For both arrays, the axis used must have dimension either 2 or 3.
 If both axes used have dimension 2, then only the z-component of the equivalent
 3-d cross product is returned.
 Otherwise, the entire vector is returned.
 The axisc argument gives the axis of the vectors in the returned cross-product
 result.
 If axis is not None, then it is assumed that axisa=axisb=axisc=axis (regardless
 of what else is specified).
 
\end_layout

\begin_layout Description
allclose
\begin_inset LatexCommand index
name "allclose"

\end_inset

 (a, b, rtol=
\begin_inset Formula $10^{-5}$
\end_inset

, atol=
\begin_inset Formula $10^{-8}$
\end_inset

) 
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns true if all components of a and b are equal subject to the given
 relative and absolute tolerances.
 This returns true if every element of a and b satisfy 
\begin_inset Formula \[
\left|a-b\right|<\textrm{atol}+\textrm{rtol}\left|b\right|.\]

\end_inset


\end_layout

\begin_layout Section
Printing arrays
\end_layout

\begin_layout Description
array2string
\begin_inset LatexCommand index
name "array2string"

\end_inset

 (a)
\end_layout

\begin_layout Description
\InsetSpace ~
 The default printing mechanism uses this function to produce a string from
 an array.
 
\end_layout

\begin_layout Description
set_printoptions
\begin_inset LatexCommand index
name "set\\_printoptions"

\end_inset

 (precision=None, theshold=None, edgeitems=None, linewidth=None, suppress=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Set options associated with representing an array.
\end_layout

\begin_deeper
\begin_layout Description
precision the default number of digits of precision for floating point output
 (default 8);
\end_layout

\begin_layout Description
threshold total number of array elements which triggers printing only the
 
\begin_inset Quotes eld
\end_inset

ends
\begin_inset Quotes erd
\end_inset

 of the array rather than a full representation (default 1000);
\end_layout

\begin_layout Description
edgeitems number of array elements in summary at beginning and end of each
 dimension (default 3);
\end_layout

\begin_layout Description
linewidth the number of characters per line (default 75);
\end_layout

\begin_layout Description
suppress Boolean value indicating whether or not to suppress printing of
 small floating point values using scientific notation (default False).
\end_layout

\end_deeper
\begin_layout Description
get_printoptions
\begin_inset LatexCommand index
name "get\\_printoptions"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the values of precision, threshold, edgeitems, linewidth, and suppress
 that control printing of arrays.
\end_layout

\begin_layout Description
set_string_function
\begin_inset LatexCommand index
name "set\\_string\\_function"

\end_inset

 (func, repr=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Set the function to use in response to str(array) or repr(array).
 By default this function is array2string.
 The function passed in must take an array argument and return a string.
 If func is None, then the print function is reset to a simple internal
 function.
 
\end_layout

\begin_layout Section
Functions redundant with methods 
\end_layout

\begin_layout Standard
Several functions are available primarily for purposes of backward compatibility
 with old Numeric, and are therefore redundant.
 The functions are all simple wrappers for asarray(a).<function>(*args, **kwds),
 or are replaceable by attribute access.
 The following list documents them.
 It is not recommended that these functions be used in new programs, but
 there are no plans for removing them as in functional form they work with
 arbitrary sequences which is sometimes desirable.
 The functions that mirror methods and attributes are: 
\series bold
take
\series default

\begin_inset LatexCommand index
name "take"

\end_inset

, 
\series bold
reshape
\series default

\begin_inset LatexCommand index
name "reshape"

\end_inset

, 
\series bold
squeeze
\series default

\begin_inset LatexCommand index
name "squeeze"

\end_inset

, 
\series bold
choose
\series default

\begin_inset LatexCommand index
name "choose"

\end_inset

, 
\series bold
repeat
\series default

\begin_inset LatexCommand index
name "repeat"

\end_inset

, 
\series bold
put
\series default

\begin_inset LatexCommand index
name "put"

\end_inset

, 
\series bold
swapaxes
\series default

\begin_inset LatexCommand index
name "swapaxes"

\end_inset

, 
\series bold
transpose
\series default

\begin_inset LatexCommand index
name "transpose"

\end_inset

, 
\series bold
real
\series default

\begin_inset LatexCommand index
name "real"

\end_inset

, 
\series bold
imag
\series default

\begin_inset LatexCommand index
name "imag"

\end_inset

, 
\series bold
sort
\series default

\begin_inset LatexCommand index
name "sort"

\end_inset

, 
\series bold
argsort
\series default

\begin_inset LatexCommand index
name "argsort"

\end_inset

, 
\series bold
amax
\begin_inset LatexCommand index
name "amax"

\end_inset

, argmax
\series default

\begin_inset LatexCommand index
name "argmax"

\end_inset

, 
\series bold
amin
\begin_inset LatexCommand index
name "amin"

\end_inset


\series default
, 
\series bold
argmin
\series default

\begin_inset LatexCommand index
name "argmin"

\end_inset

, 
\series bold
ptp
\series default

\begin_inset LatexCommand index
name "ptp"

\end_inset

, 
\series bold
alen
\series default

\begin_inset LatexCommand index
name "alen"

\end_inset

, 
\series bold
searchsorted
\series default

\begin_inset LatexCommand index
name "searchsorted"

\end_inset

, 
\series bold
diagonal
\series default

\begin_inset LatexCommand index
name "diagonal"

\end_inset

, 
\series bold
trace
\series default

\begin_inset LatexCommand index
name "trace"

\end_inset

, 
\series bold
ravel
\series default

\begin_inset LatexCommand index
name "ravel"

\end_inset

, 
\series bold
nonzero
\series default

\begin_inset LatexCommand index
name "nonzero"

\end_inset

, 
\series bold
shape
\series default

\begin_inset LatexCommand index
name "shape"

\end_inset

, 
\series bold
compress
\series default

\begin_inset LatexCommand index
name "compress"

\end_inset

, 
\series bold
clip
\series default

\begin_inset LatexCommand index
name "clip"

\end_inset

, 
\series bold
std
\series default

\begin_inset LatexCommand index
name "std"

\end_inset

, 
\series bold
var
\series default

\begin_inset LatexCommand index
name "var"

\end_inset

, 
\series bold
mean
\series default

\begin_inset LatexCommand index
name "mean"

\end_inset

, 
\series bold
sum
\series default

\begin_inset LatexCommand index
name "sum"

\end_inset

, 
\series bold
cumsum
\series default

\begin_inset LatexCommand index
name "cumsum"

\end_inset

, 
\series bold
product
\series default

\begin_inset LatexCommand index
name "product"

\end_inset

, 
\series bold
cumproduct
\series default

\begin_inset LatexCommand index
name "cumproduct"

\end_inset

, 
\series bold
sometrue
\begin_inset LatexCommand index
name "sometrue"

\end_inset


\series default
 (method is .any), 
\series bold
alltrue
\begin_inset LatexCommand index
name "alltrue"

\end_inset


\series default
 (method is .all), 
\series bold
around
\begin_inset LatexCommand index
name "around"

\end_inset


\series default
 (method is .round), 
\series bold
rank
\begin_inset LatexCommand index
name "rank"

\end_inset


\series default
 (attribute is .ndim), 
\series bold
shape
\series default

\begin_inset LatexCommand index
name "shape"

\end_inset

, 
\series bold
size
\begin_inset LatexCommand index
name "size"

\end_inset


\series default
 (.size or .shape[axis]), and 
\series bold
copy
\series default

\begin_inset LatexCommand index
name "copy"

\end_inset

.
 
\end_layout

\begin_layout Section
Dealing with data types
\end_layout

\begin_layout Description
dtype (obj, align=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a data-type object from any object.
 See Chapter 
\begin_inset LatexCommand ref
reference "cha:Data-descriptor-objects"

\end_inset

 for a more detailed explanation of what can be interpreted as a data-type
 object and the meaning of the align keyword.
 
\end_layout

\begin_layout Description
maximum_sctype (arg)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the array-scalar type of highest precision of the same general
 kind as arg which can be any recognized form for describing a data-type.
\end_layout

\begin_layout Description
issctype (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns True if obj is an array data type (or a recognized alias for one)
\end_layout

\begin_layout Description
obj2sctype (obj, default=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the array type object corresponding to obj which can be an array
 type already, a python type object, an actual array, or any recognized
 alias for an array type object.
 If no suitable data type object can be determined, return default.
\end_layout

\begin_layout Description
sctype2char (sctype)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the typecode character associated with an array-scalar type dtype.
 The first argument is first converted to a dtype if it needs to be.
 
\end_layout

\begin_layout Tip
the type attribute of data-type objects are actual Python type objects subclasse
d in a hierarchy of types.
 This can often be useful to check data types generically.
 For example, issubclass(dtype.type, integer) can check to see if the data
 type is one of the 10 different integer types.
 The issubclass function, however, raises an error if either argument is
 not an actual type object.
 NumPy defines _(arg1, arg2) that will return false instead of raise an
 error.
 Alternatively, dtype.kind is a character describing the class of the data-type
 so dtype.kind in 'iu' would also check to see if the data-type is an integer
 type.
\end_layout

\begin_layout Description
can_cast (from=d1, to=d2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return Boolean value indicating whether or not data type d1 can be cast
 to data type d2 safely (without losing precision or information).
 
\end_layout

\begin_layout Chapter
Additional Convenience Routines
\end_layout

\begin_layout Quotation
A committee is twelve men doing the work of one.
\end_layout

\begin_layout Right Address
---
\emph on
John F.
 Kennedy 
\end_layout

\begin_layout Quotation
Your mind can only hold one thought at a time.
 Make it a positive and constructive one.
\end_layout

\begin_layout Right Address
---
\emph on
H.
 Jackson Brown Jr.
 
\end_layout

\begin_layout Section
Shape functions
\end_layout

\begin_layout Description
atleast_1d
\begin_inset LatexCommand index
name "atleast\\_1d"

\end_inset

 (a1,a2,...,an)
\end_layout

\begin_layout Description
\InsetSpace ~
 Force a sequence of arrays (including array scalars) to each be at least
 1-d.
 
\end_layout

\begin_layout Description
atleast_2d
\begin_inset LatexCommand index
name "atleast\\_2d"

\end_inset

 (a1,a2,...,an)
\end_layout

\begin_layout Description
\InsetSpace ~
 Force a sequence of arrays (including array scalars) to each be at least
 2-d.
 Dimensions of length 1 are pre-pended to reach a two-dimensional array.
\end_layout

\begin_layout Description
atleast_3d
\begin_inset LatexCommand index
name "atleast\\_3d"

\end_inset

 (a1,a2,...,an)
\end_layout

\begin_layout Description
\InsetSpace ~
 Force a sequence of arrays (including array_scalars) to each be at least
 3-d.
 Dimensions of length 1 are pre-pended to reach a two-dimensional array.
\end_layout

\begin_layout Description
roll
\begin_inset LatexCommand index
name "roll"

\end_inset

 (arr, shift, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new array with the contents of arr shifted (rolled) by the amount
 given in the integer argument shift along the axis specified.
 If axis is None, then the shift takes place in the ravelled array (but
 the returned array has the same shape as arr).
 Elements that shift outside the array are rolled back into the array from
 the opposite side.
 
\end_layout

\begin_layout Description
rollaxis
\begin_inset LatexCommand index
name "rollaxis"

\end_inset

 (arr, axis, start)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return arr transposed so that the provided axis is inserted into the shape
 before start with the other dimensions rolled.
 Thus, if arr.shape is (i,j,k,l) then rollaxis(arr, 2, 0) has shape (k,i,j,l)
 and rollaxis(arr, 1, 3) has shape (i,k,j,l).
\end_layout

\begin_layout Description
vstack
\begin_inset LatexCommand index
name "vstack"

\end_inset

 (seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 Stack a sequence of arrays along the first axis (row wise).
 Arrays in seq must have the same shape along all dimensions but the first.
 Rebuilds array divided by vsplit.
 All 1-d arrays will be stacked row-wise.
\end_layout

\begin_layout Description
hstack
\begin_inset LatexCommand index
name "hstack"

\end_inset

 (seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 Stack a sequence of arrays along the second axis (column wise).
 Arrays in seq must have the same shape along all dimensions but the second.
 Rebuilds array divided by hsplit.
 Notice that 1-d arrays will be appended into a new 1-d array.
 Use column_stack to get a 2-d array from 1-d arrays.
 If some arrays are already 2-d, then the 1-d arrays need to have a dimension
 added to the end (
\emph on
e.g.

\emph default
 
\family typewriter
y[:,newaxis]
\family default
) in order to stack correctly.
 
\end_layout

\begin_layout Description
column_stack
\begin_inset LatexCommand index
name "column\\_stack"

\end_inset

 (seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 Stack a sequence of arrays as columns into a 2-d array.
 1-d arrays are converted to 2-d arrays and transposed.
 All arrays must have shapes so that the resulting array is well defined.
 Compare with 
\series bold
hstack
\series default
.
\end_layout

\begin_layout Description
row_stack
\begin_inset LatexCommand index
name "row\\_stack"

\end_inset

 (seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 Stack a sequence of 1-d arrays as rows into a 2-d array (alias for 
\series bold
vstack
\series default
).
 
\end_layout

\begin_layout Description
dstack
\begin_inset LatexCommand index
name "dstack"

\end_inset

 (seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 Stack a sequence of arrays along the third axis (depth wise).
 Arrays in seq must have the same shape along all dimensions but the third.
 Rebuilds array divided by vsplit.
\end_layout

\begin_layout Description
array_split
\begin_inset LatexCommand index
name "array\\_split"

\end_inset

 (ary, i_or_s, axis=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Divide ary into a list of sub-arrays along the specified axis.
 The i_or_s argument stands for indices_or_sections.
 If i_or_s is an integer, ary is divided into that many equally-sized arrays.
 If it is impossible to make an even split, each of the leading arrays in
 the returned list have one additional member.
 If i_or_s is a list of sorted integer, its entries define the indexes where
 ary is split.
 An empty list for i_or_s results in a single sub-array equal to the original
 array.
\end_layout

\begin_layout Description
split
\begin_inset LatexCommand index
name "split"

\end_inset

 (ary, i_or_s, axis=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 The same as array_split() except if i_or_s is an integer and it is impossible
 to make an even split, an error is raised.
\end_layout

\begin_layout Description
hsplit
\begin_inset LatexCommand index
name "hsplit"

\end_inset

 (ary, i_or_s)
\end_layout

\begin_layout Description
\InsetSpace ~
 Split a single array into multiple columns of sub-arrays (along the first
 axis if 1-d or along the second second if >1-d).
 Only works on arrays of 1 or more dimension.
 
\end_layout

\begin_layout Description
vsplit
\begin_inset LatexCommand index
name "vsplit"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Split a single array into multiple rows of sub-arrays (along the first
 axis).
 Only works on arrays of 2 or more dimensions.
\end_layout

\begin_layout Description
dsplit
\begin_inset LatexCommand index
name "dsplit"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Split a single array into multiple sub-arrays along the third axis (depth).
 Only works on arrays of 3 or more dimensions.
\end_layout

\begin_layout Description
apply_along_axis
\begin_inset LatexCommand index
name "apply\\_along\\_axis"

\end_inset

 (func1d, axis, arr, *args)
\end_layout

\begin_layout Description
\InsetSpace ~
 Execute func1d(arr[sel_i], *args) where func1d takes 1-d arrays and arr
 is an N-d array, where sel_i is a selection object sufficient to select
 a 1-d sub-array along the given axis.
 The function is executed for all 1-d arrays along axis in arr.
 
\end_layout

\begin_layout Description
apply_over_axes
\begin_inset LatexCommand index
name "apply\\_over\\_axes"

\end_inset

 (func, a, axes)
\end_layout

\begin_layout Description
\InsetSpace ~
 For each axis in the axes sequence, call func as 
\family typewriter
res=func(a, axis)
\family default
.
 If res is the same shape as a then set 
\family typewriter
a=res
\family default
 and continue.
 if 
\family typewriter
res.ndim = a.ndim -1
\family default
, then insert a dimension before axis and continue.
 
\end_layout

\begin_layout Description
expand_dims
\begin_inset LatexCommand index
name "expand\\_dims"

\end_inset

 (a, axis)
\end_layout

\begin_layout Description
\InsetSpace ~
 Expand the shape of array a by including newaxis 
\series bold
before
\series default
 the given axis.
\end_layout

\begin_layout Description
resize
\begin_inset LatexCommand index
name "resize"

\end_inset

 (a, new_shape)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns a new array with the specified shape which can be any size.
 The new array is filled with repeated copies of a.
 This function is similar in spirit to a.resize(new_shape) except that it
 fills in the new array with repeated copies and returns a new array.
 
\end_layout

\begin_layout Description
kron
\begin_inset LatexCommand index
name "kron"

\end_inset

 (a, b) 
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a composite array with blocks from 
\emph on
b
\emph default
 scaled by elements of 
\emph on
a
\emph default
.
 The number of dimensions of 
\emph on
a
\emph default
 and 
\emph on
b
\emph default
 should be the same.
 If not, then the input with fewer dimensions is pre-pended with ones (broadcast
) to the same shape as the input with more dimensions.
 The return array has this same number of dimensions with shape given by
 the product of the shape of 
\emph on
a
\emph default
 and the shape of 
\emph on
b
\emph default
.
 If either a or b is a scalar then this function is equivalent to multiply(a,b).
 
\end_layout

\begin_layout Description
\InsetSpace ~
 For example, if 
\emph on
a
\emph default
 and 
\emph on
b
\emph default
 are is 1-d the result is
\begin_inset Formula \[
\left[\begin{array}{cccc}
a[0]*b & a[1]*b & \cdots & a[-1]*b\end{array}\right]\]

\end_inset

 while if 
\emph on
a
\emph default
 and 
\emph on
b
\emph default
 are 2-d, the result is 
\begin_inset Formula \[
\left[\begin{array}{cccc}
a[0,0]*b & a[0,1]*b & \cdots & a[0,-1]*b\\
a[1,0]*b & a[1,1]*b & \cdots & a[1,-1]*b\\
\vdots & \vdots & \ddots & \vdots\\
a[-1,0]*b & a[-1,1]*b & \cdots & a[-1,-1]*b\end{array}\right]\]

\end_inset


\end_layout

\begin_deeper
\begin_layout Description
Example: 
\end_layout

\end_deeper
\begin_layout MyCode
>>> kron([1,10,100],[5,6,7])
\newline
array([  5,   6,   7,  50,  60,  70, 500, 600,
 700])
\newline
>>> kron([[1,10],[100,1000]],[[2,3],[4,5]])
\newline
array([[   2,    3,   20,
   30],
\newline
       [   4,    5,   40,   50],
\newline
       [ 200,  300, 2000, 3000],
\newline

       [ 400,  500, 4000, 5000]])
\end_layout

\begin_layout Description
tile
\begin_inset LatexCommand index
name "tile"

\end_inset

 (a, reps)
\end_layout

\begin_layout Description
\InsetSpace ~
 Tile an 
\begin_inset Formula $N$
\end_inset

-dimensional array using the shape information in reps to create a larger
 
\begin_inset Formula $N$
\end_inset

-dimensional array.
 This is equivalent to kron(ones(reps, a.dtype), a).
 The number of dimensions of a and the length of shape should be the same
 or else 1's will be pre-pended to make them the same.
 
\end_layout

\begin_deeper
\begin_layout Description
Example: 
\end_layout

\end_deeper
\begin_layout MyCode
>>> tile([5,6,7],(1,2,3))
\newline
array([[[5, 6, 7, 5, 6, 7, 5, 6, 7],
\newline
        [5,
 6, 7, 5, 6, 7, 5, 6, 7]]])
\end_layout

\begin_layout Section
Basic functions
\end_layout

\begin_layout Description
average
\begin_inset LatexCommand index
name "average"

\end_inset

 (a, axis=None, weights=None, returned=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Computes the average along the indicated axis.
 If axis is None, average over the entire array.
 Inputs can be integer or floating types; result is type float.
 If weights are given, the result is sum(a*weights)/sum(weights).
 Therefore, weights must have shape equal to a.shape or be 1-d with length
 a.shape[axis].
 Integer weights are converted to float.
 If returned is True, then return a tuple showing both the result and the
 sum of the weights (or count of the values).
 The shape of these two results will be the same.
 
\end_layout

\begin_layout Description
cov
\begin_inset LatexCommand index
name "cov"

\end_inset

 (x, y=None, rowvar=1, bias=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the covariance matrix of data in x.
 If x is a vector and y is None, then this function is equivalent to asarray(x).v
ar().
 Otherwise, x is interpreted as observations of several random variables.
 If rowvar is True (default), then the variables are in the rows and the
 observations of the variables are in the columns.
 Otherwise, the variables are in the columns and the observations are in
 the rows.
 If y is given then it is treated as another variable or set of variables
 to be added to x.
 By default, a so-called unbiased estimate of the covariance matrix is made.
 If bias is non-zero, then a biased normalization factor (with better mean-squar
e error performance) is used instead.
 If 
\begin_inset Formula $\mathbf{X}$
\end_inset

 is a random vector, then the covariance matrix is defined as 
\begin_inset Formula \[
\mathbf{C}=E\left[\left(\mathbf{X}-E\mathbf{X}\right)\left(\mathbf{X}-E\mathbf{X}\right)^{H}\right].\]

\end_inset

 It can be approximated as 
\begin_inset Formula \[
\mathbf{C}\approx\frac{1}{P}\sum_{i=0}^{N-1}\left(\mathbf{x}_{i}-\bar{\mathbf{x}}\right)\left(\mathbf{x}_{i}-\bar{\mathbf{x}}\right)^{H}\]

\end_inset

 where 
\begin_inset Formula $\mathbf{x}_{i}$
\end_inset

 is an observation of 
\begin_inset Formula $\mathbf{X}$
\end_inset

 (as a column-vector), 
\begin_inset Formula $N$
\end_inset

 is the number of observations made and 
\begin_inset Formula $P=N-1$
\end_inset

 for an unbiased estimate or 
\begin_inset Formula $P=N$
\end_inset

 for a biased (but lower mean-squared error) estimate.
 
\end_layout

\begin_layout Description
corrcoef
\begin_inset LatexCommand index
name "corrcoef"

\end_inset

 (x, y=None, rowvar=1, bias=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Estimate the correlation coefficient of x.
 By default, each row of x contains a random variable with observations
 of the random variable in the columns of x.
 (If rowvar is False, the each column is a random variable with observations
 in the rows).
 The y argument can be used to append additional variables to x.
 The 
\begin_inset Formula $i^{\textrm{th}}$
\end_inset

 row and 
\begin_inset Formula $j^{\textrm{th}}$
\end_inset

 column of the correlation coefficient matrix is defined as 
\begin_inset Formula \[
\rho_{ij}=\frac{C_{ij}}{\sqrt{C_{ii}C_{jj}}}\]

\end_inset

 where 
\begin_inset Formula $\mathbf{C}$
\end_inset

 is the covariance matrix.
 The rowvar and bias arguments are passed on to the cov function to estimate
 
\begin_inset Formula $\mathbf{C}.$
\end_inset


\end_layout

\begin_layout Description
msort
\begin_inset LatexCommand index
name "msort"

\end_inset

 (a)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new array, sorted along the first axis.
 Equivalent to b=a.copy(); b.sort(0)
\end_layout

\begin_layout Description
median
\begin_inset LatexCommand index
name "median"

\end_inset

 (m)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the median of m along its first dimension.
\end_layout

\begin_layout Description
bincount
\begin_inset LatexCommand index
name "bincount"

\end_inset

 (list=, weights=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 The list argument is a 1-d integer array.
 Let 
\begin_inset Formula $r$
\end_inset

 be the returned 1-d array whose length is (list.max()+1).
 If weights is None, then 
\begin_inset Formula $r[i]$
\end_inset

 is the number of occurrences of 
\begin_inset Formula $i$
\end_inset

 in list.
 If weight is present, then the 
\begin_inset Formula $i^{\textrm{th}}$
\end_inset

 element is 
\begin_inset Formula \[
r[i]=\sum_{j:\textrm{list}\left[j\right]=i}\textrm{weights}[j].\]

\end_inset

 Notice that if weights is None, it is equivalent to a weights array of
 all 1.
 The length of weights must be the same as the length of list.
 
\end_layout

\begin_layout Description
digitize
\begin_inset LatexCommand index
name "digitize"

\end_inset

 (x=,bins=)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array of integers the same length as x with values 
\begin_inset Formula $i$
\end_inset

 such that 
\begin_inset Formula $\textrm{bins}\left[i-1\right]\leq x<\textrm{bins}\left[i\right]$
\end_inset

 if bins is monotonically increasing, or 
\begin_inset Formula $\textrm{bins}[i]\leq x<\textrm{bins}[i-1]$
\end_inset

 if bins is monotonically decreasing.
 When 
\begin_inset Formula $x$
\end_inset

 is beyond the bounds of bins, return either 
\begin_inset Formula $i=0$
\end_inset

 or 
\begin_inset Formula $i=$
\end_inset

len(bins) as appropriate.
\end_layout

\begin_layout Description
histogram
\begin_inset LatexCommand index
name "histogram"

\end_inset

 (x=, bins=None, range=None, normed=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a histogram for the data in x (treated as one-dimensional array
 of type float).
 If bins is not a sequence, then bins should be the number of bins which
 will be constructed ranging from range[0] to range[1] or x.min() to x.max()
 if range is None.
 If normed is True, then the histogram will be normalized and comparable
 with a probability density function, otherwise it will be a count of the
 number of items in each bin.
 The return value is the tuple (n, bins) where n is the histogram.
\end_layout

\begin_layout Description
histogram2d
\begin_inset LatexCommand index
name "histogram2d"

\end_inset

 (x, y, bins=10, range=None, normed=False)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the two-dimensional histogram for a dataset (x,y) given the bins.
 Returns (histogram, xedges, yedges).
 The bins argument can be either the number of bins or a sequence of the
 bin edges if the x and y directions should have the same bins.
 If the bins argument is a sequence of length 2, then separate bin edges
 will be computed.
 The first element can be either the number of bins or the bin edges for
 the x-direction.
 The second element is interpreted as the number of bins or the bin edges
 for the y-direction.
 The returned histogram array, H, is a count of the number of samples in
 each bin.
 The array is oriented such that H[i,j] is the number of samples falling
 into binx[j] and biny[i] (notice the association x<->j and y<->i).
 Setting normed to True returns a density rather than a bin-count.
 The range argument allows specifying lower and upper bin edges (in a sequence
 of length 2 with 2-length sequences in each entry).
 The default is [[x.min(), x.max()],[y.min(), y.max()]].
 
\end_layout

\begin_layout Description
histogramdd
\begin_inset LatexCommand index
name "histogramdd"

\end_inset

 (sample, bins=10, range=None, normed=False)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the 
\begin_inset Formula $D$
\end_inset

-dimensional histogram for a (vector) dataset contained in sample give the
 bins.
 The dataset is a sequence of 
\begin_inset Formula $D$
\end_inset

 arrays or an 
\begin_inset Formula $N\times D$
\end_inset

 array where 
\begin_inset Formula $N$
\end_inset

 is the number of samples and 
\begin_inset Formula $D$
\end_inset

 is the number of dimensions.
 Returns (histogram, edges) where histogram is a 
\begin_inset Formula $D$
\end_inset

-dimensional array of shape given by the number of bins selected in each
 axis containing the number of counts that a point in the sample data fell
 into the volume bin specified.
 The edges sequence has 
\begin_inset Formula $D$
\end_inset

-entries to specify the edge boundaries for each dimension.
 The bins argument is a sequence of edge arrays or a sequence of the number
 of bins.
 If a scalar is given, it is assumed to be the number of bins for all dimensions.
 The range is a length-
\begin_inset Formula $D$
\end_inset

 sequence containing lower and upper bin edges which default to the min
 and maximum of the respective datasets.
 If normed is True, then a density rather than a bin-count is returned.
 
\end_layout

\begin_layout Description
logspace
\begin_inset LatexCommand index
name "logspace"

\end_inset

 (start, stop, num=50, endpoint=True,base=10.0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Evenly spaced samples on a logarithmic scale.
 Returns num evenly spaced (in logspace) samples from base**start to base**stop.
 If endpoint is True, then the last sample is base**stop.
\end_layout

\begin_layout Description
linspace
\begin_inset LatexCommand index
name "linspace"

\end_inset

 (start, stop, num=50, endpoint=True, retstep=False):
\end_layout

\begin_layout Description
\InsetSpace ~
 Evenly spaced samples.
 Returns num evenly spaced samples from start to stop.
 If endpoint is True, then the last sample is stop.
 If retstep is True, then return the computed step size.
\end_layout

\begin_layout Description
meshgrid
\begin_inset LatexCommand index
name "meshgrid"

\end_inset

 (x, y)
\end_layout

\begin_layout Description
\InsetSpace ~
 For 1-d arrays x, y with lengths Nx=len(x) and Ny = len(y), return X, Y
 where X and Y are (Ny, Nx) shaped arrays with the elements of x and y repeated
 to fill the array.
 
\end_layout

\begin_layout MyCode
>>> X,Y = meshgrid([1,2,3], [4,5,6,7]); print X; print Y
\newline
[[1 2 3]
\newline
 [1 2 3]
\newline

 [1 2 3]
\newline
 [1 2 3]]
\newline
[[4 4 4]
\newline
 [5 5 5]
\newline
 [6 6 6]
\newline
 [7 7 7]]
\end_layout

\begin_layout Description
select
\begin_inset LatexCommand index
name "select"

\end_inset

 (condlist, choicelist, default=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns an array comprised from different elements of choicelist depending
 on the list of conditions.
 The condlist argument is a list of Boolean condition arrays.
 The choicelist argument is a list of choice arrays (of the same size as
 the arrays in condlist).
 The result has the same size as the arrays in choicelist.
 If condlist is [
\begin_inset Formula $c_{0},\ldots,c_{N-1}$
\end_inset

], then choicelist must be of length 
\begin_inset Formula $N$
\end_inset

.
 The elements of choicelist can then be represented as [
\begin_inset Formula $v_{0},\ldots,v_{N-1}$
\end_inset

].
 The default choice if none of the conditions are met is given as the default
 argument.
 The conditions are tested in order and the first one satisfied is used
 to select the choice.
 In other words, the elements of the output array are found from the following
 tree (evaluated on an element-by-element basis)
\end_layout

\begin_layout LyX-Code

\series bold
if
\series default
 
\begin_inset Formula $c_{0}$
\end_inset

: 
\begin_inset Formula $v_{0}$
\end_inset


\newline

\series bold
elif
\series default
 
\begin_inset Formula $c_{1}$
\end_inset

: 
\begin_inset Formula $v_{1}$
\end_inset


\newline
...
\newline

\series bold
elif
\series default
 
\begin_inset Formula $c_{N-1}$
\end_inset

: 
\begin_inset Formula $v_{N-1}$
\end_inset


\newline

\series bold
else
\series default
: default
\end_layout

\begin_layout Description
piecewise
\begin_inset LatexCommand index
name "piecewise"

\end_inset

 (x, condlist, funclist, *args, **kw)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute a piecewise-defined function.
 A piecewise defined function is 
\begin_inset Formula \[
f\left(x\right)=\left\{ \begin{array}{cc}
f_{1}\left(x\right) & x\in S_{1},\\
f_{2}\left(x\right) & x\in S_{2},\\
\vdots & \vdots\\
f_{n}\left(x\right) & x\in S_{n}.\end{array}\right.\]

\end_inset

where 
\begin_inset Formula $S_{1}$
\end_inset

 are sets.
 Thus, the function is defined differently over different sub-domains of
 the input.
 Such a function can be computed using 
\family typewriter
select
\family default
 but such an implementation means calling each 
\begin_inset Formula $f_{i}$
\end_inset

 over the entire region of 
\begin_inset Formula $x.$
\end_inset

 The piecewise call guarantees that each function 
\begin_inset Formula $f_{i}$
\end_inset

 will only be called over those values of 
\begin_inset Formula $x$
\end_inset

 in 
\begin_inset Formula $S_{i}.$
\end_inset

 
\end_layout

\begin_layout Description
\InsetSpace ~
 Arguments: x is the array of values over which to call the function; condlist
 is a sequence of Boolean (indicator) arrays (or a single Boolean array)
 of the same shape as 
\begin_inset Formula $x$
\end_inset

 that defines the sets (True indicates that element of 
\begin_inset Formula $x$
\end_inset

 is in the set).
 If needed, to match the length of funclist, an 
\begin_inset Quotes eld
\end_inset

otherwise
\begin_inset Quotes erd
\end_inset

 set will be added to condlist.
 This otherwise set is defined as 
\begin_inset Formula $S_{n}=\overline{\bigcup S_{i}}.$
\end_inset

 The argument funclist is a list of functions to be called (or items to
 be inserted) corresponding to the conditions.
 Each of these functions can take extra arguments and key-word arguments
 which are passed in as *args, and **kw using standard Python syntax.
 Each of these functions should return vector output for vector input.
 If the function is a scalar, then it will simply be inserted where appropriate
 into the output.
 It is the equivalent of a constant function.
 
\end_layout

\begin_deeper
\begin_layout Description
Example: Suppose we want to compute 
\begin_inset Formula $f\left(x\right)=x^{2}\Pi\left(\frac{x}{3}\right)+u\left(x-5\right)$
\end_inset

 where 
\begin_inset Formula $\Pi\left(x\right)=1$
\end_inset

 only when 
\begin_inset Formula $\left|x\right|\leq1$
\end_inset

 and 
\begin_inset Formula $u\left(x\right)=1$
\end_inset

 only when 
\begin_inset Formula $x\geq0.$
\end_inset

 This could be done using the code:
\end_layout

\end_deeper
\begin_layout MyCode
>>> f1 = lambda x: x*x
\newline
>>> x = r_[-4:6:20j]
\newline
>>> y = piecewise(x,abs(x)<=3,[f1,0])+
piecewise(x,x>=0,[1,0])
\newline
>>> set_printoptions(precision=4); print y
\newline
[ 0.
      0.
      8.687   5.8615  3.59    1.8726  0.7091  0.0997
\newline
  1.0443  1.5429  2.5956  4.2022
  6.3629  9.0776  1.
      1.
      1.
\newline
  1.
      1.
      1.
    ]
\end_layout

\begin_layout Description
trim_zeros
\begin_inset LatexCommand index
name "trim\\_zeros"

\end_inset

 (filt, trim='fb'):
\end_layout

\begin_layout Description
\InsetSpace ~
 Trim the leading ('f' in trim) and trailing ('b' in trim) zeros from a
 sequence according to the trim keyword.
 
\end_layout

\begin_layout Description
trapz
\begin_inset LatexCommand index
name "trapz"

\end_inset

 (y, x=None, dx=1.0, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 If 
\begin_inset Formula $\mathbf{y}$
\end_inset

 contains samples of a function: 
\begin_inset Formula $y_{i}=f\left(x_{i}\right)$
\end_inset

 then trapz can be used to approximate the integral of the function using
 the trapezoidal rule.
 If the sampling is not evenly spaced use 
\begin_inset Formula $\mathbf{x}$
\end_inset

 to pass in the sample positions.
 Otherwise, only the sample-spacing is needed in dx.
 The trapz function can work with many functions at a time stored in an
 
\begin_inset Formula $N$
\end_inset

-dimensional array.
 The axis argument controls which axis defines the sampling axis (the other
 dimensions are different functions).
 The number of dimensions of the returned result is 
\begin_inset Formula $y$
\end_inset

.ndim - 1.
\end_layout

\begin_layout Description
diff
\begin_inset LatexCommand index
name "diff"

\end_inset

 (x, n=1, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Calculates the 
\begin_inset Formula $n^{\textrm{th}}$
\end_inset

 order, discrete difference along the given axis.
\end_layout

\begin_layout Description
gradient
\begin_inset LatexCommand index
name "gradient"

\end_inset

 (f, *varargs)
\end_layout

\begin_layout Description
\InsetSpace ~
 Calculate the gradient of an N-d scalar function, f.
 Uses central differences on the interior and first differences on boundaries
 to give the same shape for each component of the gradient.
 The varargs variable can contain 0, 1, or N scalars corresponding to the
 sample distances in each direction (default 1.0).
 If f is N-d, then N arrays are returned each of the same shape as f, giving
 the derivative of f with respect to each dimension.
 
\end_layout

\begin_layout Description
angle
\begin_inset LatexCommand index
name "angle"

\end_inset

 (z, deg=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the angle of a complex number z (in degrees if deg is True).
\end_layout

\begin_layout Description
unwrap
\begin_inset LatexCommand index
name "unwrap"

\end_inset

 (p, discont=pi, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Unwraps radian phase p by changing absolute jumps greater than discont
 to their 
\begin_inset Formula $2\pi$
\end_inset

 complement along the given axis.
 
\end_layout

\begin_layout Description
sort_complex
\begin_inset LatexCommand index
name "sort\\_complex"

\end_inset

 (x)
\end_layout

\begin_layout Description
\InsetSpace ~
 This is syntactic sugar for asarray(x).sort().astype(<cmplx_type>) where
 cmplx_type is csingle if x.dtype is integral with fewer bits than intp,
 clongfloat if x.dtype.type is longfloat, and cdouble for all other types.
 The sorting is done by comparing the real part of the array, and then the
 imaginary part if the real parts are the same.
 
\end_layout

\begin_layout Description
disp
\begin_inset LatexCommand index
name "disp"

\end_inset

 (mesg, device=None, linefeed=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Display a message to device (defaults to sys.stdout) with or without a closing
 linefeed.
\end_layout

\begin_layout Description
unique
\begin_inset LatexCommand index
name "unique"

\end_inset

 (seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns unique items in the 1-dimensional seq.
\end_layout

\begin_layout Description
extract
\begin_inset LatexCommand index
name "extract"

\end_inset

 (condition, arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Equivalent to arr.compress(condition.flat) and arr.flat[bool_(condition.flat)]
 which extracts the elements of (flattened) arr according to the elements
 of (flattened) condition that are True.
 
\end_layout

\begin_layout Description
place
\begin_inset LatexCommand index
name "place"

\end_inset

 (arr, mask, vals)
\end_layout

\begin_layout Description
\InsetSpace ~
 Inverse of extract.
 Equivalent to arr[abool(mask)] = vals but it uses a different algorithm.
 
\end_layout

\begin_layout Description
delete
\begin_inset LatexCommand index
name "delete"

\end_inset

 (arr, indices, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new array with the sub-arrays indicated by indices along axis
 removed.
 If axis is None, then first ravel the array and set axis to -1.
 The indices argument describes which sub-arrays along the given axis should
 be removed.
 It can be an integer, a slice object, or a sequence of integers.
 A new array is created with the corresponding sub-arrays are removed.
 
\end_layout

\begin_layout Description
insert
\begin_inset LatexCommand index
name "insert"

\end_inset

 (arr, indices, values, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Create a new array with values inserted into arr before indices.
 If axis is None, then first ravel the array and set axis to -1.
 The indices argument describes which indices along the provided axis the
 values should be inserted before.
 It can be an integer, a slice object, or a sequence of integers.
 The values argument must be broadcastable to the shape implied by where
 they will be inserted.
 
\end_layout

\begin_layout Description
append
\begin_inset LatexCommand index
name "append"

\end_inset

 (arr, values, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a new array with values appended to the end of the array along axis.
 
\end_layout

\begin_layout Description
nansum
\begin_inset LatexCommand index
name "nansum"

\end_inset

 (x, axis=None)
\end_layout

\begin_layout Description
nanmax
\begin_inset LatexCommand index
name "nanmax"

\end_inset

 (x, axis=None)
\end_layout

\begin_layout Description
nanargmax
\begin_inset LatexCommand index
name "nanargmax"

\end_inset

 (x, axis=None)
\end_layout

\begin_layout Description
nanargmin
\begin_inset LatexCommand index
name "nanargmin"

\end_inset

 (x, axis=None)
\end_layout

\begin_layout Description
nanmin
\begin_inset LatexCommand index
name "nanmin"

\end_inset

 (x, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 These functions perform their respective operations over the given axis
 (or the entire array if axis is None), after replacing any nans with appropriat
e values so as not to affect the calculation.
 
\end_layout

\begin_layout Description
vectorize
\begin_inset LatexCommand index
name "vectorize"

\end_inset

 (pyfunc, otypes=None, doc=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This creates a class whose instances have a call method that invokes a
 ufunc that has been dynamically built to call the python function pyfunc
 internally.
 The output types can be controlled by the otypes argument.
 If it is None, then the output types will be determined upon first call
 to the function using the provided inputs.
 This can be reset, by re-setting the otypes attribute to 
\begin_inset Quotes eld
\end_inset


\begin_inset Quotes erd
\end_inset

.
 The normal rules of array broadcasting are followed by the returned object.
\end_layout

\begin_layout MyCode
>>> def myfunc(a,b):
\newline
...
     if (a>b): return a
\newline
...
     else: return b-1
\newline
>>> vecfunc = vectorize(myfunc)
\newline
>>> vecfunc([[1,2,3],[5,6,9]
],[7,4,5])
\newline
array([[6, 3, 4],
\newline
       [6, 6, 9]])
\end_layout

\begin_layout Description
asarray_chkfinite
\begin_inset LatexCommand index
name "asarray\\_chkfinite"

\end_inset

 (x)
\end_layout

\begin_layout Description
\InsetSpace ~
 Like asarray(x) except an error is raised if any of the values in x are
 not finite.
 
\end_layout

\begin_layout Description
round_
\begin_inset LatexCommand index
name "round\\_"

\end_inset

 (x, decimals=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array with all the elements of x rounded to decimals places.
 Returns x if array is not floating point and rounds both the real and imaginary
 parts separately if array is complex.
 Rounds in the same way as standard python except for half-way values are
 rounded to the nearest 
\emph on
even
\emph default
 number.
\end_layout

\begin_layout Description
packbits (array, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Pack an integer array of logical data (zero/non-zero) into bits of a uint8
 data-type along the dimension given by axis.
 This dimension is shrunk by a factor of 8 (rounded up).
 Each element in the input is converted to a bit in the output which is
 set to 1 or 0 depending on whether the input is non-zero or not.
 Thus, every 8-element chunk of the input is converted to a single byte
 in the output.
 If axis is None, then the bit-packing is done on the entire array as if
 it were raveled.
\end_layout

\begin_layout Description
unpackbits (array, axis=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Unpack bits of an array of uint8 data-type into a single uint8 byte for
 each bit along the dimension given by axis.
 This dimension is thus expanded 8-fold, but otherwise the output has the
 same shape as the input.
 If axis is None, then the input is treated as a 1-d array and expanded
 8-fold so that each bit of the input is given an output byte.
 
\end_layout

\begin_layout Description
add_docstring
\begin_inset LatexCommand index
name "add\\_docstring"

\end_inset

 (obj, doc)
\end_layout

\begin_layout Description
\InsetSpace ~
 Adds a docstring to a built-in object, obj, that does not have a docstring
 defined already.
 The obj can be a built-in function-or-method, a typeobject, a method descriptor
, a getset descriptor, or a member descriptor.
 This is useful for improving the documentation of objects defined in C-compiled
 code without re-compiling.
 If the object already has a docstring, a RuntimeError is raised.
 If the object is not a supported type the code can add a docstring to,
 a TypeError is raised.
 
\end_layout

\begin_layout Description
add_newdoc
\begin_inset LatexCommand index
name "add\\_newdoc"

\end_inset

 (place, obj, doc)
\end_layout

\begin_layout Description
\InsetSpace ~
 Adds a docstring to the 
\emph on
obj
\emph default
 imported from 
\emph on
place
\emph default
 using exec 'from %s import %s' % (place, obj).
 Thus, both place and obj should be strings.
 If doc is a string, then a single docstring is added to obj from place.
 If doc is a 2-tuple, then obj must be an object with attributes that need
 to be commented.
 The first element of the doc tuple is the attribute to be commented on
 and the second element is the actual docstring.
 If doc is a list, then it must be composed of elements that are 2-tuples
 indicating that obj has several attributes that need to be documented.
 
\end_layout

\begin_layout Section
Polynomial functions
\end_layout

\begin_layout Standard
There are two interfaces for dealing with polynomials
\begin_inset LatexCommand index
name "polynomials"

\end_inset

: a class-based interface, and a collection of functions to deal with a
 polynomials represented as a simple list of coefficients.
 This latter representation results from the is a one-to-one correspondence
 between a length-
\begin_inset Formula $\left(n+1\right)$
\end_inset

 sequence of coefficients 
\begin_inset Formula $a_{n}\equiv a[n]$
\end_inset

 and an 
\begin_inset Formula $n^{\textrm{th}}$
\end_inset

 order polynomial: 
\begin_inset Formula \[
p\left(x\right)=a_{0}x^{n}+a_{1}x^{n-1}+\cdots+a_{n-1}x+a_{n}.\]

\end_inset

 Most of the functions below operate on and return a simple sequence of
 coefficients representing a polynomial.
 There is, however, a simple polynomial class that provides some utility
 for doing simple algebra on polynomials.
 
\end_layout

\begin_layout Description
poly1d
\begin_inset LatexCommand index
name "poly1d"

\end_inset

 (c_or_r, r=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 This construction returns an instance of a simple polynomial class.
 It can take either a list of coefficients on polynomial powers, or a sequence
 of roots (if r=1).
 The returned polynomial can be added, subtracted, multiplied, divided,
 and taken to integer powers, resulting in new polynomials.
 
\end_layout

\begin_deeper
\begin_layout Description
.r roots of the polynomial
\end_layout

\begin_layout Description
.o order of the polynomial
\end_layout

\begin_layout Description
.c polynomial coefficients as an array (also 
\series bold
__array__()
\series default
 )
\end_layout

\begin_layout Description
__call__(x) evaluate the polynomial at x (can be an array)
\end_layout

\begin_layout Description
__getitem__(x) p[k] returns the coefficient on the kth power of x (backwards
 from indexing the coefficient array)
\end_layout

\end_deeper
\begin_layout MyCode
>>> p=poly1d([2,5,7])
\newline
>>> print p
\newline
2
\newline
2 x + 5 x + 7
\newline
>>> print p*[1,3,1]
\newline
4     
 3      2
\newline
2 x + 11 x + 24 x + 26 x + 7
\newline
>>> print p([0.5,0.6,3])
\newline
[ 10.
    10.72  40.
  ]
\newline
>>> print p.r
\newline
[-1.25+1.3919j -1.25-1.3919j]
\end_layout

\begin_layout Description
poly
\begin_inset LatexCommand index
name "poly"

\end_inset

 (roots_or_matrix)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a sequence of coefficients representing a polynomial given the sequence
 of roots as an argument.
 Alternatively, if the argument is a 2-d array, then return the characteristic
 polynomial of the matrix.
 
\end_layout

\begin_layout Description
roots
\begin_inset LatexCommand index
name "roots"

\end_inset

 (poly)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the roots of the polynomial represented by coefficients in poly
\end_layout

\begin_layout Description
polyint
\begin_inset LatexCommand index
name "polyint"

\end_inset

 (poly, m=1, k=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an exact 
\begin_inset Formula $m^{\textrm{th}}$
\end_inset

-order integral of the polynomial represented in poly.
 If k is None, then use 0 for the integrating constants.
 Otherwise, use the scalars in the sequence k as integrating constants.
 Also available as .integ (m=1,k=0) method of poly1d objects.
\end_layout

\begin_deeper
\begin_layout Description
Example: 
\begin_inset Formula \begin{eqnarray*}
p\left(x\right) & = & x^{2}+3x+4\\
\int\int p\left(x\right) & = & \frac{1}{12}x^{4}+\frac{1}{2}x^{3}+2x^{2}+k_{0}x+k_{1}\end{eqnarray*}

\end_inset

 
\end_layout

\end_deeper
\begin_layout MyCode
>>> print polyint([1,3,4],m=2,k=[5,3])
\newline
[ 0.0833  0.5     2.
      5.
      3.
    ]
\end_layout

\begin_layout Description
polyder
\begin_inset LatexCommand index
name "polyder"

\end_inset

 (poly, m)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an exact 
\begin_inset Formula $m^{\textrm{th}}$
\end_inset

-order derivative of the polynomial represented in poly.
 Also available as .deriv(m=1) method of poly1d objects.
\end_layout

\begin_deeper
\begin_layout Description
Example: 
\begin_inset Formula \begin{eqnarray*}
p\left(x\right) & = & x^{3}+2x^{2}+4x+3\\
\frac{dp}{dx}\left(x\right) & = & 3x^{2}+4x+4\end{eqnarray*}

\end_inset


\end_layout

\end_deeper
\begin_layout MyCode
>>> polyder([1,2,4,3])
\newline
array([3, 4, 4])
\end_layout

\begin_layout Description
polyadd
\begin_inset LatexCommand index
name "polyadd"

\end_inset

 (p1, p2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add the two polynomials represented by coefficients: 
\begin_inset Formula $p_{1}\left(x\right)+p_{2}\left(x\right)$
\end_inset


\end_layout

\begin_layout Description
polysub
\begin_inset LatexCommand index
name "polysub"

\end_inset

 (p1, p2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return coefficients for the polynomial found by subtracting the two polynomials
 represented by 
\begin_inset Formula $p_{1}$
\end_inset

 and 
\begin_inset Formula $p_{2}$
\end_inset

: 
\begin_inset Formula $p_{1}\left(x\right)-p_{2}\left(x\right)$
\end_inset


\end_layout

\begin_layout Description
polymul
\begin_inset LatexCommand index
name "polymul"

\end_inset

 (p1, p2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the coefficients for 
\begin_inset Formula $p_{1}\left(x\right)p_{2}\left(x\right)$
\end_inset


\end_layout

\begin_layout Description
polydiv
\begin_inset LatexCommand index
name "polydiv"

\end_inset

 (p1, p2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the quotient, 
\begin_inset Formula $q\left(x\right)$
\end_inset

, and remainder, 
\begin_inset Formula $r\left(x\right)$
\end_inset

, so that 
\begin_inset Formula $p_{1}\left(x\right)=q\left(x\right)p_{2}\left(x\right)+r\left(x\right),$
\end_inset

 with the order of 
\begin_inset Formula $r\left(x\right)$
\end_inset

 less than the order of 
\begin_inset Formula $p_{2}\left(x\right).$
\end_inset


\end_layout

\begin_layout Description
polyval
\begin_inset LatexCommand index
name "polyval"

\end_inset

 (p, y)
\end_layout

\begin_layout Description
\InsetSpace ~
 Evaluate the polynomial 
\begin_inset Formula $p$
\end_inset

 at 
\begin_inset Formula $y$
\end_inset

.
 The argument, 
\begin_inset Formula $y$
\end_inset

, can be a number or an array or a polynomial object.
 If x is a polynomial object, then polyval performs polynomial composition:
 
\begin_inset Formula $p\left(y\left(x\right)\right),$
\end_inset

 otherwise polyval computes the value of the polynomial at each 
\begin_inset Formula $y$
\end_inset

.
 Uses Horner's rule for evaluation, but this can still lead to numerical
 instabilities for wildly fluctuating coefficients.
\end_layout

\begin_layout Description
polyfit
\begin_inset LatexCommand index
name "polyfit"

\end_inset

 (x,y,N)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute a best-fit polynomial in 
\begin_inset Formula $x$
\end_inset

 of order 
\begin_inset Formula $N$
\end_inset

, to the data, 
\begin_inset Formula $y$
\end_inset

, in the sense of minimizing averaged-squared error between the measurement
 and the model.
 Useful for quick line-fitting
\begin_inset LatexCommand index
name "fitting"

\end_inset

.
 
\end_layout

\begin_layout Section
Set Operations
\end_layout

\begin_layout Standard
The set operations
\begin_inset LatexCommand index
name "set operations|("

\end_inset

 were kindly contributed by Robert Cimrman.
 These set operations are based on sorting functions and all expect 1-d
 sequences with unique elements with the exception of unique1d and intersect1d_n
u which will flatten N-d nested-sequences to 1-d arrays and can handle non-uniqu
e elements.
 
\end_layout

\begin_layout Description
unique1d
\begin_inset LatexCommand index
name "unique1d"

\end_inset

 (arr, retindx=False)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the unique elements of arr as a 1-d array.
 If retindx is True, then also return the indices, ind, such that arr.flat[ind]
 is the set of unique values.
\end_layout

\begin_layout Description
intersect1d
\begin_inset LatexCommand index
name "intersect1d"

\end_inset

 (a1, a2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (sorted) intersection of a1 and a2 which is an array containing
 the elements of a1 that are also in a2.
 
\end_layout

\begin_layout Description
intersect1d_nu
\begin_inset LatexCommand index
name "intersect1d\\_nu"

\end_inset

 (a1, a2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (sorted) intersection of a1 and a2 but allow a1 and a2 to be
 N-d arrays with non-unique elements.
 Equivalent to intersect1d(unique1d(a1), unique1d(a2)).
 
\end_layout

\begin_layout Description
union1d
\begin_inset LatexCommand index
name "union1d"

\end_inset

 (a1, a2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (sorted) union of a1 and a2 which is an array containing elements
 that are in either a1 or a2.
 
\end_layout

\begin_layout Description
setdiff1d
\begin_inset LatexCommand index
name "setdiff1d"

\end_inset

 (a1, a2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the set-difference of a1 and a2 which is an array containing the
 elements of a1 that are 
\series bold
not
\series default
 in a2.
\end_layout

\begin_layout Description
setxor1d
\begin_inset LatexCommand index
name "setxor1d"

\end_inset

 (a1, a2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (sorted) set containing the exclusive-or of the arrays a1 and
 a2.
 The exclusive-or contains elements that are in a1 or in a2 as long as the
 element is not in both a1 and a2.
 
\end_layout

\begin_layout Description
setmember1d
\begin_inset LatexCommand index
name "setmember1d"

\end_inset

 (tocheck, set)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a Boolean 1-d array of the length of tocheck which is True whenever
 that element is contained in set and false when it is not.
 Equivalent
\begin_inset LatexCommand index
name "set operations|)"

\end_inset

 to array([x in set for x in tocheck]).
\end_layout

\begin_layout Section
Array construction using index tricks
\end_layout

\begin_layout Standard
The functions and classes in this category make it simpler to construct
 arrays.
 
\end_layout

\begin_layout Description
ix_
\begin_inset LatexCommand index
name "ix\\_"

\end_inset

 (*args)
\end_layout

\begin_layout Description
\InsetSpace ~
 This indexing cross function is useful for forming indexing arrays necessary
 to select out the cross-product of 
\begin_inset Formula $N$
\end_inset

 1-dimensional arrays.
 Note that the default indexing does not do a cross-product (which might
 be unexpected for someone coming from other programming environments).
 The default indexing is more general purpose.
 Using the ix_ constructor can produce the indexing arrays necessary to
 select a cross-product.
\end_layout

\begin_layout Description
mgrid [index expression]
\end_layout

\begin_layout Description
\InsetSpace ~
 This is an instance of a class.
 It can be used to construct a filled 
\begin_inset Quotes eld
\end_inset

mesh-grid
\begin_inset Quotes erd
\end_inset

 using slicing syntax.
 
\end_layout

\begin_layout Description
ogrid [index expression]
\end_layout

\begin_layout Description
\InsetSpace ~
 This is similar to mgrid except it returns an open grid, so as to save
 space and time.
 The broadcasting rules will ensure that any universal function operating
 on the grid will act as if the ogrid had been the result of mgrid.
\end_layout

\begin_layout Description
r_
\begin_inset LatexCommand index
name "r\\_"

\end_inset

 [index expression]
\end_layout

\begin_layout Description
\InsetSpace ~
 This is a simple way to build up arrays quickly.
 There are two use cases.
 1) If the index expression contains comma separated arrays, then stack
 them along their first axis.
 2) If the index expression contains slice notation or scalars then create
 a 1-d array with a range indicated by the slice notation.
 In other-words the slice syntax start:stop:step is equivalent to arange(start,
 stop, step) inside of the brackets.
 However, if step is an imaginary number (i.e.
 100j) then its integer portion is interpreted as a number-of-points desired
 and the start and stop are inclusive.
 In other words start:stop:step
\family typewriter
j
\family default
 is interpreted as linspace(start, stop, step, endpoint=1) inside of the
 brackets.
 After expansion of slice notation, all comma separated sequences are concatenat
ed together.
\end_layout

\begin_layout Description
\InsetSpace ~
 Optional character strings placed as the first element of the index expression
 can be used to change the output.
 The strings 'r' or 'c' result in matrix output.
 If the result is 1-d and 'r' is specified a 
\begin_inset Formula $1\times N$
\end_inset

 (row) matrix is produced.
 If the result is 1-d and 'c' is specified, then a 
\begin_inset Formula $N\times1$
\end_inset

 (column) matrix is produced.
 If the result is 2-d then both provide the same matrix result.
 
\end_layout

\begin_layout MyCode
>>> print r_[-1:1:9j,[0]*10,5,6]
\newline
[-1.
   -0.75 -0.5  -0.25  0.
    0.25  0.5   0.75  1.
    0.
    0.
\newline
  0.
    0.
    0.
    0.
    0.
    0.
    0.
    0.
    5.
    6.
  ]
\newline
>>> print r_['r',1,2,5,6]
\newline
[[1 2 5 6]]
\newline
>>> print r_['c',1,2,5,6]
\newline
[[1]
\newline
 [2]
\newline

 [5]
\newline
 [6]]
\end_layout

\begin_layout Description
\InsetSpace ~
 A string integer specifies which axis to stack multiple comma separated
 arrays along.
 
\end_layout

\begin_layout MyCode
>>> a=arange(6).reshape(2,3)
\newline
>>> r_[a,a]
\newline
array([[0, 1, 2],
\newline
       [3, 4, 5],
\newline

       [0, 1, 2],
\newline
       [3, 4, 5]])
\newline
>>> r_['-1',a,a]
\newline
array([[0, 1, 2, 0, 1,
 2],
\newline
       [3, 4, 5, 3, 4, 5]])
\end_layout

\begin_layout Description
\InsetSpace ~
 A string of two comma-separated integers allows indication of the minimum
 number of dimensions to force each entry into as the second integer (the
 axis to concatenate along is still the first integer).
 
\end_layout

\begin_layout MyCode
>>> r_['0,2',[1,2,3],[4,5,6]]
\newline
array([[1, 2, 3],
\newline
       [4, 5, 6]])
\newline
>>> r_['1,2',[1,
2,3],[4,5,6]]
\newline
array([[1, 2, 3, 4, 5, 6]])
\end_layout

\begin_layout Description
\InsetSpace ~
 A string with three comma-separated integers allows specification of the
 axis to concatenate along, the minimum number of dimensions to force the
 entries to, and which axis should contain the start of the arrays which
 are less than the specified number of dimensions.
 In other words the third integer allows you to specify where the the 1's
 should be placed in the shape of the arrays that have their shapes upgraded.
 By default, they are placed in the front of the shape tuple.
 The third argument allows you to specify where the start of the array should
 be instead.
 Thus, a third argument of '0' would place the 1's at the end of the array
 shape.
 Negative integers specify where in the new shape tuple the last dimension
 of upgraded arrays should be placed, so the default is '-1'.
\end_layout

\begin_layout MyCode
>>> r_['0,2,0', [1,2,3], [4,5,6]]
\newline
array([[1],
\newline
       [2],
\newline
       [3],
\newline
     
  [4],
\newline
       [5],
\newline
       [6]])
\newline
>>> r_['1,2,0', [1,2,3], [4,5,6]]
\newline
array([[1,
 4],
\newline
       [2, 5],
\newline
       [3, 6]])
\end_layout

\begin_layout Description
c_
\begin_inset LatexCommand index
name "c\\_"

\end_inset

 [index_expression]
\end_layout

\begin_layout Description
\InsetSpace ~
 This is short-hand for r_['-1,2,0', index_expression] useful because of
 its common occurence.
 In particular, arrays will be stacked along their last axis after being
 upgraded to at least 2-d with 1's post-pended to the shape (column vectors
 made out of 1-d arrays).
 
\end_layout

\begin_layout Section
Other indexing devices
\end_layout

\begin_layout Description
index_exp
\begin_inset LatexCommand index
name "index\\_exp"

\end_inset

 [index expression]
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a tuple of Python objects that implements the index expression and
 can be modified and placed in any other index expression.
 
\end_layout

\begin_layout MyCode
>>> index_exp[2:5,...,4,::-1]
\newline
(slice(2, 5, None), Ellipsis, 4, slice(None, None,
 -1))
\end_layout

\begin_layout Description
s_
\begin_inset LatexCommand index
name "s\\_"

\end_inset

 [index expression]
\end_layout

\begin_layout Description
\InsetSpace ~
 Translate index expressions into the equivalent Python objects.
 This is similar to index_expression except a tuple is not always returned.
 For example:
\end_layout

\begin_layout MyCode
>>> s_[1:10]
\newline
slice(1, 10, None)
\newline
>>> s_[1:10,-3:4:0.5]
\newline
(slice(1, 10, None), slice(-3,
 4, 0.5))
\end_layout

\begin_layout Description
\InsetSpace ~
 This provides a standard way to construct index expressions to pass to
 functions and methods because Python does not allow slice expressions anywhere
 except for inside brackets.
 
\end_layout

\begin_layout Description
ndindex
\begin_inset LatexCommand index
name "ndindex"

\end_inset

 (*seq)
\end_layout

\begin_layout Description
\InsetSpace ~
 A sequence of 
\begin_inset Formula $N$
\end_inset

 integers are passed in as separate arguments.
 These integers are used as the upper boundaries of an 
\begin_inset Formula $N$
\end_inset

-dimensional counter that starts at 0.
 The object returned is an iterator that implements the counter.
\end_layout

\begin_layout MyCode
>>> for index in ndindex(3,3,2):
\newline
...
     print index,
\newline
(0, 0, 0) (0, 0, 1) (0, 1, 0) (0, 1, 1) (0, 2, 0) (0, 2,
 1) (1, 0, 0) (1, 0, 1) (1, 1, 0) (1, 1, 1) (1, 2, 0) (1, 2, 1) (2, 0, 0)
 (2, 0, 1) (2, 1, 0) (2, 1, 1) (2, 2, 0) (2, 2, 1)
\end_layout

\begin_layout Description
unravel_index
\begin_inset LatexCommand index
name "unravel\\_index"

\end_inset

 (indx, dims)
\end_layout

\begin_layout Description
\InsetSpace ~
 Convert a flat index, indx, into an index tuple for an array of the given
 shape.
 Keep in mind that it may be more convenient to use indx with a.flat, then
 to unravel the index.
\end_layout

\begin_layout Section
Two-dimensional functions
\end_layout

\begin_layout Standard
These functions all deal with or return two dimensional arrays.
\end_layout

\begin_layout Description
eye
\begin_inset LatexCommand index
name "eye"

\end_inset

 (
\begin_inset Formula $N$
\end_inset

, 
\begin_inset Formula $M$
\end_inset

=None, 
\begin_inset Formula $k$
\end_inset

=0, dtype=float)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an 
\begin_inset Formula $N\times M$
\end_inset

 array of the given type with ones down the 
\begin_inset Formula $k^{\textrm{th}}$
\end_inset

 diagonal.
 If 
\begin_inset Formula $M$
\end_inset

 is None, it defaults to 
\begin_inset Formula $N$
\end_inset

.
 Alternatively, if 
\begin_inset Formula $M$
\end_inset

 is a valid data type, then it becomes the data-type used.
 
\end_layout

\begin_layout Description
vander
\begin_inset LatexCommand index
name "vander"

\end_inset

 (
\begin_inset Formula $x$
\end_inset

, 
\begin_inset Formula $N$
\end_inset

=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 The Vandermonde matrix of vector, 
\begin_inset Formula $x$
\end_inset

.
 The 
\begin_inset Formula $i^{\textrm{th}}$
\end_inset

 column of the return matrix is the 
\begin_inset Formula $m_{i}^{\textrm{th}}$
\end_inset

 power of 
\begin_inset Formula $x$
\end_inset

 where 
\begin_inset Formula $m_{i}=N-i-1$
\end_inset

.
 If 
\begin_inset Formula $N$
\end_inset

 is None, it defaults to the length of 
\begin_inset Formula $x$
\end_inset

.
 
\end_layout

\begin_layout MyCode
>>> vander([1,2,3,4,5],3)
\newline
array([[ 1,  1,  1],
\newline
       [ 4,  2,  1],
\newline
      
 [ 9,  3,  1],
\newline
       [16,  4,  1],
\newline
       [25,  5,  1]])
\end_layout

\begin_layout Description
diag
\begin_inset LatexCommand index
name "diag"

\end_inset

 (
\begin_inset Formula $v$
\end_inset

, 
\begin_inset Formula $k$
\end_inset

=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the 
\begin_inset Formula $k^{\textrm{th}}$
\end_inset

 diagonal if 
\begin_inset Formula $v$
\end_inset

 is a 2-d array, or returns an array with 
\begin_inset Formula $v$
\end_inset

 as the 
\begin_inset Formula $k^{\textrm{th}}$
\end_inset

 diagonal if 
\begin_inset Formula $v$
\end_inset

 is a 1-d array.
 
\end_layout

\begin_layout MyCode
>>> diag(arange(12).reshape(4,3),k=1)
\newline
array([1, 5])
\newline
>>> diag([1,4,5,7],k=-1)
\newline
array([
[0, 0, 0, 0, 0],
\newline
       [1, 0, 0, 0, 0],
\newline
       [0, 4, 0, 0, 0],
\newline
       [0,
 0, 5, 0, 0],
\newline
       [0, 0, 0, 7, 0]])
\end_layout

\begin_layout Description
diagflat
\begin_inset LatexCommand index
name "diagflat"

\end_inset

 (
\begin_inset Formula $v$
\end_inset

, 
\begin_inset Formula $k$
\end_inset

=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a 2-d array (of the same class as 
\begin_inset Formula $v$
\end_inset

) by placing a flattened version of 
\begin_inset Formula $v$
\end_inset

 along the 
\begin_inset Formula $k^{\textrm{th}}$
\end_inset

 diagonal.
 This differs from diag in that it only creates 2-d arrays and will work
 with any object that can be converted to an array (returning that object
 if it also defines an __array_wrap__ method).
 
\end_layout

\begin_layout Description
fliplr
\begin_inset LatexCommand index
name "fliplr"

\end_inset

 (m)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the array, m, with rows preserved and columns reversed in the left-right
 direction.
 For m.ndim > 2, this works on the first two dimensions (equivalent to m[:,::-1])
\end_layout

\begin_layout Description
flipud
\begin_inset LatexCommand index
name "flipud"

\end_inset

 (m)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the array, m, with columns preserved and rows reversed in the up-down
 direction.
 For m.ndim > 1, this works on the first dimension (equivalent to m[::-1])
\end_layout

\begin_layout Description
rot90
\begin_inset LatexCommand index
name "rot90"

\end_inset

 (m, k=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Rotate the first two dimensions of an array, m, by k*90 degrees in the
 counterclockwise direction.
 Must have m.ndim >=2.
\end_layout

\begin_layout Description
tri
\begin_inset LatexCommand index
name "tri"

\end_inset

 (
\begin_inset Formula $N$
\end_inset

, 
\begin_inset Formula $M$
\end_inset

=
\begin_inset Formula $N$
\end_inset

, k=0, dtype=aint)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an 
\begin_inset Formula $N\times M$
\end_inset

 array where all the diagonals starting from the lower left corner up to
 the 
\begin_inset Formula $\textrm{k}^{\textrm{th}}$
\end_inset

 diagonal are all ones.
 
\end_layout

\begin_layout Description
triu
\begin_inset LatexCommand index
name "triu"

\end_inset

 (m, k=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a upper-triangular 2-d array from m with all the elements below
 the 
\begin_inset Formula $\textrm{k}^{\textrm{th}}$
\end_inset

 diagonal set to 0.
 
\end_layout

\begin_layout Description
tril
\begin_inset LatexCommand index
name "tril"

\end_inset

 (m, k=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a lower-triangular 2-d array from m with all the elements above
 the 
\begin_inset Formula $\textrm{k}^{\textrm{th}}$
\end_inset

 diagonal set to 0.
 
\end_layout

\begin_layout Description
mat
\begin_inset LatexCommand index
name "mat"

\end_inset

 (data, dtype=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a matrix from data.
 Alias for numpy.asmatrix.
 The calling syntax is the same as that function.
 Note that data can be a string in which case the routine uses spaces and
 semi-colons to construct the matrix:
\end_layout

\begin_layout MyCode
>>> mat('1 3 4; 5 6 9')
\newline
matrix([[1, 3, 4],
\newline
        [5, 6, 9]])
\end_layout

\begin_layout Description
bmat
\begin_inset LatexCommand index
name "bmat"

\end_inset

 (obj, ldict=None, gdict=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Build a matrix from sub-blocks.
 This is similar to mat, except the items in the nested-sequence, or string,
 should be appropriately shaped 2-d arrays.
 If obj is a string, then ldict and gdict can be used to alter where the
 names represented in the string are found (default is current local and
 global namespace).
 
\end_layout

\begin_layout MyCode
>>> A=mat('1 2; 3 4'); B=mat('5 6; 7 8')
\newline
>>> bmat('A, B; B, A')
\newline
matrix([[1,
 2, 5, 6],
\newline
        [3, 4, 7, 8],
\newline
        [5, 6, 1, 2],
\newline
        [7, 8, 3, 4]])
\end_layout

\begin_layout Section
More data type functions
\end_layout

\begin_layout Description
issubclass_
\begin_inset LatexCommand index
name "issubclass\\_"

\end_inset

 (arg1, arg2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns True if arg1 is a sub-class of arg2, otherwise returns False.
 Similar to the built-in issubclass except it does not raise an error if
 arg1 or arg2 are not types.
 
\end_layout

\begin_layout Description
issubdtype
\begin_inset LatexCommand index
name "issubdtype"

\end_inset

 (arg1, arg2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns True if the type-object of the data-type represented by arg1 is
 a sub class of the type-object of the data-type represented by arg2.
\end_layout

\begin_layout Description
iscomplexobj
\begin_inset LatexCommand index
name "iscomplexobj"

\end_inset

 (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a single True or False value depending on whether or not obj would
 be interpreted as an array with complex-valued data type.
\end_layout

\begin_layout Description
isrealobj
\begin_inset LatexCommand index
name "isrealobj"

\end_inset

 (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a single True or False value depending on whether or not obj would
 be interpreted as an array with real-valued data type.
\end_layout

\begin_layout Description
isscalar
\begin_inset LatexCommand index
name "isscalar"

\end_inset

 (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 True if obj is a scalar (an instance of an array data type, or a standard
 Python scalar type).
 There is also a sequence of called ScalarType defined in NumPy, so that
 this can also be tested as type(obj) in numpy.ScalarType.
 
\end_layout

\begin_layout Description
nan_to_num
\begin_inset LatexCommand index
name "nan\\_to\\_num"

\end_inset

 (arr)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns an array with non-finite numbers changed to finite numbers.
 The mapping converts 
\family typewriter
nan
\family default
 to 0, 
\family typewriter
inf
\family default
 to the maximum value for the data type and 
\family typewriter
-inf
\family default
 to the minimum value for the data type.
\end_layout

\begin_layout Description
real_if_close
\begin_inset LatexCommand index
name "real\\_if\\_close"

\end_inset

 (arr, tol=100)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a real arr if arr is complex with imaginary parts less than some
 tolerance.
 If tol > 1, then it represents a multiplicative factor on the value of
 epsilon for the data type of arr.
\end_layout

\begin_layout Description
cast
\begin_inset LatexCommand index
name "cast"

\end_inset

 [dtype_or_alias] (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 Cast obj to an array of the given type.
 This is equivalent to array(obj, copy=0).astype(dtype_or_alias).
 When one type is cast to another in this fashion, a very low-level operation
 takes place.
 Typically, you get what your C-compiler produces for the cast, but notice
 that in the case of casting to a bool type, the value becomes either a
 0 or a 1.
 
\end_layout

\begin_layout MyCode
>>> cast[bool]([1,2,0,4,0]).astype(int)
\newline
array([1, 1, 0, 1, 0])
\end_layout

\begin_layout Description
asfarray
\begin_inset LatexCommand index
name "asfarray"

\end_inset

 (a, dtype=float)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array of inexact data type (floating or complexfloating).
 
\end_layout

\begin_layout Description
mintypecode
\begin_inset LatexCommand index
name "mintypecode"

\end_inset

 (typechars, typeset='GDFgdf', default='d')
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a minimum data type character from typeset that handles all given
 typechars.
 The returned type character must correspond to the data type of the smallest
 size such that an array of the returned type can handle the data from an
 array of type t for each t in typechars.
 If the typechars does not intersect with the typeset, then default is returned.
 If an element of typechars is not a string, then t=asarray(t).dtypechar
 is applied.
\end_layout

\begin_layout Description
finfo
\begin_inset LatexCommand index
name "finfo"

\end_inset

 (dtype)
\end_layout

\begin_layout Description
\InsetSpace ~
 This class allows exploration of the details of how a floating point number
 is represented in the computer.
 It can be instantiated by an inexact data type object (or an alias for
 one).
 Complex-valued data types are acceptable and are equivalent to their real-value
d counterparts.
 The attributes of the class are
\end_layout

\begin_deeper
\begin_layout Description
nmant The number of bits in the floating point mantissa, or fraction.
\end_layout

\begin_layout Description
nexp The number of bits in the floating point exponent 
\end_layout

\begin_layout Description
machep Exponent of the smallest (most negative) power of 2 that when added
 to 1.0 gives something different than 1.0.
 
\end_layout

\begin_layout Description
eps Floating point precision: 2**machep.
\end_layout

\begin_layout Description
precision Number of decimal digits of precision: int(-log10(eps)) 
\end_layout

\begin_layout Description
resolution 10**(-precision)
\end_layout

\begin_layout Description
negep Exponent of the smallest power of 2 that, subtracted from 1.0, gives
 something different than 1.0.
\end_layout

\begin_layout Description
epsneg Floating point precision: 2**negep.
\end_layout

\begin_layout Description
minexp Smallest (most negative) power of 2 producing 
\begin_inset Quotes eld
\end_inset

normal
\begin_inset Quotes erd
\end_inset

 numbers (no leading zeros in the mantissa).
 
\end_layout

\begin_layout Description
tiny The smallest (in magnitude) usable floating point number equal to 2**minexp.
\end_layout

\begin_layout Description
maxexp Smallest (positive) power of 2 that causes overflow.
\end_layout

\begin_layout Description
max The largest usable floating value: (1-epsneg)* (2**maxep)
\end_layout

\begin_layout Description
min The most negative usable floating value: -max
\end_layout

\end_deeper
\begin_layout Description
\InsetSpace ~
 The most useful attributes are probably eps, max, min, and tiny.
\end_layout

\begin_layout Section
Functions that behave like ufuncs
\end_layout

\begin_layout Standard
These functions are Python functions built on top of universal functions
 (ufuncs) and also take optional output arguments.
 They broadcast like ufuncs but do not have ufunc attributes.
\end_layout

\begin_layout Description
fix
\begin_inset LatexCommand index
name "fix"

\end_inset

 (x, y=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Round x to the nearest integer towards zero.
\end_layout

\begin_layout Description
isneginf
\begin_inset LatexCommand index
name "isneginf"

\end_inset

 (x, y=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x=-\infty$
\end_inset

.
 Should be the same as 
\family typewriter
x==NumPy.NINF
\family default
.
\end_layout

\begin_layout Description
isposinf
\begin_inset LatexCommand index
name "isposinf"

\end_inset

 (x, y=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x=+\infty.$
\end_inset

 Should be the same as 
\family typewriter
x==NumPy.PINF
\family default
.
\end_layout

\begin_layout Description
log2
\begin_inset LatexCommand index
name "log2"

\end_inset

 (x, y=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the logarithm to the base 2 of 
\begin_inset Formula $x.$
\end_inset

 An optional output array may be provided.
\end_layout

\begin_layout Section
Miscellaneous Functions
\end_layout

\begin_layout Standard
Some miscellaneous functions are available in NumPy which are included largely
 for compatibility with MLab of the old Numeric package.
 One notable difference, however, is that due to a separate implementation
 of the modified Bessel function, the kaiser window is available without
 needing a separate library.
 
\end_layout

\begin_layout Description
sinc
\begin_inset LatexCommand index
name "sinc"

\end_inset

 (
\begin_inset Formula $x$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the sinc function for 
\begin_inset Formula $x$
\end_inset

 which can be a scalar or array.
 The sinc is defined as 
\begin_inset Formula $y=\textrm{sinc}\left(x\right)=\frac{\sin\left(\pi x\right)}{\pi x}$
\end_inset

 with the caveat that the limiting value (1.0) of the ratio is taken for
 
\begin_inset Formula $x=0.$
\end_inset

 
\end_layout

\begin_layout Description
i0
\begin_inset LatexCommand index
name "i0"

\end_inset

 (
\begin_inset Formula $x$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Modified Bessel function of the first kind of order 0.
 Needed to compute the kaiser window.
 The modified Bessel function is defined as 
\begin_inset Formula \[
I_{0}\left(x\right)=\frac{1}{\pi}\int_{0}^{\pi}e^{x\cos\theta}d\theta=\sum_{k=0}^{\infty}\frac{x^{2k}}{4^{k}\left(k!\right)^{2}}.\]

\end_inset


\end_layout

\begin_layout Description
blackman
\begin_inset LatexCommand index
name "blackman"

\end_inset

 (
\begin_inset Formula $M$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an 
\begin_inset Formula $M$
\end_inset

-point Blackman smoothing window which is sequence of length 
\begin_inset Formula $M$
\end_inset

 with values given for 
\begin_inset Formula $n=0\ldots M-1$
\end_inset

 by 
\begin_inset Formula \[
w\left[n\right]=0.42-0.5\cos\left(2\pi\frac{n}{M-1}\right)+0.08\cos\left(4\pi\frac{n}{M-1}\right).\]

\end_inset


\end_layout

\begin_layout Description
bartlett
\begin_inset LatexCommand index
name "bartlett"

\end_inset

 (
\begin_inset Formula $M$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an 
\begin_inset Formula $M$
\end_inset

-point Bartlett (triangular) smoothing window as 
\begin_inset Formula \[
w\left[n\right]=\left\{ \begin{array}{cc}
2\frac{n}{M-1} & 0\leq n\leq\frac{M-1}{2},\\
2-2\frac{n}{M-1} & \frac{M-1}{2}<n\leq M-1.\end{array}\right.\]

\end_inset


\end_layout

\begin_layout Description
hanning
\begin_inset LatexCommand index
name "hanning"

\end_inset

 (
\begin_inset Formula $M$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an 
\begin_inset Formula $M$
\end_inset

-point Hanning smoothing window defined as 
\begin_inset Formula \[
w\left[n\right]=\frac{1}{2}-\frac{1}{2}\cos\left(2\pi\frac{n}{M-1}\right).\]

\end_inset


\end_layout

\begin_layout Description
hamming
\begin_inset LatexCommand index
name "hamming"

\end_inset

 (
\begin_inset Formula $M$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an 
\begin_inset Formula $M$
\end_inset

-point Hamming smoothing window defined for 
\begin_inset Formula $n=0\ldots M-1$
\end_inset

 as 
\begin_inset Formula \[
w\left[n\right]=0.54-0.46\cos\left(2\pi\frac{n}{M-1}\right).\]

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 All of the windowing functions are smoothing windows that attempt to balance
 the inherent trade off between side-lobe height (ringing) and main-lobe
 width (resolution) in the frequency domain.
 A rectangular window has the smallest main-lobe width but the largest side-lobe
 height.
 A windowing (tapering) function tries to can help trade off main-lobe width
 By sacrificing a little in resolution using a windowing function These
 windows can be used to smooth data using the convolve function.
 Figure 
\begin_inset LatexCommand ref
reference "cap:window functions"

\end_inset

 shows the windowing functions described so far and their time- and frequency-do
main behavior.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Graphics
	filename Figures/fig1.eps
	lyxscale 48
	width 49line%
	keepAspectRatio

\end_inset


\hfill

\begin_inset Graphics
	filename Figures/fig2.eps
	lyxscale 48
	width 49line%
	keepAspectRatio

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:window functions"

\end_inset

Blackman, Bartlett, Hanning, and Hamming windows in the time and frequency
 domain showing the trade-off between main-lobe width and side-lobe height
 (Figures made with matplotlib).
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The trade-off between main-lobe and side-lobe has been studied extensively.
 Solutions that maximize energy in the main-lobe compared to energy in the
 side-lobes can be found by finding an eigenvector which can be expensive
 to compute for large window sizes.
 A good approximation to these prolate-spheroidal windows is the Kaiser
 window.
 
\end_layout

\begin_layout Description
kaiser
\begin_inset LatexCommand index
name "kaiser"

\end_inset

 (
\begin_inset Formula $M$
\end_inset

, 
\begin_inset Formula $\beta$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an 
\begin_inset Formula $M$
\end_inset

-point Kaiser smoothing window.
 The 
\begin_inset Formula $\beta$
\end_inset

 parameter controls the width of the window (and the frequency-domain side-lobe
 height and main-lobe width).
 The window is defined as 
\begin_inset Formula \[
w\left[n\right]=\frac{1}{I_{0}\left(\beta\right)}I_{0}\left(\beta\sqrt{1-\frac{\left(2n-M-1\right)^{2}}{\left(M-1\right)^{2}}}\right).\]

\end_inset

 There is an empirical relationship between 
\begin_inset Formula $\beta$
\end_inset

 and the side-lobe height which can be used in FIR filter design.
 To achieve a side-lobe height of 
\begin_inset Formula $-\alpha$
\end_inset

dB, the 
\begin_inset Formula $\beta$
\end_inset

 parameter is 
\begin_inset Formula \[
\beta=\left\{ \begin{array}{cc}
0.1002\left(\alpha-8.7\right) & \alpha>50,\\
0.5842\left(\alpha-21\right)^{0.4}+0.07886\left(\alpha-21\right) & 21\leq\alpha\leq50,\\
0 & \alpha<21.\end{array}\right.\]

\end_inset

 The length 
\begin_inset Formula $M$
\end_inset

 of the window determines the transition width.
 To obtain a transition width of 
\begin_inset Formula $\Delta\omega$
\end_inset

rad/s the window-length must be at least:
\begin_inset Formula \[
M=\frac{\alpha-8}{2.285\Delta\omega}+1.\]

\end_inset


\end_layout

\begin_layout Section
Utility functions
\end_layout

\begin_layout Description
set_numeric_ops
\begin_inset LatexCommand index
name "set\\_numeric\\_ops"

\end_inset

 (<op1>=func1, <op2>=func2, ...)
\end_layout

\begin_layout Description
\InsetSpace ~
 This function can be used to alter the operations used for internal array
 calculations and array special methods.
 Replaceable operations (and possible entries for <opN>) are add, subtract,
 multiply, divide, remainder, power, sqrt, negative, absolute, invert, left_shif
t, right_shift, bitwise_and, bitwise_or, less, less_equal, equal, not_equal,
 greater, greater_equal, floor_divide, true_divide, logical_or, logical_and,
 floor, ceil, maximum, and minimum.
 The example code below changes, then restores, the old Numeric behavior
 of remainder (which was changed because it was not consistent with Python).
 
\end_layout

\begin_layout MyCode
>>> a = array([-3.,-2,-1,0,1,2,3])
\newline
>>> print a % -2.1
\newline
[-0.9 -2.
  -1.
   0.
  -1.1 -0.1 -1.2]
\newline
>>> oldops = set_numeric_ops(remainder=fmod)
\newline
>>> print a %
 -2.1
\newline
[-0.9 -2.
  -1.
   0.
   1.
   2.
   0.9]
\newline
>>> newops = set_numeric_ops(**oldops)
\newline
>>> print a % -2.1
\newline
[-0.9 -2.
  -1.
   0.
  -1.1 -0.1 -1.2]
\newline
>>> print 3 % -2.1 # comparison
\newline
-1.2
\end_layout

\begin_layout Description
get_include
\begin_inset LatexCommand index
name "get\\_include"

\end_inset

 ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the directory that contains the numpy include files.
 The numpy.distutils automatically includes this directory in building extensions.
 
\end_layout

\begin_layout Description
get_numarray_include
\begin_inset LatexCommand index
name "get\\_numarray\\_include"

\end_inset

 (type=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the directory that contains the numarray compatible C-API include
 files.
 If type is not None, then return a list containing both the numarray compatible
 C-API include files and the numpy include files.
 The latter form is only needed when building an extension without the use
 of numpy.distutils.
 
\end_layout

\begin_layout Description
deprecate
\begin_inset LatexCommand index
name "deprecate"

\end_inset

 (func, oldname, newname)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a deprecated function named 'oldname' that has been replaced by
 'newname'.
 This new deprecated function issues a warning before calling the old function.
 The name and docs of the function are also updated to be oldname instead
 of the name that func has.
 Example usage.
 If you want to deprecate the function named 'old' in favor of a new function
 named 'new' which has the same calling conention then this could be done
 with the assignment
\end_layout

\begin_deeper
\begin_layout LyX-Code
old = deprecate(new, 'old', 'new')
\end_layout

\end_deeper
\begin_layout Chapter
Scalar objects
\end_layout

\begin_layout Standard
\begin_inset LatexCommand label
name "cha:Scalar-objects"

\end_inset


\end_layout

\begin_layout Quotation
Never worry about numbers.
 Help one person at a time, and always start with the person nearest you.
\end_layout

\begin_layout Right Address
---
\emph on
Mother Teresa
\end_layout

\begin_layout Quotation
A great many people think they are thinking when they are merely rearranging
 their prejudices.
\end_layout

\begin_layout Right Address
---
\emph on
William James
\end_layout

\begin_layout Standard
One
\begin_inset LatexCommand index
name "array scalars|("

\end_inset

 important new feature of NumPy is the addition of a new scalar object for
 each of the 21 different data types that an array can have.
 Do not confuse these scalar objects with the data-type objects.
 There is one data-type object.
 It contains a 
\family typewriter
.type
\family default
 attribute which points to the Python type that each element of the array
 will be returned as
\begin_inset Foot
status open

\begin_layout Standard
with the exception of object data-types which return the underlying object
 and not a 
\begin_inset Quotes eld
\end_inset

scalar
\begin_inset Quotes erd
\end_inset

 type.
 
\end_layout

\end_inset

.
 The built-in data-types point have .
\family typewriter
type
\family default
 attributes that point to these scalar objects.
 Five (or six) of these new scalar objects are essentially equivalent to
 fundamental Python types and therefore inherit from them as well as from
 the generic array scalar type.
 The bool_ data type is very similar to the Python BooleanType but does
 not inherit from it because Python's BooleanType does not allow itself
 to be inherited from, and on the C-level the size of the actual bool_ data
 is not the same as a Python Boolean scalar.
 Table 
\begin_inset LatexCommand ref
reference "cap:Array-scalar-types"

\end_inset

 shows which array scalars inherit from basic Python types.
 
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Array-scalar-types"

\end_inset

Array scalar types that inherit from basic Python types.
 The intc array data type might also inherit from the IntType if it has
 the same number of bits as the int_ array data type on your platform.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="6" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
array data type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Python type
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
int_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
IntType
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
float_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
FloatType
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
complex_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ComplexType
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
str_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
StringType
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
unicode_
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
UnicodeType
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The array scalars have the same attributes and methods as arrays and live
 in a hierarchy of scalar types so they can be easily classified based on
 their type objects.
 However, because array scalars are immutable, and attributes change intrinsic
 properties of the object, the 
\series bold
array scalar attributes are not settable
\series default
.
\end_layout

\begin_layout Standard
Array scalars can be detected using the hierarchy of data types.
 For example, 
\family typewriter
isinstance(val, generic)
\family default
 will return True if val is an array scalar object.
 Alternatively, what kind of array scalar is present can be determined using
 other members of the data type hierarchy.
 Thus, for example 
\family typewriter
isinstance(val, complexfloating)
\family default
 will return True if val is a complex valued type, while 
\family typewriter
isinstance(val, flexible)
\family default
 will return true if val is one of the flexible itemsize array types (string,
 unicode, void).
 
\end_layout

\begin_layout Warning
The bool_ type is not a subclass of the int_ type (the bool_ type is not
 even a number type).
 This is different than Python's default implementation of bool as a sub-class
 of int.
\end_layout

\begin_layout Section
Attributes of array scalars
\end_layout

\begin_layout Standard
The array scalar objects have an 
\family typewriter
__array_priority__
\family default
 of NPY_SCALAR_PRIORITY (-1,000,000.0).
 They also do not (yet) have a ctypes attribute.
 Otherwise, they share the same attributes as arrays:
\end_layout

\begin_layout Description
flags
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns True for CONTIGUOUS, OWNDATA, FORTRAN, and ALIGNED.
 Always returns False for WRITEABLE, and UPDATEIFCOPY.
 
\end_layout

\begin_layout Description
shape
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns ().
\end_layout

\begin_layout Description
strides
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns ().
\end_layout

\begin_layout Description
ndim 
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns 0.
\end_layout

\begin_layout Description
data 
\end_layout

\begin_layout Description
\InsetSpace ~
 A read-only buffer object of size self.itemsize,
\end_layout

\begin_layout Description
size
\end_layout

\begin_layout Description
\InsetSpace ~
 Return 1.
\end_layout

\begin_layout Description
itemsize
\end_layout

\begin_layout Description
\InsetSpace ~
 The number of bytes this scalar requires.
\end_layout

\begin_layout Description
base
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns None.
\end_layout

\begin_layout Description
dtype
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns data type descriptor corresponding to this array scalar.
 
\end_layout

\begin_layout Description
real
\end_layout

\begin_layout Description
\InsetSpace ~
 The real part of the scalar.
\end_layout

\begin_layout Description
imag
\end_layout

\begin_layout Description
\InsetSpace ~
 The imaginary part of the scalar (or 0 if this is real).
\end_layout

\begin_layout Description
flat
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a 1-d iterator object (of size 1).
\end_layout

\begin_layout Description
T
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a reference to self.
\end_layout

\begin_layout Description
__array_interface__
\end_layout

\begin_layout Description
\InsetSpace ~
 The Python-side to the array interface.
 
\end_layout

\begin_layout Description
__array_struct__ 
\end_layout

\begin_layout Description
\InsetSpace ~
 The C-side to the array interface
\end_layout

\begin_layout Description
__array_priority__
\end_layout

\begin_layout Description
\InsetSpace ~
 -100.0 (very low-priority).
 
\end_layout

\begin_layout Description
__array_wrap__ (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns an array scalar from an array
\end_layout

\begin_layout Section
Methods of array scalars
\end_layout

\begin_layout Standard
Array scalars have exactly the same methods as arrays.
 The default behavior of these methods is to internally convert the scalar
 to an equivalent 0-dimensional array and to call the corresponding array
 method.
 The exceptions to these rules are given below.
 In addition, math operations on array scalars are defined so that the same
 hardware flags are set and used to interpret the results as for ufunc.
 Therefore the error state used for ufuncs also carries over to the math
 on array scalars.
\end_layout

\begin_layout Description
__new__ (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 The default behavior is to return a new array or array scalar by calling
 array(obj) with the corresponding data type.
 There are two situations when this default behavior is delayed until another
 approach is tried.
 First, when the array scalar type inherits from a Python type, then the
 Python types new method is called first and the default method is called
 only if that approach fails.
 The second situation is for the 
\family typewriter
void
\family default
 data type where a single integer-like argument will cause a void scalar
 of that size to be created and initialized to 0.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 Notice that because array(obj) is called for new, if obj is a nested sequence,
 then the return object could actually be an 
\family typewriter
ndarray
\family default
.
 Thus, arrays of the correct type can also be created by calling the array
 data type name directly:
\end_layout

\begin_layout MyCode
>>> uint32([[5,6,7,8],[1,2,3,4]])
\newline
array([[5, 6, 7, 8],
\newline
       [1, 2, 3, 4]],
 dtype=uint32)
\end_layout

\begin_layout Description
__array__ (<None>)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns a 0-dimensional array of the given data type, or of type(self)
 if argument is None.
\end_layout

\begin_layout Description
__array_wrap__ (array)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns a scalar array object from the first-element of the array.
\end_layout

\begin_layout Description
__squeeze__ ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns self.
\end_layout

\begin_layout Description
byteswap (<False>)
\end_layout

\begin_layout Description
\InsetSpace ~
 Trying to set the first (inplace) argument to True raises a ValueError.
 Otherwise, this returns a new array scalar with the data byteswapped.
 
\end_layout

\begin_layout Description
__reduce__ ()
\end_layout

\begin_layout Description
\InsetSpace ~
 This is called to pickle an array scalar.
 It returns a tuple of (numpy.core.multiarray.scalar, self.dtypestr, obj or
 self.tostring()) which can be used to reconstruct the scalar on unpickling.
 Notice that no state is written, because the entire scalar can be constructed
 from just the string.
 Also, if this is an object array scalar, then the Python object being reference
d is written.
\end_layout

\begin_layout Description
__setstate__ ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Does nothing but return None.
\end_layout

\begin_layout Description
setflags ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Does nothing, as flags cannot be set for scalars
\begin_inset LatexCommand index
name "array scalars|)"

\end_inset

.
\end_layout

\begin_layout Section
Defining New Types
\end_layout

\begin_layout Standard
There are two ways to effectively define a new type of array.
 One way is to simply subclass the ndarray and overwrite the methods of
 interest.
 This will work to a degree, but internally certain behaviors are fixed
 by the data type of the array.
 To fully customize the data type of an array you need to define a new data-type
 for the array, and register it with NumPy.
 This new type can only be defined in C.
 How to define a new data type in C will be discussed in the next part of
 the book.
\end_layout

\begin_layout Chapter
Data-type (
\family typewriter
dtype
\family default
) Objects
\end_layout

\begin_layout Quotation
We cannot expect that all nations will adopt like systems, for conformity
 is the jailer of freedom and the enemy of growth.
\end_layout

\begin_layout Right Address
---
\emph on
John F.
 Kennedy
\end_layout

\begin_layout Quotation
What information consumes is rather obvious: it consumes the attention of
 its recipients.
 Hence, a wealth of information creates a poverty of attention and a need
 to allocate that attention efficiently among the overabundance of information
 sources that might consume it.
\end_layout

\begin_layout Right Address
---
\emph on
Herbert Simon
\end_layout

\begin_layout Standard
\begin_inset LatexCommand label
name "cha:Data-descriptor-objects"

\end_inset

It
\begin_inset LatexCommand index
name "dtype|("

\end_inset

 is important not to confuse the 
\begin_inset Quotes eld
\end_inset

array-scalars
\begin_inset Quotes erd
\end_inset

 with the 
\begin_inset Quotes eld
\end_inset

data-type objects.
\begin_inset Quotes erd
\end_inset

 It is true that an array-scalar can be interpreted as a data-type object
 and so can be used to refer to the data-type of an array.
 However, the data-type object is a separate Python object.
 Every ndarray has an associated data-type object that completely defines
 the data in the array (including any named fields).
 For every built-in data-type object there is an associated type object
 whose instances are the array-scalars.
 Because of the association between each data-type object and a type-object
 of the corresponding array scalar, the array-scalar type-objects can also
 be thought of as data-types.
 However, for the type objects of flexible array-scalars (string, unicode_,
 and void), the type-objects alone are not enough to specify the full data-type
 because the length is not given.
 The data-type constructor, 
\series bold
numpy.dtype
\series default
, converts any object that can be considered as a data-type into a data-type
 object which is the actual object an ndarray looks to in order to interpret
 each element of its data region.
 Whenever a data-type is required in a NumPy function or method, supplying
 a dtype object is always fastest.
 If the object supplied is not a dtype object, then it will be converted
 to one using dtype(obj).
 Therefore, understanding data-type objects is the key to understanding
 how data types are really represented and understood in NumPy.
\end_layout

\begin_layout Section
Attributes
\begin_inset LatexCommand index
name "dtype!attributes|("

\end_inset


\end_layout

\begin_layout Description
type
\begin_inset LatexCommand index
name "dtype!attributes!type"

\end_inset

 The
\begin_inset LatexCommand index
name "The"

\end_inset

 type object used to instantiate a scalar of this data-type.
\end_layout

\begin_layout Description
kind
\begin_inset LatexCommand index
name "dtype!attributes!kind"

\end_inset

 A character code (one of 'biufcSUV') identifying the general kind of data.
 
\end_layout

\begin_layout Description
char
\begin_inset LatexCommand index
name "dtype!attributes!char"

\end_inset

 A unique character code for each of the 21 different built-in types.
 
\end_layout

\begin_layout Description
num
\begin_inset LatexCommand index
name "dtype!attributes!num"

\end_inset

 A unique number for each of the 21 different built-in types roughly ordered
 from least-to-most precision.
 
\end_layout

\begin_layout Description
str
\begin_inset LatexCommand index
name "dtype!attributes!str"

\end_inset

 The array-protocol typestring of this data-type object.
\end_layout

\begin_layout Description
name
\begin_inset LatexCommand index
name "dtype!attributes!name"

\end_inset

 A bit-width name for this data-type (un-sized flexible data-type objects
 are missing the width).
 
\end_layout

\begin_layout Description
byteorder
\begin_inset LatexCommand index
name "dtype!attributes!byteorder"

\end_inset

 A character indicating the byte-order of this data-type object ('=' : native,
 '<' : little-endian, '>' : big-endian, '|' : not applicable).
 All built-in data-type objects have byteorder either '=' or '|'.
 
\end_layout

\begin_layout Description
itemsize
\begin_inset LatexCommand index
name "dtype!attributes!itemsize"

\end_inset

 The element size of this data-type object.
 For 18 of the 21 types this number is fixed by the data-type.
 For the flexible data-types, this number can be anything.
 
\end_layout

\begin_layout Description
alignment
\begin_inset LatexCommand index
name "dtype!attributes!alignment"

\end_inset

 The required alignment (in bytes) of this data-type according to the compiler.
 More information is available in the C-API section.
 
\end_layout

\begin_layout Description
fields
\begin_inset LatexCommand index
name "dtype!attributes!fields"

\end_inset

 A dictionary showing any named fields that have been defined for this data-type
 (or None if there are no named fields).
 Fields can be assigned to any built-in data-type (
\emph on
e.g.

\emph default
 using the tuple input to the dtype constructor).
 However, fields are most useful for (subtypes of) void data-types which
 can be any size.
 Fields are a convenient way to keep track of fixed-size sub-parts of the
 total fixed-size array-element, or record.
 A field is defined in terms of another dtype object and an offset (in bytes)
 into the current record.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 The fields dictionary is indexed by keys that are the names of the fields.
 Each entry in the dictionary is a tuple fully describing the field: (dtype,
 offset[, title]).
 If present, the optional title can actually be any object (if it is string
 or unicode then it will also be a key in the fields dictionary, otherwise
 it's meta-data).
 Notice also, that the first two elements of the tuple can be passed directly
 as arguments to the getfield and setfield attributes of an ndarray.
 If field names are not specified in a constructor, they default to 'f0',
 'f2', ..., 'f<n-1>'.
 
\end_layout

\begin_layout Description
names
\begin_inset LatexCommand index
name "dtype!attributes!char"

\end_inset

 An ordered list of field names.
 This can be used to walk through all of the named fields in offset order.
 Notice that the defined fields do not have to 
\begin_inset Quotes eld
\end_inset

cover
\begin_inset Quotes erd
\end_inset

 the record, but the itemsize of the container data-type object must always
 be at least as large as the itemsizes of the data-type objects in the defined
 fields.
 This attribute is None if there are no fields.
\end_layout

\begin_layout Description
subdtype
\begin_inset LatexCommand index
name "dtype!attributes!subdtype"

\end_inset

 Numarray introduced the concept of a fixed-length record having fields
 that were themselves arrays of another data-type.
 This is supported at a fundamental level in NumPy using this attribute
 which maintains the simplicity of defining a field by another data-type
 object.
 It either returns None or a tuple (base dtype, shape) where shape is a
 tuple showing the size of the C-contiguous array and the base dtype object
 indicates the data-type in each element of the subarray.
 If a field whose dtype object has this attribute is retrieved, then the
 extra dimensions implied by the shape are tacked on to the end of the retrieved
 array.
 
\end_layout

\begin_layout Description
descr
\begin_inset LatexCommand index
name "dtype!attributes!descr"

\end_inset

 An array-interface-compliant full description of the data-type.
 The format is that required by the 'descr' key in the __array_interface__.
\end_layout

\begin_layout Description
isbuiltin
\begin_inset LatexCommand index
name "dtype!attributes!isbuiltin"

\end_inset

 A 1 if self is one of the built-in dtype objects; a 2 if self is a user-defined
 dtype object; a 0, otherwise.
\end_layout

\begin_layout Description
isnative
\begin_inset LatexCommand index
name "dtype!attributes!isnative"

\end_inset

 True if this data-type object has a byteorder that is native to the platform;
 otherwise False.
\end_layout

\begin_layout Description
hasobject
\begin_inset LatexCommand index
name "dtype!attributes!hasobject"

\end_inset

 True if self contains reference-counted objects in any of it's fields or
 sub data-types.
 Recall that what is actually in the ndarray memory representing the Python
 object is the memory address of that object (a pointer).
 Special handling may be required and this attribute is useful for distinguishin
g data-types that may contain arbitrary Python objects and data-types that
 won't.
 
\end_layout

\begin_layout Description
flags
\begin_inset LatexCommand index
name "dtype!attributes!flags"

\end_inset

 Bit-flags for the data-type describing how the data-type will be interpreted.
 Bit-masks are in numpy.core.multiarray as the constants ITEM_HASOBJECT, LIST_PICK
LE, ITEM_IS_POINTER, NEEDS_INIT, NEEDS_PYAPI, USE_GETITEM, USE_SETITEM.
 A full explanation of these flags is in the second part of this book.
 These flags are largely useful for user-defined data-types.
 
\begin_inset LatexCommand index
name "dtype!attributes|)"

\end_inset


\end_layout

\begin_layout Section
Construction
\end_layout

\begin_layout Description
dtype (obj, align=0, copy=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "dtype!construction|("

\end_inset

Return a new data-type object from obj.
 The keyword argument, align, can only be nonzero if obj is a dictionary,
 or a comma-separated string.
 If it is non-zero in those cases it is used to add padding as needed to
 the fields to match what the compiler that compiled NumPy would do to a
 similar C-struct.
 The copy argument guarantees a new copy of the data-type object, otherwise,
 the result may just be a reference to a built-in data-type object.
\end_layout

\begin_layout Description
\InsetSpace ~
 Objects that can be converted to a data-type object are described in the
 following list.
 Because every object in this list can be converted to a data-type object
 it can also be used whenever a 
\family typewriter
dtype
\family default
 is requested by a function or method in NumPy.
 
\end_layout

\begin_deeper
\begin_layout Description
dtype 
\begin_inset LatexCommand index
name "dtype!construction!from float"

\end_inset

Returns itself.
\end_layout

\begin_layout Description
None 
\begin_inset LatexCommand index
name "dtype!construction!from None"

\end_inset

Returns the default data-type descriptor object: float.
\end_layout

\begin_layout Description
type-object 
\begin_inset LatexCommand index
name "dtype!construction!from type"

\end_inset

Many Python type objects can be converted to data-type objects.
\end_layout

\begin_deeper
\begin_layout Enumerate
Array-scalar types: The type-objects of the 21 built-in array scalars all
 convert to an associated data-type object.
 This is true for sub-classes as well.
 Not all data-type information can be supplied with a type-object.
 Flexible data-types with default itemsizes of 0, for example, require an
 itemsize to be useful.
\end_layout

\begin_deeper
\begin_layout Description
Examples: int32, float64, uint16, complex128
\end_layout

\end_deeper
\begin_layout Enumerate
Generic types: The generic hierarchical type objects convert to corresponding
 dtype objects according to the associations: (numeric, inexact, floating)
 --> float; complexfloating --> cfloat; (integer, signedinteger) --> int_;
 unsignedinteger --> uint; character --> string; (generic, flexible) -->
 void.
 
\end_layout

\begin_layout Enumerate
Builtin types: Several python types are equivalent to a corresponding array
 scalar when used to generate a dtype object: int --> int_; bool --> bool_;
 float --> float_; complex --> cfloat; str --> string; unicode --> unicode_;
 buffer --> void; (all others) --> object_.
\end_layout

\begin_deeper
\begin_layout Description
Examples: object, str, float, int
\end_layout

\end_deeper
\begin_layout Enumerate
Any type object with the dtype attribute: The attribute will be accessed
 and used directly.
 The attribute must return something that is convertible into a dtype object.
 
\end_layout

\end_deeper
\begin_layout Description
string 
\begin_inset LatexCommand index
name "dtype!construction!from string"

\end_inset

Several kinds of strings can be converted.
 Recognized strings can be pre-pended with '>', or '<', to specify the byteorder.
\end_layout

\begin_deeper
\begin_layout Enumerate
One-character strings: Each built-in data-type has a character code (the
 updated Numeric typecodes), that uniquely identifies it.
 
\end_layout

\begin_deeper
\begin_layout Description
Examples: 'b', 'H', 'f', 'd', 'F', 'D', Float64, Int32, UInt16
\end_layout

\end_deeper
\begin_layout Enumerate
Array-protocol type strings: The first character specifies the kind of data
 and the remaining characters specify how many bytes of data.
 The supported kinds are 'b' --> Boolean, 'i' --> (signed) integer, 'u'
 --> unsigned integer, 'f' --> floating-point, 'c' --> complex-floating
 point, 'S', 'a' --> string, 'U' --> unicode, 'V' --> anything (void).
 
\end_layout

\begin_deeper
\begin_layout Description
Examples: 'i4', 'f8', 'c16', 'b1', 'S10', 'a25'
\end_layout

\end_deeper
\begin_layout Enumerate
Comma-separated field formats: numarray introduced a short-hand notation
 for specifying the format of a record as a comma-separated string of basic
 formats.
 A basic format in this context is an optional shape specifier followed
 by an array-protocol type string.
 Parenthesis are required on the shape if it is greater than 1-d.
 NumPy allows a modification on the format in that any string that can uniquely
 identify the type can be used to specify the data-type in a field.
 This data-type defines fields named 'f0', 'f2', ..., 'f<N-1>' where N (>1)
 is the number of comma-separated basic formats in the string.
 If the optional shape specifier is provided, then the data-type for the
 corresponding field contains a subdtype attribute providing the shape.
 
\end_layout

\begin_deeper
\begin_layout Description
Examples: 
\begin_inset Quotes eld
\end_inset

i4, (2,3)f8, f4
\begin_inset Quotes erd
\end_inset

; 
\begin_inset Quotes eld
\end_inset

a3, 3u8, (3,4)a10
\begin_inset Quotes erd
\end_inset


\end_layout

\end_deeper
\begin_layout Enumerate
Any string in NumPy.sctypeDict.keys():
\end_layout

\begin_deeper
\begin_layout Description
Examples: 'uint32', 'Int16', 'Uint64', 'Float64', 'Complex64'
\end_layout

\end_deeper
\end_deeper
\begin_layout Description
tuple 
\begin_inset LatexCommand index
name "dtype!construction!from tuple"

\end_inset

Three kinds of tuples each of length 2 can be converted into a data-type
 object:
\end_layout

\begin_deeper
\begin_layout Enumerate
(flexible dtype, itemsize): The first argument must be an object that is
 converted to a flexible data-type object (one whose element size is 0),
 the second argument is an integer providing the desired itemsize.
\end_layout

\begin_deeper
\begin_layout Description
Examples: (void, 10); (str, 35), ('U', 10)
\end_layout

\end_deeper
\begin_layout Enumerate
(fixed dtype, shape): The first argument is any object that can be converted
 into a fixed-size data-type object.
 The second argument is the desired shape of this type.
 If the shape parameter is 1, then the data-type object is equivalent to
 fixed dtype.
\end_layout

\begin_deeper
\begin_layout Description
Examples: (int32, (2,5)); ('S10', 1)=='S10'; ('i4, (2,3)f8, f4', (2,3))
\end_layout

\end_deeper
\begin_layout Enumerate
(base dtype, new dtype): Both arguments must be convertible to data-type
 objects in this case.
 The base dtype is the data-type object that the new data-type builds on.
 This is how you could assign named fields to any built-in data-type object.
 
\end_layout

\begin_deeper
\begin_layout Description
Examples: (int32, {'real':(int16,0), 'imag':(int16,2)}); (int32, (int8,
 4)); 
\newline
('i4', [('r','u1'),('g','u1'),('b','u1'),('a','u1')])
\end_layout

\end_deeper
\end_deeper
\begin_layout Description
list 
\begin_inset LatexCommand index
name "dtype!construction!from list"

\end_inset

(array description interface): This style is more fully described at 
\begin_inset LatexCommand url
name "this site"
target "http://numpy.scipy.org/array_interface.html"

\end_inset

.
 It consists of a list of fields where each field is described by a tuple
 of length 2 or 3.
 The first element of the tuple is the field name (if this is '' then a
 standard field name, 'f#', is assigned).
 The field name may also be a 2-tuple of strings where the first string
 is either a 
\begin_inset Quotes eld
\end_inset

title
\begin_inset Quotes erd
\end_inset

 (which may be any string or unicode string) or meta-data for the field
 which can be any object, and the second string is the 
\begin_inset Quotes eld
\end_inset

name
\begin_inset Quotes erd
\end_inset

 which must be a valid Python identifier.
 The second element of the tuple can be anything that can be interpreted
 as a data-type.
 The optional third element of the tuple contains the shape if this field
 represents an array of the data-type in the second element.
 This style does not accept align=1 as it is assumed that all of the memory
 is accounted for by the array interface description.
 See the web-page for more examples.
 Note that a 3-tuple with a third argument equal to 1 is equivalent to a
 2-tuple.
\end_layout

\begin_layout Description
Examples: [('big','>i4'), ('little','<i4')]; [('R','u1'), ('G','u1'), ('B','u1')
, ('A','u1')]
\end_layout

\begin_layout Description
dictionary 
\begin_inset LatexCommand index
name "dtype!construction!from dict"

\end_inset

There are two dictionary styles.
 The first is a standard dictionary format while the second accepted format
 allows the fields attribute of dtype objects to be interpreted as a data-type.
 
\end_layout

\begin_deeper
\begin_layout Enumerate
names and formats: This style has two required and two optional keys.
 The 'names' and 'formats' keys are required.
 Their respective values are equal-length lists with the field names and
 the field formats.
 The field names must be strings and the field formats can be any object
 accepted by dtypedescr constructor.
 The optional keys in the dictionary are 'offsets' and 'titles' and their
 values must each be lists of the same length as the 'names' and 'formats'
 lists.
 The 'offsets' value is a list of integer offsets for each field, while
 the 'titles' value is a list of titles for each field (None can be used
 if no title is desired for that field).
 The titles can be any string or unicode object and will add another entry
 to the fields dictionary keyed by the title and referencing the same field
 tuple which will contain the title as an additional tuple member.
 
\end_layout

\begin_deeper
\begin_layout Description
Examples: {'names': ['r','g','b','a'], 'formats': [uint8, uint8, uint8,
 uint8]}; {'names':['r','b'], 'formats': ['u1', 'u1'], 'offsets': [0, 2],
 'titles': ['Red pixel', 'Blue pixel']}
\end_layout

\end_deeper
\begin_layout Enumerate
data-type object fields: This style is patterned after the format of the
 fields dictionary in a data-type object.
 It contains string or unicode keys that refer to (data-type, offset) or
 (data-type, offset, title) tuples.
 
\end_layout

\begin_deeper
\begin_layout Description
Examples: {'col1': ('S10', 0), 'col2': (float32, 10), 'col3': (int, 14)}
\begin_inset LatexCommand index
name "dtype!construction|)"

\end_inset


\end_layout

\end_deeper
\end_deeper
\end_deeper
\begin_layout Section
Methods
\begin_inset LatexCommand index
name "dtype!methods|("

\end_inset


\end_layout

\begin_layout Description
newbyteorder 
\begin_inset LatexCommand index
name "dtype!methods!newbyteorder"

\end_inset

(<'swap'>)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a new copy of self with its byteorder changed according to the
 optional argument.
 All changes are also propagated to the data-type objects of all fields
 and sub-arrays.
 If a byteorder of '|' (meaning ignore) is encountered it is left unchanged.
 The default behavior is to swap the byteorder.
 Other possible arguments are 'big' ('>'), 'little' ('<'), and 'native'
 ('=') which recursively forces the byteorder of self (and it's field data-type
 objects and any sub-arrays) to the corresponding byteorder.
 
\end_layout

\begin_layout Description
__reduce__
\begin_inset LatexCommand index
name "dtype!methods!\\_\\_reduce\\_\\_"

\end_inset

 ()
\end_layout

\begin_layout Description
__setstate__
\begin_inset LatexCommand index
name "dtype!methods!\\_\\_setstate\\_\\_"

\end_inset

 (state)
\end_layout

\begin_layout Description
\InsetSpace ~
 Data-type objects can be pickled because of these two methods.
 The __reduce__() method returns a 3-tuple consisting of (callable object,
 args, state), where the callable object is numpy.core.multiarray.dtype and
 args is (typestring, 0, 1) unless the data-type inherits from void (or
 is user-defined) in which case args is (typeobj, 0, 1).
 The state is an 8-tuple with (version, endian, self.subdtype, self.names,
 self.fields, self.itemsize, self.alignment, self.flags).
 The self.itemsize and self.alignment entries are both -1 if the data-type
 object is built-in and not flexible (because they are fixed on creation).
 The setstate method takes the saved state and updates the date-type 
\begin_inset LatexCommand index
name "dtype!methods|)"

\end_inset

object.
\begin_inset LatexCommand index
name "dtype|)"

\end_inset


\end_layout

\begin_layout Chapter
Standard Classes
\end_layout

\begin_layout Quotation
To generalize is to be an idiot.
 
\end_layout

\begin_layout Right Address
---
\emph on
William Blake
\end_layout

\begin_layout Quotation
Not everything that can be counted counts, and not everything that counts
 can be counted.
\end_layout

\begin_layout Right Address
---
\emph on
Albert Einstein
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ndarray!subtyping|("

\end_inset

The ndarray in NumPy is a 
\begin_inset Quotes eld
\end_inset

new-style
\begin_inset Quotes erd
\end_inset

 Python built-in-type.
 Therefore, it can be inherited from (in Python or in C) if desired.
 Therefore, it can form a foundation for many useful classes.
 Often whether to sub-class the array object or to simply use the core array
 component as an internal part of a new class is a difficult decision, and
 can be simply a matter of choice.
 NumPy has several tools for simplifying how your new object interacts with
 other array objects, and so the choice may not be significant in the end.
 One way to simplify the question is by asking yourself if the object you
 are interested can be replaced as a single array or does it really require
 two or more arrays at it's core.
 For example, in the standard NumPy distribution, the matrix and records
 classes inherit from the ndarray, while masked arrays use two ndarrays
 as objects of its internal structure.
\end_layout

\begin_layout Standard
Note that asarray(a) always returns the base-class ndarray.
 If you are confident that your use of the array object can handle any subclass
 of an ndarray, then asanyarray(a) can be used to allow subclasses to propagate
 more cleanly through your subroutine.
 In principal a subclass could redefine any aspect of the array and therefore,
 under strict guidelines, asanyarray(a) would rarely be useful.
 However, most subclasses of the arrayobject will not redefine certain aspects
 of the array object such as the buffer interface, or the attributes of
 the array.
 One of important example, however, of why your subroutine may not be able
 to handle an arbitrary subclass of an array is that matrices redefine the
 '*' operator to be matrix-multiplication, rather than element-by-element
 multiplication.
\end_layout

\begin_layout Section
Special attributes and methods recognized by NumPy
\begin_inset LatexCommand index
name "ndarray!attributes!recognized by|("

\end_inset


\end_layout

\begin_layout Description
__array_finalize__ (obj)
\end_layout

\begin_layout Description
\InsetSpace ~
 This method is called whenever the system internally allocates a new array
 from obj, where obj is a subclass (subtype) of the (big)ndarray.
 It can be used to change attributes of self after construction (so as to
 ensure a 2-d matrix for example), or to update meta-information from the
 
\begin_inset Quotes eld
\end_inset

parent.
\begin_inset Quotes erd
\end_inset

 Subclasses inherit a default implementation of this method that does nothing.
\end_layout

\begin_layout Description
__array_wrap__ (array)
\end_layout

\begin_layout Description
\InsetSpace ~
 This method should return an instance of the class from the ndarray object
 passed in.
 For example, this is called after every ufunc for the object with the highest
 __array_priority__.
 The ufunc-computed array object is passed in and whatever is returned is
 passed to the user.
 Subclasses inherit a default implementation of this method.
\end_layout

\begin_layout Description
__array__ (dtype <None>)
\end_layout

\begin_layout Description
\InsetSpace ~
 This method is called to obtain an ndarray object when needed.
 You should always guarantee this returns an actual ndarray object.
 Subclasses inherit a default implementation of this method.
 
\end_layout

\begin_layout Description
__array_priority__
\end_layout

\begin_layout Description
\InsetSpace ~
 The value of this attribute is used to determine what type of object to
 return in situations where there is more than one possibility for the Python
 type of the returned object.
 Subclasses inherit a default value of 1.0 for this attribute.
\begin_inset LatexCommand index
name "ndarray!attributes!recognized by|)"

\end_inset


\begin_inset LatexCommand index
name "ndarray!subtyping|)"

\end_inset


\end_layout

\begin_layout Section
Matrix Objects
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "matrix|("

\end_inset

Matrix objects inherit from the ndarray and therefore, they have the same
 attributes and methods of ndarrays.
 There are six important differences of matrix objects, however that may
 lead to unexpected results when you use matrices but expect them to act
 like arrays:
\end_layout

\begin_layout Enumerate
Matrix objects can be created using a string notation to allow Matlab-style
 syntax where spaces separate columns and semicolons (';') separate rows.
 
\end_layout

\begin_layout Enumerate
Matrix objects are always two-dimensional.
 This has far-reaching implications, in that m.ravel() is still two-dimensional
 (with a 1 in the first dimension) and item selection returns two-dimensional
 objects so that sequence behavior is fundamentally different than arrays.
\end_layout

\begin_layout Enumerate
Matrix objects over-ride multiplication to be matrix-multiplication.
 
\series bold
Make sure you understand this for functions that you may want to receive
 matrices.
 Especially in light of the fact that asanyarray(m) returns a matrix when
 m is a matrix.
\end_layout

\begin_layout Enumerate
Matrix objects over-ride power to be matrix raised to a power.
 The same warning about using power inside a function that uses asanyarray(...)
 to get an array object holds for this fact.
 
\end_layout

\begin_layout Enumerate
The default __array_priority__ of matrix objects is 10.0, and therefore mixed
 operations with ndarrays always produce matrices.
 
\end_layout

\begin_layout Enumerate
Matrices have special attributes which make calculations easier.
 These are
\end_layout

\begin_deeper
\begin_layout Enumerate
.T --- return the transpose of self
\end_layout

\begin_layout Enumerate
.H --- return the conjugate transpose of self
\end_layout

\begin_layout Enumerate
.I --- return the inverse of self
\end_layout

\begin_layout Enumerate
.A --- return a view of the data of self as a 2d array (no copy is done).
\end_layout

\end_deeper
\begin_layout Warning
Matrix objects over-ride multiplication, '*', and power, '**', to be matrix-mult
iplication and matrix power, respectively.
 If your subroutine can accept sub-classes and you do not convert to base-class
 arrays, then you must use the ufuncs multiply and power to be sure that
 you are performing the correct operation for all inputs.
 
\end_layout

\begin_layout Standard
The matrix class is a Python subclass of the ndarray and can be used as
 a reference for how to construct your own subclass of the ndarray.
 Matrices can be created from other matrices, strings, and anything else
 that can be converted to an 
\family typewriter
ndarray
\family default
.
 The name 
\begin_inset Quotes eld
\end_inset

mat
\begin_inset Quotes erd
\end_inset

 is an alias for 
\begin_inset Quotes eld
\end_inset

matrix
\begin_inset Quotes erd
\end_inset

 in NumPy.
\end_layout

\begin_layout Description
Example\InsetSpace ~
1: Matrix creation from a string
\end_layout

\begin_layout MyCode
>>> a=mat('1 2 3; 4 5 3')
\newline
>>> print (a*a.T).I
\newline
[[ 0.2924 -0.1345]
\newline
 [-0.1345  0.0819]]
\end_layout

\begin_layout Description
Example\InsetSpace ~
2: Matrix creation from nested sequence
\end_layout

\begin_layout MyCode
>>> mat([[1,5,10],[1.0,3,4j]])
\newline
matrix([[  1.+0.j,   5.+0.j,  10.+0.j],
\newline
        [
  1.+0.j,   3.+0.j,   0.+4.j]])
\end_layout

\begin_layout Description
Example\InsetSpace ~
3: Matrix creation from an array
\end_layout

\begin_layout MyCode
>>> mat(random.rand(3,3)).T
\newline
matrix([[ 0.7699,  0.7922,  0.3294],
\newline
        [ 0.2792,
  0.0101,  0.9219],
\newline
        [ 0.3398,  0.7571,  0.8197]])
\end_layout

\begin_layout Description
matrix (data, dtype=None, copy=True)
\end_layout

\begin_layout Description
\InsetSpace ~
 The sequence to convert to a matrix is passed in as data.
 If dtype is None, then the data-type is determined from the data.
 If copy is True, then a copy of the data is made, otherwise, the same data
 buffer is used.
 If no buffer can be found for data, then a copy is also made.
 Note: The matrix object is actually a class and so using this syntax calls
 matrix.__new__(matrix, data, dtype, copy) which is what happens whenever
 you 
\begin_inset Quotes eld
\end_inset

call
\begin_inset Quotes erd
\end_inset

 any class object as a function.
\end_layout

\begin_layout Description
mat 
\end_layout

\begin_layout Description
\InsetSpace ~
 Just another name for matrix.
\end_layout

\begin_layout Description
asmatrix (data, dtype=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the data without copying.
 Equivalent to matrix(data, dtype, copy=False).
\end_layout

\begin_layout Description
bmat (obj, ldict=None, gdict=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Build a matrix object from a string, nested sequence or an array.
 This command lets you build up matrices from other other objects.
 The ldict and gdict parameters are local and module (global) dictionaries
 that are only used when obj is a string.
 If they are not provided, then the local and module dictionaries present
 when bmat is called are used.
\begin_inset LatexCommand index
name "matrix|)"

\end_inset


\end_layout

\begin_layout MyCode
>>> A = mat('2 2; 2 2'); B=mat('1 1; 1 1');
\newline
>>> print bmat('A B; B A')
\newline
[[2
 2 1 1]
\newline
 [2 2 1 1]
\newline
 [1 1 2 2]
\newline
 [1 1 2 2]]
\end_layout

\begin_layout Section
Memory-mapped-file arrays
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "memory maps|("

\end_inset

Memory-mapped files are useful for reading and/or modifying small segments
 of a large file with regular layout, without reading the entire file into
 memory.
 A simple subclass of the ndarray uses a memory-mapped file for the data
 buffer of the array.
 For small files, the over-head of reading the entire file into memory is
 typically not significant, however for large files using memory mapping
 can save considerable resources.
 
\end_layout

\begin_layout Note
Memory-mapped arrays use the the Python memory-map object which (prior to
 Python 2.5) does not allow files to be larger than a certain size depending
 on the platform.
 This size is always < 2GB even on 64-bit systems.
 
\end_layout

\begin_layout Standard
The class is called memmap and is available in the NumPy namespace.
 The __new__ method of the class has been re-written to have the following
 syntax:
\end_layout

\begin_layout Description
__new__ (cls, filename, dtype=uint8, mode='r+', offset=0, shape=None, order=0)
 
\end_layout

\begin_deeper
\begin_layout Description
filename The file name to be used as the array data buffer
\end_layout

\begin_layout Description
dtype A data-type object used to interpret the file contents (including
 byteorder).
\end_layout

\begin_layout Description
mode The mode to open the file in.
 Valid modes are 'readonly' or 'r', 'copyonwrite' or 'c', 'readwrite' or
 'r+', and 'write' or 'w+'.
 This mode determines the WRITEABLE flag of the returned array.
\end_layout

\begin_layout Description
offset An offset into the file to start the array data.
\end_layout

\begin_layout Description
shape The desired shape of the array.
 If this is None, then the returned array will be 1-d with the number of
 elements determined by the file size and data type.
\end_layout

\begin_layout Description
order Either 'C' or 'Fortran' to indicate the order that an N-D array should
 be interpreted.
 This only has an effect if the shape is greater than 2-D.
\end_layout

\end_deeper
\begin_layout Standard
Memory-mapped-file arrays have one additional method (besides those they
 inherit from the ndarray): self.
\series bold
flush
\series default
() which can be called manually by the user to ensure that any changes to
 the array actually get written to disk. This also occurs on deleting
 the memmap object
 
\end_layout

\begin_layout Description
Example: 
\end_layout

\begin_layout MyCode
>>> a = memmap('newfile.dat', dtype=float, mode='w+', shape=1000)
\newline
>>> a[10]
 = 10.0
\newline
>>> a[30] = 30.0
\newline
>>> del a
\newline
>>> b = fromfile('newfile.dat', dtype=float)
\newline
>>>
 print b[10], b[30]
\newline
10.0 30.0
\newline
>>> a = memmap('newfile.dat', dtype=float)
\newline
>>> print
 a[10], a[30]
\newline
10.0 30.0
\end_layout

\begin_layout Section
Character arrays (numpy.char)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "character arrays|("

\end_inset

These are enhanced arrays of either string type or unicode_ type.
 These arrays inherit from the ndarray, but specially-define the operations
 +, *, and % on a (broadcasting) element-by-element basis.
 These operations are not available on the standard ndarray of character
 type.
 In addition, the chararray has all of the standard string (and unicode)
 methods, executing them on an element-by-element basis.
 Perhaps the easiest way to create a chararray is to use self.view(chararray)
 where self is an ndarray of string or unicode data-type.
 However, a chararray can also be created using the numpy.chararray.__new__
 method.
\end_layout

\begin_layout Description
__new__ (shape, itemsize, unicode=False, buffer=None, offset=0, strides=None,
 order=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Create a new character array of string or unicode type and itemsize characters.
 Create the array using buffer (with offset and strides) if it is not None.
 If buffer is None, then construct a new array with strides in Fortran order
 if len(shape) >=2 and order is 'Fortran' (otherwise the strides will be
 in 'C' order).
 
\end_layout

\begin_layout Description
char.array (obj, itemsize=None, copy=True, unicode=False, order=None) 
\end_layout

\begin_layout Description
\InsetSpace ~
 Create a chararray from the nested sequence obj.
 If obj is an ndarray of data-type unicode_ or string, then its data is
 wrapped by the chararray object and converted to the desired type (string
 or unicode).
 
\end_layout

\begin_layout Standard
Another difference with the standard ndarray of string data-type is that
 the chararray inherits the feature introduced by Numarray that white-space
 at the end of any element in the array will be ignored on item retrieval
 and comparison operations.
 
\begin_inset LatexCommand index
name "character arrays|)"

\end_inset


\end_layout

\begin_layout Section
Record Arrays (numpy.rec)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "record arrays|("

\end_inset

NumPy provides a powerful data-type object that allows any ndarray to hold
 (arbitrarily nested) record-like items with named-field access to the sub-types.
 This is possible without any special record-array sub-class.
 Consider the example where each item in the array is a simple record of
 name, age, and weight.
 You could specify a data-type for an array of such records using the following
 data-type object:
\end_layout

\begin_layout MyCode
>>> desc = dtype({'names': ['name', 'age', 'weight'], 'formats': ['S30',
 'i2', 'f4']})
\newline
>>> a = array([('Bill',31,260.0),('Fred', 15, 145.0)],dtype=desc)
\newline
>>>
 print a[0]
\newline
('Bill', 31, 260.0)
\newline
>>> print a['name']
\newline
['Bill' 'Fred']
\newline
>>> print
 a['age']
\newline
[31 15]
\newline
>>> print a['weight']
\newline
[ 260.
  145.]
\newline
>>> print a[0]['name'], a[0]['age'], a[0]['weight']
\newline
Bill 31 260.0
\newline
>>>
 print len(a[0])
\newline
3
\end_layout

\begin_layout Standard
This example shows how a general array can be assigned named fields and
 how these fields can be accessed.
 In this case the a[0] object is an array-scalar of type void.
 The void array-scalars are unique in that they contain references to (rather
 than copies of) the underlying data whenever fields are defined.
 Therefore, the record data can be modified in place:
\end_layout

\begin_layout MyCode
>>> a[0]['name'] = 'George'; print a
\newline
[('George', 31, 260.0) ('Fred', 15, 145.0)]
\end_layout

\begin_layout Standard
The recarray subclass and its accompanying record item add the ability to
 access named fields through attribute lookup.
 A quick way to get a record array is to use the view method of the ndarray.
 
\end_layout

\begin_layout MyCode
>>> r = a.view(recarray)
\newline
>>> print r.name
\newline
['George' 'Fred']
\end_layout

\begin_layout Standard
The numpy.core.records module (aliased to nump.rec when numpy is imported)
 contains additional convenience functions for constructing record arrays.
 All of the following constructors have two different mechanisms for specifying
 the data-type.
 Either the dtype= argument can be specified or the argument formats= can
 be specified along with an optional set of four additional keyword arguments
 (names=, titles=, aligned= and byteorder=).
 In some cases neither dtype= nor formats= is required as the data-type
 can be inferred from the object passed in as the first argument.
\end_layout

\begin_layout Standard
The five argument method for specifying a data-type constructs a data-type
 object internally.
 The comma-separated formats string is used to specify the fields.
 The names (and optional titles) of the fields can be specified by a comma-separ
ated string of names (or titles).
 The aligned flag determines whether the fields are packed (False) or padded
 (True) according to the platform compiler rules.
 The byteorder argument allows specification of the byte-order for all of
 the fields at once (they can also be specified individually in the formats
 string).
 The default byte-order is native to the platform.
 
\end_layout

\begin_layout Description
array (obj, dtype=None, shape=None, offset=0, strides=None, formats=None,
 names=None, titles=None, aligned=False, byteorder=None, copy=True)
\end_layout

\begin_layout Description
\InsetSpace ~
 A general-purpose record array constructor that is a front-end to the other
 constructors If obj is None, then call the 
\series bold
recarray
\series default
 constructor.
 If obj is a string, then call the 
\series bold
fromstring
\series default
 constructor.
 If obj is a list or a tuple then if the first object is an ndarray, then
 call 
\series bold
fromarrays
\series default
, otherwise call 
\series bold
fromrecords
\series default
.
 If obj is a recarray, then make a copy of the data in recarray (if copy
 is True) and use the new formats, names, and titles.
 If obj is a file then call 
\series bold
fromfile
\series default
.
 Finally, if obj is an ndarray, then return obj.view(recarray) and make a
 copy of the data if copy is True.
 Otherwise, call the __array_interface__ attribute and try to convert using
 the information returned from that object.
 Either dtype or the formats argument must be given if obj is None, a string,
 or a file, and if obj is None so the recarray constructor will be called,
 then shape must be given as well.
 
\end_layout

\begin_layout Description
fromarrays (array_list, dtype=None, shape=None, formats=None, names=None,
 titles=None, aligned=False, byteorder=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Create a record array from a (flat) list of ndarrays.
 The data from the arrays will be copied into the fields.
 If formats is None and dtype is None, then the formats will be determined
 from the arrays.
 The names and titles arguments can be a list, tuple or a (comma-separated)
 string specifying the names and/or titles to use for the fields.
 If aligned is True, then the structure will be padded according to the
 rules of the compiler that NumPy was compiled with.
\end_layout

\begin_layout MyCode
>>> x1 = array([21,32,14])
\newline
>>> x2 = array(['my','first','name'])
\newline
>>> x3 =
 array([3.1, 4.5, 6.2])
\newline
>>> r = rec.fromarrays([x1,x2,x3], names='id, word, number')
\newline
>
>> print r[1]
\newline
(32, 'first', 4.5)
\newline
>>> r.number
\newline
array([ 3.1,  4.5,  6.2])
\newline
>>> r.word
\newline
chararra
y(['my', 'first', 'name'], 
\newline
      dtype='|S5')
\end_layout

\begin_layout Description
fromrecords (rec_list, dtype=None, shape=None, formats=None, names=None,
 titles=None, aligned=False, byteorder=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a record array from a (nested) sequence of tuples that define
 the records.
 If formats are not given, they are deduced from the records, but this is
 slower.
 The field names and field titles can be specified.
 If aligned is non-zero, then the record array is padded so that fields
 are aligned as the platform compiler would do if the fields represented
 a C-struct.
\end_layout

\begin_layout MyCode
>>> recs = [('Bill', 31, 260.0), ('Fred', 15, 145.0)]
\newline
>>> r = rec.fromrecords(recs,
 formats='S30,i2,f4', names='name, age, weight')
\newline
>>> print r.name
\newline
['Bill' 'Fred']
\newline
>>
> print r.age
\newline
[31 15]
\newline
>>> print r.weight
\newline
[ 260.
  145.]
\end_layout

\begin_layout Description
fromstring (datastring, dtype=None, shape=None, offset=0, formats=None,
 names=None, titles=None, aligned=0, byteorder=None):
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a record array using the provided datastring (at the given offset)
 as the memory.
 The record array will be read-only.
 The byteorder argument may be used to specify the byteorder of all of the
 fields at the same time.
 A True aligned argument causes padding fields to be added as needed so
 that the fields are aligned on boundaries determined by the compiler.
 The shape of the returned array can also be specified.
 
\end_layout

\begin_layout Description
fromfile (fd, dtype=None, shape=None, offset=0, formats=None, names=None,
 titles=None, aligned=False, byteorder=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a record array from the (binary) data in the given file object,
 fd.
 This object may be an open file or a string to indicate a file to read
 from.
 If offset is non-zero, then data is read from the file at offset bytes
 from the current position.
 
\end_layout

\begin_layout Standard
The following classes are also available in the numpy.core (and therefore
 the numpy) namespace
\end_layout

\begin_layout Description
record A subclass of the void array scalar type that allows field access
 using attributes.
 
\end_layout

\begin_layout Description
recarray A subclass of the ndarray that allows field access using attributes
\end_layout

\begin_deeper
\begin_layout Description
__new__ (subtype, shape, formats, names=None, titles=None, buf=None, offset=0,
 strides=None, byteorder=None, aligned=0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct an array of the given subtype and shape with data-type (record,
 dtype) where dtype is constructed from formats, names, and titles.
 If buf is None, then create new memory.
 Otherwise, use the memory of buf exposed through the buffer protocol.
\end_layout

\end_deeper
\begin_layout Description
format_parser A class useful for creating a data-type descriptor from formats,
 names, titles, and aligned arguments.
 This is used by several of the record array constructors for consistency
 in behavior.
 
\end_layout

\begin_deeper
\begin_layout Description
__init__ (self, formats, names, titles, aligned=False, byteorder=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Construct a data-type object from formats, names, titles, aligned, and
 byteorder arguments.
 Upon completion the constructed data-type object is in self._descr.
 
\begin_inset LatexCommand index
name "record arrays|)"

\end_inset


\end_layout

\end_deeper
\begin_layout Section
Masked Arrays (numpy.ma)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "masked arrays|("

\end_inset

These are adapted from the masked arrays provided with Numeric.
 Masked Arrays do not inherit from the ndarray, they simply use two ndarray
 objects in their internal representation.
 Fortunately, as I have not used masked arrays in my work, Paul Dubois (the
 original author of MA for Numeric) adapted and modified the code for use
 by NumPy.
 Alexander Belopolsky (Sasha) added additional functions and improvements
 
\end_layout

\begin_layout Standard
Masked arrays are created using the masked array creation function.
 
\end_layout

\begin_layout Description
ma.array (data, dtype=None, copy=True, order='C', mask=ma.nomask, fill_value=None)
\end_layout

\begin_deeper
\begin_layout Description
data Something that can be converted to an array.
 If data is already a masked array, then if mask is ma.nomask, the mask used
 be data.mask and the data used data.data.
 
\end_layout

\begin_layout Description
dtype The data-type of the underlying array
\end_layout

\begin_layout Description
copy If copy is False, then every effort will be made to not copy the data.
 
\end_layout

\begin_layout Description
order Specify whether the array is in 'C', 'Fortran', or 'Any' order 
\end_layout

\begin_layout Description
mask Masked values are excluded from calculations.
 If this is ma.nomask, then there are no masked values.
 Otherwise, this should be an object that is convertible to an array of
 Booleans with the same shape as data.
\end_layout

\begin_layout Description
fill_value This value is used to fill in masked values when necessary.
 The fill_value is not used for computation for functions within the ma
 module.
\end_layout

\end_deeper
\begin_layout Standard
Masked arrays have the same methods and attributes as arrays with the addition
 of the mask attribute as well as the 
\begin_inset Quotes eld
\end_inset

hidden
\begin_inset Quotes erd
\end_inset

 attributes ._data and ._mask.
 
\begin_inset LatexCommand index
name "masked arrays|)"

\end_inset


\end_layout

\begin_layout Section
Standard container class
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "user\\_array"

\end_inset


\begin_inset LatexCommand index
name "container class"

\end_inset

For backward compatibility and as a standard 
\begin_inset Quotes eld
\end_inset

container
\begin_inset Quotes erd
\end_inset

 class, the UserArray from Numeric has been brought over to NumPy and named
 
\series bold
numpy.lib.user_array.container
\series default
 The container class is a Python class whose self.array attribute is an ndarray.
 Multiple inheritance is probably easier with numpy.lib.user_array.container
 than with the ndarray itself and so it is included by default.
 It is not documented here beyond mentioning its existence because you are
 encouraged to use the ndarray class directly if you can.
 
\end_layout

\begin_layout Section
Array Iterators
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "array iterator"

\end_inset

Iterators are a powerful concept for array processing.
 Essentially, iterators implement a generalized for-loop.
 If myiter is an iterator object, then the Python code
\end_layout

\begin_layout LyX-Code
for val in myiter:
\end_layout

\begin_layout LyX-Code
    ...
\end_layout

\begin_layout LyX-Code
    some code involving val
\end_layout

\begin_layout LyX-Code
    ...
\end_layout

\begin_layout Standard
calls val=myiter.next() repeatedly until StopIteration is raised by the iterator.
 There are several ways to iterate over an array that may be useful: default
 iteration, flat iteration, and 
\begin_inset Formula $N$
\end_inset

-dimensional enumeration.
\end_layout

\begin_layout Subsection
Default iteration
\end_layout

\begin_layout Standard
The default iterator of an ndarray object is the default Python iterator
 of a sequence type.
 Thus, when the array object itself is used as an iterator.
 The default behavior is equivalent to:
\end_layout

\begin_layout LyX-Code
for i in arr.shape[0]:
\end_layout

\begin_layout LyX-Code
    val = arr[i]
\end_layout

\begin_layout Standard
This default iterator selects a sub-array of dimension 
\begin_inset Formula $N-1$
\end_inset

 from the array.
 This can be a useful construct for defining recursive algorithms.
 To loop over the entire array requires 
\begin_inset Formula $N$
\end_inset

 for-loops.
 
\end_layout

\begin_layout MyCode
>>> a = arange(24).reshape(3,2,4)+10
\newline
>>> for val in a:
\newline
...
     print 'item:', val
\newline
item: [[10 11 12 13]
\newline
 [14 15 16 17]]
\newline
item: [[18 19
 20 21]
\newline
 [22 23 24 25]]
\newline
item: [[26 27 28 29]
\newline
 [30 31 32 33]]
\end_layout

\begin_layout Subsection
Flat iteration
\end_layout

\begin_layout Standard
As mentioned previously, the flat attribute of ndarray objects returns an
 iterator that will cycle over the entire array in C-style contiguous order.
 
\end_layout

\begin_layout MyCode
>>> for i, val in enumerate(a.flat):
\newline
...
     if i%5 == 0: print i, val
\newline
0 10
\newline
5 15
\newline
10 20
\newline
15 25
\newline
20 30
\end_layout

\begin_layout Standard
Here, I've used the built-in enumerate iterator to return the iterator index
 as well as the value.
\end_layout

\begin_layout Subsection
N-dimensional enumeration
\end_layout

\begin_layout Standard
Sometimes it may be useful to get the N-dimensional index while iterating.
 The ndenumerate iterator can achieve this.
\end_layout

\begin_layout MyCode
>>> for i, val in ndenumerate(a):
\newline
...
     if sum(i)%5 == 0: print i, val
\newline
(0, 0, 0) 10
\newline
(1, 1, 3) 25
\newline
(2, 0, 3) 29
\newline
(2,
 1, 2) 32
\end_layout

\begin_layout Subsection
Iterator for broadcasting
\end_layout

\begin_layout Standard
The general concept of broadcasting is also available from Python using
 the 
\series bold
broadcast
\series default
 iterator.
 This object takes 
\begin_inset Formula $N$
\end_inset

 objects as inputs and returns an iterator that returns tuples providing
 each of the input sequence elements in the broadcasted result.
\end_layout

\begin_layout MyCode
>>> for val in broadcast([[1,0],[2,3]],[0,1]):
\newline
...
     print val
\newline
(1, 0)
\newline
(0, 1)
\newline
(2, 0)
\newline
(3, 1)
\end_layout

\begin_layout Description
\InsetSpace ~
 The methods and attributes of the broadcast object are:
\end_layout

\begin_deeper
\begin_layout Description
nd the number of dimensions in the broadcasted result.
\end_layout

\begin_layout Description
shape the shape of the broadcasted result.
\end_layout

\begin_layout Description
size the total size of the broadcasted result.
\end_layout

\begin_layout Description
index the current (flat) index into the broadcasted array
\end_layout

\begin_layout Description
iters a tuple of (broadcasted) NumPy.flatiter objects, one for each array.
\end_layout

\begin_layout Description
reset ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Reset the multiter object to the beginning.
\end_layout

\begin_layout Description
next ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Get the next tuple of objects from the (broadcasted) arrays
\end_layout

\end_deeper
\begin_layout Chapter
Universal Functions
\end_layout

\begin_layout Standard
\begin_inset LatexCommand label
name "par:The-Ufunc-Object"

\end_inset


\end_layout

\begin_layout Quotation
Computers make it easier to do a lot of things, but most of the things they
 make it easier to do don't need to be done.
\end_layout

\begin_layout Right Address
---
\emph on
Andy Rooney
\end_layout

\begin_layout Quotation
People think computers will keep them from making mistakes.
 They're wrong.
 With computers you make mistakes faster.
\end_layout

\begin_layout Right Address
---
\emph on
Adam Osborne
\end_layout

\begin_layout Section
Description
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ufunc|("

\end_inset

Universal functions are wrappers that provide a common interface to mathematical
 functions that operate on scalars, and can be made to operate on arrays
 in an element-by-element fashion.
 All 
\family typewriter
u
\family default
niversal 
\family typewriter
func
\family default
tion
\family typewriter
s
\family default
 (
\family typewriter
ufuncs
\family default
) wrap some core function that takes 
\begin_inset Formula $n_{i}$
\end_inset

 (scalar) inputs and produces 
\begin_inset Formula $n_{o}$
\end_inset

 (scalar) outputs.
 Typically, this core function is implemented in compiled code but a Python
 function can also be wrapped into a universal function using the basic
 method 
\family typewriter
frompyfunc
\family default
 in the umath module.
 
\end_layout

\begin_layout Description
frompyfunc (func, nin, nout)
\begin_inset LatexCommand index
name "frompyfunc"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 This function returns a new universal function wrapping a Python function
 func with nin inputs and nout outputs.
 The resulting universal function works using Object arrays for both input
 and output.
 The vectorize class makes use of frompyfunc internally.
 You can view the source code using numpy.source(numpy.vectorize).
\end_layout

\begin_layout Subsection
Broadcasting
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "broadcasting"

\end_inset

Each universal function takes array inputs and produces array outputs by
 performing the core function element-wise on the inputs.
 The standard broadcasting rules are applied so that inputs without exactly
 the same shapes can still be usefully operated on.
 Broadcasting can be understood by four rules:
\end_layout

\begin_layout Enumerate
All input arrays with ndim smaller than the input array of largest ndim
 have 1's pre-pended to their shapes.
\end_layout

\begin_layout Enumerate
The size in each dimension of the output shape is the maximum of all the
 input shapes in that dimension.
\end_layout

\begin_layout Enumerate
An input can be used in the calculation if it's shape in a particular dimension
 either matches the output shape or has value exactly 1.
\end_layout

\begin_layout Enumerate
If an input has a dimension size of 1 in its shape, the first data entry
 in that dimension will be used for all calculations along that dimension.
 In other words, the stepping machinery of the ufunc will simply not step
 along that dimension when otherwise needed (the stride will be 0 for that
 dimension).
 
\end_layout

\begin_layout Standard
While perhaps a bit difficult to explain, broadcasting can be quite useful
 and becomes second nature rather quickly.
 Broadcasting is used throughout NumPy to decide how to handle non equally-shape
d arrays.
 
\end_layout

\begin_layout Subsection
Output type determination
\end_layout

\begin_layout Standard
The output of the ufunc (and its methods) does not have to be an ndarray.
 All output arrays will be passed to the __array_wrap__ method of any input
 (besides ndarrays, and scalars) that defines it 
\series bold
and
\series default
 has the highest __array_priority__ of any other input to the universal
 function.
 The default __array_priority__ of the ndarray is 0.0, and the default __array_pr
iority__ of a subtype is 1.0.
 Matrices have __array_priority__ equal to 10.0.
 
\end_layout

\begin_layout Standard
The ufuncs can also all take output arguments.
 The output will be cast if necessary to the provided output array.
 If a class with an __array__ method is used for the output, results will
 be written to the object returned by __array__.
 Then, if the class also has an __array_wrap__ method, the returned 
\family typewriter
ndarray
\family default
 result will be passed to that method just before passing control back to
 the caller.
 
\end_layout

\begin_layout Subsection
Use of internal buffers
\end_layout

\begin_layout Standard
Internally, buffers are used for misaligned data, swapped data, and data
 that has to be converted from one data type to another.
 The size of the internal buffers is settable on a per-thread basis.
 There can be up to 
\begin_inset Formula $2\left(n_{i}+n_{o}\right)$
\end_inset

 buffers of the specified size created to handle the data from all the inputs
 and outputs of a ufunc.
 The default size of the buffer is 10,000 elements.
 Whenever buffer-based calculation would be needed, but all input arrays
 are smaller than the buffer size, those misbehaved or incorrect typed arrays
 will be copied before the calculation proceeds.
 Adjusting the size of the buffer may therefore alter the speed at which
 ufunc calculations of various sorts are completed.
 A simple interface for setting this variable is accessible using the function
 
\end_layout

\begin_layout Description
setbufsize (size)
\begin_inset LatexCommand index
name "setbufsize"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Set the buffer size to the given number of elements in the current thread.
 Return the old buffer size (so that it can be reset later if desired).
 
\end_layout

\begin_layout Subsection
Error handling
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "error handling"

\end_inset

Universal functions can trip special floating point status registers in
 your hardware (such as divide-by-zero).
 If available on your platform, these registers will be regularly checked
 during calculation.
 The user can determine what should be done if errors are encountered.
 Error handling is controlled on a per-thread basis.
 Four errors can be individually configured: divide-by-zero, overflow, underflow
, and invalid.
 The errors can each be set to ignore, warn, raise, or call.
 The easiest way to configure the error mask is using the function 
\end_layout

\begin_layout Description
seterr (all=None, divide=None, over=None, under=None, invalid=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "seterr"

\end_inset

This will set the current thread so that errors can be handled if desired.
 If one of the errors is set to 'call', then a function must be provided
 using the seterrcall() routine.
 If any of the arguments are None, then that error mask will be unchanged.
 The return value of this function is a dictionary with the old error conditions.
 Thus, you can restore the old condition after you are finished with your
 function by calling seterr(**old).
 If all is set, then all errors will be set to the specified value.
 
\end_layout

\begin_layout Description
seterrcall (callable)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "seterrcall"

\end_inset

This sets the function to call when an error is triggered for an error condition
 configured with the 
\begin_inset Quotes eld
\end_inset

call
\begin_inset Quotes erd
\end_inset

 handler.
 This function should take two arguments: a string showing the type of error
 that triggered the call, and an integer showing the state of the floating
 point status registers.
 Any return value of the call function will be ignored, but errors can be
 raised by the function.
 Only one error function handler can be specified for all the errors.
 The status argument shows which errors were raised.
 The return value of this routine is the old callable.
 The argument passed in to this function must be any callable object with
 the right signature or None.
 
\end_layout

\begin_layout Note
FPE_DIVIDEBYZERO, FPE_OVERFLOW, FPE_UNDERFLOW, and FPE_INVALID, are all
 defined constants in NumPy.
 The status flag returned for a 'call' error handling type shows which errors
 were raised by adding these constants together.
\end_layout

\begin_layout Subsection
Optional keyword arguments
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ufunc!keyword arguments"

\end_inset

All ufuncs take optional keyword arguments.
 These represent rather advanced usage and will likely not be used by most
 users.
 
\end_layout

\begin_layout Description
sig= either a data-type, a tuple of data-types, or a special signature string
 indicating the input and output types of a ufunc.
 This argument allows you to specify a specific signature for a the 1-d
 loop to use in the underlying calculation.
 If the loop specified does not exist for the ufunc, then a TypeError is
 raised.
 Normally a suitable loop is found automatically by comparing the input
 types with what is available and searching for a loop with data-types to
 which all inputs can be cast safely.
 This key-word argument lets you by-pass that search and choose a loop you
 want.
 A list of available signatures is available in the 
\series bold
types
\series default
 attribute of the ufunc object.
 
\end_layout

\begin_layout Description
extobj= a list of length 1, 2, or 3 specifying the ufunc buffer-size, the
 error mode integer, and the error call-back function.
 Normally, these values are looked-up in a thread-specific dictionary.
 Passing them here bypasses that look-up and uses the low-level specification
 provided for the error-mode.
 This may be useful as an optimization for calculations requiring lots of
 ufuncs on small arrays in a loop.
 
\end_layout

\begin_layout Section
Attributes
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ufunc!attributes"

\end_inset

There are some informational attributes that universal functions possess.
 None of the attributes can be set.
 
\end_layout

\begin_layout Description
__doc__
\end_layout

\begin_layout Description
\InsetSpace ~
 A docstring for each ufunc.
 The first part of the docstring is dynamically generated from the number
 of outputs, the name, and the number of inputs.
 The second part of the doc string is provided at creation time and stored
 with the ufunc.
 
\end_layout

\begin_layout Description
__name__
\end_layout

\begin_layout Description
\InsetSpace ~
 The name of this ufunc.
\end_layout

\begin_layout Description
nin 
\end_layout

\begin_layout Description
\InsetSpace ~
 The number of inputs
\end_layout

\begin_layout Description
nout
\end_layout

\begin_layout Description
\InsetSpace ~
 The number of outputs
\end_layout

\begin_layout Description
nargs
\end_layout

\begin_layout Description
\InsetSpace ~
 The total number of inputs + outputs
\end_layout

\begin_layout Description
ntypes
\end_layout

\begin_layout Description
\InsetSpace ~
 The total number of different types for which this ufunc is defined.
\end_layout

\begin_layout Description
types
\end_layout

\begin_layout Description
\InsetSpace ~
 A list of length ntypes containing strings showing the types for which
 this ufunc is defined.
 Other types may still be used as inputs (and as output arrays), they will
 just need casting.
 For inputs, standard casting rules will be used to determine which of the
 supplied internal functions that will be used (and therefore the default
 type of the output).
 Results will always be force-cast to any array provided to hold the output.
 
\end_layout

\begin_layout Description
identity
\end_layout

\begin_layout Description
\InsetSpace ~
 A 1, 0, or None to show the identity for this universal function.
 This identity is used for reduction on zero-sized arrays (arrays with a
 shape that includes a 0).
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Universal function (ufunc) attributes.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="9" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Name
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Description
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
__doc__
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Dynamic docstring.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
__name__
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Name of ufunc
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
nin
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Number of input arguments
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
nout
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Number of output arguments
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
nargs
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Total number of arguments
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ntypes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Number of defined inner loops.
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
types
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
List showing types for which inner loop is defined.
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
identity
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Identity for this ufunc.
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Casting Rules
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ufunc!casting rules"

\end_inset

At the core of every ufunc is a one-dimensional strided loop that implements
 the actual function for a specific type combination.
 When a ufunc is created, it is given a static list of inner loops and a
 corresponding list of type signatures over which the ufunc operates.
 The ufunc machinery uses this list to determine which inner loop to use
 for a particular case.
 You can inspect the 
\family typewriter
.types
\family default
 attribute for a particular ufunc to see which type combinations have a
 defined inner loop and which output type they produce (the character codes
 are used in that output for brevity).
 
\end_layout

\begin_layout Standard
Casting must be done on one or more of the inputs whenever the ufunc does
 not have a core loop implementation for the input types provided.
 If an implementation for the input types cannot be found, then the algorithm
 searches for an implementation with a type signature to which all of the
 inputs can be cast 
\begin_inset Quotes eld
\end_inset

safely.
\begin_inset Quotes erd
\end_inset

 The first one it finds in its internal list of loops is selected and performed
 with types cast.
 Recall that internal copies during ufuncs (even for casting) are limited
 to the size of an internal buffer which is user settable.
 
\end_layout

\begin_layout Note
Universal functions in NumPy are flexible enough to have mixed type signatures.
 Thus, for example, a universal function could be defined that works with
 floating point and integer values.
 See ldexp for an example.
\end_layout

\begin_layout Standard
By the above description, the casting rules are essentially implemented
 by the question of when a data type can be cast 
\begin_inset Quotes eld
\end_inset

safely
\begin_inset Quotes erd
\end_inset

 to another data type.
 The answer to this question can be determined in Python with a function
 call: can_cast (fromtype, totype).
 Figure shows the results of this call for my 32-bit system on the 21 internally
 supported types.
 You can generate this table for your system with code shown in that Figure.
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout MyCode
>>> def print_table(ntypes):
\newline
...
     print 'X',
\newline
...
     for char in ntypes: print char,
\newline
...
     print
\newline
...
     for row in ntypes:
\newline
...
         print row,
\newline
...
         for col in ntypes:
\newline
...
             print int(can_cast(row, col)),
\newline
...
         print
\newline
>>> print_table(typecodes['All'])
\newline
X ? b h i l q p B H I L Q
 P f d g F D G S U V O
\newline
? 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
\newline
b 0
 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1
\newline
h 0 0 1 1 1 1 1 0 0 0 0 0 0
 1 1 1 1 1 1 1 1 1 1
\newline
i 0 0 0 1 1 1 1 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1
\newline
l 0 0
 0 1 1 1 1 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1
\newline
q 0 0 0 0 0 1 0 0 0 0 0 0 0 0
 1 1 0 1 1 1 1 1 1
\newline
p 0 0 0 1 1 1 1 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1
\newline
B 0 0 1
 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
\newline
H 0 0 0 1 1 1 1 0 1 1 1 1 1 1 1
 1 1 1 1 1 1 1 1
\newline
I 0 0 0 0 0 1 0 0 0 1 1 1 1 0 1 1 0 1 1 1 1 1 1
\newline
L 0 0 0 0
 0 1 0 0 0 1 1 1 1 0 1 1 0 1 1 1 1 1 1
\newline
Q 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1
 0 1 1 1 1 1 1
\newline
P 0 0 0 0 0 1 0 0 0 1 1 1 1 0 1 1 0 1 1 1 1 1 1
\newline
f 0 0 0 0 0
 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1
\newline
d 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0
 1 1 1 1 1 1
\newline
g 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1 1 1 1
\newline
F 0 0 0 0 0 0
 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1
\newline
D 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1
 1 1 1 1 1
\newline
G 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1
\newline
S 0 0 0 0 0 0 0
 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1
\newline
U 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1
\newline
V 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1
\newline
O 0 0 0 0 0 0 0 0
 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1
\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Code segment showing the can cast safely table for a 32-bit system.
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
You should note that, while included in the table for completeness, the
 'S', 'U', and 'V' types cannot be operated on by ufuncs.
 Also, note that on a 64-bit system the integer types may have different
 sizes resulting in a slightly altered table.
 
\end_layout

\begin_layout Standard
Mixed scalar-array operations use a different set of casting rules that
 ensure that a scalar cannot upcast an array unless the scalar is of a fundament
ally different kind of data (
\emph on
i.e.

\emph default
 under a different hierachy in the data type hierarchy) then the array.
 This rule enables you to use scalar constants in your code (which as Python
 types are interpreted accordingly in ufuncs) without worrying about whether
 the precision of the scalar constant will cause upcasting on your large
 (small precision) array.
 
\end_layout

\begin_layout Section
Methods
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ufunc!methods|("

\end_inset

All ufuncs have 4 methods.
 However, these methods only make sense on ufuncs that take two input arguments
 and return one output argument.
 Attempting to call these methods on other ufuncs will cause a 
\family typewriter
ValueError
\family default
.
 The reduce-like methods all take an axis keyword and a dtype keyword, and
 the arrays must all have dimension >= 1.
 The 
\emph on
axis
\emph default
 keyword specifies which axis of the array the reduction will take place
 over and may be negative, but must be an integer.
 The 
\emph on
dtype
\emph default
 keyword allows you to manage a very common problem that arises when naively
 using <op>.reduce.
 Sometimes you may have an array of a certain data type and wish to add
 up all of its elements, but the result does not fit into the data type
 of the array.
 This commonly happens if you have an array of single-byte integers.
 The dtype keyword allows you to alter the data type that the reduction
 takes place over (and therefore the type of the output).
 Thus, you can ensure that the output is a data type with large-enough precision
 to handle your output.
 The responsibility of altering the reduce type is mostly up to you.
 There is one exception: if no dtype is given for a reduction on the 
\begin_inset Quotes eld
\end_inset

add
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

multiply
\begin_inset Quotes erd
\end_inset

 operations, then if the input type is an integer (or boolean) data-type
 and smaller than the size of the int_ data type, it will be internally
 upcast to the int_ (or uint) data type.
 
\end_layout

\begin_layout Warning
A reduce-like operation on an array with a data type that has range 
\begin_inset Quotes eld
\end_inset

too small
\begin_inset Quotes erd
\end_inset

 to handle the result will silently wrap.
 You should use dtype to increase the data type over which reduction takes
 place.
\end_layout

\begin_layout Subsection
Reduce
\end_layout

\begin_layout Description
<op>.reduce (array=, axis=0, dtype=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "ufunc!methods!reduce"

\end_inset

For each one-dimensional sequence along the 
\emph on
axis
\emph default
 dimension of the array, return a single number resulting from recursively
 applying the operation to succesive elements along that dimension.
 If the input array has 
\begin_inset Formula $N$
\end_inset

 dimensions, then the returned array has 
\begin_inset Formula $N-1$
\end_inset

 dimensions.
 This produces the equivalent of the following Python code :
\end_layout

\begin_layout LyX-Code
>>> indx = [index_exp[:]]*array.ndim
\newline
>>> indx[axis] = 0; N=array.shape[axis]
\newline
>>>
 result = array[indx].astype(dtype)
\newline
>>> for i in range(1,N):
\newline
...
     indx[axis] = i
\newline
...
     <op>(result, array[indx], result)
\end_layout

\begin_layout Description
\InsetSpace ~
 Studying the above code can also help you gain an appreciation for how
 to do generic indexing in Python using 
\family typewriter
index_exp
\family default
.
 For example, if <op> is add, then <op>.reduce produces a summation along
 the given axis.
 If <op> is prod, then a repeated multiply is performed.
\end_layout

\begin_layout Subsection
Accumulate
\end_layout

\begin_layout Description
<op>.accumulate (array=, axis=0, dtype=None) 
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "ufunc!methods!accumulate"

\end_inset

This method is similar to reduce, except it returns an array of the same
 shape as the input, and keeps intermediate calculations.
 The operation is still performed along the access.
 This method underlies the operations of the cumsum and cumprod methods
 of arrays.
 The following Python code implements an equivalent of the accumulate method.
\end_layout

\begin_layout LyX-Code
>>> i1 = [index_exp[:]]*array.ndim
\newline
>>> i2 = [index_exp[:]]*array.ndim
\newline
>>> i1[axis]
 = 0; N=array.shape[axis]
\newline
>>> result = array.astype(dtype)
\newline
>>> for i in range(1,N):
\newline
...
     i1[axis] = i
\newline
...
     i2[axis] = i-1
\newline
...
     <op>(result[i1], array[i1], result[i2])
\end_layout

\begin_layout Subsection
Reduceat
\end_layout

\begin_layout Description
<op>.reduceat (array=, indices=, axis=0, dtype=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "ufunc!methods!reduceat"

\end_inset

This method is a generalization of both reduce and accumulate.
 It offers the ability to reduce along an axis but only between certain
 indices.
 The indices input must be a one dimensional (index) sequence.
 Then, if 
\begin_inset Formula $I_{k}$
\end_inset

 is the 
\begin_inset Formula $k^{\textrm{th}}$
\end_inset

 element of indices, the reduceat method computes <op>.reduce(array[
\begin_inset Formula $I_{k}$
\end_inset

:
\begin_inset Formula $I_{k+1}$
\end_inset

]).
 This formula assumes 
\begin_inset Formula $I_{k+1}>I_{k}$
\end_inset

, and also that 
\begin_inset Formula $I_{k+1}$
\end_inset

 is the length of the input array when 
\begin_inset Formula $I_{k}$
\end_inset

 is the last element.
 There is no requirement that the indices be monotonic.
 If 
\begin_inset Formula $I_{k+1}\leq I_{k},$
\end_inset

 then reduceat simply returns array[
\begin_inset Formula $I_{k}$
\end_inset

] for that particular element of indices.
 In these formulas, we have assumed that array is one dimensional (or axis
 is 0).
 If the array is 
\begin_inset Formula $N$
\end_inset

-dimensional and axis>0, then the index expression needs axis ':' (full
 slice objects) inserted (i.e.
 array[
\begin_inset Formula $\underbrace{:,\ldots,:}_{\textrm{axis}},I_{k}:I_{k+1}$
\end_inset

]).
 The effect is to slice along the axis dimension.
 Equivalent Python code is
\end_layout

\begin_layout LyX-Code
>>> i1 = [index_exp[:]]*array.ndim
\newline
>>> i2 = [index_exp[:]]*array.ndim
\newline
>>> outshape
 = list(array.shape)
\newline
>>> N = array.shape[axis]
\newline
>>> outshape[axis] = len(indices)
\newline
>>>
 result = zeros(outshape, dtype or array.dtype) 
\newline
>>> for k,Ik in enumerate(indices
): 
\newline
...
     i1[axis] = k
\newline
...
     try:
\newline
...
         Ikp1 = indices[k+1]
\newline
...
     except IndexError: 
\newline
...
         Ikp1 = N 
\newline
...
     if (Ikp1 > Ik):
\end_layout

\begin_layout LyX-Code
...
         i2[axis] = index_exp[Ik:Ikp1]
\newline
...
         result[i1] = <op>.reduce(array[i2],axis=axis,dtype=dtype)
\newline
...
     else:
\newline
...
         result[i1] = array[Ik].astype(dtype)
\end_layout

\begin_layout Description
\InsetSpace ~
 The returned array has as many dimensions as the input array, and is the
 same shape except for the 
\emph on
axis
\emph default
 dimension which has shape equal to the length of indices (the number of
 reduce operations that were performed).
 If you ever have a need to compute multiple reductions over portions of
 an array, then (if you can get your mind around what it is doing) reduceat
 may be just what you were looking for.
 
\end_layout

\begin_deeper
\begin_layout Description
Example: Suppose a is a two-dimensional array of shape 
\begin_inset Formula $10\times20$
\end_inset

.
 Then, res=add.reduce (a, [0,3,1]) returns a 
\begin_inset Formula $3\times20$
\end_inset

 array with res[0,:] = add.reduce(a[:,0:3]), res[1,:] = a[:,3], and res[2,:]
 = add.reduce(a[:,1:]).
 
\end_layout

\end_deeper
\begin_layout Subsection
Outer
\end_layout

\begin_layout Description
<op>.outer (a, b)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "ufunc!methods!outer"

\end_inset

This method computes an outer operation on <op>.
 It computes <op>(a2, b2) where a2 is 'a' with b.ndim 1's post-pended to
 it's shape and b2 is 'b' with a.ndim 1's pre-pended to its shape (broadcasting
 takes care of this automatically in the code below).
 The return shape has a.ndim + b.ndim dimensions.
 Equivalent Python code is 
\end_layout

\begin_layout LyX-Code
>>> a.shape += (1,)*b.ndim
\newline
>>> <op>(a,b)
\newline
>>> a = a.squeeze()
\end_layout

\begin_layout Standard
\InsetSpace ~
 Among many other uses, arithmetic tables can be conveniently built using
 outer: 
\begin_inset LatexCommand index
name "ufunc!methods|)"

\end_inset


\end_layout

\begin_layout MyCode
>>> multiply.outer([1,7,9,12],arange(5,12))
\newline
array([[  5,   6,   7,   8,  
 9,  10,  11],
\newline
       [ 35,  42,  49,  56,  63,  70,  77],
\newline
       [ 45,  54,
  63,  72,  81,  90,  99],
\newline
       [ 60,  72,  84,  96, 108, 120, 132]])
\end_layout

\begin_layout Section
Available ufuncs
\end_layout

\begin_layout Standard
There are currently more than 60 universal functions defined on one or more
 types, covering a wide variety of operations.
 Some of these ufuncs are called automatically on arrays when the relevant
 infix notation is used (i.e.
 add(a,b) is called internally when a + b is written and a or b is an ndarray).
 Nonetheless, you may still want to use the ufunc call in order to use the
 optional output argument(s) to place the output(s) in an object (or in
 objects) of your choice.
 
\end_layout

\begin_layout Standard
Recall that each ufunc operates element-by-element.
 Therefore, each ufunc will be described as if acting on a set of scalar
 inputs to return a set of scalar outputs.
\end_layout

\begin_layout Note
The ufunc still returns its output(s) even if you use the optional output
 argument(s).
 
\end_layout

\begin_layout Subsection
Math operations
\end_layout

\begin_layout Description
add (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "add"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=x_{1}+x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1+x2
\family default
 for arrays 
\end_layout

\begin_layout Description
subtract (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

]) 
\begin_inset LatexCommand index
name "subtract"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=x_{1}-x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1-x2
\family default
 for arrays 
\end_layout

\begin_layout Description
multiply (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

]) 
\begin_inset LatexCommand index
name "multiply"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=x_{1}\cdot x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1*x2
\family default
 for arrays.
\end_layout

\begin_layout Description
divide (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "divide"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=x_{1}/x_{2}$
\end_inset

 Integer division results in truncation.
 Floating-point does not.
 Called to implement 
\family typewriter
x1/x2
\family default
 for arrays (when __future__.division is not active).
 
\end_layout

\begin_layout Description
true_divide (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "true\\_divide"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 This version of division always returns an inexact number so that integer
 division returns floating point.
 Called with __future__.division is active to implement 
\family typewriter
x1/x2
\family default
 for arrays.
\end_layout

\begin_layout Description
floor_divide (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "floor\\_divide"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 This version of division always results in truncation of an fractional
 part remaining.
 Called to implement 
\family typewriter
x1//x2
\family default
 for arrays.
\end_layout

\begin_layout Description
negative (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "negative"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=-x$
\end_inset

.
 Called to implement 
\family typewriter
-x
\family default
 for arrays.
\end_layout

\begin_layout Description
power (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "power"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=x_{1}^{x_{2}}$
\end_inset

.
 There is no three-term power ufunc defined.
 This two-term power function is called to implement 
\family typewriter
pow(x1,x2,<any>)
\family default
 or 
\family typewriter
x1**x2
\family default
 for arrays.
 Note that the third term in 
\family typewriter
pow
\family default
 is ignored for array arguments.
\end_layout

\begin_layout Description
remainder (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "remainder"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Returns 
\begin_inset Formula $x-y$
\end_inset

*floor(
\begin_inset Formula $x/y$
\end_inset

).
 Result has the sign of 
\begin_inset Formula $y$
\end_inset

.
 Called to implement 
\family typewriter
x1%x2
\family default
.
\end_layout

\begin_layout Description
mod (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 Same as remainder (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

]).
 
\end_layout

\begin_layout Description
fmod (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $x_{1}=kx_{2}+y$
\end_inset

 where 
\begin_inset Formula $k$
\end_inset

 is the largest integer satisfying this equation.
 Computes C-like 
\begin_inset Formula $x_{1}\%x_{2}$
\end_inset

 element-wise.
 This was the behavior of 
\family typewriter
x1%x2
\family default
 in old Numeric.
\end_layout

\begin_layout Description
absolute (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "absolute"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=\left|x\right|.$
\end_inset

 Called to implement 
\family typewriter
abs(x)
\family default
 for arrays.
 
\end_layout

\begin_layout Description
rint (x, [, y])
\end_layout

\begin_layout Description
\InsetSpace ~
 Round 
\begin_inset Formula $x$
\end_inset

 to the nearest integer.
 Rounds half-way cases to the nearest even integer.
\end_layout

\begin_layout Description
sign (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 Sets 
\begin_inset Formula $y$
\end_inset

 according to 
\begin_inset Formula \[
\textrm{sign}\left(x\right)=\left\{ \begin{array}{cc}
1 & x:>0,\\
0 & x=0,\\
-1 & x<0.\end{array}\right.\]

\end_inset


\end_layout

\begin_layout Description
conj (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "conj"

\end_inset


\end_layout

\begin_layout Description
conjugate (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "conjugate"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=\overline{x}$
\end_inset

; in other words, the complex conjugate of 
\begin_inset Formula $x$
\end_inset

.
\end_layout

\begin_layout Description
exp (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "exp"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=e^{x}.$
\end_inset


\end_layout

\begin_layout Description
log (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "log"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=\log\left(x\right)$
\end_inset

.
 In other words, 
\begin_inset Formula $y$
\end_inset

 is the number so that 
\begin_inset Formula $e^{y}=x$
\end_inset

.
 
\end_layout

\begin_layout Description
expm1 (
\begin_inset Formula $x$
\end_inset

, [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=e^{x}-1.$
\end_inset

 Calculated so that it is accurate for small 
\begin_inset Formula $\left|x\right|.$
\end_inset

 
\end_layout

\begin_layout Description
log1p (
\begin_inset Formula $x$
\end_inset

, [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=\log\left(1+x\right)$
\end_inset

 but accurate for small 
\begin_inset Formula $\left|x\right|.$
\end_inset

 Returns the number 
\begin_inset Formula $y$
\end_inset

 such that 
\begin_inset Formula $e^{y}-1=x$
\end_inset


\end_layout

\begin_layout Description
log10 (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "log10"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=\log10\left(x\right)$
\end_inset

.
 In other words, 
\begin_inset Formula $y$
\end_inset

 is the number so that 
\begin_inset Formula $10^{y}=x.$
\end_inset


\end_layout

\begin_layout Description
sqrt (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "sqrt"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=\sqrt{x}.$
\end_inset


\end_layout

\begin_layout Description
square (
\begin_inset Formula $x$
\end_inset

 [,
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=x*x$
\end_inset

 
\end_layout

\begin_layout Description
reciprocal (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=1/x$
\end_inset


\end_layout

\begin_layout Description
ones_like (
\begin_inset Formula $x$
\end_inset

, [, 
\begin_inset Formula $y$
\end_inset

])
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset Formula $y=1$
\end_inset

 If an output argument is not given the returned data-type is the same as
 the input data type.
\end_layout

\begin_layout Tip
The optional output arguments can be used to help you save memory for large
 calculations.
 If your arrays are large, complicated expressions can take longer than
 absolutely necessary due to the creation and (later) destruction of temporary
 calculation spaces.
 For example, the expression 'G=a*b+c' is equivalent to t1=A*B; G=T1+C;
 del t1; It will be more quickly executed as G=A*B; add(G,C,G) which is
 the same as G=A*B; G+=C.
\end_layout

\begin_layout Subsection
Trigonometric functions
\end_layout

\begin_layout Standard
All trigonometric functions use radians when an angle is called for.
 The ratio of degrees to radians is 
\begin_inset Formula $180^{\circ}/\pi.$
\end_inset


\end_layout

\begin_layout Description
sin (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "sin"

\end_inset


\end_layout

\begin_layout Description
cos (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "cos"

\end_inset


\end_layout

\begin_layout Description
tan (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "tan"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The standard trignometric functions.
 
\begin_inset Formula $y=\sin\left(x\right),$
\end_inset

 
\begin_inset Formula $y=\cos\left(x\right),$
\end_inset

 and 
\begin_inset Formula $y=\tan\left(x\right).$
\end_inset


\end_layout

\begin_layout Description
arcsin (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arcsin"

\end_inset


\end_layout

\begin_layout Description
arccos (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arccos"

\end_inset


\end_layout

\begin_layout Description
arctan (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arctan"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The inverse trigonometric functions: 
\begin_inset Formula $y=\sin^{-1}\left(x\right),$
\end_inset

 
\begin_inset Formula $y=\cos^{-1}\left(x\right)$
\end_inset

, 
\begin_inset Formula $y=\tan^{-1}\left(x\right).$
\end_inset

 These return the value of 
\begin_inset Formula $y$
\end_inset

 (in radians) such that 
\begin_inset Formula $\sin\left(y\right)=x$
\end_inset

 with 
\begin_inset Formula $y\in\left[-\frac{\pi}{2},\frac{\pi}{2}\right]$
\end_inset

; 
\begin_inset Formula $\cos\left(y\right)=x$
\end_inset

 with 
\begin_inset Formula $y\in\left[0,\pi\right]$
\end_inset

; and 
\begin_inset Formula $\tan\left(y\right)=x$
\end_inset

 with 
\begin_inset Formula $y\in\left[-\frac{\pi}{2},\frac{\pi}{2}\right]$
\end_inset

, respectively.
 
\end_layout

\begin_layout Description
arctan2 (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arctan2"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Returns 
\begin_inset Formula $\tan^{-1}\left(\frac{x_{1}}{x_{2}}\right)$
\end_inset

 but takes into account the sign on 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

 to place the angle in the correct quadrant.
 The angle 
\begin_inset Formula $y$
\end_inset

 is returned in the full range 
\begin_inset Formula $-\pi<y\leq\pi$
\end_inset

.
 The angle is chosen so that 
\begin_inset Formula $\sin\left(y\right)=\frac{x_{1}}{\sqrt{x_{1}^{2}+x_{2}^{2}}},$
\end_inset

 and 
\begin_inset Formula $\cos\left(y\right)=\frac{x_{2}}{\sqrt{x_{1}^{2}+x_{2}^{2}}}.$
\end_inset

 Particular values are showin in the following table:
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
\begin_inset Formula $x_{1}$
\end_inset


\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
\begin_inset Formula $x_{2}$
\end_inset


\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
\begin_inset Formula $y=\textrm{arctan2}\left(x_{1},x_{2}\right)$
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
1
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
0
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
1
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
\begin_inset Formula $\frac{\pi}{2}$
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
-1
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
\begin_inset Formula $\pi$
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
-1
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
\begin_inset Formula $-\frac{\pi}{2}$
\end_inset

 
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Description
hypot (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "hypot"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Returns 
\begin_inset Formula $y=\sqrt{x_{1}^{2}+x_{2}^{2}}.$
\end_inset

 Given a complex number in cartesian form, arctan2 and hypot can be used
 to compute phase and magnitude, quickly.
\end_layout

\begin_layout Description
sinh (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "sinh"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Computes 
\begin_inset Formula $y=\sinh\left(x\right)$
\end_inset

 which is defined as 
\begin_inset Formula $\frac{1}{2}\left(e^{x}-e^{-x}\right).$
\end_inset


\end_layout

\begin_layout Description
cosh (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "cosh"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Computes 
\begin_inset Formula $y=\cosh\left(x\right)$
\end_inset

 which is defined as 
\begin_inset Formula $\frac{1}{2}\left(e^{x}+e^{-x}\right).$
\end_inset

 
\end_layout

\begin_layout Description
tanh (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "tanh"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Computes 
\begin_inset Formula $y=\tanh\left(x\right)$
\end_inset

 which is defined as 
\begin_inset Formula $\left(e^{x}-e^{-x}\right)/\left(e^{x}+e^{-x}\right).$
\end_inset


\end_layout

\begin_layout Description
arcsinh (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arcsinh"

\end_inset


\end_layout

\begin_layout Description
arccosh (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arccosh"

\end_inset


\end_layout

\begin_layout Description
arctanh (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "arctanh"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 These compute the inverse hyperpolic functions.
 
\begin_inset Formula $y=\textrm{arc}func\left(x\right)$
\end_inset

 is the (principal) value of 
\begin_inset Formula $y$
\end_inset

 such that 
\begin_inset Formula $func\left(y\right)=x.$
\end_inset


\end_layout

\begin_layout Subsection
Bit-twiddling functions
\end_layout

\begin_layout Standard
These function all need integer arguments and they maniuplate the bit-pattern
 of those arguments.
\end_layout

\begin_layout Description
bitwise_and (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "bitwise\\_and"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Each bit in 
\begin_inset Formula $y$
\end_inset

 is the result of a bit-wise 'and' operation on the corresponding bits in
 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1&x2
\family default
 for arrays.
 
\end_layout

\begin_layout Description
bitwise_or (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "bitwise\\_or"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Each bit in 
\begin_inset Formula $y$
\end_inset

 is the result of a bit-wise 'or' operation on the corresponding bits in
 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1|x2
\family default
 for arrays.
\end_layout

\begin_layout Description
bitwise_xor (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "bitwise\\_xor"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Each bit in 
\begin_inset Formula $y$
\end_inset

 is the result of a bit-wise 'xor' operation on the corresponding bits in
 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

.
 An xor operation sets the output to 1 if one and only one of the input
 bits is 1.
 Called to implement 
\family typewriter
x1^x2
\family default
 for arrays.
 Using the bitwise_xor operation and the optional output argument you can
 swap the values of two integer arrays of equivalent types without using
 temporary arrays.
\end_layout

\begin_layout MyCode
>>> a=arange(10)
\newline
>>> b=arange(10,20)
\newline
>>> bitwise_xor(a,b,a); bitwise_xor(a,b,b);
\newline
>>
> bitwise_xor(a,b,a)
\newline
array([10, 11, 12, 13, 14, 15, 16, 17, 18, 19])
\newline
>>> print
 a; print b
\newline
[10 11 12 13 14 15 16 17 18 19]
\newline
[0 1 2 3 4 5 6 7 8 9]
\end_layout

\begin_layout Description
invert (
\begin_inset Formula $x$
\end_inset

, [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "invert"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Each bit in 
\begin_inset Formula $y$
\end_inset

 is the opposite of the corresponding bit in 
\begin_inset Formula $x$
\end_inset

.
 Called to implement 
\family typewriter
~x
\family default
 for arrays.
\end_layout

\begin_layout Description
left_shift (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "left\\_shift"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Shifts the bits of 
\begin_inset Formula $x_{1}$
\end_inset

 to the left by 
\begin_inset Formula $x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1<<x2
\family default
 for arrays.
 Provided there is no overflow, the result is equal to 
\begin_inset Formula $y=x_{1}2^{x_{2}}.$
\end_inset

 
\end_layout

\begin_layout Description
right_shift (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "right\\_shift"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Shifts the bits of 
\begin_inset Formula $x_{1}$
\end_inset

 to the right by 
\begin_inset Formula $x_{2}$
\end_inset

.
 Called to implement 
\family typewriter
x1>>x2
\family default
 for arrays.
 Absent overflow, the result is equal to 
\begin_inset Formula $y=x_{1}2^{-x_{2}}$
\end_inset

.
\end_layout

\begin_layout Subsection
Comparison functions
\end_layout

\begin_layout Standard
All of these functions (except maximum, minimum, and sign) return Boolean
 arrays.
 
\end_layout

\begin_layout Description
greater (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "greater"

\end_inset


\end_layout

\begin_layout Description
greater_equal (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "greater\\_equal"

\end_inset


\end_layout

\begin_layout Description
less (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "less"

\end_inset


\end_layout

\begin_layout Description
less_equal (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "less\\_equal"

\end_inset


\end_layout

\begin_layout Description
not_equal (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "not\\_equal"

\end_inset


\end_layout

\begin_layout Description
equal (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "equal"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 These functions are called to implement 
\family typewriter
x1>x2
\family default
, 
\family typewriter
x1>=x2
\family default
, 
\family typewriter
x1<x2
\family default
, 
\family typewriter
x1<=x2
\family default
, 
\family typewriter
x1!=x2
\family default
 (or 
\family typewriter
x1<>x2
\family default
), and 
\family typewriter
x1==x2
\family default
, respectively, for arrays.
\end_layout

\begin_layout Description
\InsetSpace ~
 The fact that these functions return Boolean arrays make them very useful
 in combination with advanced array indexing.
 Thus, for example, arr[arr>10] = 10 clips large values to 10.
 Used in conjunction with bitwise operators quite complicated expressions
 are possible.
 For example, arr[~((arr<10)&(arr>5))] = 0 clips all values outside of the
 range 
\begin_inset Formula $\left(5,10\right)$
\end_inset

 to 0.
 
\end_layout

\begin_layout Warning
Do not use the Python keywords 
\family typewriter
and
\family default
 and 
\family typewriter
or
\family default
 to combine logical array expressions.
 These keywords will test the truth value of the entire array (not element-by-el
ement as you might expect).
 Use the bitwise operators: & and | instead.
\end_layout

\begin_layout Description
logical_and (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "logical\\_and"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The output is the truth value of 
\begin_inset Formula $x_{1}$
\end_inset

 
\series bold
and
\series default
 
\begin_inset Formula $x_{2}$
\end_inset

.
 Numbers equal to 0 are considered False.
 Nonzero numbers are True.
\end_layout

\begin_layout Description
logical_or (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "logical\\_or"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The output, 
\begin_inset Formula $y$
\end_inset

, is the truth value of 
\begin_inset Formula $x_{1}$
\end_inset

 
\series bold
or 
\begin_inset Formula $x_{2}$
\end_inset


\series default
 .
\end_layout

\begin_layout Description
logical_xor (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "logical\\_xor"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The output, 
\begin_inset Formula $y$
\end_inset

, is the truth value of 
\begin_inset Formula $x_{1}$
\end_inset

 
\series bold
xor 
\begin_inset Formula $x_{2}$
\end_inset


\series default
, which is the same as (
\begin_inset Formula $x_{1}$
\end_inset

 and not 
\begin_inset Formula $x_{2}$
\end_inset

) or (not 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

).
\end_layout

\begin_layout Description
logical_not (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "logical\\_not"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The output, 
\begin_inset Formula $y$
\end_inset

 is the truth value of 
\series bold
not
\series default
 
\begin_inset Formula $x$
\end_inset

.
 
\end_layout

\begin_layout Warning
The Bitwise operators (& and |) are the proper way to combine element-by-element
 array comparisons.
 Be sure to understand the operator precedence: (a>2) & (a<5) is the proper
 syntax because a>2 & a<5 will result in an error due to the fact that 2
 & a is evaluated first.
\end_layout

\begin_layout Description
maximum (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "maximum"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The output, 
\begin_inset Formula $y$
\end_inset

, is the larger of 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

.
 
\end_layout

\begin_layout MyCode
>>> maximum([1,0,5,10],[3,2,4,5])
\newline
array([ 3,  2,  5, 10])
\newline
>>> max([1,0,5,10],[3,2,
4,5])
\newline
[3, 2, 4, 5]
\end_layout

\begin_layout Tip
The Python function max() will find the maximum over a one-dimensional array,
 but it will do so using a slower sequence interface.
 The reduce method of the maximum ufunc is much faster.
 Also, the max() method will not give answers you might expect for arrays
 with greater than one dimension.
 The reduce method of minimum also allows you to compute a total minimum
 over an array.
\end_layout

\begin_layout Description
minimum (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

])
\begin_inset LatexCommand index
name "minimum"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 The output, 
\begin_inset Formula $y$
\end_inset

, is the smaller of 
\begin_inset Formula $x_{1}$
\end_inset

 and 
\begin_inset Formula $x_{2}$
\end_inset

.
\end_layout

\begin_layout MyCode
>>> minimum([1,0,5,10],[3,2,4,5])
\newline
array([1, 0, 4, 5])
\newline
>>> min([1,0,5,10],[3,2,4,5]
)
\newline
[1, 0, 5, 10]
\end_layout

\begin_layout Warning
the behavior of maximum(a,b) is than that of max(a,b).
 As a ufunc, maximum(a,b) performs an element-by-element comparison of a
 and b and chooses each element of the result according to which element
 in the two arrays is larger.
 In contrast, max(a,b) treats the objects a and b as a whole, looks at the
 (total) truth value of a>b and uses it to return either a or b (as a whole).
 A similar difference exists between minimum(a,b) and min(a,b).
 
\end_layout

\begin_layout Subsection
Floating functions
\end_layout

\begin_layout Standard
Recall that all of these functions work element-by-element over an array,
 returning an array output.
 The description details only a single operation.
\end_layout

\begin_layout Description
isreal (
\begin_inset Formula $x$
\end_inset

)
\begin_inset LatexCommand index
name "isreal"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x$
\end_inset

 has an imaginary part that is 0.
\end_layout

\begin_layout Description
iscomplex (
\begin_inset Formula $x$
\end_inset

)
\begin_inset LatexCommand index
name "iscomplex"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x$
\end_inset

 has an imaginary part that is non-zero.
 
\end_layout

\begin_layout Description
isfinite (
\begin_inset Formula $x$
\end_inset

)
\begin_inset LatexCommand index
name "isfinite"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x$
\end_inset

 is a finite floating point number (not a NaN or an Inf).
 
\end_layout

\begin_layout Description
isinf (
\begin_inset Formula $x$
\end_inset

)
\begin_inset LatexCommand index
name "isinf"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x$
\end_inset

 is 
\begin_inset Formula $\pm\infty$
\end_inset

.
 
\end_layout

\begin_layout Description
isnan (
\begin_inset Formula $x$
\end_inset

)
\begin_inset LatexCommand index
name "isnan"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 True if 
\begin_inset Formula $x$
\end_inset

 is Not-a-Number.
 This represents invalid results.
 When a NaN is created, the invalid flag is set.
 If you set the error mode of invalid to 'warn', 'raise', or 'call', then
 the appropriate action will be performed on NaN creation.
 
\end_layout

\begin_layout Description
signbit (
\begin_inset Formula $x$
\end_inset

)
\begin_inset LatexCommand index
name "signbit"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 True where the sign bit of the floating point number is set.
 This should correspond to 
\begin_inset Formula $x>0$
\end_inset

 when 
\begin_inset Formula $x$
\end_inset

 is a finite number.
 When, 
\begin_inset Formula $x$
\end_inset

 is NaN or infinite, then this tests the actual signbit.
 
\end_layout

\begin_layout Description
modf (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y_{1}$
\end_inset

, 
\begin_inset Formula $y_{2}$
\end_inset

]) 
\begin_inset LatexCommand index
name "modf"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Breaks up the floating point value 
\begin_inset Formula $x$
\end_inset

 into its fractional, 
\begin_inset Formula $y_{1}$
\end_inset

, and integral, 
\begin_inset Formula $y_{2}$
\end_inset

, parts.
 Thus, 
\begin_inset Formula $x=y_{1}+y_{2}$
\end_inset

 with 
\family typewriter
floor(y2)==y2
\family default
.
 
\end_layout

\begin_layout Description
ldexp (
\begin_inset Formula $x$
\end_inset

, 
\begin_inset Formula $n$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

]) 
\begin_inset LatexCommand index
name "ldexp"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Fast multiply of a floating point number by an integral power of 2: 
\begin_inset Formula $y=2^{n}x.$
\end_inset


\end_layout

\begin_layout Description
frexp (
\begin_inset Formula $x$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

, 
\begin_inset Formula $n$
\end_inset

]) 
\begin_inset LatexCommand index
name "frexp"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Breaks up the floating point value 
\begin_inset Formula $x$
\end_inset

 into a normalized fraction, 
\begin_inset Formula $y$
\end_inset

 and an exponent, 
\begin_inset Formula $n$
\end_inset

 which corresponds to how the value is represented in the computer.
 The results are such that 
\begin_inset Formula $x=y2^{n}.$
\end_inset

 Effectively, the inverse of ldexp.
 
\end_layout

\begin_layout Description
fmod (
\begin_inset Formula $x_{1}$
\end_inset

, 
\begin_inset Formula $x_{2}$
\end_inset

 [, 
\begin_inset Formula $y$
\end_inset

]) 
\begin_inset LatexCommand index
name "fmod"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Computes the remainder of dividing 
\begin_inset Formula $x_{1}$
\end_inset

 by 
\begin_inset Formula $x_{2}$
\end_inset

.
 The result, 
\begin_inset Formula $y$
\end_inset

, is 
\begin_inset Formula $x_{1}-nx_{2}$
\end_inset

 where 
\begin_inset Formula $n$
\end_inset

 is the quotient (rounded towards zero to an integer) of 
\begin_inset Formula $x_{1}/x_{2}.$
\end_inset

 
\end_layout

\begin_layout Description
floor (
\begin_inset Formula $x$
\end_inset

 [,
\begin_inset Formula $y$
\end_inset

 ]) 
\begin_inset LatexCommand index
name "floor"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Return 
\begin_inset Formula $y=\left\lfloor x\right\rfloor $
\end_inset

 where 
\begin_inset Formula $y$
\end_inset

 is the nearest integer smaller-than or equal to 
\begin_inset Formula $x.$
\end_inset

 Thus, 
\begin_inset Formula $ $
\end_inset


\begin_inset Formula $\left\lfloor x\right\rfloor \leq x<\left\lfloor x\right\rfloor +1$
\end_inset

.
 
\end_layout

\begin_layout Description
ceil (
\begin_inset Formula $x$
\end_inset

 [,
\begin_inset Formula $y$
\end_inset

 ]) 
\begin_inset LatexCommand index
name "ceil"

\end_inset


\end_layout

\begin_layout Description
\InsetSpace ~
 Return 
\begin_inset Formula $y=\left\lceil x\right\rceil $
\end_inset

 where 
\begin_inset Formula $y$
\end_inset

 is the nearest integer greater-than or equal to 
\begin_inset Formula $x$
\end_inset

.
 Thus, 
\begin_inset Formula $x\leq\left\lceil x\right\rceil <x+1.$
\end_inset


\begin_inset LatexCommand index
name "ufunc|)"

\end_inset


\end_layout

\begin_layout Chapter
Basic Modules
\end_layout

\begin_layout Quotation
It is the mark of an educated mind to rest satisfied with the degree of
 precision which the nature of the subject admits and not to seek exactness
 where only an approximation is possible.
\end_layout

\begin_layout Right Address
---
\emph on
Aristotle
\end_layout

\begin_layout Quotation
"Oh no.
 We're in the hands of engineers!"
\end_layout

\begin_layout Right Address
---
\emph on
Malcolm, Ian in 'Jurassic Park'
\end_layout

\begin_layout Standard
The NumPy distribution contains some basic functionality equivalent to what
 was available in the Numeric packages previously.
 This section documents the new interfaces.
 These are sub-packages of the NumPy namespace.
 The linalg and fft capabilities are useful but limited.
 You should install the full SciPy package to access more functionality.
 The numpy.dual module contains functions that are defined in both SciPy
 and NumPy.
 If SciPy defines func, then numpy.dual.func will point to the SciPy version,
 otherwise it will point to the NumPy version.
 It must be imported specifically to be used.
 Table 
\begin_inset LatexCommand ref
reference "cap:Functions-in-numpy.dual"

\end_inset

 shows the functions defined in numpy.dual that are in both NumPy and SciPy.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Functions-in-numpy.dual"

\end_inset

Functions in numpy.dual (both in NumPy and SciPy)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="4" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="middle" leftline="true" rightline="true" width="55text%">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Family
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Functions
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Fourier Transforms
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
fft, ifft, fft2, ifft2, fftn, ifftn
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Linear Algebra
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
norm, det, inv, pinv, solve, eig, eigh, eigvals, eigvalsh, lstsq, cholesky,
 svd
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Special Functions
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
i0
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Linear Algebra (
\family typewriter
linalg
\family default
)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "linalg|("

\end_inset

These functions are in the numpy.linalg sub-package.
\end_layout

\begin_layout Description
inv (A)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the (matrix) inverse of the 2-d array A.
 The result, X, is such that dot(A,X) is equal to eye(*A.shape) (to within
 machine precision).
 
\end_layout

\begin_layout Description
solve (A,b)
\end_layout

\begin_layout Description
\InsetSpace ~
 Find the solution to the linear equation 
\begin_inset Formula $\mathbf{Ax}=\mathbf{b}$
\end_inset

, where 
\begin_inset Formula $A$
\end_inset

 is a 2-d array and 
\begin_inset Formula $b$
\end_inset

 is a 1-d or 2-d array.
 
\end_layout

\begin_layout Description
tensorsolve (A, b, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Find the solution, 
\begin_inset Formula $x_{kl}$
\end_inset

, to the multi-index linear equation 
\begin_inset Formula \[
\sum_{kl}A_{ijkl}x_{kl}=b_{ij}.\]

\end_inset

 The axes argument specifies which dimensions of 
\begin_inset Formula $A$
\end_inset

 are summed over.
 If it is None, then the last A.ndim - b.ndim dimensions are summed over.
 The result, therefore, has dimension x.ndim = A.ndim-b.ndim.
 
\end_layout

\begin_layout Description
tensorinv (A, ind=2)
\end_layout

\begin_layout Description
\InsetSpace ~
 Find the tensor inverse of 
\begin_inset Formula $A$
\end_inset

, defined to be the tensor such that tensordot (Ainv, A) is an identity
 operator.
 
\end_layout

\begin_layout Description
cholesky (A)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return, 
\begin_inset Formula $\mathbf{L}$
\end_inset

, the Cholesky decomposition of 
\begin_inset Formula $\mathbf{A}$
\end_inset

.
 Cholesky decomposition is applicable to a Hermitian, positive definite
 matrices.
 When 
\begin_inset Formula $\mathbf{A}=\mathbf{A}^{H}$
\end_inset

 and 
\begin_inset Formula $\mathbf{x}^{H}\mathbf{Ax}\geq0$
\end_inset

 for all 
\begin_inset Formula $\mathbf{x}$
\end_inset

, then decompositions of 
\begin_inset Formula $\mathbf{A}$
\end_inset

 can be found so that 
\begin_inset Formula $\mathbf{A}=\mathbf{LL}^{H}$
\end_inset

, where 
\begin_inset Formula $\mathbf{L}$
\end_inset

 is lower-triangular.
 
\end_layout

\begin_layout Description
eigvals (A)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return all solutions (
\begin_inset Formula $\lambda$
\end_inset

) to the equation 
\begin_inset Formula $\mathbf{Ax}=\lambda\mathbf{x}$
\end_inset

.
\end_layout

\begin_layout Description
eig (A)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return all solutions 
\begin_inset Formula $\left(\lambda,\mathbf{x}\right)$
\end_inset

 to the equation 
\begin_inset Formula $\mathbf{Ax}=\lambda\mathbf{x}$
\end_inset

.
 The first element of the return tuple contains all the eigenvalues.
 The second element of the return tuple contains the eigenvectors in the
 columns (x[:,i] is the ith eigenvector).
\end_layout

\begin_layout Description
eigvalsh (U)
\end_layout

\begin_layout Description
eigh (U)
\end_layout

\begin_layout Description
\InsetSpace ~
 These functions are identical to eigvals and eig except they only work
 with Hermitian matrices where 
\begin_inset Formula $\mathbf{U}^{H}=\mathbf{U}$
\end_inset

 (only the lower-triangular part of the array is used).
\end_layout

\begin_layout Description
svd (A)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the singular value decomposition of the 2-d array 
\begin_inset Formula $\mathbf{A}$
\end_inset

.
 Every 
\begin_inset Formula $m\times n$
\end_inset

 matrix can be decomposed into a pair of unitary matrices, 
\begin_inset Formula $\mathbf{U}=\mathbf{U}^{H}$
\end_inset

 (
\begin_inset Formula $m\times m$
\end_inset

) and 
\begin_inset Formula $\mathbf{V}=\mathbf{V}^{H}$
\end_inset

 (
\begin_inset Formula $n\times n$
\end_inset

) and an 
\begin_inset Formula $m\times n$
\end_inset

 
\begin_inset Quotes eld
\end_inset

diagonal
\begin_inset Quotes erd
\end_inset

 matrix 
\begin_inset Formula $\boldsymbol{\Sigma}$
\end_inset

, such that 
\begin_inset Formula $\mathbf{A}=\mathbf{U\boldsymbol{\Sigma}}\mathbf{V}^{H}$
\end_inset

.
 The only non-zero portion of 
\begin_inset Formula $\boldsymbol{\Sigma}$
\end_inset

 is the upper 
\begin_inset Formula $r\times r$
\end_inset

 block where 
\begin_inset Formula $r=\min\left(m,n\right)$
\end_inset

.
 The svd function returns three arrays as a tuple: (
\begin_inset Formula $\mathbf{U}$
\end_inset

, 
\begin_inset Formula $\boldsymbol{\sigma}$
\end_inset

, 
\begin_inset Formula $\mathbf{V}^{H}$
\end_inset

).
 The singular values are returned in the 1-d array 
\begin_inset Formula $\boldsymbol{\sigma}$
\end_inset

.
 If needed, the array 
\begin_inset Formula $\boldsymbol{\Sigma}$
\end_inset

 can be found (if really needed) using the command diag(
\begin_inset Formula $\boldsymbol{\sigma}$
\end_inset

) which creates the 
\begin_inset Formula $r\times r$
\end_inset

 diagonal block and then inserting this into a zeros matrix:
\end_layout

\begin_layout MyCode
>>> A = random.rand(3,5)
\newline
>>> from numpy.dual import svd; U,s,Vh = svd(A)
\newline
>>>
 r=min(*A.shape); Sig = zeros_like(A);
\newline
>>> Sig[:r,:r] = diag(s); print Sig
\newline
[[
 2.1634  0.
      0.
      0.
      0.
    ]
\newline
 [ 0.
      0.7076  0.
      0.
      0.
    ]
\newline
 [ 0.
      0.
      0.2098  0.
      0.
    ]]
\end_layout

\begin_layout Description
pinv (A, rcond=
\begin_inset Formula $10^{-10}$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the generalized, pseudo inverse, of 
\begin_inset Formula $A$
\end_inset

.
 For invertible matrices, this is the same as the inverse.
 
\end_layout

\begin_layout Description
det (A)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the determinant of the array.
 The determinant of an array is the product of its singular values.
 
\end_layout

\begin_layout Description
lstsq (A, b, rcond=
\begin_inset Formula $10^{-10}$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return (x, resids, rank, s) where x minimizes resids=
\begin_inset Formula $\left\Vert \mathbf{Ax}-\mathbf{b}\right\Vert _{2}$
\end_inset

.
 The output rank is the rank of A and s is the singular values of a in descendin
g order.
 Singular values less than s[0]*rcond are treated as 0.
 If the rank of A is less than the number of columns of A or greater than
 the number of rows, resids will be returned as an empty array.
\begin_inset LatexCommand index
name "linalg|)"

\end_inset


\end_layout

\begin_layout Section
Discrete Fourier Transforms (
\family typewriter
fft
\family default
)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "fft|("

\end_inset

All of the algorithms here are most efficient if the length of the data
 is a power of 2 (or decomposable into low prime factors).
 
\end_layout

\begin_layout Description
fft (x, n=None, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return, X, the N-point Discrete Fourier Transform (DFT) of x along the
 given axis using a fast algorithm.
 If N is larger than x.shape[axis], then x will be zero-padded.
 If N is smaller than x.shape[axis], then the first N items will be used.
 The result is computed for 
\begin_inset Formula $k=0\ldots n-1$
\end_inset

 from the formula: 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
X\left[k\right]=\sum_{m=0}^{n-1}x[m]\exp\left(-j\frac{2\pi km}{n}\right).\]

\end_inset


\end_layout

\begin_layout Tip
The fft returns values for 
\begin_inset Formula $k=0\ldots N-1$
\end_inset

.
 Because 
\begin_inset Formula $X\left[N-k\right]=X[-k]$
\end_inset

 in the FFT formula, larger values of k correspond also to negative frequencies.
\end_layout

\begin_layout Description
ifft (X, n=None, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the inverse of the fft so that (ifft(fft(a)) == a within numerical
 precision.
 The order of frequencies must be the same as returned by fft.
 The result is computed (using a fast algorithm) for 
\begin_inset Formula $m=0\ldots n-1$
\end_inset

 from the formula:
\end_layout

\begin_layout Standard
\begin_inset Formula \[
x\left[m\right]=\frac{1}{n}\sum_{k=0}^{n-1}X\left[k\right]\exp\left(j\frac{2\pi km}{n}\right).\]

\end_inset


\end_layout

\begin_layout Standard
Sometimes having the 
\begin_inset Quotes eld
\end_inset

negative
\begin_inset Quotes erd
\end_inset

 frequencies at the end of the output returned by fft can be a little confusing.
 There are two ways to deal with this confusion.
 In my opinion, the most useful way is to get a collection of DFT sample
 frequencies and use them to keep track of where each frequency is.
 The function 
\family typewriter
fftfreq
\family default
 provides these sample frequencies.
 Making an x-y plot, where the sample frequencies are along the 
\begin_inset Quotes eld
\end_inset

x
\begin_inset Quotes erd
\end_inset

-axis and the result of the DFT is along the 
\begin_inset Quotes eld
\end_inset

y
\begin_inset Quotes erd
\end_inset

-axis provides a useful visualization with the zero-frequency at the center
 of the plot.
 The advantage of this approach is that your data is still in proper order
 for using the 
\family typewriter
ifft
\family default
 function.
 Some people, however, prefer to simply swap one-half of the output with
 the other.
 This is exactly what the function 
\family typewriter
fftshift
\family default
 does.
 Of course, now the data is not in the proper order for the ifft function,
 but to each his own.
 
\end_layout

\begin_layout Standard
The reason that the 
\begin_inset Quotes eld
\end_inset

negative
\begin_inset Quotes erd
\end_inset

 frequencies are in the upper part of the return signal was given in the
 description of the DFT.
 The reason is that the output of the DFT is just one period of a periodic
 function (with period 
\begin_inset Formula $n$
\end_inset

).
 The traditional output of the FFT algorithm is to provide the portion of
 the function from from 
\begin_inset Formula $k=0$
\end_inset

 to 
\begin_inset Formula $k=n-1$
\end_inset

.
 
\end_layout

\begin_layout Description
fftshift (x, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Shift zero-frequency component to the center of the spectrum.
 This function swaps half-spaces for all axes listed (defaults to all of
 them).
 
\end_layout

\begin_layout Description
ifftshift (x, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Reverse the effect of the fftshift operation.
 Thus, it takes zero-centered data and shifts it into the correct order
 for the ifft operation.
\end_layout

\begin_layout Description
fftfreq (n, d=1.0)
\end_layout

\begin_layout Description
\InsetSpace ~
 Provide the DFT sample frequencies.
 The returned float array contains the frequency bins in the order returned
 from the fft function.
 If given, 
\begin_inset Formula $d$
\end_inset

 represents the sample-spacing.
 The units on the frequency bins are cycles / unit.
 For example, the following example computes the output frequencies (in
 Hz) of the fft of 
\begin_inset Formula $256$
\end_inset

 samples of a voice signal sampled at 20000Hz.
\end_layout

\begin_layout MyCode
>>> from numpy.fft import fftfreq; f=fftfreq(256,d=1./20e3)
\newline
>>> print f[0],
 f[1], f[2], f[128]
\newline
0.0 78.125 156.25 -10000.0
\end_layout

\begin_layout Description
fft2 (x, s=None, axes=(-2,-1))
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the two-dimensional fft of the array x for each 2-d array formed
 by axes.
 The 2-d fft is computed as 
\begin_inset Formula \[
X\left[k_{0},k_{1}\right]=\sum_{m_{0}=0}^{s[0]-1}\sum_{m_{1}=0}^{s[1]-1}x\left[m_{0},m_{1}\right]\exp\left(-j\frac{2\pi k_{0}m_{0}}{s[0]}\right)\exp\left[-j\frac{2\pi k_{1}m_{1}}{s\left[1\right]}\right]\]

\end_inset

 and can be realized by repeated application of the 1-d fft (first over
 the axes[0] and then over axes[1]).
 In other-words fft2(x,s,axes) is equivalent to fft(fft(x, s[0], axes[0]),
 s[1], axes[1]).
 The 2-d fft is returned for 
\begin_inset Formula $k_{0}=0\ldots s[0]-1$
\end_inset

 and 
\begin_inset Formula $k_{1}=0\ldots s[1]-1.$
\end_inset

 Symmetry (
\begin_inset Formula $X\left[s[0]-k_{0},s[1]-k_{1}\right]=X[-k_{0},-k_{1}]$
\end_inset

) ensures that higher values of 
\begin_inset Formula $k_{i}$
\end_inset

 correspond to negative frequencies.
 
\end_layout

\begin_layout Description
ifft2 (X, s=None, axes=(-2,-1))
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the inverse of the two-dimension fft.
 Thus, ifft2(fft2(x)) == x to within numerical precision.
 Note that the 
\begin_inset Quotes eld
\end_inset

negative frequencies
\begin_inset Quotes erd
\end_inset

 must be 
\end_layout

\begin_layout Description
fftn (x, s=None, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the 
\begin_inset Formula $N$
\end_inset

-dimensional fft of x.
 If s is not given, then if axes is given, then 
\begin_inset Formula $N$
\end_inset

=len(axes), otherwise 
\begin_inset Formula $N$
\end_inset

=x.ndim.
 If s is given, then 
\begin_inset Formula $N$
\end_inset

=len(s).
 Results are computed using a similar formula as for the 1- and 2-d FFT
 with 
\begin_inset Formula $N$
\end_inset

 summations.
 
\end_layout

\begin_layout Description
ifftn (X, s=None, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the 
\begin_inset Formula $N$
\end_inset

-dimensional inverse fft of 
\begin_inset Formula $X$
\end_inset

.
 Note that ifftn(fftn(x)) == x to within machine precision.
 
\end_layout

\begin_layout Standard
The Discrete Fourier transform returns complex-valued data (even for real-valued
 input).
 If the data was originally real-valued, then much of the output of the
 full DFT is redundant.
 Notice that if 
\begin_inset Formula $x\left[m\right]$
\end_inset

 is real, then 
\begin_inset Formula \begin{eqnarray*}
X\left[n-k\right] & = & \sum_{m=0}^{n-1}x[m]\exp\left(-j\frac{2\pi\left(n-k\right)m}{n}\right)\\
 & = & \left[\sum_{m=0}^{n-1}x\left[m\right]\exp\left(-j\frac{2\pi km}{n}\right)\right]^{*}\\
 & = & X^{*}\left[k\right],\end{eqnarray*}

\end_inset

where 
\begin_inset Formula $a^{*}$
\end_inset

 denotes the complex-conjugate of 
\begin_inset Formula $a$
\end_inset

.
 So, the upper half of the fft output (the negative frequencies) is determined
 exactly by the lower half of the output when the input is purely real.
 This kind of symmetry is called Hermitian symmetry.
 The real-valued Fourier transforms described next take advantage of Hermitian
 symmetry to compute only the unique outputs more quickly.
 
\end_layout

\begin_layout Standard
The symmetry in higher dimensions is always about the origin.
 If 
\begin_inset Formula $N$
\end_inset

 is the number of dimensions, then: 
\begin_inset Formula \[
X[n_{1}-k_{1},n_{2}-k_{2},\ldots n_{N}-k_{N}]=X^{*}\left[k_{1},k_{2},\ldots,k_{N}\right].\]

\end_inset

Thus, the data-savings remains constant at about 1/2 for higher dimensions
 as well.
 
\end_layout

\begin_layout Description
rfft (x, n=None, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the first n//2+1 points of the 
\begin_inset Formula $n$
\end_inset

-point discrete Fourier transform of the real valued data along the given
 axis.
 The returned array will be just the first half of the 
\family typewriter
fft
\family default
, corresponding to positive frequencies: rfft(x) == fft(x)[:n//2+1]
\end_layout

\begin_layout Description
irfft (X, n=None, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the inverse 
\begin_inset Formula $n$
\end_inset

-point discrete Fourier transform along the given axis using the first n//2+1
 points.
 To within numerical precision, irfft(rfft(x))==x.
 
\end_layout

\begin_layout Description
rfft2 (x, s=None, axes=(-2, -1))
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute only the first half-plane of the two-dimensional discrete Fourier
 transform corresponding to unique values.
 s[0] and 
\begin_inset Formula $s[1]$
\end_inset

-point DFTs will be computed along axes[0] and axes[1] dimensions, respectively.
 Requires a real array.
 If 
\begin_inset Formula $s$
\end_inset

 is None it defaults to the shape of 
\begin_inset Formula $x.$
\end_inset

 The real fft will be computed along the last axis specified in axes while
 a full fft will be computed in the other dimension.
\end_layout

\begin_layout Description
irfft2 (X, s=None, axes=(-2, -1))
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the inverse of the 2-d DFT using only the first quadrant.
 Returns a real array such that to within numerical precision irfft2(rfft2(x))==
x.
\end_layout

\begin_layout Description
rfftn (x, s=None, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute only the unique part of the 
\begin_inset Formula $N$
\end_inset

-dimensional DFT from a real-valued array.
 If 
\begin_inset Formula $s$
\end_inset

 is None it defaults to the shape of x.
 If axes is not given it defaults to all the axes (-n,
\begin_inset Formula $\ldots$
\end_inset

, -1).
 The length of axes provides the dimensionality of the DFT.
 The unique part of the real 
\begin_inset Formula $N$
\end_inset

-dimensional DFT is obtained by slicing the full fft along the last axis
 specified and taking n//2+1 slices.
 rfftn(x) == fft(x)[sliceobj] where sliceobj[axes[-1]] = slice(None,s[-1]//2+1,N
one).
\end_layout

\begin_layout Description
irfftn (X, s=None, axes=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Compute the inverse DFT from the unique portions of the N-dimensional DFT
 provided by 
\family typewriter
rfftn
\family default
.
\end_layout

\begin_layout Standard
Occasionally, the situation may arise where you have complex-valued data
 with Hermitian symmetry (or real-valued symmetric data).
 This ensures that the Fourier transform will be real.
 The two functions below can calculate it without wasting extra space for
 the zero-valued imaginary entries of the Discrete Fourier transform, or
 the entire signal.
\end_layout

\begin_layout Description
hfft (x, n=None, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Calculate the 
\begin_inset Formula $n$
\end_inset

-point real-valued Fourier transform from (the first half of Hermitian-symmetric
 data, x.
 
\end_layout

\begin_layout Description
ihfft (X, n=None, axis=-1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return (the first half-of) Hermitian-symmetric data from the real-valued
 Fourier transform, X.
\begin_inset LatexCommand index
name "fft|)"

\end_inset


\end_layout

\begin_layout Section
Random Numbers (
\family typewriter
random
\family default
)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "random|("

\end_inset

The random number capabilities surpass those that were available in Numeric.
 The random number facilities were generously contributed by Robert Kern,
 who has been a dedicated and patient help to many mailing list questioners.
 Robert built the random package using Pyrex to build on top of his own
 code as well as that of randomkit by Jean-Sebastien Roy as well as code
 by Ivan Frohne.
 The fundamental random number generator is the Mersenne Twister based on
 code written by Makoto Matsumoto and Takuji Nishimura (and modified for
 Python by Raymond Hettinger).
 Random numbers from discrete and continuous distributions are available,
 as well as some useful random-number-related utilities.
 Many of the random number generators are based on algorithms published
 by Luc Devroye in 
\begin_inset Quotes eld
\end_inset

Non-Uniform Random Variate Generation
\begin_inset Quotes erd
\end_inset

 available electronically at 
\begin_inset LatexCommand htmlurl
target "http://cgm.cs.mcgill.ca/~luc/rnbookindex.html"

\end_inset


\end_layout

\begin_layout Standard
Each of the discrete and continuous random number generators take a size
 keyword.
 If this is None (default), then the size is determined from the additional
 inputs (using ufunc-like broadcasting).
 If no additional inputs are needed, or if these additional inputs are scalars,
 then a single number is generated from the selected distribution.
 If size is an integer, then a 1-d array of that size is generated filled
 with random numbers from the selected distribution.
 Finally, if size is a tuple, then an array of that shape is returned filled
 with random numbers.
 
\end_layout

\begin_layout Standard
Many distributions take additional inputs as parameters.
 These additional inputs must be broadcastable to each other (and to the
 size parameter if it is not None).
 The broadcasting behavior of the additional inputs is ufunc-like.
 
\end_layout

\begin_layout Subsection
Discrete Distributions
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "random!discrete|("

\end_inset

Discrete random numbers take on only a countable number of values (typically
 integers).
 Each distribution has associated with it a probability mass function (pmf),
 
\begin_inset Formula $p_{m}\left(k;\cdot\right),$
\end_inset

 that is defined as the probability that the returned random number is 
\begin_inset Formula $k$
\end_inset

.
 The arguments after 
\begin_inset Formula $k$
\end_inset

 represent possible parameters to the distribution.
 Thus, let 
\begin_inset Formula $X\left(\cdot\right)$
\end_inset

 represent the random number generator for a particular distribution.
 Then, 
\begin_inset Formula \[
p_{m}\left(k;\cdot\right)=\textrm{Probability}\left\{ X\left(\cdot\right)=k\right\} .\]

\end_inset


\end_layout

\begin_layout Standard
It will be useful to define the discrete indicator function, 
\begin_inset Formula $I_{S}\left(k\right),$
\end_inset

 where 
\begin_inset Formula $S$
\end_inset

 is a set of integers (often represented by an interval).
 
\begin_inset Formula $I_{S}\left(k\right)=1$
\end_inset

 if 
\begin_inset Formula $k\in S$
\end_inset

, otherwise 
\begin_inset Formula $I_{S}\left(k\right)=0.$
\end_inset

 This convenient notation isolates the relevance of a particular functional
 form to a certain range.
 Also, the formulas below make use of the following definition: 
\begin_inset Formula \[
\left(\begin{array}{c}
n\\
k\end{array}\right)=\frac{n!}{k!\left(n-k\right)!}\]

\end_inset

 where 
\begin_inset Formula $k!=k\cdot\left(k-1\right)\cdot\cdots\cdot2\cdot1.$
\end_inset

 
\end_layout

\begin_layout Description
binomial (n, p, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This random number models the number of successes in 
\begin_inset Formula $n$
\end_inset

 independent trials of a random experiment where the probability of success
 in each experiment is 
\begin_inset Formula $p$
\end_inset

.
 
\begin_inset Formula \[
p_{m}\left(k\right)=\left(\begin{array}{c}
n\\
k\end{array}\right)p^{k}\left(1-p\right)^{n-k}I_{\left[0,n\right]}\left(k\right).\]

\end_inset


\end_layout

\begin_layout Description
geometric (p, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This random number models the number of (independent) attempts required
 to obtain a success where the probability of success on each attempt is
 
\begin_inset Formula $p$
\end_inset

.
 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
p_{m}\left(k;p\right)=\left(1-p\right)^{k-1}p\, I_{\left[1,\infty\right)}\left(k\right).\]

\end_inset


\end_layout

\begin_layout Description
hypergeometric (ngood, nbad, nsample, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Imagine a probability theorists favorite urn filled with 
\begin_inset Formula $n_{g}$
\end_inset


\begin_inset Quotes eld
\end_inset

good
\begin_inset Quotes erd
\end_inset

 objects and 
\begin_inset Formula $n_{b}$
\end_inset

 
\begin_inset Quotes eld
\end_inset

bad
\begin_inset Quotes erd
\end_inset

 objects.
 In other words there are two types of objects in a jar.
 The hypergeometric random number models how many 
\begin_inset Quotes eld
\end_inset

good
\begin_inset Quotes erd
\end_inset

 objects will be present when 
\begin_inset Formula $N$
\end_inset

 items are taken out of the urn without replacement.
\end_layout

\begin_layout Standard
\begin_inset Formula \[
p\left(k;n_{g},n_{b},N\right)=\frac{\left(\begin{array}{c}
n_{g}\\
k\end{array}\right)\left(\begin{array}{c}
n_{b}\\
N-k\end{array}\right)}{\left(\begin{array}{c}
n_{g}+n_{b}\\
N\end{array}\right)}I_{\left[N-n_{b},\textrm{min}\left(n,N\right)\right]}\left(k\right).\]

\end_inset


\end_layout

\begin_layout Description
logseries (p, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A random number whose pmf with terms proportional to the Taylor series
 expansion of 
\begin_inset Formula $\log\left(1-p\right)$
\end_inset

.
 It has been used in biological studies to model the species abundance distribut
ion.
 
\begin_inset Formula \[
p_{m}\left(k;p\right)=-\frac{p^{k}}{k\log\left(1-p\right)}\, I_{\left[1,\infty\right)}\left(k\right).\]

\end_inset


\end_layout

\begin_layout Description
multinomial (n, pvals, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This generator produces random vectors of length 
\begin_inset Formula $N$
\end_inset

 where 
\begin_inset Formula $N=\textrm{len}\left(pvals\right)$
\end_inset

.
 The shape of the returned array is always the shape indicated by size +
 (
\begin_inset Formula $N,$
\end_inset

).
 The multinomial distribution is a generalization of the binomial distribution.
 This time, 
\begin_inset Formula $n$
\end_inset

 trials of an experiment are independently repeated but each trial results
 in 
\begin_inset Formula $N$
\end_inset

 possible integers 
\begin_inset Formula $k_{1},k_{2},\ldots,k_{N}$
\end_inset

 with 
\begin_inset Formula $\sum_{i=1}^{N}k_{i}=n.$
\end_inset

 
\begin_inset Formula \begin{eqnarray*}
p_{m}\left(k_{1},k_{2},\ldots,k_{N};\cdot\right) & = & \textrm{Probability}\left\{ X\left(\cdot\right)=\left[k_{1},k_{2},\cdots,k_{N}\right]\right\} \\
 & = & \frac{n!}{k_{1}!k_{2}!\cdots k_{N}!}p_{1}^{k_{1}}p_{2}^{k_{2}}\cdots p_{N}^{k_{N}}\end{eqnarray*}

\end_inset

where 
\begin_inset Formula $pvals=[p_{1},p_{2},\ldots,p_{N}].$
\end_inset

 It must be true that 
\begin_inset Formula $\sum_{i=1}^{N}p_{i}=1.$
\end_inset

 Therefore, as long as 
\begin_inset Formula $\sum_{i=1}^{N-1}p_{i}\leq1,$
\end_inset

 the last entry in 
\begin_inset Formula $pvals$
\end_inset

 is computed as 
\begin_inset Formula $1-\sum_{i=1}^{N-1}p_{i}$
\end_inset

.
\end_layout

\begin_layout Description
negative_binomial (n, p, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Models the number of extra independent trials (beyond 
\begin_inset Formula $n$
\end_inset

) required to accumulate a total of 
\begin_inset Formula $n$
\end_inset

 successes where the probability of success on each trial is 
\begin_inset Formula $p.$
\end_inset

 Equivalently, this random number models the number of failures encountered
 while accumulating 
\begin_inset Formula $n$
\end_inset

 successes during independent trials of the experiment that succeeds with
 probability, 
\begin_inset Formula $p$
\end_inset

.
 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
p_{m}\left(k;n,p\right)=\left(\begin{array}{c}
k+n-1\\
n-1\end{array}\right)p^{n}\left(1-p\right)^{k}\, I_{\left[0,\infty\right)}\left(k\right).\]

\end_inset


\end_layout

\begin_layout Description
poisson (lam=1.0, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This random number counts the number of successes in 
\begin_inset Formula $n$
\end_inset

 independent experiments (where the probability of success in each experiment
 is 
\begin_inset Formula $p$
\end_inset

) in the limit as 
\begin_inset Formula $n\rightarrow\infty$
\end_inset

 and 
\begin_inset Formula $p\rightarrow0$
\end_inset

 gets very small such that 
\begin_inset Formula $\lambda=np\geq0$
\end_inset

 is a constant.
 It can be used, for example, to model how many typographical errors are
 on each page of a book.
\end_layout

\begin_layout Standard
\begin_inset Formula \[
p\left(k;\lambda\right)=e^{-\lambda}\frac{\lambda^{k}}{k!}\, I_{\left[0,\infty\right)}\left(k\right).\]

\end_inset


\end_layout

\begin_layout Description
zipf (a, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 The probability mass function of this random number (also called the zeta
 distribution) is 
\begin_inset Formula \[
p_{m}\left(k;a\right)=\frac{1}{\zeta\left(a\right)k^{a}}\, I_{\left[1,\infty\right)}\left(k\right),\]

\end_inset

where 
\begin_inset Formula \[
\zeta\left(a\right)=\sum_{n=1}^{\infty}\frac{1}{n^{a}}\]

\end_inset

is the Riemann zeta function.
 Zipf distributions have been shown to characterize use of words in a natural
 language (like English), the popularity of library books, and even the
 use of the web.
 The Zipf distribution describes collections that have a few items whose
 probability of selection is very high, a medium number of items whose probabili
ty of selection is medium, and a huge number of items whose probability
 of selection is very low.
\begin_inset LatexCommand index
name "random!discrete|)"

\end_inset


\end_layout

\begin_layout Subsection
Continuous Distributions
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "random!continuous|("

\end_inset

Continuous random numbers can take on an uncountable number of values.
 Therefore, the value returned by a continuous distribution is denoted 
\begin_inset Formula $x$
\end_inset

.
 Because there is an uncountable number of possibilities for the random
 number
\begin_inset Foot
status open

\begin_layout Standard
A computer actually always generates a random number from a discrete distributio
n because there are only a finite set of numbers that can be represented
 by a computer.
 However, for continuous random number generators, the resulting random
 numbers usually approximate the continuous distribution well enough to
 ignore the subtlety.
\end_layout

\end_inset

, a continuous distribution is modeled by a probability density function,
 
\begin_inset Formula $f\left(x;\cdot\right).$
\end_inset

 To obtain the probability that the random number generated by 
\begin_inset Formula $X\left(\cdot\right)$
\end_inset

 is in a certain interval, we integrate this density function: 
\begin_inset Formula \[
\int_{-\infty}^{b}f\left(x\right)dx=\textrm{Probability}\left\{ X\left(\cdot\right)\leq b\right\} .\]

\end_inset


\end_layout

\begin_layout Standard
To obtain a probability, we have to integrate 
\begin_inset Formula $f\left(x\right)$
\end_inset

 which is why it is called a density function.
 Most continuous distributions are defined by their probability density
 functions (pdf).
 Some have basic origins, a few are derived from other distributions, and
 some are used mainly for modelling unknown distributions.
 
\end_layout

\begin_layout Standard
Some of the parameters of the distributions are labeled as location (
\emph on
loc
\emph default
) and 
\emph on
scale
\emph default
 parameters.
 These parameters are not shown in the equation for the pdf.
 because they affect the distribution in a known way.
 This is due to the fact that if 
\begin_inset Formula $X$
\end_inset

 is a number drawn from a distribution with pdf 
\begin_inset Formula $f_{X}\left(x\right),$
\end_inset

 then 
\begin_inset Formula $Y=Sx+L$
\end_inset

 is a number drawn from a distribution with pdf 
\begin_inset Formula \[
f_{Y}\left(y\right)=\frac{1}{S}f_{X}\left(\frac{y-L}{S}\right).\]

\end_inset

 Thus, from the standard from provided, the pdf of the actual random numbers
 generated by fixing the location and scale parameters can be quickly found.
\end_layout

\begin_layout Standard
In this section, the indicator function 
\begin_inset Formula $I_{A}\left(x\right)$
\end_inset

 will be used where 
\begin_inset Formula $A$
\end_inset

 is a set defined over all the real numbers.
 For clarity,
\begin_inset Formula \[
I_{A}\left(x\right)=\left\{ \begin{array}{cc}
1 & x\in A,\\
0 & x\not\in A.\end{array}\right.\]

\end_inset

 Also, the following functions are used in the definitions: 
\begin_inset Formula \begin{eqnarray*}
\Gamma\left(x\right) & = & \int_{0}^{\infty}t^{x-1}e^{-t}dt=\left(x-1\right)\Gamma\left(x-1\right),\\
B\left(a,b\right) & = & \frac{\Gamma\left(a\right)\Gamma\left(b\right)}{\Gamma\left(a+b\right)}.\end{eqnarray*}

\end_inset


\end_layout

\begin_layout Description
beta (
\begin_inset Formula $a$
\end_inset

, 
\begin_inset Formula $b$
\end_inset

, size=None)
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;a,b\right)=\frac{1}{B\left(a,b\right)}x^{a-1}\left(1-x\right)^{b-1}I_{\left(0,1\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
chisquare (
\begin_inset Formula $\nu$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 If 
\begin_inset Formula $Z_{1},\ldots,Z_{\nu}$
\end_inset

 are random numbers from standard normal distributions, then 
\begin_inset Formula $W=\sum_{k=1}^{\nu}Z_{k}^{2}$
\end_inset

 is a random number from the chi-square 
\begin_inset Formula $\left(\chi^{2}\right)$
\end_inset

 distribution with 
\begin_inset Formula $\nu$
\end_inset

 degrees of freedom.
 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;\nu\right)=\frac{1}{2\Gamma\left(\frac{\nu}{2}\right)}\left(\frac{x}{2}\right)^{\nu/2-1}e^{-x/2}I_{\left[0,\infty\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
dirichlet (
\begin_inset Formula $\boldsymbol{\alpha},$
\end_inset

 size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A vector of random numbers which are drawn from a multivariate Dirichlet
 distribution.
 The length of the parameter vector, 
\begin_inset Formula $\boldsymbol{\alpha},$
\end_inset

 is the length, 
\begin_inset Formula $N$
\end_inset

, of the random vector.
 The joint pdf is:
\end_layout

\begin_layout Description
\begin_inset Formula \[
f\left(\mathbf{x},\boldsymbol{\alpha}\right)=\frac{\prod_{i=1}^{N}\Gamma\left(\alpha_{i}\right)}{\Gamma\left(\sum_{i=1}^{N}\alpha_{i}\right)}\prod_{i=1}^{N}x_{i}^{\alpha_{i}-1}.\]

\end_inset


\series medium
 
\end_layout

\begin_layout Description
exponential (scale=1.0, size=None) 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x\right)=e^{-x}I_{\left[0,\infty\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
f (
\begin_inset Formula $\nu_{1}$
\end_inset

, 
\begin_inset Formula $\nu_{2}$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 The distribution of 
\begin_inset Formula $\frac{X_{1}/\nu_{1}}{X_{2}/\nu_{2}}$
\end_inset

 where 
\begin_inset Formula $X_{i}$
\end_inset

 is chi-squared with 
\begin_inset Formula $\nu_{i}$
\end_inset

 degrees of freedom.
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;\nu_{1},\nu_{2}\right)=\frac{\nu_{2}^{\nu_{2}/2}\nu_{1}^{\nu_{1}/2}x^{\nu_{1}/2-1}}{\left(\nu_{2}+\nu_{1}x\right)^{\left(\nu_{1}+\nu_{2}\right)/2}B\left(\frac{\nu_{1}}{2},\frac{\nu_{2}}{2}\right)}I_{\left[0,\infty\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
gamma (
\begin_inset Formula $a$
\end_inset

, scale=1.0, size=None)
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;a\right)=\frac{1}{\Gamma\left(a\right)}x^{a-1}e^{-x}I_{\left[0,\infty\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
gumbel (loc=0.0, scale=1.0, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A right-skewed extreme value distribution.
 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x\right)=\exp\left[-x-e^{-x}\right].\]

\end_inset


\end_layout

\begin_layout Description
laplace (loc=0.0, scale=1.0, size=None)
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x\right)=\frac{1}{2}e^{-\left|x\right|}.\]

\end_inset


\end_layout

\begin_layout Description
lognormal (
\begin_inset Formula $\mu$
\end_inset

=0.0, 
\begin_inset Formula $\sigma$
\end_inset

=1.0, size=None)
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;\mu,\sigma\right)=\frac{1}{\sigma x\sqrt{2\pi}}\exp\left[-\frac{1}{2}\left(\frac{\log x-\mu}{\sigma}\right)^{2}\right]I_{\left[0,\infty\right)}\left(x\right),\]

\end_inset

The parameters, 
\begin_inset Formula $\mu$
\end_inset

 and 
\begin_inset Formula $\sigma$
\end_inset

 are not the mean and variance of this distribution, but the parameters
 of the underlying normal distribution.
 Random numbers from this distribution are generated as 
\begin_inset Formula $e^{\sigma Z+\mu}$
\end_inset

 where 
\begin_inset Formula $Z$
\end_inset

 is a standard normal random number.
 
\end_layout

\begin_layout Description
logistic (loc=0.0, scale=1.0, size=None) 
\begin_inset Formula \[
f\left(x\right)=\frac{e^{-x}}{\left[1+e^{-x}\right]^{2}}I_{\left[0,\infty\right)}\left(x\right)\]

\end_inset


\end_layout

\begin_layout Description
multivariate_normal (
\begin_inset Formula $\mathbf{\boldsymbol{\mu}}$
\end_inset

, 
\begin_inset Formula $\mathbf{C}$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns a vector of random numbers which are jointly drawn from a multivariate
 normal distribution.
 The last-dimension of the output array contains the sample vector, which
 is of length 
\begin_inset Formula $N=\textrm{len}\left(mean\right).$
\end_inset

 The covariance matrix must be 
\begin_inset Formula $N\times N$
\end_inset

.
 If 
\begin_inset Formula $\boldsymbol{\mu}\equiv mean$
\end_inset

 and 
\begin_inset Formula $\mathbf{C}=cov$
\end_inset

, then the joint-pdf representing the returned random vector(s) is 
\begin_inset Formula \[
f\left(\mathbf{x}\right)=\frac{1}{\sqrt{\left(2\pi\right)^{N}\left|\mathbf{C}\right|}}\exp\left[-\frac{1}{2}\left(\mathbf{x}-\boldsymbol{\mu}\right)^{T}\mathbf{C}^{-1}\left(\mathbf{x}-\boldsymbol{\mu}\right)\right].\]

\end_inset


\end_layout

\begin_layout Description
noncentral_chisquare (
\begin_inset Formula $\nu$
\end_inset

, 
\begin_inset Formula $\lambda$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This is the distribution of 
\begin_inset Formula $\sum_{i=1}^{\nu}\left(Z_{i}+\delta_{i}\right)^{2}$
\end_inset

 where 
\begin_inset Formula $Z_{i}$
\end_inset

 are independent standard normal random numbers and 
\begin_inset Formula $\delta_{i}$
\end_inset

 are constants.
 It is a a generalized Rayleigh-Rice distribution: 
\end_layout

\begin_deeper
\begin_layout Standard
\begin_inset Formula \[
f\left(x;\nu,\lambda\right)=e^{-\left(\lambda+x\right)/2}\frac{1}{2}\left(\frac{x}{\lambda}\right)^{\left(\nu-2\right)/4}I_{\left(\nu-2\right)/2}\left(\sqrt{\lambda x}\right)I_{\left(0,\infty\right)}\left(x\right),\]

\end_inset

 where 
\begin_inset Formula $I_{\nu}\left(z\right)$
\end_inset

 (a real-number in the subscript, not an interval) is the modified Bessel
 Function of the first kind.
 
\end_layout

\end_deeper
\begin_layout Description
noncentral_f (
\begin_inset Formula $\nu_{1}$
\end_inset

, 
\begin_inset Formula $\nu_{2}$
\end_inset

, 
\begin_inset Formula $\lambda$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 The pdf of this distribution is 
\begin_inset Formula \begin{eqnarray*}
f\left(x;\nu_{1},\nu_{2},\lambda\right) & = & \exp\left[\frac{\lambda}{2}+\frac{\lambda v_{1}x}{2\left(\nu_{1}x+\nu_{2}\right)}\right]\nu_{1}^{\nu_{1}/2}\nu_{2}^{\nu_{2}/2}x^{\nu_{1}/2-1}\\
 &  & \times\left(\nu_{2}+\nu_{1}x\right)^{-\left(\nu_{1}+\nu_{2}\right)/2}\\
 &  & \times\frac{\Gamma\left(\frac{\nu_{1}}{2}\right)\Gamma\left(1+\frac{\nu_{2}}{2}\right)L_{n_{2}/2}^{n_{1}/2-1}\left(-\frac{\lambda\nu_{1}x}{2\left(\nu_{1}x+\nu_{2}\right)}\right)}{B\left(\frac{\nu_{1}}{2},\frac{\nu_{2}}{2}\right)\Gamma\left(\frac{\nu_{1}+\nu_{2}}{2}\right)}.\end{eqnarray*}

\end_inset


\end_layout

\begin_layout Description
normal (loc=0.0, scale=1.0, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 The normal, or Gaussian, distribution is the limiting distribution of independe
nt samples from any sufficiently well-behaved distributions (this is the
 content of the celebrated central limit theorem).
 The normal distribution is also the distribution of maximum entropy when
 the mean and variance alone are fixed.
 These two facts account for its name as well as the wide variety of situations
 that can be usefully modelled using the normal distribution.
 Because it is so widely used, the full pdf with the location 
\begin_inset Formula $\left(\mu\right)$
\end_inset

 and scale 
\begin_inset Formula $\left(\sigma\right)$
\end_inset

 parameters is provided:
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x\right)=\frac{1}{\sigma\sqrt{2\pi}}\exp\left[-\frac{\left(x-\mu\right)^{2}}{2\sigma^{2}}\right].\]

\end_inset


\end_layout

\begin_layout Description
pareto (
\begin_inset Formula $a$
\end_inset

, size=None)
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;a\right)=\frac{a}{x^{a+1}}I_{\left[1,\infty\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
power (
\begin_inset Formula $a$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A special case of the beta distribution with 
\begin_inset Formula $b=1.$
\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;a\right)=ax^{a-1}I_{\left[0,1\right]}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
rand (
\begin_inset Formula $d_{1}$
\end_inset

,
\begin_inset Formula $d_{2}$
\end_inset

, 
\begin_inset Formula $\ldots$
\end_inset

,
\begin_inset Formula $d_{n}$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 A convenient interface to obtain an array of shape 
\begin_inset Formula $\left(d_{1},d_{2},\ldots,d_{n}\right)$
\end_inset

 of uniform random numbers in the interval 
\begin_inset Formula $\left[0,1\right).$
\end_inset

 Notice the different convention for passing in the shape (as separate arguments
 instead of a tuple).
 The standard convention is used in the function numpy.random.random(shape)
 for which this function is merely a convenient short-hand.
 If you have a tuple named shape, then rand(*shape) will work correctly.
\end_layout

\begin_layout Description
randint (low, high=None, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Equally probably random integers in the range 
\begin_inset Formula $low\leq x<high$
\end_inset

.
 If 
\begin_inset Formula $high$
\end_inset

 is None, then the range is 
\begin_inset Formula $0\leq x<low$
\end_inset

.
 Similar to random_integers, but check the difference on the bounds.
\end_layout

\begin_layout Description
randn (
\begin_inset Formula $d_{1}$
\end_inset

,
\begin_inset Formula $d_{2}$
\end_inset

, 
\begin_inset Formula $\ldots$
\end_inset

,
\begin_inset Formula $d_{n}$
\end_inset

)
\end_layout

\begin_layout Description
\InsetSpace ~
 A convenient interface to obtain an array of shape 
\begin_inset Formula $\left(d_{1},d_{2},\ldots,d_{n}\right)$
\end_inset

 of standard normal 
\begin_inset Formula $\left(\mu=0,\,\sigma=1\right)$
\end_inset

 random numbers.
 Notice the different convention for passing in the shape (as separate arguments
 intead of a tuple).
 The standard convention is used in the function numpy.random.standard_normal(shap
e) for which this function is merely a convenient short-hand.
 If you have a tuple named shape, then randn(*shape) will work correctly.
\end_layout

\begin_layout Description
random_integers (low, high=None, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Equally probably random integers in the range 
\begin_inset Formula $low\leq x\leq high$
\end_inset

.
 If high is None, then the range is 
\begin_inset Formula $1\leq x\leq low$
\end_inset

.
 Similar to randint, but check the difference on the bounds.
\end_layout

\begin_layout Description
rayleigh (scale=1.0, size=None) 
\end_layout

\begin_layout Description
\InsetSpace ~
 Rayleigh-distributed random numbers can be obtained as 
\begin_inset Formula $X=\sqrt{Z_{1}^{2}+Z_{2}^{2}}$
\end_inset

 where 
\begin_inset Formula $Z_{i}$
\end_inset

 are independent standard normal random numbers.
 The scale parameter is also the mode of the distribution (the value of
 
\begin_inset Formula $X$
\end_inset

 with highest probability).
 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x\right)=xe^{-x^{2}/2}I_{[0,\infty)}\left(x\right)\]

\end_inset


\end_layout

\begin_layout Description
standard_cauchy (size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A Cauchy distribution is a heavy-tailed distribution with no variance.
 It's distribution is that of the ratio of two standard normal distributions
 
\begin_inset Formula $Z_{1}/Z_{2}.$
\end_inset

 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x\right)=\frac{1}{\pi\left(1+x^{2}\right)}.\]

\end_inset


\end_layout

\begin_layout Description
standard_exponential (size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A standard exponetial random number with scale=1.0.
 The pdf was given under the description of 
\family typewriter
random.exponential
\family default
.
\end_layout

\begin_layout Description
standard_gamma (
\begin_inset Formula $a$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A standard gamma random number with scale=1.0.
 The pdf was given under the description of 
\family typewriter
random.gamma
\family default
.
\end_layout

\begin_layout Description
standard_normal (size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A zero-mean, unit-variance, normally distributed random number often denoted
 
\begin_inset Formula $Z.$
\end_inset

 
\begin_inset Formula \[
f\left(x\right)=\frac{1}{\sqrt{2\pi}}e^{-x^{2}/2}.\]

\end_inset


\end_layout

\begin_layout Description
standard_t (
\begin_inset Formula $\nu$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Often called Student's t distribution, this random number distribution
 arises in the problem of estimating the mean of normally distributed samples
 when the sample-size is small.
 The first parameter, 
\begin_inset Formula $\nu$
\end_inset

, is the number of degrees of freedom of the distribution.
 
\begin_inset Formula \[
f\left(x;\nu\right)\frac{\Gamma\left(\frac{\nu+1}{2}\right)}{\sqrt{\pi\nu}\Gamma\left(\frac{\nu}{2}\right)\left[1+\frac{x^{2}}{\nu}\right]^{\frac{\nu+1}{2}}}.\]

\end_inset


\end_layout

\begin_layout Description
triangular (left, mode, right, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns random numbers according to a triangularly-shaped density that
 starts at left, peaks at mode, and ends at right.
\end_layout

\begin_layout Description
uniform (low=0.0, high=1.0, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns random numbers that are equally probable over the range 
\begin_inset Formula $\left[low,\, high\right).$
\end_inset


\end_layout

\begin_layout Description
vonmises (
\begin_inset Formula $\mu$
\end_inset

, 
\begin_inset Formula $\kappa$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 A continuous distribution that is well suited for circular attributes such
 as angles, time of day, day of the year, etc.
 The mean direction is 
\begin_inset Formula $\mu$
\end_inset

 and concentration (or dispersion) parameter is 
\begin_inset Formula $\kappa.$
\end_inset

 For small 
\begin_inset Formula $\kappa$
\end_inset

 the distribution tends towards a uniform distribution over 
\begin_inset Formula $\left[-\pi,\pi\right].$
\end_inset

 For large 
\begin_inset Formula $\kappa$
\end_inset

, the distribution tends towards a normal distribution with mean 
\begin_inset Formula $\mu$
\end_inset

 and variance 
\begin_inset Formula $1/\kappa.$
\end_inset

 
\begin_inset Formula \[
f\left(x\right)=\frac{e^{\kappa\cos\left(x-\mu\right)}}{2\pi I_{0}\left(\kappa\right)}I_{\left[-\pi,\pi\right]}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Description
wald (
\begin_inset Formula $\mu$
\end_inset

, 
\begin_inset Formula $\lambda$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 This distribution is also called the inverse Gaussian distribution (and
 the Wald distribution considered as a special case when 
\begin_inset Formula $\mu=\lambda$
\end_inset

).
 It can be generated by noticing that if 
\begin_inset Formula $X$
\end_inset

 is a wald random number then 
\begin_inset Formula $\frac{\lambda\left(X-\mu\right)^{2}}{\mu^{2}X}$
\end_inset

 is the square of a standard normal random number (i.e.
 it is chi-square with one degree of freedom).
 The pdf is 
\begin_inset Formula \[
f\left(x\right)=\sqrt{\frac{\lambda}{2\pi x^{3}}}e^{-\frac{\lambda\left(x-\mu\right)^{2}}{2\mu^{2}x}}.\]

\end_inset


\end_layout

\begin_layout Description
weibull (
\begin_inset Formula $a$
\end_inset

, size=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 An extreme-value distribution: 
\end_layout

\begin_layout Standard
\begin_inset Formula \[
f\left(x;c\right)=ax^{a-1}\exp\left(-x^{a}\right)I_{\left(0,\infty\right)}\left(x\right).\]

\end_inset


\end_layout

\begin_layout Subsection
Miscellaneous utilities
\end_layout

\begin_layout Description
bytes (length)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a string of random bytes of the provided length.
\end_layout

\begin_layout Description
get_state ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an object that holds the state of the random number generator (allows
 you to restart simulations where you left off).
\end_layout

\begin_layout Description
set_state (state)
\end_layout

\begin_layout Description
\InsetSpace ~
 Set the state of the random number generator.
 The argument should be the returned object of a previous get_state command.
\end_layout

\begin_layout Description
shuffle (sequence)
\end_layout

\begin_layout Description
\InsetSpace ~
 Randomly permute the items of any sequence.
 If sequence is an array, then it must be 1-d.
\end_layout

\begin_layout Description
permutation (n)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a permutation of the integers from 0 to n-1.
 
\begin_inset LatexCommand index
name "random!continuous|)"

\end_inset


\begin_inset LatexCommand index
name "random|)"

\end_inset


\end_layout

\begin_layout Section
Matrix-specific functions (matlib)
\end_layout

\begin_layout Standard
This module contains functions that are geared specifically toward matrix
 objects.
 In particular it includes the functions 
\series bold
empty
\series default
, 
\series bold
ones
\series default
, 
\series bold
zeros
\series default
, 
\series bold
identity
\series default
, 
\series bold
eye
\series default
, 
\series bold
rand
\series default
, and 
\series bold
randn
\series default
 each of which returns a matrix object by default instead of an ndarray
 object.
\end_layout

\begin_layout Section
Ctypes utiltity functions (ctypeslib)
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ctypeslib"

\end_inset

This module contains utility functions that make it easier to work with
 the ctypes module.
 
\end_layout

\begin_layout Description
load_library (name, path)
\end_layout

\begin_layout Description
\InsetSpace ~
 Load a shared library named 
\begin_inset Quotes eld
\end_inset

name
\begin_inset Quotes erd
\end_inset

 (use the full name including any prefix but excluding the extension) located
 in the directory indicated by path and return a ctypes library object whose
 attributes are the functions in the library.
 If ctypes is not available, this function will raise an ImportError.
 If there is an error loading the library, ctypes raises an OSError.
 The extension is appended to the library name (on a platform-dependent
 basis) unless the name includes the 
\begin_inset Quotes eld
\end_inset

.
\begin_inset Quotes erd
\end_inset

 character in which case name is assumed to be the 
\begin_inset Quotes eld
\end_inset

full-name
\begin_inset Quotes erd
\end_inset

 of the library.
 
\end_layout

\begin_layout Description
ndpointer (dtype=None, ndim=None, shape=None, flags=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Create a class object that can be used in the argtypes list of a ctypes
 function that will do basic type, number-of-dimensions, shape, and flags
 checking on input array objects.
 Setting an argtypes entry with the result of this function allows passing
 arrays directly to ctypes-wrapped functions.
 The returned class object will contain a from_param method as required
 by ctypes.
 This from_param method takes the array object, does data-type, number-of-dimens
ions, shape, and flags checking on the object and if all tests pass returns
 an object that ctypes can use as the data area of the array.
 Checking is not performed for any entries which are None in this class
 creation function.
 
\end_layout

\begin_layout Chapter
Testing and Packaging
\end_layout

\begin_layout Quotation
Research is what I'm doing when I don't know what I'm doing.
\end_layout

\begin_layout Right Address
---
\emph on
Werner von Braun
\end_layout

\begin_layout Quotation
The most likely way for the world to be destroyed, most experts agree, is
 by accident.
 That's where we come in; we're computer professionals.
 We cause accidents.
\end_layout

\begin_layout Right Address
---
\emph on
Nathaniel Borenstein
\end_layout

\begin_layout Standard
There are two additional sub-packages distributed with NumPy that simplify
 the process of distributing and testing code based on NumPy.
 The numpy.distutils sub-package extends the standard distutils package to
 handle Fortran code along with providing support for the auto-generated
 code in NumPy.
 The numpy.testing sub-package defines a few functions and classes for standardiz
ing unit-tests in NumPy.
 These facilities can be used in your own packages that build on top of
 NumPy.
 
\end_layout

\begin_layout Section
Testing
\end_layout

\begin_layout Standard
In this sub-package are two classes and some useful utilities for writing
 unit-tests
\end_layout

\begin_layout Description
NumpyTestCase a subclass of unittest.TestCase which adds a measure method
 that can determine the elasped time to execute a code string and enhances
 the __call__ method 
\end_layout

\begin_layout Description
NumpyTest the test manager for NumPy which was extracted originally from
 the SciPy code base.
 This test manager makes it easy to add unit-tests to a package simply by
 creating a tests sub-directory with files named test_<module>.py.
 These test files should then define sub-classes of NumpyTestCase (or unittest.Te
stCase) named 
\begin_inset Quotes eld
\end_inset

test*
\begin_inset Quotes erd
\end_inset

.
 These classes should then define functions named 
\begin_inset Quotes eld
\end_inset

test*
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

bench*
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

check*
\begin_inset Quotes erd
\end_inset

 that contain the actual unit-tests.
 The first keyword argument should specify the level above which this test
 should be run.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 To run the tests excecute NumpyTest(<package>).test(level=1, verbosity=1)
 which will run all tests above the given level using the given verbosity.
 Here <package> can be either a string or a previously imported module.
 You can get the level and verbosity arguments from sys.argv using NumpyTest(<pac
kage>).run() with -v or --verbosity and -l or --level as command-line arguments.
\end_layout

\begin_layout Description
set_local_path (reldir='', level=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 prepend local directory (+ reldir) to sys.path.
 The caller is responsible for removing this path using restore_path().
\end_layout

\begin_layout Description
set_package_path (level=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 prepend package directory to sys.path.
 This should be called from a test_file.py that satisfies the tree structure:
 <somepath>/<somedir>/test_file.py.
 The, the first existing path name from the list <somepath>/build/lib.<platform>-
<version>, <somepath>/..
 is pre-pended to sys.path.
 The caller is responsible for removing this path using restore_path().
\end_layout

\begin_layout Description
restore_path ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Remove the first entry from sys.path.
\end_layout

\begin_layout Description
assert_equal (actual, desired, err_msg='', verbose=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Raise an assertion error if the two items are not equal.
 Automatically calls assert_array_equal if actual or desired is an ndarray.
 
\end_layout

\begin_layout Description
assert_almost_equal (actual, desired, decimal=7, err_msg='', verbose=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Raise an assertion error if the two items are not equal within decimal
 places.
 Automatically calls assert_array_almost_equal if actual or desired is an
 ndarray.
\end_layout

\begin_layout Description
assert_approx_equal (actual, desired, significant=7, err_msg='', verbose=1)
\end_layout

\begin_layout Description
\InsetSpace ~
 Raise an assertion error if the two items are not equal to within the given
 significant digits.
 Does not work on arrays.
 
\end_layout

\begin_layout Description
assert_array_equal (x, y, err_msg='')
\end_layout

\begin_layout Description
\InsetSpace ~
 Raise an error if the two arrays x and y are not equal at every element.
 
\end_layout

\begin_layout Description
assert_array_less (x, y, err_msg='')
\end_layout

\begin_layout Description
\InsetSpace ~
 Raise an error if the two arrays x and y have different shapes or if x
 is not less than y at every element.
 
\end_layout

\begin_layout Description
assert_array_almost_equal (x, y, decimal=6, err_msg='')
\end_layout

\begin_layout Description
\InsetSpace ~
 Raise an error if x and y are not equal to decimal places at every element.
\end_layout

\begin_layout Description
jiffies ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a number of 1/100ths of a second that this process has been scheduled
 in user mode.
 Implemented using time.time() unless on Linux where the special /proc directory
 filesystem is used.
 
\end_layout

\begin_layout Description
memusage ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the virtual memory size in bytes of the running python.
 If the operation is not supported on the platform, then return None.
 This works only on linux for now.
\end_layout

\begin_layout Description
rand (*args)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return an array of random numbers with the given shape using only the standard
 library random number generator.
\end_layout

\begin_layout Description
runstring (astr, dict)
\end_layout

\begin_layout Description
\InsetSpace ~
 Run the given string in the dictionary provided.
 Functional form for (exec astr in dict) that is useful for the failUnlessRaises
 method of unittest.TestCase class.
\end_layout

\begin_layout Section
NumPy Distutils
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "distutils"

\end_inset

NumPy provides enhanced distutils functionality to make it easier to build
 and install sub-packages, auto-generate code, and extension modules that
 use Fortran-compiled libraries.
 To use features of numpy distutils use the setup command from numpy.distutils.cor
e.
 A useful Configuration class is also provided in numpy.distutils.misc_util
 that can make it easier to construct keyword arguments to pass to the setup
 function (by passing the dictionary obtained from the todict() method of
 the class).
 More information is available in the NumPy Distutils Users Guide in <site-packa
ges>/numpy/doc/DISTUTILS.txt.
\end_layout

\begin_layout Subsection
misc_util
\end_layout

\begin_layout Description
Configuration (package_name=None, parent_name=None, top_path=None, package_path=
None, **attrs)
\end_layout

\begin_layout Description
\InsetSpace ~
 
\begin_inset LatexCommand index
name "Configuration"

\end_inset

Construct a configuration instance for the given package name.
 If parent_name is not None, then construct the package as a sub-package
 of the parent_name package.
 If top_path and package_path are None then they are assumed equal to the
 path of the file this instance was created in.
 The setup.py files in the numpy distribution are good examples of how to
 use the Configuration instance.
\end_layout

\begin_deeper
\begin_layout Description
self.todict () 
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a dictionary compatible with the keyword arguments of distutils
 setup function.
 Thus, this method may be used as setup(**config.todict()).
\end_layout

\begin_layout Description
self.get_distribution ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the distutils distribution object for self.
\end_layout

\begin_layout Description
self.get_subpackage (subpackage_name, subpackage_path=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a Configuration instance for the sub-package given.
 If subpackage_path is None then the path is assumed to be the local path
 plus the subpackage_name.
 If a setup.py file is not found in the subpackage_path, then a default configura
tion is used.
\end_layout

\begin_layout Description
self.add_subpackage (subpackage_name, subpackage_path=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add a sub-package to the current Configuration instance.
 This is useful in a setup.py script for adding sub-packages to a package.
 The sub-package is contained in subpackage_path / subpackage_name and this
 directory may contain a setup.py script or else a default setup (suitable
 for Python-code-only subpackages) is assumed.
 If the subpackage_path is None, then it is assumed to be located in the
 local path / subpackage_name.
 
\end_layout

\begin_layout Description
self.add_data_files (*files)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add files to the list of data_files to be included with the package.
 The form of each element of the files sequence is very flexible allowing
 many combinations of where to get the files from the package and where
 they should ultimately be installed on the system.
 The most basic usage is for an element of the files argument sequence to
 be a simple filename.
 This will cause that file from the local path to be installed to the installati
on path of the self.name package (package path).
 The file argument can also be a relative path in which case the entire
 relative path will be installed into the package directory.
 Finally, the file can be an absolute path name in which case the file will
 be found at the absolute path name but installed to the package path.
\end_layout

\begin_layout Description
\InsetSpace ~
 This basic behavior can be augmented by passing a 2-tuple in as the file
 argument.
 The first element of the tuple should specify the relative path (under
 the package install directory) where the remaining sequence of files should
 be installed to (it has nothing to do with the file-names in the source
 distribution).
 The second element of the tuple is the sequence of files that should be
 installed.
 The files in this sequence can be filenames, relative paths, or absolute
 paths.
 For absolute paths the file will be installed in the top-level package
 installation directory (regardless of the first argument).
 Filenames and relative path names will be installed in the package install
 directory under the path name given as the first element of the tuple.
 An example may clarify:
\end_layout

\begin_deeper
\begin_layout LyX-Code
self.add_data_files('foo.dat',
\newline
('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']),
 
\newline
'bar/cat.dat', 
\newline
'/full/path/to/can.dat')
\end_layout

\begin_layout Standard
will install these data files to:
\end_layout

\begin_layout LyX-Code
<package install directory>/
\newline
 foo.dat
\newline
 fun/
\newline
   gun.dat
\newline
   nun/
\newline
     pun.dat
\newline
 sun.dat
\newline

 bar/
\newline
   car.dat
\newline
 can.dat
\end_layout

\begin_layout Standard
where <package install directory> is the package (or sub-package) directory
 such as '/usr/lib/python2.4/site-packages/mypackage' ('C:
\backslash

\backslash
Python2.4
\backslash

\backslash
Lib
\backslash

\backslash
site-packages
\backslash

\backslash
mypackage') or '/usr/lib/python2.4/site-packages/mypackage/mysubpackage'
 ('C:
\backslash

\backslash
Python2.4
\backslash

\backslash
Lib
\backslash

\backslash
site-packages
\backslash

\backslash
mypackage
\backslash

\backslash
mysubpackage').
\end_layout

\end_deeper
\begin_layout Standard
\InsetSpace ~
 An additional feature is that the path to a data-file can actually be a
 function that takes no arguments and returns the actual path(s) to the
 data-files.
 This is useful when the data files are generated while building the package.
 
\end_layout

\begin_layout Description
self.add_data_dir (data_path)
\end_layout

\begin_layout Description
\InsetSpace ~
 Recursively add files under data_path to the list of data_files to be installed
 (and distributed).
 The data_path can be either a relative path-name, or an absolute path-name,
 or a 2-tuple where the first argument shows where in the install directory
 the data directory should be installed to.
 For example suppose the source directory contains fun/foo.dat and fun/bar/car.dat
\end_layout

\begin_layout LyX-Code
self.add_data_dir('fun')
\newline
self.add_data_dir(('sun', 'fun'))
\newline
self.add_data_dir(('gun',
 '/full/path/to/fun'))
\end_layout

\begin_layout Standard
\InsetSpace ~
 Will install data-files to the locations
\end_layout

\begin_layout LyX-Code
<package install directory>/
\newline
  fun/
\newline
    foo.dat
\newline
    bar/
\newline
      car.dat
\newline
  sun/
\newline
 
   foo.dat
\newline
    bar/
\newline
      car.dat
\newline
  gun/
\newline
    foo.dat
\newline
    car.dat
\end_layout

\begin_layout Description
self.add_include_dirs (*paths)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add the given sequence of paths to the beginning of the include_dirs list.
 This list will be visible to all extension modules of the current package.
\end_layout

\begin_layout Description
self.add_headers (*files)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add the given sequence of files to the beginning of the headers list.
 By default, headers will be installed under <python-include>/<self.name.replace('.
','/')>/ directory.
 If an item of files is a tuple, then its first argument specifies the actual
 installation location relative to the <python-include> path.
\end_layout

\begin_layout Description
self.add_extension (name, sources, **kw)
\end_layout

\begin_layout Description
\InsetSpace ~
 Create and add an Extension instance to the ext_modules list.
 The first argument defines the name of the extension module that will be
 installed under the self.name package.
 The second argument is a list of sources.
 This method also takes the following optional keyword arguments that are
 passed on to the Extension constructor: include_dirs, define_macros, undef_macr
os, library_dirs, libraries, runtime_library_dirs, extra_objects, swig_opts,
 depends, language, f2py_options, module_dirs, and extra_info.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 The self.paths(...) method is applied to all lists that may contain paths.
 The extra_info is a dictionary or a list of dictionaries whose content
 will be appended to the keyword arguments.
 The depends list contains paths to files or directories that the sources
 of the extension module depend on.
 If any path in the depends list is newer than the extension module, then
 the module will be rebuilt.
 
\end_layout

\begin_layout Description
\InsetSpace ~
 The list of sources may contain functions (called source generators) which
 must take an extension instance and a build directory as inputs and return
 a source file or list of source files or None.
 If None is returned then no sources are generated.
 If the Extension instance has no sources after processing all source generators
, then no extension module is built.
 
\end_layout

\begin_layout Description
self.add_library (name, sources, **build_info)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add a library to the list of libraries.
 Allowed keyword arguments are depends, macros, include_dirs, extra_compiler_arg
s, and f2py_options.
 The name is the name of the library to be built and sources is a list of
 sources (or source generating functions) to add to the library.
\end_layout

\begin_layout Description
self.add_scripts (*files)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add the sequence of files to the beginning of the scripts list.
 Scripts will be installed under the <prefix>/bin/ directory.
 
\end_layout

\begin_layout Description
self.paths (*paths)
\end_layout

\begin_layout Description
\InsetSpace ~
 Applies glob.glob(...) to each path in the sequence (if needed) and pre-pends
 the local_path if needed.
 Because this is called on all source lists, this allows wildcard characters
 to be specified in lists of sources for extension modules and libraries
 and scripts and allows path-names be relative to the source directory.
\end_layout

\begin_layout Description
self.get_config_cmd ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the numpy.distutils config command instance.
\end_layout

\begin_layout Description
self.get_build_temp_dir ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a path to a temporary directory where temporary files should be
 placed.
\end_layout

\begin_layout Description
self.have_f77c ()
\end_layout

\begin_layout Description
\InsetSpace ~
 True if a Fortran 77 compiler is available (because a simple Fortran 77
 code was able to be compiled successfully).
\end_layout

\begin_layout Description
self.have_f90c ()
\end_layout

\begin_layout Description
\InsetSpace ~
 True if a Fortran 90 compiler is available (because a simple Fortran 90
 code was able to be compiled successfully) 
\end_layout

\begin_layout Description
self.get_version ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a version string of the current package or None if the version informati
on could not be detected.
 This method scans files named __version__.py, <packagename>_version.py, version.py
, and __svn_version__.py for string variables version, __version__, and <packagen
ame>_version, until a version number is found.
\end_layout

\begin_layout Description
self.make_svn_version_py ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Appends a data function to the data_files list that will generate __svn_version
__.py file to the current package directory.
 This file will be removed from the source directory when Python exits (so
 that it can be re-generated next time the package is built).
 This is intended for working with source directories that are in an SVN
 repository.
 
\end_layout

\begin_layout Description
self.make_config_py ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Generate a package __config__.py file containing system information used
 during the building of the package.
 This file is installed to the package installation directory.
\end_layout

\begin_layout Description
self.get_info (*names)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return information (from system_info.get_info) for all of the names in the
 argument list in a single dictionary.
 
\end_layout

\end_deeper
\begin_layout Description
get_numpy_include_dirs ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the include directory where the numpy/arrayobject.h and numpy/ufuncobject.
h files are found.
 This should be added to the include_dirs of any extension module built
 using NumPy.
 If numpy.distutils is used to build the extension, then this directory is
 added automatically.
 
\end_layout

\begin_layout Description
get_numarray_include_dirs ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the include directory where the numpy/libnumarray.h file is found.
 This should be added to the include_dirs of any extension module that relies
 on the Numarray-compatible C-API.
 
\end_layout

\begin_layout Description
dict_append (d, **kwds)
\end_layout

\begin_layout Description
\InsetSpace ~
 Add the keyword arguments given as entries in the dictionary provided as
 the first argument.
 If the entry is already present, then assume it is a list and extend the
 list with the keyword value.
\end_layout

\begin_layout Description
appendpath (prefix, path)
\end_layout

\begin_layout Description
\InsetSpace ~
 Platform-independent intelligence for appending path to prefix.
 It replaces '/' in the prefix and the path with the correct path-separator
 on the platform ad returns a full path name that will be valid for the
 platform.
 
\end_layout

\begin_layout Description
allpath (name)
\end_layout

\begin_layout Description
\InsetSpace ~
 Convert a '/' separated pathname to one using the platform's path separator.
\end_layout

\begin_layout Description
dot_join (*args)
\end_layout

\begin_layout Description
\InsetSpace ~
 Converts a sequence of string arguments to a string joined by '.' (removing
 any empty strings).
 
\end_layout

\begin_layout Description
generate_config_py (extension, build_dir)
\end_layout

\begin_layout Description
\InsetSpace ~
 A suitable function that can be used in a source list.
 This constructs a python file that contains system_info information used
 during building the package.
 Generally easier to use a Configuration instance and the config.make_config_py()
 method.
\end_layout

\begin_layout Description
get_cmd (cmdname, _cache={})
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns an instance of the distutils command object named cmdname if the
 setup distribution instance has been initialized.
 Caches the result in _cache[cmdname] and gets it from there if present.
\end_layout

\begin_layout Description
terminal_has_colors ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Tries to determine if the stdout terminal can be written to using ANSI
 colors.
 Returns 1 if it can be determined that ANSI colors are acceptable or 0
 if not.
 
\end_layout

\begin_layout Description
red_text (s)
\end_layout

\begin_layout Description
green_text (s)
\end_layout

\begin_layout Description
yellow_text (s)
\end_layout

\begin_layout Description
blue_text (s)
\end_layout

\begin_layout Description
cyan_text (s)
\end_layout

\begin_layout Description
\InsetSpace ~
 If terminal_has_colors() is true, then these commands return a string with
 the necessary codes prepended to display the given string argument in the
 specified color on an ANSI terminal.
 If terminal_has_colors() is false, then these functions simply return the
 input argument.
 
\end_layout

\begin_layout Description
cyg2win32 (path)
\end_layout

\begin_layout Description
\InsetSpace ~
 Convert a cygwin path beginning with /cygdrive to a standard win32 path
 name.
 
\end_layout

\begin_layout Description
all_strings (lst)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return True if all items in the input list are string objects otherwise
 return False.
\end_layout

\begin_layout Description
has_f_sources (sources)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return True if any of the source files listed in the input argument are
 Fortran files because its name matches against the compiled regular expression
 
\series bold
fortran_ext_match
\series default
.
\end_layout

\begin_layout Description
has_cxx_sources (sources)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return True if any of the source files listed in the input argument are
 C++ files because its name matches against the compiled regular expression
 
\series bold
cxx_ext_match
\series default
.
\end_layout

\begin_layout Description
filter_sources (sources)
\end_layout

\begin_layout Description
\InsetSpace ~
 From the provided list of sources, return four lists of filenames containing
 C, C++, Fortran, and Fortran 90 module sources respectively.
 The compiled regular expressions used in this search (which are also available
 in the misc_util module) are cxx_ext_match, fortran_ext_match, f90_ext_match,
 and f90_module_name_match.
 
\end_layout

\begin_layout Description
get_dependencies (sources)
\end_layout

\begin_layout Description
\InsetSpace ~
 Scan the files in the sources list for include statements.
\end_layout

\begin_layout Description
is_local_src_dir (directory)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return True if the provided directory is the local current working directory.
 
\end_layout

\begin_layout Description
get_ext_source_files (ext)
\end_layout

\begin_layout Description
\InsetSpace ~
 Get sources and any include files in the same directory from an Extension
 instance.
\end_layout

\begin_layout Description
get_script_files (scripts)
\end_layout

\begin_layout Description
\InsetSpace ~
 Returns the list scripts with all non-string arguments removed.
\end_layout

\begin_layout Subsection
Other modules
\end_layout

\begin_layout Description
system_info.get_info (name)
\end_layout

\begin_layout Description
\InsetSpace ~
 For the given string representing a particular resource, return a dictionary
 that is compatible with the distutils.setup keyword arguments.
 If this is an empty dictionary, then the requested resource is not available.
 Some of the names that can be checked are 'lapack_opt', 'blas_opt', 'fft_opt',
 'fftw', 'fftw3', 'fftw2', 'djbfft', 'numpy', 'numarray', 'boost_python',
 'agg2', 'wx', 'gdk', 'xft', 'freetype2'.
 
\end_layout

\begin_layout Description
system_info.get_standard_file (filename)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return a list of length 0 to 3 containing the full-path filenames for the
 filename provided.
 The filename is searched for in three places in the following order 1)
 the system-wide location which is the directory that the system_info file
 is located in; 2) the directory specified by the environment variable HOME;
 and 3) the current local directory.
 
\end_layout

\begin_layout Description
cpuinfo.cpu an instance of a cpuinfo class that defines methods for checking
 various aspects of the cpu.
 The info attribute is a list of length (# of CPUs).
 Each entry is a dictionary providing technical information about that CPU.
 
\end_layout

\begin_layout Description
log.set_verbosity (level)
\end_layout

\begin_layout Description
\InsetSpace ~
 Set the distutils logging threshold and return the previously stored value.
 The level is an integer that corresponds to distutils.log thresholds: -1
 <--> ERROR, 0 <--> WARN, 1 <--> INFO, and 2 <--> DEBUG.
 
\end_layout

\begin_layout Description
exec_command
\end_layout

\begin_deeper
\begin_layout Description
exec_command (command, execute_in='', use_shell=None, use_tee=None, _with_python
=1, **env)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return (status, output) of the executed command.
 The command input is a string of executable and arguments.
 The output contains both stderr and stdout messages.
 If execute_in is given, then change to the provided directory prior to
 executing the command and afterwords restore to the current directory.
 On NT, and DOS systems the returned status is correct for external commands.
 However, wild cards will not work for non-posix systems.
\end_layout

\begin_layout Description
splitcmdline (line) 
\end_layout

\begin_layout Description
\InsetSpace ~
 Inverse of ' '.join(sys.argv)
\end_layout

\begin_layout Description
find_executable (exe, path=None)
\end_layout

\begin_layout Description
\InsetSpace ~
 Return full path of an executable using information from the PATH environment
 variable.
 Equivalent to the POSIX 'which' command.
\end_layout

\begin_layout Description
get_pythonexe ()
\end_layout

\begin_layout Description
\InsetSpace ~
 Return the full path to the python executable with some fixes for nt and
 dos to replace pythonw with python if it is encountered.
 A basic wrapper around sys.executable.
\end_layout

\end_deeper
\begin_layout Section
Conversion of .src files
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "code generation"

\end_inset

NumPy distutils supports automatic conversion of source files named <somefile>.sr
c.
 This facility can be used to maintain very similar code blocks requiring
 only simple changes between blocks.
 During the build phase of setup, if a template file named <somefile>.src
 is encountered, a new file named <somefile> is constructed from the template
 and placed in the build directory to be used instead.
 Two forms of template conversion are supported.
 The first form occurs for files named named <file>.ext.src where ext is a
 recognized Fortran extension (f, f90, f95, f77, for, ftn, pyf).
 The second form is used for all other cases.
 
\end_layout

\begin_layout Subsection
Fortran files
\end_layout

\begin_layout Standard
This template converter will replicate all 
\series bold
function
\series default
 and 
\series bold
subroutine
\series default
 blocks in the file with names that contain '<...>' according to the rules
 in '<...>'.
 The number of comma-separated words in '<...>' determines the number of times
 the block is repeated.
 What these words are indicates what that repeat rule, '<...>', should be replaced
 with in each block.
 All of the repeat rules in a block must contain the same number of comma-separa
ted words indicating the number of times that block should be repeated.
 If the word in the repeat rule needs a comma, leftarrow, or rightarrow,
 then prepend it with a backslash '
\backslash
'.
 If a word in the repeat rule matches '
\backslash

\backslash
<index>' then it will be replaced with the <index>-th word in the same repeat
 specification.
 There are two forms for the repeat rule: named and short.
\end_layout

\begin_layout Subsubsection
Named repeat rule
\end_layout

\begin_layout Standard
A named repeat rule is useful when the same set of repeats must be used
 several times in a block.
 It is specified using <rule1=item1, item2, item3,..., itemN>, where N is the
 number of times the block should be repeated.
 On each repeat of the block, the entire expression, '<...>' will be replaced
 first with item1, and then with item2, and so forth until N repeats are
 accomplished.
 Once a named repeat specification has been introduced, the same repeat
 rule may be used 
\series bold
in the current block
\series default
 by referring only to the name (i.e.
 <rule1>.
 
\end_layout

\begin_layout Subsubsection
Short repeat rule
\end_layout

\begin_layout Standard
A short repeat rule looks like <item1, item2, item3, ..., itemN>.
 The rule specifies that the entire expression, '<...>' should be replaced
 first with item1, and then with item2, and so forth until N repeats are
 accomplished.
 
\end_layout

\begin_layout Subsubsection
Pre-defined names
\end_layout

\begin_layout Standard
The following predefined named repeat rules are available:
\end_layout

\begin_layout Itemize
<prefix=s,d,c,z>
\end_layout

\begin_layout Itemize
<_c=s,d,c,z>
\end_layout

\begin_layout Itemize
<_t=real, double precision, complex, double complex>
\end_layout

\begin_layout Itemize
<ftype=real, double precision, complex, double complex>
\end_layout

\begin_layout Itemize
<ctype=float, double, complex_float, complex_double>
\end_layout

\begin_layout Itemize
<ftypereal=float, double precision, 
\backslash

\backslash
0, 
\backslash

\backslash
1> 
\end_layout

\begin_layout Itemize
<ctypereal=float, double, 
\backslash

\backslash
0, 
\backslash

\backslash
1>
\end_layout

\begin_layout Subsection
Other files
\end_layout

\begin_layout Standard
Non-Fortran files use a separate syntax for defining template blocks that
 should be repeated using a variable expansion similar to the named repeat
 rules of the Fortran-specific repeats.
 The template rules for these files are: 
\end_layout

\begin_layout Enumerate
\begin_inset Quotes eld
\end_inset

/**begin repeat
\begin_inset Quotes erd
\end_inset

 on a line by itself marks the beginning of a segment that should be repeated.
\end_layout

\begin_layout Enumerate
Named variable expansions are defined using #name=item1, item2, item3, ...,
 itemN# and placed on successive lines.
 These variables are replaced in each repeat block with corresponding word.
 All named variables in the same repeat block must define the same number
 of words.
 
\end_layout

\begin_layout Enumerate
In specifying the repeat rule for a named variable, item*N is short-hand
 for item, item, ..., item repeated N times.
 In addition, parenthesis in combination with *N can be used for grouping
 several items that should be repeated.
 Thus, #name=(item1, item2)*4# is equivalent to #name=item1, item2, item1,
 item2, item1, item2, item1, item2#
\end_layout

\begin_layout Enumerate
\begin_inset Quotes eld
\end_inset

*/
\begin_inset Quotes erd
\end_inset

 on a line by itself marks the end of the the variable expansion naming.
 The next line is the first line that will be repeated using the named rules.
\end_layout

\begin_layout Enumerate
Inside the block to be repeated, the variables that should be expanded are
 specified as @name@.
 
\end_layout

\begin_layout Enumerate
\begin_inset Quotes eld
\end_inset

/**end repeat**/
\begin_inset Quotes erd
\end_inset

 on a line by itself marks the previous line as the last line of the block
 to be repeated.
 
\end_layout

\begin_layout Standard
\begin_inset Include \input{capi.lyx}
preview false

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand printindex

\end_inset


\end_layout

\end_body
\end_document