\chapter{Ufuncs}
\label{cha:ufuncs}

\section{What are Ufuncs?}
\label{sec:what-are-ufuncs}

The operations on arrays that were mentioned in the previous section
(element-wise addition, multiplication, etc.) all share some features --- they
all follow similar rules for broadcasting, coercion and ``element-wise
operation''. Just as standard addition is available in Python through the add
function in the operator module, array operations are available through
callable objects as well. Thus, the following objects are available in the
numarray module:

\begin{table}[htbp]
   \centering
   \caption{Universal Functions, or ufuncs. The operators which invoke them
   when applied to arrays are indicated in parentheses. The entries in slanted
   typeface refer to unary ufuncs, while the others refer to binary ufuncs.} 
   \label{tab:ufuncs}
   \begin{tabular}{llll}
      add ($+$)         & subtract ($-$)   & multiply (*)       & divide ($/$) \\
      remainder (\%)    & power (**)       & \textsl{arccos}    & \textsl{arccosh} \\
      \textsl{arcsin}   & \textsl{arcsinh} & \textsl{arctan}    & \textsl{arctanh} \\
      \textsl{cos}      & \textsl{cosh}    & \textsl{tan}       & \textsl{tanh} \\
      \textsl{log10}    & \textsl{sin}     & \textsl{sinh}      & \textsl{sqrt} \\
      \textsl{absolute (abs)} & \textsl{fabs}    & \textsl{floor}     & \textsl{ceil} \\
      fmod              & \textsl{exp}     & \textsl{log}       & \textsl{conjugate} \\
      maximum           & minimum \\
      greater ($>$)     & greater\_equal ($>=$) & equal ($==$)  \\
      less ($<$)        & less\_equal ($<=$)  & not\_equal ($!=$) \\
      logical\_or       & logical\_xor     & logical\_not  & logical\_and \\
      bitwise\_or ($|$) & bitwise\_xor (\^{}) 
                        & bitwise\_not (\textasciitilde)  & bitwise\_and (\&)
      \\
      rshift ($>>$)       & lshift ($<<$)
   \end{tabular}
\end{table}

\remark{Add a remark here on how numarray does (or will) handle 'true'
and 'floor' division, which can be activated in Python 2.2 with
\samp{from __future__ import division}?.
Note: with 'true' division, \samp{1/2 == 0.5} and not \samp{0}.}

All of these ufuncs can be used as functions. For example, to use
\function{add}, which is a binary ufunc (i.e.\ it takes two arguments), one can
do either of:
\begin{verbatim}
>>> a = arange(10)
>>> print add(a,a)
[ 0  2  4  6  8 10 12 14 16 18]
>>> print a + a
[ 0  2  4  6  8 10 12 14 16 18]
\end{verbatim}
In other words, the \code{+} operator on arrays performs exactly the same thing
as the \function{add} ufunc when operated on arrays.  For a unary ufunc such as
\function{sin}, one can do, e.g.:
\begin{verbatim}
>>> a = arange(10)
>>> print sin(a)
[ 0.          0.84147096  0.90929741  0.14112    -0.7568025
      -0.95892429 -0.27941549  0.65698659  0.98935825  0.41211849]
\end{verbatim}
A unary ufunc returns an array with the same shape as its argument array, but
with each element replaced by the application of the function to that element
(\code{sin(0)=0}, \code{sin(1)=0.84147098}, etc.).

There are three additional features of ufuncs which make them different from
standard Python functions. They can operate on any Python sequence in addition
to arrays; they can take an ``output'' argument; they have methods which are
themselves callable with arrays and sequences. Each of these will be described
in turn.

Ufuncs can operate on any Python sequence. Ufuncs have so far been described as
callable objects which take either one or two arrays as arguments (depending on
whether they are unary or binary). In fact, any Python sequence which can be
the input to the \function{array} constructor can be used.  The return value
from ufuncs is always an array.  Thus:
\begin{verbatim}
>>> add([1,2,3,4], (1,2,3,4))
array([2, 4, 6, 8])
\end{verbatim}


\subsection{Ufuncs can take output arguments}
\label{sec:ufuncs-can-take}

