Element-wise Functions

Array API specification for element-wise functions.

A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.

  • Positional parameters must be positional-only parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.

  • Optional parameters must be keyword-only arguments.

  • Broadcasting semantics must follow the semantics defined in Broadcasting.

  • Unless stated otherwise, functions must support the data types defined in Data Types.

  • Functions may only be required for a subset of input data type. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See Data Type Categories.

  • Unless stated otherwise, functions must adhere to the type promotion rules defined in Type Promotion Rules.

  • Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.

  • Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in Accuracy.

Objects in API

abs(x, /)

Calculates the absolute value for each element x_i of the input array x (i.e., the element-wise result has the same magnitude as the respective element in x but has positive sign).

acos(x, /)

Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain [-1, +1] and codomain [+0, +π], for each element x_i of the input array x.

acosh(x, /)

Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain [+1, +infinity] and codomain [+0, +infinity], for each element x_i of the input array x.

add(x1, x2, /)

Calculates the sum for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

asin(x, /)

Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain [-1, +1] and codomain [-π/2, +π/2] for each element x_i of the input array x.

asinh(x, /)

Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain [-infinity, +infinity] and codomain [-infinity, +infinity], for each element x_i in the input array x.

atan(x, /)

Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain [-infinity, +infinity] and codomain [-π/2, +π/2], for each element x_i of the input array x.

atan2(x1, x2, /)

Calculates an implementation-dependent approximation of the inverse tangent of the quotient x1/x2, having domain [-infinity, +infinity] x [-infinity, +infinity] (where the x notation denotes the set of ordered pairs of elements (x1_i, x2_i)) and codomain [-π, +π], for each pair of elements (x1_i, x2_i) of the input arrays x1 and x2, respectively.

atanh(x, /)

Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain [-1, +1] and codomain [-infinity, +infinity], for each element x_i of the input array x.

bitwise_and(x1, x2, /)

Computes the bitwise AND of the underlying binary representation of each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

bitwise_left_shift(x1, x2, /)

Shifts the bits of each element x1_i of the input array x1 to the left by appending x2_i (i.e., the respective element in the input array x2) zeros to the right of x1_i.

bitwise_invert(x, /)

Inverts (flips) each bit for each element x_i of the input array x.

bitwise_or(x1, x2, /)

Computes the bitwise OR of the underlying binary representation of each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

bitwise_right_shift(x1, x2, /)

Shifts the bits of each element x1_i of the input array x1 to the right according to the respective element x2_i of the input array x2.

bitwise_xor(x1, x2, /)

Computes the bitwise XOR of the underlying binary representation of each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

ceil(x, /)

Rounds each element x_i of the input array x to the smallest (i.e., closest to -infinity) integer-valued number that is not less than x_i.

cos(x, /)

Calculates an implementation-dependent approximation to the cosine, having domain (-infinity, +infinity) and codomain [-1, +1], for each element x_i of the input array x.

cosh(x, /)

Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain [-infinity, +infinity] and codomain [-infinity, +infinity], for each element x_i in the input array x.

divide(x1, x2, /)

Calculates the division for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

equal(x1, x2, /)

Computes the truth value of x1_i == x2_i for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

exp(x, /)

Calculates an implementation-dependent approximation to the exponential function, having domain [-infinity, +infinity] and codomain [+0, +infinity], for each element x_i of the input array x (e raised to the power of x_i, where e is the base of the natural logarithm).

expm1(x, /)

Calculates an implementation-dependent approximation to exp(x)-1, having domain [-infinity, +infinity] and codomain [-1, +infinity], for each element x_i of the input array x.

floor(x, /)

Rounds each element x_i of the input array x to the greatest (i.e., closest to +infinity) integer-valued number that is not greater than x_i.

floor_divide(x1, x2, /)

Rounds the result of dividing each element x1_i of the input array x1 by the respective element x2_i of the input array x2 to the greatest (i.e., closest to +infinity) integer-value number that is not greater than the division result.

greater(x1, x2, /)

Computes the truth value of x1_i > x2_i for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

greater_equal(x1, x2, /)

Computes the truth value of x1_i >= x2_i for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

isfinite(x, /)

Tests each element x_i of the input array x to determine if finite (i.e., not NaN and not equal to positive or negative infinity).

isinf(x, /)

Tests each element x_i of the input array x to determine if equal to positive or negative infinity.

isnan(x, /)

Tests each element x_i of the input array x to determine whether the element is NaN.

less(x1, x2, /)

Computes the truth value of x1_i < x2_i for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

less_equal(x1, x2, /)

Computes the truth value of x1_i <= x2_i for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

log(x, /)

Calculates an implementation-dependent approximation to the natural (base e) logarithm, having domain [0, +infinity] and codomain [-infinity, +infinity], for each element x_i of the input array x.

log1p(x, /)

Calculates an implementation-dependent approximation to log(1+x), where log refers to the natural (base e) logarithm, having domain [-1, +infinity] and codomain [-infinity, +infinity], for each element x_i of the input array x.

log2(x, /)

Calculates an implementation-dependent approximation to the base 2 logarithm, having domain [0, +infinity] and codomain [-infinity, +infinity], for each element x_i of the input array x.

log10(x, /)

Calculates an implementation-dependent approximation to the base 10 logarithm, having domain [0, +infinity] and codomain [-infinity, +infinity], for each element x_i of the input array x.

logaddexp(x1, x2, /)

Calculates the logarithm of the sum of exponentiations log(exp(x1) + exp(x2)) for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

logical_and(x1, x2, /)

Computes the logical AND for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

logical_not(x, /)

Computes the logical NOT for each element x_i of the input array x.

logical_or(x1, x2, /)

Computes the logical OR for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

logical_xor(x1, x2, /)

Computes the logical XOR for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

multiply(x1, x2, /)

Calculates the product for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

negative(x, /)

Computes the numerical negative of each element x_i (i.e., y_i = -x_i) of the input array x.

not_equal(x1, x2, /)

Computes the truth value of x1_i != x2_i for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

positive(x, /)

Computes the numerical positive of each element x_i (i.e., y_i = +x_i) of the input array x.

pow(x1, x2, /)

Calculates an implementation-dependent approximation of exponentiation by raising each element x1_i (the base) of the input array x1 to the power of x2_i (the exponent), where x2_i is the corresponding element of the input array x2.

remainder(x1, x2, /)

Returns the remainder of division for each element x1_i of the input array x1 and the respective element x2_i of the input array x2.

round(x, /)

Rounds each element x_i of the input array x to the nearest integer-valued number.

sign(x, /)

Returns an indication of the sign of a number for each element x_i of the input array x.

sin(x, /)

Calculates an implementation-dependent approximation to the sine, having domain (-infinity, +infinity) and codomain [-1, +1], for each element x_i of the input array x.

sinh(x, /)

Calculates an implementation-dependent approximation to the hyperbolic sine, having domain [-infinity, +infinity] and codomain [-infinity, +infinity], for each element x_i of the input array x.

square(x, /)

Squares (x_i * x_i) each element x_i of the input array x.

sqrt(x, /)

Calculates the square root, having domain [0, +infinity] and codomain [0, +infinity], for each element x_i of the input array x.

subtract(x1, x2, /)

Calculates the difference for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

tan(x, /)

Calculates an implementation-dependent approximation to the tangent, having domain (-infinity, +infinity) and codomain (-infinity, +infinity), for each element x_i of the input array x.

tanh(x, /)

Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain [-infinity, +infinity] and codomain [-1, +1], for each element x_i of the input array x.

trunc(x, /)

Rounds each element x_i of the input array x to the integer-valued number that is closest to but no greater than x_i.