diff options
Diffstat (limited to 'numpy/doc/numpybook/numpybook.lyx')
| -rw-r--r-- | numpy/doc/numpybook/numpybook.lyx | 27836 |
1 files changed, 27836 insertions, 0 deletions
diff --git a/numpy/doc/numpybook/numpybook.lyx b/numpy/doc/numpybook/numpybook.lyx new file mode 100644 index 000000000..16ee19d90 --- /dev/null +++ b/numpy/doc/numpybook/numpybook.lyx @@ -0,0 +1,27836 @@ +#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 +sync +\series default +() which must be called manually by the user to ensure that any changes + to the array actually get written to disk. + +\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 |