16.5. Universal Functions (ufuncs)
Numeric supplies named functions with the same semantics as Python's arithmetic, comparison, and bitwise operators, and mathematical functions like those supplied by built-in modules math and cmath (covered in "The math and cmath Modules" on page 365), such as sin, cos, log, and exp.
These functions are objects of type ufunc (which stands for "universal function") and share several traits in addition to those they have in common with array operators (element-wise operation, broadcasting, coercion). Every ufunc instance u is callable, is applicable to sequences as well as to arrays, and accepts an optional output argument. If u is binary (i.e., if u accepts two operand arguments), u also has four callable attributes, named u.accumulate, u.outer, u.reduce, and u.reduceat. The ufunc objects supplied by Numeric apply only to arrays with numeric typecodes (i.e., not to arrays with typecode 'O' or 'c') and Python sequences of numbers.
When you start with a list L, it's faster to call u directly on L rather than to convert L to an array. u's return value is an array a; you can perform further computation, if any, on a; if you need a list result, convert the resulting array to a list at the end by calling method tolist. For example, say you must compute the logarithm of each item of a list and return another list. On my laptop, with N set to 2222, a list comprehension such as:
def logsupto(N): return [math.log(x) for x in range(2,N)]
takes about 5.2 milliseconds. Using Python's built-in map:
def logsupto(N): return map(math.log, range(2,N))
is faster, about 3.7 milliseconds. Using Numeric's ufunc named log:
def logsupto(N): return Numeric.log(Numeric.arange(2,N)).tolist( )
reduces the time to about 2.1 milliseconds. Taking some care to exploit the output argument to the log ufunc:
def logsupto(N): temp = Numeric.arange(2, N, typecode=Numeric.Float) Numeric.log(temp, output=temp) return temp.tolist( )
further reduces the time, down to just 2 milliseconds. The ability to accelerate such simple but massive computations (here by almost three times) with so little effort is a good part of the attraction of Numeric, and particularly of Numeric's ufunc objects. Do take care not to carelessly code something like:
def logsupto(N): return Numeric.log(range(2,N)).tolist( )
which, on my laptop, takes about 18 milliseconds; clearly, the conversions from list to array and from integer to float may dominate actual computations in a case like this one.
16.5.1. The Optional output Argument
Any ufunc u accepts an optional last argument output that specifies an output array. If supplied, output must be an array or array slice of the right shape and type for u's results (no coercion, no broadcasting). u stores results in output and does not create a new array. output can be the same as an input array argument a of u. Indeed, output is normally specified in order to substitute common idioms such as a=u(a,b) with faster equivalents such as u(a,b,a). However, output cannot share data with a without being a (i.e., output can't be a different view of some or all of a's data). If you pass such a disallowed output argument, Numeric is normally unable to diagnose your error and raise an exception, so instead you may get wrong results.
Whether you pass the optional output argument or not, a ufunc u returns its results as the function's return value. When you do not pass output, u stores the results it returns in a new array object, so you normally bind u's return value to some reference in order to be able to access u's results later. When you pass the output argument, u stores the results in output, so you need not bind u's return value. You can later access u's results as the new contents of the array object passed as output.
16.5.2. Callable Attributes
Every binary ufunc u supplies four attributes that are also callable objects.
16.5.3. ufunc Objects Supplied by Numeric
Numeric supplies several ufunc objects, as listed in Table 16-3.
Here's how you can use ufunc to get a "ramp" of numbers, decreasing then increasing:
print Numeric.maximum(range(1,20),range(20,1,-1)) # prints: [20 19 18 17 16 15 14 13 12 11 11 12 13 14 15 16 17 18 19]
16.5.4. Shorthand for Commonly Used ufunc Methods
Numeric defines function synonyms for some commonly used methods of ufunc objects, as listed in Table 16-4.