Elementwise Functions ¶
Array API specification for elementwise 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 positionalonly parameters. Positionalonly parameters have no externallyusable name. When a function accepting positionalonly parameters is called, positional arguments are mapped to these parameters based solely on their order.

Optional parameters must be keywordonly 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, floatingpoint operations must adhere to IEEE 7542019.

Unless stated otherwise, elementwise 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 elementwise result has the same magnitude as the respective element in
x
but has positive sign).
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is0
, the result is+0
. 
If
x_i
isinfinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the absolute value of each element in
x
. The returned array must have the same data type asx
.

acos(x, /) ¶
Calculates an implementationdependent 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
. Each elementwise result is expressed in radians.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is greater than1
, the result isNaN
. 
If
x_i
is less than1
, the result isNaN
. 
If
x_i
is1
, the result is+0
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse cosine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

acosh(x, /) ¶
Calculates an implementationdependent approximation to the inverse hyperbolic cosine, having domain
[+1,
+infinity]
and codomain
[+0,
+infinity]
, for each element
x_i
of the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than1
, the result isNaN
. 
If
x_i
is1
, the result is+0
. 
If
x_i
is+infinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array whose elements each represent the area of a hyperbolic sector. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse hyperbolic cosine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
.
Special Cases ¶
For floatingpoint operands,

If either
x1_i
orx2_i
isNaN
, the result isNaN
. 
If
x1_i
is+infinity
andx2_i
isinfinity
, the result isNaN
. 
If
x1_i
isinfinity
andx2_i
is+infinity
, the result isNaN
. 
If
x1_i
is+infinity
andx2_i
is+infinity
, the result is+infinity
. 
If
x1_i
isinfinity
andx2_i
isinfinity
, the result isinfinity
. 
If
x1_i
is+infinity
andx2_i
is a finite number, the result is+infinity
. 
If
x1_i
isinfinity
andx2_i
is a finite number, the result isinfinity
. 
If
x1_i
is a finite number andx2_i
is+infinity
, the result is+infinity
. 
If
x1_i
is a finite number andx2_i
isinfinity
, the result isinfinity
. 
If
x1_i
is0
andx2_i
is0
, the result is0
. 
If
x1_i
is0
andx2_i
is+0
, the result is+0
. 
If
x1_i
is+0
andx2_i
is0
, the result is+0
. 
If
x1_i
is+0
andx2_i
is+0
, the result is+0
. 
If
x1_i
is either+0
or0
andx2_i
is a nonzero finite number, the result isx2_i
. 
If
x1_i
is a nonzero finite number andx2_i
is either+0
or0
, the result isx1_i
. 
If
x1_i
is a nonzero finite number andx2_i
isx1_i
, the result is+0
. 
In the remaining cases, when neither
infinity
,+0
,0
, nor aNaN
is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 7542019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is aninfinity
of appropriate mathematical sign.
Note
Floatingpoint addition is a commutative operation, but not always associative.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise sums. The returned array must have a data type determined by Type Promotion Rules .

asin(x, /) ¶
Calculates an implementationdependent 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
. Each elementwise result is expressed in radians.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is greater than1
, the result isNaN
. 
If
x_i
is less than1
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse sine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

asinh(x, /) ¶
Calculates an implementationdependent approximation to the inverse hyperbolic sine, having domain
[infinity,
+infinity]
and codomain
[infinity,
+infinity]
, for each element
x_i
in the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+infinity
, the result is+infinity
. 
If
x_i
isinfinity
, the result isinfinity
.
Parameters ¶

x : <array>

input array whose elements each represent the area of a hyperbolic sector. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse hyperbolic sine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

atan(x, /) ¶
Calculates an implementationdependent 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
. Each elementwise result is expressed in radians.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+infinity
, the result is an implementationdependent approximation to+π/2
. 
If
x_i
isinfinity
, the result is an implementationdependent approximation toπ/2
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse tangent of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

atan2(x1, x2, /) ¶
Calculates an implementationdependent 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. Each elementwise result is expressed in radians.
The mathematical signs of
x1_i
and
x2_i
determine the quadrant of each elementwise result. The quadrant (i.e., branch) is chosen such that each elementwise result is the signed angle in radians between the ray ending at the origin and passing through the point
(1,0)
and the ray ending at the origin and passing through the point
(x2_i,
x1_i)
.
Note
Note the role reversal: the “ycoordinate” is the first function parameter; the “xcoordinate” is the second function parameter. The parameter order is intentional and traditional for the twoargument inverse tangent function where the ycoordinate argument is first and the xcoordinate argument is second.
By IEEE 754 convention, the inverse tangent of the quotient
x1/x2
is defined for
x2_i
equal to positive or negative zero and for either or both of
x1_i
and
x2_i
equal to positive or negative
infinity
.
Special Cases ¶
For floatingpoint operands,

If either
x1_i
orx2_i
isNaN
, the result isNaN
. 
If
x1_i
is greater than0
andx2_i
is+0
, the result is an implementationdependent approximation to+π/2
. 
If
x1_i
is greater than0
andx2_i
is0
, the result is an implementationdependent approximation to+π/2
. 
If
x1_i
is+0
andx2_i
is greater than0
, the result is+0
. 
If
x1_i
is+0
andx2_i
is+0
, the result is+0
. 
If
x1_i
is+0
andx2_i
is0
, the result is an implementationdependent approximation to+π
. 
If
x1_i
is+0
andx2_i
is less than0
, the result is an implementationdependent approximation to+π
. 
If
x1_i
is0
andx2_i
is greater than0
, the result is0
. 
If
x1_i
is0
andx2_i
is+0
, the result is0
. 
If
x1_i
is0
andx2_i
is0
, the result is an implementationdependent approximation toπ
. 
If
x1_i
is0
andx2_i
is less than0
, the result is an implementationdependent approximation toπ
. 
If
x1_i
is less than0
andx2_i
is+0
, the result is an implementationdependent approximation toπ/2
. 
If
x1_i
is less than0
andx2_i
is0
, the result is an implementationdependent approximation toπ/2
. 
If
x1_i
is greater than0
,x1_i
is a finite number, andx2_i
is+infinity
, the result is+0
. 
If
x1_i
is greater than0
,x1_i
is a finite number, andx2_i
isinfinity
, the result is an implementationdependent approximation to+π
. 
If
x1_i
is less than0
,x1_i
is a finite number, andx2_i
is+infinity
, the result is0
. 
If
x1_i
is less than0
,x1_i
is a finite number, andx2_i
isinfinity
, the result is an implementationdependent approximation toπ
. 
If
x1_i
is+infinity
andx2_i
is finite, the result is an implementationdependent approximation to+π/2
. 
If
x1_i
isinfinity
andx2_i
is finite, the result is an implementationdependent approximation toπ/2
. 
If
x1_i
is+infinity
andx2_i
is+infinity
, the result is an implementationdependent approximation to+π/4
. 
If
x1_i
is+infinity
andx2_i
isinfinity
, the result is an implementationdependent approximation to+3π/4
. 
If
x1_i
isinfinity
andx2_i
is+infinity
, the result is an implementationdependent approximation toπ/4
. 
If
x1_i
isinfinity
andx2_i
isinfinity
, the result is an implementationdependent approximation to3π/4
.
Parameters ¶

x1 : <array>

input array corresponding to the ycoordinates. Should have a floatingpoint data type.


x2 : <array>

input array corresponding to the xcoordinates. Must be compatible with
x1
(see Broadcasting ). Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse tangent of the quotient
x1/x2
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

atanh(x, /) ¶
Calculates an implementationdependent approximation to the inverse hyperbolic tangent, having domain
[1,
+1]
and codomain
[infinity,
+infinity]
, for each element
x_i
of the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than1
, the result isNaN
. 
If
x_i
is greater than1
, the result isNaN
. 
If
x_i
is1
, the result isinfinity
. 
If
x_i
is+1
, the result is+infinity
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
.
Parameters ¶

x : <array>

input array whose elements each represent the area of a hyperbolic sector. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the inverse hyperbolic tangent of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

first input array. Should have an integer or boolean data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have an integer or boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

first input array. Should have an integer data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have an integer data type. Each element must be greater than or equal to0
.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

bitwise_invert(x, /) ¶
Inverts (flips) each bit for each element
x_i
of the input array
x
.
Parameters ¶

x : <array>

input array. Should have an integer or boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have the same data type as
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
.
Parameters ¶

x1 : <array>

first input array. Should have an integer or boolean data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have an integer or boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

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
.
Note
This operation must be an arithmetic shift (i.e., signpropagating) and thus equivalent to floor division by a power of two.
Parameters ¶

x1 : <array>

first input array. Should have an integer data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have an integer data type. Each element must be greater than or equal to0
.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

first input array. Should have an integer or boolean data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have an integer or boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

ceil(x, /) ¶
Rounds each element
x_i
of the input array
x
to the smallest (i.e., closest to
infinity
) integervalued number that is not less than
x_i
.
Special Cases ¶

If
x_i
is already integervalued, the result isx_i
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the rounded result for each element in
x
. The returned array must have the same data type asx
.

cos(x, /) ¶
Calculates an implementationdependent approximation to the cosine, having domain
(infinity,
+infinity)
and codomain
[1,
+1]
, for each element
x_i
of the input array
x
. Each element
x_i
is assumed to be expressed in radians.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is1
. 
If
x_i
is0
, the result is1
. 
If
x_i
is+infinity
, the result isNaN
. 
If
x_i
isinfinity
, the result isNaN
.
Parameters ¶

x : <array>

input array whose elements are each expressed in radians. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the cosine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

cosh(x, /) ¶
Calculates an implementationdependent approximation to the hyperbolic cosine, having domain
[infinity,
+infinity]
and codomain
[infinity,
+infinity]
, for each element
x_i
in the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is1
. 
If
x_i
is0
, the result is1
. 
If
x_i
is+infinity
, the result is+infinity
. 
If
x_i
isinfinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array whose elements each represent a hyperbolic angle. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the hyperbolic cosine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
.
Special Cases ¶
For floatingpoint operands,

If either
x1_i
orx2_i
isNaN
, the result isNaN
. 
If
x1_i
is either+infinity
orinfinity
andx2_i
is either+infinity
orinfinity
, the result isNaN
. 
If
x1_i
is either+0
or0
andx2_i
is either+0
or0
, the result isNaN
. 
If
x1_i
is+0
andx2_i
is greater than0
, the result is+0
. 
If
x1_i
is0
andx2_i
is greater than0
, the result is0
. 
If
x1_i
is+0
andx2_i
is less than0
, the result is0
. 
If
x1_i
is0
andx2_i
is less than0
, the result is+0
. 
If
x1_i
is greater than0
andx2_i
is+0
, the result is+infinity
. 
If
x1_i
is greater than0
andx2_i
is0
, the result isinfinity
. 
If
x1_i
is less than0
andx2_i
is+0
, the result isinfinity
. 
If
x1_i
is less than0
andx2_i
is0
, the result is+infinity
. 
If
x1_i
is+infinity
andx2_i
is a positive (i.e., greater than0
) finite number, the result is+infinity
. 
If
x1_i
is+infinity
andx2_i
is a negative (i.e., less than0
) finite number, the result isinfinity
. 
If
x1_i
isinfinity
andx2_i
is a positive (i.e., greater than0
) finite number, the result isinfinity
. 
If
x1_i
isinfinity
andx2_i
is a negative (i.e., less than0
) finite number, the result is+infinity
. 
If
x1_i
is a positive (i.e., greater than0
) finite number andx2_i
is+infinity
, the result is+0
. 
If
x1_i
is a positive (i.e., greater than0
) finite number andx2_i
isinfinity
, the result is0
. 
If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is+infinity
, the result is0
. 
If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
isinfinity
, the result is+0
. 
If
x1_i
andx2_i
have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign. 
If
x1_i
andx2_i
have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign. 
In the remaining cases, where neither
infinity
,+0
,0
, norNaN
is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 7542019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is aninfinity
of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign.
Parameters ¶

x1 : <array>

dividend input array. Should have a floatingpoint data type.


x2 : <array>

divisor input array. Must be compatible with
x1
(see Broadcasting ). Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

first input array. May have any data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). May have any data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

exp(x, /) ¶
Calculates an implementationdependent 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).
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is1
. 
If
x_i
is0
, the result is1
. 
If
x_i
is+infinity
, the result is+infinity
. 
If
x_i
isinfinity
, the result is+0
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the evaluated exponential function result for each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

expm1(x, /) ¶
Calculates an implementationdependent approximation to
exp(x)1
, having domain
[infinity,
+infinity]
and codomain
[1,
+infinity]
, for each element
x_i
of the input array
x
.
Note
The purpose of this function is to calculate
exp(x)1.0
more accurately when
x
is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply
exp(x)1.0
. See FDLIBM, or some other IEEE 7542019 compliant mathematical library, for a potential reference implementation.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+infinity
, the result is+infinity
. 
If
x_i
isinfinity
, the result is1
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the evaluated result for each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

floor(x, /) ¶
Rounds each element
x_i
of the input array
x
to the greatest (i.e., closest to
+infinity
) integervalued number that is not greater than
x_i
.
Special Cases ¶

If
x_i
is already integervalued, the result isx_i
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the rounded result for each element in
x
. The returned array must have the same data type asx
.

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
) integervalue number that is not greater than the division result.
Parameters ¶

x1 : <array>

dividend input array. Should have a numeric data type.


x2 : <array>

divisor input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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
.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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).
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing test results. An element
out_i
isTrue
ifx_i
is finite andFalse
otherwise. The returned array must have a data type ofbool
.

isinf(x, /) ¶
Tests each element
x_i
of the input array
x
to determine if equal to positive or negative infinity.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing test results. An element
out_i
isTrue
ifx_i
is either positive or negative infinity andFalse
otherwise. The returned array must have a data type ofbool
.

isnan(x, /) ¶
Tests each element
x_i
of the input array
x
to determine whether the element is
NaN
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing test results. An element
out_i
isTrue
ifx_i
isNaN
andFalse
otherwise. The returned array should have a data type ofbool
.

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
.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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
.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

log(x, /) ¶
Calculates an implementationdependent 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
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than0
, the result isNaN
. 
If
x_i
is either+0
or0
, the result isinfinity
. 
If
x_i
is1
, the result is+0
. 
If
x_i
is+infinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the evaluated natural logarithm for each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

log1p(x, /) ¶
Calculates an implementationdependent 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
.
Note
The purpose of this function is to calculate
log(1+x)
more accurately when
x
is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply
log(1+x)
. See FDLIBM, or some other IEEE 7542019 compliant mathematical library, for a potential reference implementation.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than1
, the result isNaN
. 
If
x_i
is1
, the result isinfinity
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is+infinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the evaluated result for each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

log2(x, /) ¶
Calculates an implementationdependent approximation to the base
2
logarithm, having domain
[0,
+infinity]
and codomain
[infinity,
+infinity]
, for each element
x_i
of the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than0
, the result isNaN
. 
If
x_i
is either+0
or0
, the result isinfinity
. 
If
x_i
is1
, the result is+0
. 
If
x_i
is+infinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the evaluated base
2
logarithm for each element inx
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

log10(x, /) ¶
Calculates an implementationdependent approximation to the base
10
logarithm, having domain
[0,
+infinity]
and codomain
[infinity,
+infinity]
, for each element
x_i
of the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than0
, the result isNaN
. 
If
x_i
is either+0
or0
, the result isinfinity
. 
If
x_i
is1
, the result is+0
. 
If
x_i
is+infinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the evaluated base
10
logarithm for each element inx
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
.
Special Cases ¶
For floatingpoint operands,

If either
x1_i
orx2_i
isNaN
, the result isNaN
. 
If either
x1_i
orx2_i
is+infinity
, the result is+infinity
.
Parameters ¶

x1 : <array>

first input array. Should have a floatingpoint data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
. Zeros are considered the equivalent of
False
, while nonzeros are considered the equivalent of
True
.
Parameters ¶

x1 : <array>

first input array. Should have a boolean data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

logical_not(x, /) ¶
Computes the logical NOT for each element
x_i
of the input array
x
. Zeros are considered the equivalent of
False
, while nonzeros are considered the equivalent of
True
.
Parameters ¶

x : <array>

input array. Should have a boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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
. Zeros are considered the equivalent of
False
, while nonzeros are considered the equivalent of
True
.
Parameters ¶

x1 : <array>

first input array. Should have a boolean data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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
. Zeros are considered the equivalent of
False
, while nonzeros are considered the equivalent of
True
.
Parameters ¶

x1 : <array>

first input array. Should have a boolean data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a boolean data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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
.
Special Cases ¶
For floatingpoint operands,

