Universal functions (ufunc)

A universal function, or ufunc, is a function that performs element-wise operations on data in ndarrays. They can be thought of as fast vectorised wrappers for simple functions that take one or more scalar values and produce one or more scalar results.

Many ufuncs are simple element-wise transformations, such as sqrt or exp:

import numpy as np


data = np.arange(10)

data

array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

np.sqrt(data)

array([0.        , 1.        , 1.41421356, 1.73205081, 2.        ,
       2.23606798, 2.44948974, 2.64575131, 2.82842712, 3.        ])

np.exp(data)

array([1.00000000e+00, 2.71828183e+00, 7.38905610e+00, 2.00855369e+01,
       5.45981500e+01, 1.48413159e+02, 4.03428793e+02, 1.09663316e+03,
       2.98095799e+03, 8.10308393e+03])

These are called single-digit ufuncs. Others, such as add or maximum, take two arrays (i.e. binary ufuncs) and return a single array as the result:

x = np.random.randn(8)

y = np.random.randn(8)

x

array([-1.23545026, -2.97614783,  1.81553171,  1.01874633,  0.08063104,
       -0.4605132 ,  2.26014706,  1.88403856])

y

array([ 0.70506547, -0.64166724,  2.10440297,  0.09330584, -1.47706135,
       -0.99220346,  0.54688573,  0.06453598])

np.maximum(x, y)

array([ 0.70506547, -0.64166724,  2.10440297,  1.01874633,  0.08063104,
       -0.4605132 ,  2.26014706,  1.88403856])

Here numpy.maximum calculated the element-wise maximum of the elements in x and y.

Some ufunc, such as modf, a vectorised version of the built-in Python divmod, return multiple arrays: the fractional and integral parts of a floating-point array:

data = x * 5

data

array([ -6.1772513 , -14.88073913,   9.07765855,   5.09373163,
         0.40315522,  -2.30256598,  11.3007353 ,   9.42019279])

remainder, whole_part = np.modf(x)

remainder

array([-0.23545026, -0.97614783,  0.81553171,  0.01874633,  0.08063104,
       -0.4605132 ,  0.26014706,  0.88403856])

whole_part

array([-1., -2.,  1.,  1.,  0., -0.,  2.,  1.])

Ufuncs accept an optional out argument that allows you to transfer your results to an existing array instead of creating a new one:

out = np.zeros_like(data)

np.add(data, 1)

array([ -5.1772513 , -13.88073913,  10.07765855,   6.09373163,
         1.40315522,  -1.30256598,  12.3007353 ,  10.42019279])

np.add(data, 1, out=out)

array([ -5.1772513 , -13.88073913,  10.07765855,   6.09373163,
         1.40315522,  -1.30256598,  12.3007353 ,  10.42019279])

out

array([ -5.1772513 , -13.88073913,  10.07765855,   6.09373163,
         1.40315522,  -1.30256598,  12.3007353 ,  10.42019279])

Some single-digit ufuncs:

Function	Description
abs, fabs	calculates the absolute value element by element for integer, floating point or complex values
sqrt	calculates the square root of each element (corresponds to data ** 0,5)
square	calculates the square of each element (corresponds to data ** 2)
exp	calculates the exponent ex of each element
log, log10, log2, log1p	Natural logarithm (base e), log base 10, log base 2 and log(1 + x) respectively
sign	calculates the sign of each element: 1 (positive), 0 (zero), or -1 (negative)
ceil	calculates the upper limit of each element (i.e. the smallest integer greater than or equal to this number)
floor	calculates the lower limit of each element (i.e. the largest integer less than or equal to each element)
rint	rounds elements to the nearest integer, preserving the dtype
modf	returns the fractional and integer parts of the array as separate arrays
isnan	returns a boolean array indicating whether each value is NaN (Not a Number)
isfinite, isinf	returns a boolean array indicating whether each element is finite (not-inf, not-NaN) or infinite, respectively
cos, cosh, sin, sinh, tan, tanh	regular and hyperbolic trigonometric functions
arccos, arccosh, arcsin, arcsinh, arctan, arctanh	Inverse trigonometric functions
logical_not	calculates the truth value of not x element by element (corresponds to ~data)

Some binary universal functions:

Function	Description
add	add corresponding elements in arrays
subtract	subtracts elements in the second array from the first array
multiply	multiply array elements
divide, floor_divide	divide or truncate the remainder
power	increases elements in the first array to the powers specified in the second array
maximum, fmax	element-wise maximum; fmax ignores NaN
minimum, fmin	element-wise minimum; fmin ignores NaN
mod	element-wise modulus (remainder of the division)
copysign	copies the sign of the values in the second argument to the values in the first argument
greater, greater_equal, less, less_equal, equal, not_equal	perform element-wise comparisons that result in a Boolean array (corresponds to the infix operators >, >=, <, <=, ==, !=)
logical_and	calculates the element-wise truth value of the logical operation AND (&)
logical_or	calculates the element-wise truth value of the logical operation OR (|)
logical_xor	calculates the element-wise truth value of the logical operation XOR (^)

Note:

A complete overview of binary universal functions can be found in Universal functions (ufunc).