In many computations with large sets of numbers, arrays are often used only
once. For example, a computation on a large set of numbers could involve the
following step
\begin{verbatim}
dataset = dataset * 1.20 
\end{verbatim}
This can also be written as the following using the Ufunc form:
\begin{verbatim}
dataset = multiply(dataset, 1.20)
\end{verbatim}
In both cases, a temporary array is created to store the results of the
computation before it is finally copied into \var{dataset}. It is
more efficient, both in terms of memory and computation time, to do an
``in-place'' operation.  This can be done by specifying an existing array as
the place to store the result of the ufunc. In this example, one can 
write:\footnote[1]{for Python-2.2.2 or later: `dataset *= 1.20' also works}
\begin{verbatim}
multiply(dataset, 1.20, dataset) 
\end{verbatim}
This is not a step to take lightly, however. For example, the ``big and slow''
version (\code{dataset = dataset * 1.20}) and the ``small and fast'' version
above will yield different results in at least one case:
\begin{itemize}
\item If the type of the target array is not that which would normally be
   computed, the operation will not coerce the array to the expected data type.
   (The result is done in the expected data type, but coerced back to the
   original array type.)
\item Example:
\begin{verbatim}
\>>> a=arange(5,type=Int32)
>>> print a[::-1]*1.7
[ 6.8  5.1  3.4  1.7  0. ]
>>> multiply(a[::-1],1.7,a)
>>> print a
[6 5 3 1 0]
>>> a *= 1.7
>>> print a
[0 1 3 5 6]
\end{verbatim}
\end{itemize}

The output array does not need to be the same variable as the input array. In
numarray, in contrast to Numeric, the output array may have any type (automatic
conversion is performed on the output).

\subsection{Ufuncs have special methods}
\label{sec:ufuncs-have-special-methods}


\begin{methoddesc}{reduce}{a, axis=0}
   If you don't know about the \function{reduce} command in Python, review
   section 5.1.3 of the Python Tutorial
   (\url{http://www.python.org/doc/current/tut/}). Briefly,
   \function{reduce} is most often used with two arguments, a callable object
   (such as a function), and a sequence. It calls the callable object with the
   first two elements of the sequence, then with the result of that operation
   and the third element, and so on, returning at the end the successive
   ``reduction'' of the specified callable object over the sequence elements.
   Similarly, the \method{reduce} method of ufuncs is called with a sequence as
   an argument, and performs the reduction of that ufunc on the sequence. As an
   example, adding all of the elements in a rank-1 array can be done with:
\begin{verbatim}
>>> a = array([1,2,3,4])
>>> print add.reduce(a)   # with Python's reduce, same as reduce(add, a)
10
\end{verbatim}
   When applied to arrays which are of rank greater than one, the reduction
   proceeds by default along the first axis:
\begin{verbatim}
>>> b = array([[1,2,3,4],[6,7,8,9]])
>>> print b
[[1 2 3 4]
 [6 7 8 9]]
>>> print add.reduce(b)
[ 7  9 11 13]
\end{verbatim}
   A different axis of reduction can be specified with a second integer
   argument:
\begin{verbatim}
>>> print b
[[1 2 3 4]
 [6 7 8 9]]
>>> print add.reduce(b, axis=1)
[10 30]
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}{accumulate}{a}
   The \method{accumulate} ufunc method is simular to \method{reduce}, except
   that it returns an array containing the intermediate results of the
   reduction:
\begin{verbatim}
>>> a = arange(10)
>>> print a
[0 1 2 3 4 5 6 7 8 9]
>>> print add.accumulate(a)
[ 0  1  3  6 10 15 21 28 36 45] # 0, 0+1, 0+1+2, 0+1+2+3, ... 0+...+9
>>> print add.reduce(a) # same as add.accumulate(a)[-1] w/o side effects on a
45                                      
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}{outer}{a, b}
   The third ufunc method is \method{outer}, which takes two arrays as
   arguments and returns the ``outer ufunc'' of the two arguments. Thus the
   \method{outer} method of the \function{multiply} ufunc, results in the outer
   product. The \method{outer} method is only supported for binary methods.
\begin{verbatim}
>>> print a
[0 1 2 3 4]
>>> print b
[0 1 2 3]
>>> print add.outer(a,b)
[[0 1 2 3]
 [1 2 3 4]
 [2 3 4 5]
 [3 4 5 6]
 [4 5 6 7]]
>>> print multiply.outer(b,a)
[[ 0  0  0  0  0]
 [ 0  1  2  3  4]
 [ 0  2  4  6  8]
 [ 0  3  6  9 12]]
>>> print power.outer(a,b)
[[ 1  0  0  0]
 [ 1  1  1  1]
 [ 1  2  4  8]
 [ 1  3  9 27]
 [ 1  4 16 64]]
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}{reduceat}{}
   The reduceat method of Numeric has not been implemented in numarray.
\end{methoddesc}

\subsection{Ufuncs always return new arrays}
\label{sec:ufuncs-always-return}

Except when the output argument is used as described above, ufuncs always
return new arrays which do not share any data with the input arrays.


\section{Which are the Ufuncs?}
\label{sec:which-are-ufuncs}

Table \ref{tab:ufuncs} lists all the ufuncs. We will first discuss the
mathematical ufuncs, which perform operations very similar to the functions in
the \module{math} and \module{cmath} modules, albeit elementwise, on arrays.
Originally,  numarray ufuncs came in two forms, unary and binary.  More
recently (1.3) numarray has added support for ufuncs with up to 16 total
input or output parameters.  These newer ufuncs are called N-ary ufuncs.

\subsection{Unary Mathematical Ufuncs}
\label{sec:unary-math-ufuncs}

Unary ufuncs take only one argument.  The following ufuncs apply the
predictable functions on their single array arguments, one element at a time:
\function{arccos}, \function{arccosh}, \function{arcsin}, \function{arcsinh},
\function{arctan}, \function{arctanh}, \function{cos}, \function{cosh},
\function{exp}, \function{log}, \function{log10}, \function{sin},
\function{sinh}, \function{sqrt}, \function{tan}, \function{tanh},
\function{abs}, \function{fabs}, \function{floor}, \function{ceil},
\function{conjugate}.  As an example:
\begin{verbatim}
>>> print x
[0 1 2 3 4]
>>> print cos(x)
[ 1.          0.54030231 -0.41614684 -0.9899925  -0.65364362]
>>> print arccos(cos(x))
[ 0.          1.          2.          3.          2.28318531]
# not a bug, but wraparound: 2*pi%4 is 2.28318531
\end{verbatim}


\subsection{Binary Mathematical Ufuncs}
\label{sec:binary-math-ufuncs}

These ufuncs take two arrays as arguments, and perform the specified
mathematical operation on them, one pair of elements at a time: \function{add},
\function{subtract}, \function{multiply}, \function{divide},
\function{remainder}, \function{power}, \function{fmod}.


\subsection{Logical and bitwise ufuncs}
\label{sec:logical-ufuncs}

The ``logical'' ufuncs also perform their operations on arrays or numbers 
in elementwise fashion, just like the "mathematical" ones.  Two are special
(\function{maximum} and \function{miminum}) in that they return arrays with
entries taken from their input arrays:
\begin{verbatim}
>>> print x
[0 1 2 3 4]
>>> print y
[ 2.   2.5  3.   3.5  4. ]
>>> print maximum(x, y)
[ 2.   2.5  3.   3.5  4. ]
>>> print minimum(x, y)
[ 0.  1.  2.  3.  4.]
\end{verbatim}
The others logical ufuncs return arrays of 0's or 1's and of type Bool:
\function{logical_and}, \function{logical_or}, \function{logical_xor},
\function{logical_not}, 
These are fairly
self-explanatory, especially with the associated symbols from the standard
Python version of the same operations in Table \ref{tab:ufuncs} above. 
The bitwise ufuncs,
\function{bitwise_and}, \function{bitwise_or},
\function{bitwise_xor}, \function{bitwise_not},  
\function{lshift}, \function{rshift},  
on the other hand, only work with integer arrays (of any word size), and
will return integer arrays of the larger bit size of the two input arrays:
\begin{verbatim}
>>> x
array([7, 7, 0], type=Int8)
>>> y
array([4, 5, 6])
>>> x & y          # bitwise_and(x,y)
array([4, 5, 0])
>>> x | y          # bitwise_or(x,y)
array([7, 7, 6])   
>>> x ^ y          # bitwise_xor(x,y)
array([3, 2, 6]) 
>>> ~ x            # bitwise_not(x)
array([-8, -8, -1], type=Int8)

\end{verbatim}
We discussed finding contents of arrays based on arrays' indices by using slice.
Often, especially when dealing with the result of computations or data
analysis, one needs to ``pick out'' parts of matrices based on the content of
those matrices. For example, it might be useful to find out which elements of
an array are negative, and which are positive. The comparison ufuncs are
designed for such operation. Assume an array with various positive
and negative numbers in it (for the sake of the example we'll generate it from
scratch):
\begin{verbatim}
>>> print a
[[ 0  1  2  3  4]
 [ 5  6  7  8  9]
 [10 11 12 13 14]
 [15 16 17 18 19]
 [20 21 22 23 24]]
>>> b = sin(a)
>>> print b
[[ 0.          0.84147098  0.90929743  0.14112001 -0.7568025 ]
 [-0.95892427 -0.2794155   0.6569866   0.98935825  0.41211849]
 [-0.54402111 -0.99999021 -0.53657292  0.42016704  0.99060736]
 [ 0.65028784 -0.28790332 -0.96139749 -0.75098725  0.14987721]
 [ 0.91294525  0.83665564 -0.00885131 -0.8462204  -0.90557836]]
>>> print greater(b, .3)
[[0 1 1 0 0]
 [0 0 1 1 1]
 [0 0 0 1 1]
 [1 0 0 0 0]
 [1 1 0 0 0]]
\end{verbatim}


\subsection{Comparisons}
\label{sec:comparisons}

The comparison functions \function{equal}, \function{not_equal},
\function{greater}, \function{greater_equal}, \function{less}, and
\function{less_equal} are invoked by the operators \code{==}, \code{!=},
\code{>}, \code{>=}, \code{<}, and \code{<=} respectively, but they can also be
called directly as functions. Continuing with the preceding example,
\begin{verbatim}
>>> print less_equal(b, 0)
[[1 0 0 0 1]
 [1 1 0 0 0]
 [1 1 1 0 0]
 [0 1 1 1 0]
 [0 0 1 1 1]]
\end{verbatim}
This last example has 1's where the corresponding elements are less than or
equal to 0, and 0's everywhere else.

The operators and the comparison functions are not exactly equivalent.  To
compare an array a with an object b, if b can be converted to an array, the
result of the comparison is returned. Otherwise, zero is returned. This means
that comparing a list and comparing an array can return quite different
answers. Since the functional forms such as equal will try to make arrays from
their arguments, using equal can result in a different result than using
\code{==}.
\begin{verbatim}
>>> a = array([1, 2, 3])
>>> b = [1, 2, 3]
>>> print a == 2
[0 1 0]
>>> print b == 2  
0          # (False since 2.3)
>>> print equal(a, 2)
[0 1 0]
>>> print equal(b, 2)
[0 1 0]
\end{verbatim}

\subsection{Ufunc shorthands}
\label{sec:ufunc-shorthands}

Numarray defines a few functions which correspond to popular ufunc methods:
for example, \function{add.reduce} is synonymous with the \function{sum}
utility function:
\begin{verbatim}
>>> a = arange(5)                       # [0 1 2 3 4]
>>> print sum(a)                        # 0 + 1 + 2 + 3 + 4
10
\end{verbatim}
Similarly, \function{cumsum} is equivalent to \function{add.accumulate} (for
``cumulative sum''), \function{product} to \function{multiply.reduce}, and
\function{cumproduct} to \function{multiply.accumulate}.  Additional useful
``utility'' functions are \function{all} and \function{any}:
\begin{verbatim}
>>> a = array([0,1,2,3,4])
>>> print greater(a,0)
[0 1 1 1 1]
>>> all(greater(a,0))
0
>>> any(greater(a,0))
1
\end{verbatim}

\section{Writing your own ufuncs!}

This section describes a new process for defining your own universal functions.
It explains a new interface that enables the description of N-ary ufuncs, those
that use semi-arbitrary numbers \((<= 16)\) of inputs and outputs.

\subsection{Runtime components of a ufunc}

A numarray universal function maps from a Python function name to a set of C
functions.  Ufuncs are polymorphic and figure out what to do in C when passed a
particular set of input parameter types.  C functions, on the other hand, can
only be run on parameters which match their type signatures.  The task of
defining a universal function is one of describing how different parameter
sequences are mapped from Python array types to C function signatures and back.

At runtime, there are three principle kinds of things used to define a
universal function.

\begin {enumerate}
\item Ufunc 

The universal function is itself a callable Python object.  Ufuncs organize a
collection of Cfuncs to be called based on the actual parameter types seen at
runtime.  The same Ufunc is typically associated with several Cfuncs each of
which handles a unique Ufunc type signature.  Because a Ufunc typically has
more than one C func, it can also be implemented using more than one library
function.

\item Library function

A pre-existing function written in C or Fortran which will ultimately be called
for each element of the ufunc parameter arrays.  

\item Cfunc

Cfuncs are binding objects that map C library functions safely into Python.
It's the job of a Cfunc to interpret typeless pointers corresponding to the
parameter arrays as particular C data types being passed down from the ufunc.
Further, the Cfunc casts array elements from the input type to the Libraray
function parameter type.  This process lets the ufunc implementer describe the
ufunc type signatures which will be processed most efficiently by the
underlying Library function by enabling per-call element-by-element type casts.
Ufunc calling signatures which are not represented directly by a Cfunc result
in blockwise coercion to the closest matching Cfunc, which is slower.

\end {enumerate}

\subsection{Source components of a ufunc}
There are 4 source components required to define numarray ufuncs, one of which
is hand written, two are generated, and the last is assumed to be pre-existing:

\begin {enumerate}
\item Code generation script

The primary source component for defining new universal functions is a Python
script used to generate the other components.  For a standalone set of
functions, putting the code generation directives in setup.py can be done as in
the example numarray/Examples/ufunc/setup_airy.py.  The code generation script
only executes at install time.

\item Extension module

A private extension module is generated which contains a collection of Cfuncs
for the package being created.  The extension module contains a dictionary
mapping from ufuncs/types to Cfuncs.

\item Ufunc init file 

A Python script used at ufunc import time is required to construct Ufunc
objects from Cfuncs.  This code is boilerplate created with the code generation
directive \function{make_stub()}.

\item Library functions

The C functions which are ultimately called by a Ufunc need to be defined
somewhere, typically in a third party C or Fortran library which is linked
to the Extension module.
\end{enumerate}

\subsection{Ufunc code generation}
There are several code generation directives provided by package
numarray.codegenerator which are called at installation time to generate the
Cfunc extension module and Ufunc init file.

\begin{funcdesc}{UfuncModule}{module_name}
The \class{UfuncModule} constructor creates a module object which collects code
which is later output to form the Cfunc extension module.  The name passed to
the constructor defines the name of the Python extension module, not the source
code.
\begin{verbatim}
m = UfuncModule("_na_special")
\end{verbatim}
\end{funcdesc}

\begin{methoddesc}{add_code}{code_string}
The \method{add_code()} method of a \class{UfuncModule} object is used to add
arbitrary code to the module at the point that \method{add_code()} is
called. Here it includes a header file used to define prototypes for the C
library functions which this extension will ultimately call.
\begin{verbatim}
m.add_code('#include "airy.h"')
\end{verbatim}
\end{methoddesc}

\begin{methoddesc}{add_nary_ufunc}{ufunc_name, c_name,
    ufunc_signatures, c_signature, forms=None} 
The \method{add_nary_ufunc()} method declares a Ufunc and relates it to one
library function and a collection of Cfunc bindings for it.  The
\var{signatures} parameter defines which ufunc type signatures receive Cfunc
bindings. Input types which don't match those signature are blockwise coerced
to the best matching signature.  \method{add_nary_ufunc()} can be called for
the same Ufunc name more than once and can thus be used to associate multiple
library functions with the same Ufunc.
\begin{verbatim}
m.add_nary_ufunc(ufunc_name = "airy",
                 c_function  = "airy",    
                 signatures  =["dxdddd",
                               "fxffff"],
                 c_signature = "dxdddd")
\end{verbatim}
\end{methoddesc}

\begin{methoddesc}{generate}{source_filename}
The \method{generate()} method asks the \class{UfuncModule} object to emit the
code for an extension module to the specified \var{source_filename}.
\begin{verbatim}
m.generate("Src/_na_specialmodule.c")
\end{verbatim}
\end{methoddesc}

\begin{funcdesc}{make_stub}{stub_filename, cfunc_extension, add_code=None}
The \function{make_stub()} function is used to generate the boilerplate Python
code which constructs universal functions from a Cfunc extension module at
import time.  \function{make_stub()} accepts a \var{add_code} parameter which
should be a string containing any additional Python code to be injected into
the stub module.  Here \function{make_stub()} creates the init file
``Lib/__init__.py'' associated with the Cfunc extension ``_na_special'' and
includes some extra Python code to define the \function{plot_airy()} function.
\begin{verbatim}
extra_stub_code = '''

import matplotlib.pylab as mpl

def plot_airy(start=-10,stop=10,step=0.1,which=1):
    a = mpl.arange(start, stop, step)
    mpl.plot(a, airy(a)[which])

    b = 1.j*a + a
    ba = airy(b)[which]

    h = mpl.figure(2)
    mpl.plot(b.real, ba.real)

    i = mpl.figure(3)
    mpl.plot(b.imag, ba.imag)
    
    mpl.show()
'''

make_stub("Lib/__init__", "_na_special", add_code=extra_stub_code)
\end{verbatim}

\end{funcdesc}

\subsection{Type signatures and signature ordering}

Type signatures are described using the single character typecodes from
Numeric.  Since the type signature and form of a Cfunc need to be encoded in
its name for later identification, it must be brief.  

\begin{verbatim}
typesignature ::= <inputtypes> + ``x'' + <outputtypes>
inputtypes ::= [<typecode>]+
outputtypes ::= [<typecode>]+
typecode ::= "B" | "1" | "b" | "s" | "w" | "i" | "u" |
             "N" | "U" | "f" | "d" | "F" | "D"
\end{verbatim}

For example,  the type signature corresponding to one Int32 input and one Int16
output is "ixs".

A type signature is a sequence of ordered types.  One signature can be compared
to another by comparing corresponding elements, in left to right order.
Individual elements are ranked using the order from the previous section.  A
ufunc maintains its associated Cfuncs as a sorted sequence and selects the
first Cfunc which is \(>=\) the input type signature;  this defines the notion
of ``best matching''.

\subsection{Forms}

The \method{add_nary_ufunc()} method has a parameter \var{forms} which enables
generation of code with some extra properties.  It specifies the list of
function forms for which dedicated code will be generated.  If you don't
specify \var{forms}, it defaults to a (list of a) single form which specifies
that all inputs and outputs corresponding to the type signature are vectors.
Input vectors are passed by value, output vectors are passed by reference.  The
default form implies that the library function return value, if there is one,
is ignored.  The following Python code shows the default form:

\begin{verbatim}
["v"*n_inputs + "x" + "v"*n_outputs] 
\end{verbatim}

Forms are denoted using a syntax very similar to, and typically symmetric with,
type signatures.

\begin{verbatim}

form ::=  <inputs> "x" <outputs>
inputs ::= ["v"|"s"]*
outputs ::= ["f"]?["v"]* | "A" | "R"

The form character values have different meanings than for type
signatures:

'v'  :   vector,  an array of input or output values
's'  :   scalar,  a non-array input value
'f'  :   function,  the c_function returns a value
'R'  :   reduce,    this binary ufunc needs a reduction method
'A'  :   accumulate this binary ufunc needs an accumulate method
'x'  :   separator  delineates inputs from outputs

\end{verbatim}

So, a form consists of some input codes followed by a lower case "x" followed
by some output codes.  

The form for a C function which takes 4 input values, the last of which is
assumed to be a scalar, returns one value, and fills in 2 additional output
values is:  "vvvsxfvv".

Using "s" to designate scalar parameters is a useful performance
optimization for cases where it is known that only a single value is
passed in from Python to be used in all calls to the c function.  This
prevents the blockwise expansion of the scalar value into a vector.

Use "f" to specify that the C function return value should be kept; it must
always be the first output and will therefore appear as the first element of
the result tuple.

For ufuncs of two input parameters (binary ufuncs), two additional form
characters are possible: A (accumulate) and R (reduce).  Each of these
characters constitutes the *entire* ufunc form, so the form is denoted "R" or
"A".  For these kinds of cfuncs, the type signature always reads \code{<t>x<t>}
where \code{<t>} is one of the type characters.  

One reason for all these codes is so that the many Cfuncs generated for Ufuncs
can be easily named.  The name for the Cfunc which implements \function{add()}
for two Int32 inputs and one Int32 output and where all parameters are arrays
is: "add_iixi_vvxv".  The cfunc name for \method{add.reduce()} with two integer
parameters would be written as "add_ixi_R" and for \method{add.accumulate()}
as "add_ixi_A".

The set of Cfuncs generated is based on the signatures \emph{crossed} with the
forms.  Multiple calls to \method{add_nary_ufunc()} can be used the reduce the
effects of signature/form crossing.

\newpage
\subsection{Ufunc Generation Example}

This section includes code from Examples/ufunc/setup_airy.py in the numarray
source distribution to illustrate how to create a package which defines your
own universal functions.  

This script eventually generates two files: _na_airymodule.c and
__init__.py.  The former defines an extension module which creates
numarray cfuncs, c helpers for the numarray airy() ufunc.  The latter
file includes Python code which automatically constructs numarray
universal functions (ufuncs) from the cfuncs in _na_airymodule.c.

\begin{verbatim}

import distutils, os, sys
from distutils.core import setup
from numarray.codegenerator import UfuncModule, make_stub
from numarray.numarrayext import NumarrayExtension

m = UfuncModule("_na_special")

m.add_code('#include "airy.h"')

m.add_nary_ufunc(ufunc_name = "airy",
                 c_function  = "airy",    
                 signatures  =["dxdddd",
                               "fxffff"],
                 c_signature = "dxdddd")

m.add_nary_ufunc(ufunc_name = "airy",
                 c_function  ="cairy_fake",
                 signatures  =["DxDDDD",
                               "FxFFFF"],
                 c_signature = "DxDDDD")

m.generate("Src/_na_specialmodule.c")

\end{verbatim}

\begin{verbatim}

extra_stub_code = '''
def plot_airy(start=-10,stop=10,step=0.1,which=1):
    import matplotlib.pylab as mpl;

    a = mpl.arange(start, stop, step);
    mpl.plot(a, airy(a)[which]);

    b = 1.j*a + a
    ba = airy(b)[which]

    h = mpl.figure(2)
    mpl.plot(b.real, ba.real)

    i = mpl.figure(3)
    mpl.plot(b.imag, ba.imag)
    
    mpl.show()
'''

make_stub("Lib/__init__", "_na_special", 
          add_code=extra_stub_code)

dist = setup(name = "na_special",
      version = "0.1",
      maintainer = "Todd Miller",
      maintainer_email = "jmiller@stsci.edu",
      description = "airy() universal function for numarray",
      url = "http://www.scipy.org/",
      packages = ["numarray.special"],
      package_dir = { "numarray.special":"Lib" },
      ext_modules = [ NumarrayExtension( 'numarray.special._na_special',
                                         ['Src/_na_specialmodule.c',
                                          'Src/airy.c',
                                          'Src/const.c',
                                          'Src/polevl.c']
                                        )
                     ]
     )

\end{verbatim}

Additional explanatory text is available in
numarray/Examples/ufunc/setup_airy.py.  Scripts used to extract
numarray ufunc specs from the existing Numeric ufunc definitions
in scipy.special are in numarray/Examples/ufunc/RipNumeric as an
example of how to convert existing Numeric code to numarray.



%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 79
%% indent-tabs-mode: nil
%% ispell-dictionary: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "numarray"
%% TeX-parse-self: t
%% End: