Universal functions (cupy.ufunc)#

CuPy provides universal functions (a.k.a. ufuncs) to support various elementwise operations. CuPy’s ufunc supports following features of NumPy’s one:

  • Broadcasting

  • Output type determination

  • Casting rules

ufunc#

ufunc(name, nin, nout, _Ops ops[, preamble, ...])

Universal function.

Methods#

These methods are only available for selected ufuncs.

Hint

In case you need support for other ufuncs, submit a feature request along with your use-case in the tracker issue.

Available ufuncs#

Math operations#

add(x1, x2, /[, out, casting, dtype])

Adds two arrays elementwise.

subtract(x1, x2, /[, out, casting, dtype])

Subtracts arguments elementwise.

multiply(x1, x2, /[, out, casting, dtype])

Multiplies two arrays elementwise.

matmul

matmul(x1, x2, /, out=None, **kwargs)

divide

true_divide(x1, x2, /, out=None, *, casting='same_kind', dtype=None)

logaddexp(x1, x2, /[, out, casting, dtype])

Computes log(exp(x1) + exp(x2)) elementwise.

logaddexp2(x1, x2, /[, out, casting, dtype])

Computes log2(exp2(x1) + exp2(x2)) elementwise.

true_divide(x1, x2, /[, out, casting, dtype])

Elementwise true division (i.e.

floor_divide(x1, x2, /[, out, casting, dtype])

Elementwise floor division (i.e.

negative(x, /[, out, casting, dtype])

Takes numerical negative elementwise.

positive(x, /[, out, casting, dtype])

Takes numerical positive elementwise.

power(x1, x2, /[, out, casting, dtype])

Computes x1 ** x2 elementwise.

float_power(x1, x2, /[, out, casting, dtype])

First array elements raised to powers from second array, element-wise.

remainder

mod(x1, x2, /, out=None, *, casting='same_kind', dtype=None)

mod(x1, x2, /[, out, casting, dtype])

Computes the remainder of Python division elementwise.

fmod(x1, x2, /[, out, casting, dtype])

Computes the remainder of C division elementwise.

divmod(x1, x2[, out1, out2], / [[, out, ...])

absolute(x, /[, out, casting, dtype])

Elementwise absolute value function.

fabs(x, /[, out, casting, dtype])

Calculates absolute values element-wise.

rint(x, /[, out, casting, dtype])

Rounds each element of an array to the nearest integer.

sign(x, /[, out, casting, dtype])

Elementwise sign function.

heaviside(x1, x2, /[, out, casting, dtype])

Compute the Heaviside step function.

conj

conjugate(x, /, out=None, *, casting='same_kind', dtype=None)

conjugate(x, /[, out, casting, dtype])

Returns the complex conjugate, element-wise.

exp(x, /[, out, casting, dtype])

Elementwise exponential function.

exp2(x, /[, out, casting, dtype])

Elementwise exponentiation with base 2.

log(x, /[, out, casting, dtype])

Elementwise natural logarithm function.

log2(x, /[, out, casting, dtype])

Elementwise binary logarithm function.

log10(x, /[, out, casting, dtype])

Elementwise common logarithm function.

expm1(x, /[, out, casting, dtype])

Computes exp(x) - 1 elementwise.

log1p(x, /[, out, casting, dtype])

Computes log(1 + x) elementwise.

sqrt(x, /[, out, casting, dtype])

Elementwise square root function.

square(x, /[, out, casting, dtype])

Elementwise square function.

cbrt(x, /[, out, casting, dtype])

Elementwise cube root function.

reciprocal(x, /[, out, casting, dtype])

Computes 1 / x elementwise.

gcd(x1, x2, /[, out, casting, dtype])

Computes gcd of x1 and x2 elementwise.

lcm(x1, x2, /[, out, casting, dtype])

Computes lcm of x1 and x2 elementwise.

Trigonometric functions#

sin(x, /[, out, casting, dtype])

Elementwise sine function.

cos(x, /[, out, casting, dtype])

Elementwise cosine function.

tan(x, /[, out, casting, dtype])

Elementwise tangent function.

arcsin(x, /[, out, casting, dtype])

Elementwise inverse-sine function (a.k.a.

arccos(x, /[, out, casting, dtype])

Elementwise inverse-cosine function (a.k.a.

arctan(x, /[, out, casting, dtype])

Elementwise inverse-tangent function (a.k.a.

arctan2(x1, x2, /[, out, casting, dtype])

Elementwise inverse-tangent of the ratio of two arrays.

hypot(x1, x2, /[, out, casting, dtype])

Computes the hypoteneous of orthogonal vectors of given length.

sinh(x, /[, out, casting, dtype])

Elementwise hyperbolic sine function.

cosh(x, /[, out, casting, dtype])

Elementwise hyperbolic cosine function.

tanh(x, /[, out, casting, dtype])

Elementwise hyperbolic tangent function.

arcsinh(x, /[, out, casting, dtype])

Elementwise inverse of hyperbolic sine function.

arccosh(x, /[, out, casting, dtype])

Elementwise inverse of hyperbolic cosine function.

arctanh(x, /[, out, casting, dtype])

Elementwise inverse of hyperbolic tangent function.

degrees

rad2deg(x, /, out=None, *, casting='same_kind', dtype=None)

radians(x, /[, out, casting, dtype])

Converts angles from degrees to radians elementwise.

deg2rad

radians(x, /, out=None, *, casting='same_kind', dtype=None)

rad2deg(x, /[, out, casting, dtype])

Converts angles from radians to degrees elementwise.

Bit-twiddling functions#

bitwise_and(x1, x2, /[, out, casting, dtype])

Computes the bitwise AND of two arrays elementwise.

bitwise_or(x1, x2, /[, out, casting, dtype])

Computes the bitwise OR of two arrays elementwise.

bitwise_xor(x1, x2, /[, out, casting, dtype])

Computes the bitwise XOR of two arrays elementwise.

invert(x, /[, out, casting, dtype])

Computes the bitwise NOT of an array elementwise.

left_shift(x1, x2, /[, out, casting, dtype])

Shifts the bits of each integer element to the left.

right_shift(x1, x2, /[, out, casting, dtype])

Shifts the bits of each integer element to the right.

Comparison functions#

greater(x1, x2, /[, out, casting, dtype])

Tests elementwise if x1 > x2.

greater_equal(x1, x2, /[, out, casting, dtype])

Tests elementwise if x1 >= x2.

less(x1, x2, /[, out, casting, dtype])

Tests elementwise if x1 < x2.

less_equal(x1, x2, /[, out, casting, dtype])

Tests elementwise if x1 <= x2.

not_equal(x1, x2, /[, out, casting, dtype])

Tests elementwise if x1 != x2.

equal(x1, x2, /[, out, casting, dtype])

Tests elementwise if x1 == x2.

logical_and(x1, x2, /[, out, casting, dtype])

Computes the logical AND of two arrays.

logical_or(x1, x2, /[, out, casting, dtype])

Computes the logical OR of two arrays.

logical_xor(x1, x2, /[, out, casting, dtype])

Computes the logical XOR of two arrays.

logical_not(x, /[, out, casting, dtype])

Computes the logical NOT of an array.

maximum(x1, x2, /[, out, casting, dtype])

Takes the maximum of two arrays elementwise.

minimum(x1, x2, /[, out, casting, dtype])

Takes the minimum of two arrays elementwise.

fmax(x1, x2, /[, out, casting, dtype])

Takes the maximum of two arrays elementwise.

fmin(x1, x2, /[, out, casting, dtype])

Takes the minimum of two arrays elementwise.

Floating functions#

isfinite(x, /[, out, casting, dtype])

Tests finiteness elementwise.

isinf(x, /[, out, casting, dtype])

Tests if each element is the positive or negative infinity.

isnan(x, /[, out, casting, dtype])

Tests if each element is a NaN.

fabs(x, /[, out, casting, dtype])

Calculates absolute values element-wise.

signbit(x, /[, out, casting, dtype])

Tests elementwise if the sign bit is set (i.e.

copysign(x1, x2, /[, out, casting, dtype])

Returns the first argument with the sign bit of the second elementwise.

nextafter(x1, x2, /[, out, casting, dtype])

Computes the nearest neighbor float values towards the second argument.

modf(x[, out1, out2], / [[, out, casting, dtype])

Extracts the fractional and integral parts of an array elementwise.

ldexp(x1, x2, /[, out, casting, dtype])

Computes x1 * 2 ** x2 elementwise.

frexp(x[, out1, out2], / [[, out, casting, ...])

Decomposes each element to mantissa and two's exponent.

fmod(x1, x2, /[, out, casting, dtype])

Computes the remainder of C division elementwise.

floor(x, /[, out, casting, dtype])

Rounds each element of an array to its floor integer.

ceil(x, /[, out, casting, dtype])

Rounds each element of an array to its ceiling integer.

trunc(x, /[, out, casting, dtype])

Rounds each element of an array towards zero.

Generalized Universal Functions#

In addition to regular ufuncs, CuPy also provides a wrapper class to convert regular cupy functions into Generalized Universal Functions as in NumPy https://numpy.org/doc/stable/reference/c-api/generalized-ufuncs.html. This allows to automatically use keyword arguments such as axes, order, dtype without needing to explicitly implement them in the wrapped function.

GeneralizedUFunc(func, signature, **kwargs)

Creates a Generalized Universal Function by wrapping a user provided function with the signature.