If either
x1_i
orx2_i
isNaN
, the result isNaN
. 
If
x1_i
is either+infinity
orinfinity
andx2_i
is either+0
or0
, the result isNaN
. 
If
x1_i
is either+0
or0
andx2_i
is either+infinity
orinfinity
, the result isNaN
. 
If
x1_i
andx2_i
have the same mathematical sign, the result has a positive mathematical sign, unless the result isNaN
. If the result isNaN
, the “sign” ofNaN
is implementationdefined. 
If
x1_i
andx2_i
have different mathematical signs, the result has a negative mathematical sign, unless the result isNaN
. If the result isNaN
, the “sign” ofNaN
is implementationdefined. 
If
x1_i
is either+infinity
orinfinity
andx2_i
is either+infinity
orinfinity
, the result is a signed infinity with the mathematical sign determined by the rule already stated above. 
If
x1_i
is either+infinity
orinfinity
andx2_i
is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. 
If
x1_i
is a nonzero finite number andx2_i
is either+infinity
orinfinity
, the result is a signed infinity with the mathematical sign determined by the rule already stated above. 
In the remaining cases, where neither
infinity
norNaN
is involved, the product must be computed and rounded to the nearest representable value according to IEEE 7542019 and a supported rounding mode. If the magnitude is too large to represent, the result is aninfinity
of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign.
Note
Floatingpoint multiplication is not always associative due to finite precision.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise products. The returned array must have a data type determined by Type Promotion Rules .

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

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the evaluated result for each element in
x
. The returned array must have a data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

first input array. May have any data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ).

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type of
bool
.

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

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the evaluated result for each element in
x
. The returned array must have the same data type asx
.

pow(x1, x2, /) ¶
Calculates an implementationdependent 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
.
Special Cases ¶
For floatingpoint operands,

If
x1_i
is not equal to1
andx2_i
isNaN
, the result isNaN
. 
If
x2_i
is+0
, the result is1
, even ifx1_i
isNaN
. 
If
x2_i
is0
, the result is1
, even ifx1_i
isNaN
. 
If
x1_i
isNaN
andx2_i
is not equal to0
, the result isNaN
. 
If
abs(x1_i)
is greater than1
andx2_i
is+infinity
, the result is+infinity
. 
If
abs(x1_i)
is greater than1
andx2_i
isinfinity
, the result is+0
. 
If
abs(x1_i)
is1
andx2_i
is+infinity
, the result is1
. 
If
abs(x1_i)
is1
andx2_i
isinfinity
, the result is1
. 
If
x1_i
is1
andx2_i
is notNaN
, the result is1
. 
If
abs(x1_i)
is less than1
andx2_i
is+infinity
, the result is+0
. 
If
abs(x1_i)
is less than1
andx2_i
isinfinity
, the result is+infinity
. 
If
x1_i
is+infinity
andx2_i
is greater than0
, the result is+infinity
. 
If
x1_i
is+infinity
andx2_i
is less than0
, the result is+0
. 
If
x1_i
isinfinity
,x2_i
is greater than0
, andx2_i
is an odd integer value, the result isinfinity
. 
If
x1_i
isinfinity
,x2_i
is greater than0
, andx2_i
is not an odd integer value, the result is+infinity
. 
If
x1_i
isinfinity
,x2_i
is less than0
, andx2_i
is an odd integer value, the result is0
. 
If
x1_i
isinfinity
,x2_i
is less than0
, andx2_i
is not an odd integer value, the result is+0
. 
If
x1_i
is+0
andx2_i
is greater than0
, the result is+0
. 
If
x1_i
is+0
andx2_i
is less than0
, the result is+infinity
. 
If
x1_i
is0
,x2_i
is greater than0
, andx2_i
is an odd integer value, the result is0
. 
If
x1_i
is0
,x2_i
is greater than0
, andx2_i
is not an odd integer value, the result is+0
. 
If
x1_i
is0
,x2_i
is less than0
, andx2_i
is an odd integer value, the result isinfinity
. 
If
x1_i
is0
,x2_i
is less than0
, andx2_i
is not an odd integer value, the result is+infinity
. 
If
x1_i
is less than0
,x1_i
is a finite number,x2_i
is a finite number, andx2_i
is not an integer value, the result isNaN
.
Parameters ¶

x1 : <array>

first input array whose elements correspond to the exponentiation base. Should have a floatingpoint data type.


x2 : <array>

