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:

[1]:
import numpy as np


data = np.arange(10)
[2]:
data
[2]:
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
[3]:
np.sqrt(data)
[3]:
array([0.        , 1.        , 1.41421356, 1.73205081, 2.        ,
       2.23606798, 2.44948974, 2.64575131, 2.82842712, 3.        ])
[4]:
np.exp(data)
[4]:
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:

[5]:
x = np.random.randn(8)
[6]:
y = np.random.randn(8)
[7]:
x
[7]:
array([-1.23545026, -2.97614783,  1.81553171,  1.01874633,  0.08063104,
       -0.4605132 ,  2.26014706,  1.88403856])
[8]:
y
[8]:
array([ 0.70506547, -0.64166724,  2.10440297,  0.09330584, -1.47706135,
       -0.99220346,  0.54688573,  0.06453598])
[9]:
np.maximum(x, y)
[9]:
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:

[10]:
data = x * 5
[11]:
data
[11]:
array([ -6.1772513 , -14.88073913,   9.07765855,   5.09373163,
         0.40315522,  -2.30256598,  11.3007353 ,   9.42019279])
[12]:
remainder, whole_part = np.modf(x)
[13]:
remainder
[13]:
array([-0.23545026, -0.97614783,  0.81553171,  0.01874633,  0.08063104,
       -0.4605132 ,  0.26014706,  0.88403856])
[14]:
whole_part
[14]:
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:

[15]:
out = np.zeros_like(data)
[16]:
np.add(data, 1)
[16]:
array([ -5.1772513 , -13.88073913,  10.07765855,   6.09373163,
         1.40315522,  -1.30256598,  12.3007353 ,  10.42019279])
[17]:
np.add(data, 1, out=out)
[17]:
array([ -5.1772513 , -13.88073913,  10.07765855,   6.09373163,
         1.40315522,  -1.30256598,  12.3007353 ,  10.42019279])
[18]:
out
[18]:
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).