second input array whose elements correspond to the exponentiation exponent. Must be compatible with
x1
(see Broadcasting ). Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the elementwise results. The returned array must have a data type determined by Type Promotion Rules .

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
.
Parameters ¶

x1 : <array>

dividend input array. Should have a numeric data type.


x2 : <array>

divisor input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise results. Each elementwise result must have the same sign as the respective element
x2_i
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

round(x, /) ¶
Rounds each element
x_i
of the input array
x
to the nearest integervalued number.
Special Cases ¶

If
x_i
is already integervalued, the result isx_i
. 
If two integers are equally close to
x_i
, the result is the even integer closest tox_i
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the rounded result for each element in
x
. The returned array must have the same data type asx
.

sign(x, /) ¶
Returns an indication of the sign of a number for each element
x_i
of the input array
x
.
Special Cases ¶

If
x_i
is less than0
, the result is1
. 
If
x_i
is either0
or+0
, the result is0
. 
If
x_i
is greater than0
, the result is+1
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the evaluated result for each element in
x
. The returned array must have the same data type asx
.

sin(x, /) ¶
Calculates an implementationdependent approximation to the sine, having domain
(infinity,
+infinity)
and codomain
[1,
+1]
, for each element
x_i
of the input array
x
. Each element
x_i
is assumed to be expressed in radians.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is either+infinity
orinfinity
, the result isNaN
.
Parameters ¶

x : <array>

input array whose elements are each expressed in radians. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the sine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

sinh(x, /) ¶
Calculates an implementationdependent approximation to the hyperbolic sine, having domain
[infinity,
+infinity]
and codomain
[infinity,
+infinity]
, for each element
x_i
of the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+infinity
, the result is+infinity
. 
If
x_i
isinfinity
, the result isinfinity
.
Parameters ¶

x : <array>

input array whose elements each represent a hyperbolic angle. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the hyperbolic sine of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

square(x, /) ¶
Squares (
x_i
*
x_i
) each element
x_i
of the input array
x
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the evaluated result for each element in
x
. The returned array must have a data type determined by Type Promotion Rules .

sqrt(x, /) ¶
Calculates the square root, having domain
[0,
+infinity]
and codomain
[0,
+infinity]
, for each element
x_i
of the input array
x
. After rounding, each result must be indistinguishable from the infinitely precise result (as required by IEEE 754).
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is less than0
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+infinity
, the result is+infinity
.
Parameters ¶

x : <array>

input array. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the square root of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

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
. The result of
x1_i

x2_i
must be the same as
x1_i
+
(x2_i)
and must be governed by the same floatingpoint rules as addition (see
add()
).
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.

Returns ¶

out : <array>

an array containing the elementwise differences. The returned array must have a data type determined by Type Promotion Rules .

tan(x, /) ¶
Calculates an implementationdependent approximation to the tangent, having domain
(infinity,
+infinity)
and codomain
(infinity,
+infinity)
, for each element
x_i
of the input array
x
. Each element
x_i
is assumed to be expressed in radians.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is either+infinity
orinfinity
, the result isNaN
.
Parameters ¶

x : <array>

input array whose elements are expressed in radians. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the tangent of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

tanh(x, /) ¶
Calculates an implementationdependent approximation to the hyperbolic tangent, having domain
[infinity,
+infinity]
and codomain
[1,
+1]
, for each element
x_i
of the input array
x
.
Special Cases ¶
For floatingpoint operands,

If
x_i
isNaN
, the result isNaN
. 
If
x_i
is+0
, the result is+0
. 
If
x_i
is0
, the result is0
. 
If
x_i
is+infinity
, the result is+1
. 
If
x_i
isinfinity
, the result is1
.
Parameters ¶

x : <array>

input array whose elements each represent a hyperbolic angle. Should have a floatingpoint data type.

Returns ¶

out : <array>

an array containing the hyperbolic tangent of each element in
x
. The returned array must have a floatingpoint data type determined by Type Promotion Rules .

trunc(x, /) ¶
Rounds each element
x_i
of the input array
x
to the integervalued number that is closest to but no greater than
x_i
.
Special Cases ¶

If
x_i
is already integervalued, the result isx_i
.
Parameters ¶

x : <array>

input array. Should have a numeric data type.

Returns ¶

out : <array>

an array containing the rounded result for each element in
x
. The returned array must have the same data type asx
.
