Elementwise#
- ivy.abs(x, /, *, out=None)[source]#
Calculate the absolute value for each element
x_i
of the input arrayx
(i.e., the element-wise result has the same magnitude as the respective element inx
but has positive sign).Note
For signed integer data types, the absolute value of the minimum representable integer is implementation-dependent.
Special Cases
For real-valued floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is-0
, the result is+0
.If
x_i
is-infinity
, the result is+infinity
.
For complex floating-point operands, let
a = real(x_i)
andb = imag(x_i)
. andIf
a
is either+infinity
or-infinity
andb
is any value (includingNaN
), the result is+infinity
.If
a
is any value (includingNaN
) andb
is+infinity
, the result is+infinity
.If
a
is either+0
or-0
, the result isabs(b)
.If
b
is+0
or-0
, the result isabs(a)
.If
a
isNaN
andb
is a finite number, the result isNaN
.If
a
is a finite number andb
isNaN
, the result isNaN
.If
a
isNa``N and ``b
isNaN
, the result isNaN
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the absolute value of each element in
x
. The returned array must have the same data type asx
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([-1,0,-6]) >>> y = ivy.abs(x) >>> print(y) ivy.array([1, 0, 6])
>>> x = ivy.array([3.7, -7.7, 0, -2, -0]) >>> y = ivy.abs(x) >>> print(y) ivy.array([ 3.7, 7.7, 0., 2., 0.])
>>> x = ivy.array([[1.1, 2.2, 3.3], [-4.4, -5.5, -6.6]]) >>> ivy.abs(x, out=x) >>> print(x) ivy.array([[ 1.1, 2.2, 3.3], [4.4, 5.5, 6.6]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 2.6, -3.5]), b=ivy.array([4.5, -5.3, -0, -2.3])) # noqa >>> y = ivy.abs(x) >>> print(y) { a: ivy.array([0., 2.6, 3.5]), b: ivy.array([4.5, 5.3, 0., 2.3]) }
- ivy.acos(x, /, *, out=None)[source]#
Calculate 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. Each element-wise result is expressed in radians.
Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is greater than1
, the result isNaN
.If
x_i
is less than-1
, the result isNaN
.If
x_i
is1
, the result is+0
.
For complex floating-point operands, let a = real(x_i) and b = imag(x_i), and
If
a
is either+0
or-0
andb
is+0
, the result isπ/2 - 0j
.if
a
is either+0
or-0
andb
isNaN
, the result isπ/2 + NaN j
.If
a
is a finite number andb
is+infinity
, the result isπ/2 - infinity j
.If
a
is a nonzero finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is-infinity
andb
is a positive (i.e., greater than 0) finite number, the result isπ - infinity j
.If
a
is+infinity
andb
is a positive (i.e., greater than 0) finite number, the result is+0 - infinity j
.If
a
is-infinity
andb
is+infinity
, the result is3π/4 - infinity j
.If
a
is+infinity
andb
is+infinity
, the result isπ/4 - infinity j
.If
a
is either+infinity
or-infinity
andb
isNaN
, the result isNaN ± infinity j
(sign of the imaginary component is unspecified).If
a
isNaN
andb
is a finite number, the result isNaN + NaN j
.if
a
isNaN
andb
is+infinity
, the result isNaN - infinity j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the inverse cosine of each element in x. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([0., 1., -1.]) >>> y = ivy.acos(x) >>> print(y) ivy.array([1.57, 0. , 3.14])
>>> x = ivy.array([1., 0., -1.]) >>> y = ivy.zeros(3) >>> ivy.acos(x, out=y) >>> print(y) ivy.array([0. , 1.57, 3.14])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., -1, 1]), b=ivy.array([1., 0., -1])) >>> y = ivy.acos(x) >>> print(y) { a: ivy.array([1.57, 3.14, 0.]), b: ivy.array([0., 1.57, 3.14]) }
- ivy.acosh(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the inverse hyperbolic cosine, having domain
[+1, +infinity]
and codomain[+0, +infinity]
, for each elementx_i
of the input arrayx
.Special cases
For floating-point 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
.
For complex floating-point operands, let a = real(x_i) and b = imag(x_i), and
If
a
is either+0
or-0
andb
is+0
, the result is+0 + πj/2
.If
a
is a finite number andb
is+infinity
, the result is+infinity + πj/2
.If
a
is a nonzero finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is+0
andb
isNaN
, the result isNaN ± πj/2
(sign of the imaginary component is unspecified).If
a
is-infinity
andb
is a positive (i.e., greater than 0) finite number, the result is+infinity + πj
.If
a
is+infinity
andb
is a positive (i.e., greater than 0) finite number, the result is+infinity + 0j
.If
a
is-infinity
andb
is+infinity
, the result is+infinity + 3πj/4
.If
a
is+infinity
andb
is+infinity
, the result is+infinity + πj/4
.If
a
is either+infinity
or-infinity
andb
isNaN
, the result is+infinity + NaN j
.If
a
isNaN
andb
is a finite number, the result isNaN + NaN j
.if
a
isNaN
andb
is+infinity
, the result is+infinity + NaN j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the inverse hyperbolic cosine of each element in x. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([1, 2.5, 10]) >>> y = ivy.acosh(x) >>> print(y) ivy.array([0. , 1.57, 2.99])
>>> x = ivy.array([1., 2., 6.]) >>> y = ivy.zeros(3) >>> ivy.acosh(x, out=y) >>> print(y) ivy.array([0. , 1.32, 2.48])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([1., 2., 10.]), b=ivy.array([1., 10., 6.])) >>> y = ivy.acosh(x) >>> print(y) { a: ivy.array([0., 1.32, 2.99]), b: ivy.array([0., 2.99, 2.48]) }
- ivy.add(x1, x2, /, *, alpha=None, out=None)[source]#
Calculate the sum for each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.Special cases
For floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is+infinity
andx2_i
is-infinity
, the result isNaN
.If
x1_i
is-infinity
andx2_i
is+infinity
, the result isNaN
.If
x1_i
is+infinity
andx2_i
is+infinity
, the result is+infinity
.If
x1_i
is-infinity
andx2_i
is-infinity
, the result is-infinity
.If
x1_i
is+infinity
andx2_i
is a finite number, the result is+infinity
.If
x1_i
is-infinity
andx2_i
is a finite number, the result is-infinity
.If
x1_i
is a finite number andx2_i
is+infinity
, the result is+infinity
.If
x1_i
is a finite number andx2_i
is-infinity
, the result is-infinity
.If
x1_i
is-0
andx2_i
is-0
, the result is-0
.If
x1_i
is-0
andx2_i
is+0
, the result is+0
.If
x1_i
is+0
andx2_i
is-0
, the result is+0
.If
x1_i
is+0
andx2_i
is+0
, the result is+0
.If
x1_i
is either+0
or-0
andx2_i
is a nonzero finite number, the result isx2_i
.If
x1_i
is a nonzero finite number andx2_i
is either+0
or-0
, the result isx1_i
.If
x1_i
is a nonzero finite number andx2_i
is-x1_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 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an infinity of appropriate mathematical sign.
Note
Floating-point addition is a commutative operation, but not always associative.
For complex floating-point operands, addition is defined according to the following table. For real components
a
andc
, and imaginary componentsb
andd
,c
dj
c+dj
a
a + c
a + dj
(a+c) + dj
bj
c + bj
(b+d)j
c + (b+d)j
a+bj
(a+c) + bj
a + (b+d)j
(a+c) + (b+d)j
For complex floating-point operands, the real valued floating-point special cases must independently apply to the real and imaginary component operation involving real numbers as described in the above table. For example, let
a = real(x1_i)
,c = real(x2_i)
,d = imag(x2_i)
, and - ifa
is-0
, the real component of the result is-0
. - Similarly, ifb
is+0
andd
is-0
, the imaginary component of the result is+0
.Hence, if
z1 = a + bj = -0 + 0j
andz2 = c + dj = -0 - 0j
, then the result ofz1 + z2
is-0 + 0j
.- Parameters:
x1 (
Union
[float
,Array
,NativeArray
]) – first input array. Should have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have a numeric data type.alpha (
Optional
[Union
[int
,float
]], default:None
) – optional scalar multiplier forx2
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise sums. The returned array must have a data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
inputs:>>> x = ivy.array([1, 2, 3]) >>> y = ivy.array([4, 5, 6]) >>> z = ivy.add(x, y) >>> print(z) ivy.array([5, 7, 9])
>>> x = ivy.array([1, 2, 3]) >>> y = ivy.array([4, 5, 6]) >>> z = ivy.add(x, y, alpha=2) >>> print(z) ivy.array([9, 12, 15])
>>> x = ivy.array([[1.1, 2.3, -3.6]]) >>> y = ivy.array([[4.8], [5.2], [6.1]]) >>> z = ivy.zeros((3, 3)) >>> ivy.add(x, y, out=z) >>> print(z) ivy.array([[5.9, 7.1, 1.2], [6.3, 7.5, 1.6], [7.2, 8.4, 2.5]])
>>> x = ivy.array([[[1.1], [3.2], [-6.3]]]) >>> y = ivy.array([[8.4], [2.5], [1.6]]) >>> ivy.add(x, y, out=x) >>> print(x) ivy.array([[[9.5], [5.7], [-4.7]]])
- ivy.angle(z, /, *, deg=False, out=None)[source]#
Calculate Element-wise the angle for an array of complex numbers(x+yj).
- Parameters:
- Return type:
- Returns:
ret – Returns an array of angles for each complex number in the input. If deg is False(default), angle is calculated in radian and if deg is True, then angle is calculated in degrees.
Examples
>>> z = ivy.array([-1 + 1j, -2 + 2j, 3 - 3j]) >>> z ivy.array([-1.+1.j, -2.+2.j, 3.-3.j]) >>> ivy.angle(z) ivy.array([ 2.35619449, 2.35619449, -0.78539816]) >>> ivy.angle(z,deg=True) ivy.array([135., 135., -45.])
- ivy.asin(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation of the principal value of the inverse sine, having domain
[-1, +1]
and codomain[-π/2, +π/2]
for each elementx_i
of the input arrayx
. Each element- wise result is expressed in radians.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is greater than1
, the result isNaN
.If
x_i
is less than-1
, the result isNaN
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.
For complex floating-point operands, special cases must be handled as if the operation is implemented as
-1j * asinh(x * 1j)
.- Parameters:
- Return type:
- Returns:
ret – an array containing the inverse sine of each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([-2.4, -0, +0, 3.2, float('nan')]) >>> y = ivy.asin(x) >>> print(y) ivy.array([nan, 0., 0., nan, nan])
>>> x = ivy.array([-1, -0.5, 0.6, 1]) >>> y = ivy.zeros(4) >>> ivy.asin(x, out=y) >>> print(y) ivy.array([-1.57,-0.524,0.644,1.57])
>>> x = ivy.array([[0.1, 0.2, 0.3],[-0.4, -0.5, -0.6]]) >>> ivy.asin(x, out=x) >>> print(x) ivy.array([[0.1,0.201,0.305],[-0.412,-0.524,-0.644]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 0.1, 0.2]), ... b=ivy.array([0.3, 0.4, 0.5])) >>> y = ivy.asin(x) >>> print(y) {a:ivy.array([0.,0.1,0.201]),b:ivy.array([0.305,0.412,0.524])}
- ivy.asinh(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the inverse hyperbolic sine, having domain
[-infinity, +infinity]
and codomain[-infinity, +infinity]
, for each elementx_i
in the input arrayx
.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is-infinity
.
For complex floating-point operands, let
a = real(x_i)
andb = imag(x_i)
, andIf
a
is+0
andb
is+0
, the result is+0 + 0j
.If
a
is a positive (i.e., greater than0
) finite number andb
is+infinity
, the result is+infinity + πj/2
.If
a
is a finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is+infinity
andb
is a positive (i.e., greater than0
) finite number, the result is+infinity + 0j
.If
a
is+infinity
andb
is+infinity
, the result is+infinity + πj/4
.If
a
isNaN
andb
is+0
, the result isNaN + 0j
.If
a
isNaN
andb
is nonzero finite number, the result isNaN + NaNj
.If
a
isNaN
andb
is+infinity
, the result is±infinity ± NaNj
, (sign of real component is unspecified).If
a
isNaN
andb
isNaN
,NaN + NaNj
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the inverse hyperbolic sine of each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([-3.5, -0, +0, 1.3, float('nan')]) >>> y = ivy.asinh(x) >>> print(y) ivy.array([-1.97, 0., 0., 1.08, nan])
>>> x = ivy.array([-2, -0.75, 0.9, 1]) >>> y = ivy.zeros(4) >>> ivy.asinh(x, out=y) >>> print(y) ivy.array([-1.44, -0.693, 0.809, 0.881])
>>> x = ivy.array([[0.2, 0.4, 0.6],[-0.8, -1, -2]]) >>> ivy.asinh(x, out=x) >>> print(x) ivy.array([[ 0.199, 0.39, 0.569], [-0.733, -0.881, -1.44]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 1, 2]), ... b=ivy.array([4.2, -5.3, -0, -2.3])) >>> y = ivy.asinh(x) >>> print(y) { a: ivy.array([0., 0.881, 1.44]), b: ivy.array([2.14, -2.37, 0., -1.57]) }
- ivy.atan(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation of the principal value of the inverse tangent, having domain
[-infinity, +infinity]
and codomain[-π/2, +π/2]
, for each elementx_i
of the input arrayx
. Each element-wise result is expressed in radians.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
is+infinity
, the result is an implementation-dependent approximation to+π/2
.If
x_i
is-infinity
, the result is an implementation-dependent approximation to-π/2
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the inverse tangent of each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([0., 1., 2.]) >>> y = ivy.atan(x) >>> print(y) ivy.array([0. , 0.785, 1.11 ])
>>> x = ivy.array([4., 0., -6.]) >>> y = ivy.zeros(3) >>> ivy.atan(x, out=y) >>> print(y) ivy.array([ 1.33, 0. , -1.41])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., -1, 1]), b=ivy.array([1., 0., -6])) >>> y = ivy.atan(x) >>> print(y) { a: ivy.array([0., -0.785, 0.785]), b: ivy.array([0.785, 0., -1.41]) }
- ivy.atan2(x1, x2, /, *, out=None)[source]#
Calculate an implementation-dependent approximation of the inverse tangent of the quotient
x1/x2
, having domain[-infinity, +infinity] x. [-infinity, +infinity]
(where thex
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 arraysx1
andx2
, respectively. Each element-wise result is expressed in radians. The mathematical signs ofx1_i and x2_i
determine the quadrant of each element-wise result. The quadrant (i.e., branch) is chosen such that each element-wise 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)
.Special cases
For floating-point 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 approximation to+π/2
.If
x1_i
is greater than0
andx2_i
is-0
, the result is an 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
is-0
, the result is an approximation to+π
.If
x1_i
is+0
andx2_i
is less than 0, the result is an approximation to+π
.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
is-0
, the result is an approximation to-π
.If
x1_i
is-0
andx2_i
is less than0
, the result is an approximation to-π
.If
x1_i
is less than0
andx2_i
is+0
, the result is an approximation to-π/2
.If
x1_i
is less than0
andx2_i
is-0
, the result is an 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
is-infinity
, the result is an approximation to+π
.If
x1_i
is less than0
,x1_i
is a finite number, andx2_i
is+infinity
, the result is-0
.If
x1_i
is less than0
,x1_i
is a finite number, andx2_i
is-infinity
, the result is an approximation to-π
.If
x1_i
is+infinity
andx2_i
is finite, the result is an approximation to+π/2
.If
x1_i
is-infinity
andx2_i
is finite, the result is an approximation to-π/2
.If
x1_i
is+infinity
andx2_i
is+infinity
, the result is an approximation to+π/4
.If
x1_i
is+infinity
andx2_i
is-infinity
, the result is an approximation to+3π/4
.If
x1_i
is-infinity
andx2_i
is+infinity
, the result is an approximation to-π/4
.If
x1_i
is-infinity
andx2_i
is-infinity
, the result is an approximation to-3π/4
.
- Parameters:
x1 (
Union
[Array
,NativeArray
]) – input array corresponding to the y-coordinates. Should have a floating-point data type.x2 (
Union
[Array
,NativeArray
]) – input array corresponding to the x-coordinates. Must be compatible withx1
. Should have a floating-point data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the inverse tangent of the quotient
x1/x2
. The returned array must have a floating-point data type.
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([1.0, -1.0, -2.0]) >>> y = ivy.array([2.0, 0.0, 3.0]) >>> z = ivy.atan2(x, y) >>> print(z) ivy.array([ 0.464, -1.57 , -0.588])
>>> x = ivy.array([1.0, 2.0]) >>> y = ivy.array([-2.0, 3.0]) >>> z = ivy.zeros(2) >>> ivy.atan2(x, y, out=z) >>> print(z) ivy.array([2.68 , 0.588])
>>> nan = float("nan") >>> x = ivy.array([nan, 1.0, 1.0, -1.0, -1.0]) >>> y = ivy.array([1.0, +0, -0, +0, -0]) >>> z = ivy.atan2(x, y) >>> print(z) ivy.array([ nan, 1.57, 1.57, -1.57, -1.57])
>>> x = ivy.array([+0, +0, +0, +0, -0, -0, -0, -0]) >>> y = ivy.array([1.0, +0, -0, -1.0, 1.0, +0, -0, -1.0]) >>> z = ivy.atan2(x, y) >>> print(z) ivy.array([0. , 0. , 0. , 3.14, 0. , 0. , 0. , 3.14])
>>> inf = float("infinity") >>> x = ivy.array([inf, -inf, inf, inf, -inf, -inf]) >>> y = ivy.array([1.0, 1.0, inf, -inf, inf, -inf]) >>> z = ivy.atan2(x, y) >>> print(z) ivy.array([ 1.57 , -1.57 , 0.785, 2.36 , -0.785, -2.36 ])
>>> x = ivy.array([2.5, -1.75, 3.2, 0, -1.0]) >>> y = ivy.array([-3.5, 2, 0, 0, 5]) >>> z = ivy.atan2(x, y) >>> print(z) ivy.array([ 2.52 , -0.719, 1.57 , 0. , -0.197])
>>> x = ivy.array([[1.1, 2.2, 3.3], [-4.4, -5.5, -6.6]]) >>> y = ivy.atan2(x, x) >>> print(y) ivy.array([[ 0.785, 0.785, 0.785], [-2.36 , -2.36 , -2.36 ]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 2.6, -3.5]), ... b=ivy.array([4.5, -5.3, -0])) >>> y = ivy.array([3.0, 2.0, 1.0]) >>> z = ivy.atan2(x, y) { a: ivy.array([0., 0.915, -1.29]), b: ivy.array([0.983, -1.21, 0.]) }
>>> x = ivy.Container(a=ivy.array([0., 2.6, -3.5]), ... b=ivy.array([4.5, -5.3, -0, -2.3])) >>> y = ivy.Container(a=ivy.array([-2.5, 1.75, 3.5]), ... b=ivy.array([2.45, 6.35, 0, 1.5])) >>> z = ivy.atan2(x, y) >>> print(z) { a: ivy.array([3.14, 0.978, -0.785]), b: ivy.array([1.07, -0.696, 0., -0.993]) }
- ivy.atanh(x, /, *, out=None)[source]#
Return a new array with the inverse hyperbolic tangent of the elements of
x
.- Parameters:
- Return type:
- Returns:
ret – an array containing the inverse hyperbolic tangent of each element in
x
. The returned array must have a floating-point data type determined by Type Promotion Rules.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsSpecial cases
For real-valued floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is less than-1
, the result isNaN
.If
x_i
is greater than1
, the result isNaN
.If
x_i
is-1
, the result is-infinity
.If
x_i
is+1
, the result is+infinity
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is+0
andb
is+0
, the result is+0 + 0j
.If
a
is+0
andb
isNaN
, the result is+0 + NaN j
.If
a
is1
andb
is+0
, the result is+infinity + 0j
.If
a
is a positive (i.e., greater than0
) finite number andb
is+infinity
, the result is+0 + πj/2
.If
a
is a nonzero finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is+infinity
andb
is a positive (i.e., greater than0
) finite number, the result is+0 + πj/2
.If
a
is+infinity
andb
is+infinity
, the result is+0 + πj/2
.If
a
is+infinity
andb
isNaN
, the result is+0 + NaN j
.If
a
isNaN
andb
is a finite number, the result isNaN + NaN j
.If
a
isNaN
andb
is+infinity
, the result is±0 + πj/2
(sign of the real component is unspecified).If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
Examples
With
ivy.Array
input:>>> x = ivy.array([0, -0.5]) >>> y = ivy.atanh(x) >>> print(y) ivy.array([ 0. , -0.549])
>>> x = ivy.array([0.5, -0.5, 0.]) >>> y = ivy.zeros(3) >>> ivy.atanh(x, out=y) >>> print(y) ivy.array([ 0.549, -0.549, 0. ])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., -0.5]), b=ivy.array([ 0., 0.5])) >>> y = ivy.atanh(x) >>> print(y) { a: ivy.array([0., -0.549]), b: ivy.array([0., 0.549]) }
- ivy.bitwise_and(x1, x2, /, *, out=None)[source]#
Compute the bitwise AND of the underlying binary representation of each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.- Parameters:
x1 (
Union
[int
,bool
,Array
,NativeArray
]) – first input array. Should have an integer or boolean data type.x2 (
Union
[int
,bool
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have an integer or boolean data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
inputs:>>> x = ivy.array([2, 3, 7]) >>> y = ivy.array([7, 1, 15]) >>> z = ivy.bitwise_and(x, y) >>> print(z) ivy.array([2, 1, 7])
>>> x = ivy.array([[True], [False]]) >>> y = ivy.array([[True], [True]]) >>> ivy.bitwise_and(x, y, out=x) >>> print(x) ivy.array([[ True],[False]])
>>> x = ivy.array([1]) >>> y = ivy.array([3]) >>> ivy.bitwise_and(x, y, out=y) >>> print(y) ivy.array([1])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([1, 2, 3]), b=ivy.array([4, 5, 6])) >>> y = ivy.Container(a=ivy.array([7, 8, 9]), b=ivy.array([10, 11, 11])) >>> z = ivy.bitwise_and(x, y) >>> print(z) { a: ivy.array([1, 0, 1]), b: ivy.array([0, 1, 2]) }
With a mix of
ivy.Array
andivy.Container
inputs:>>> x = ivy.array([True, True]) >>> y = ivy.Container(a=ivy.array([True, False]), b=ivy.array([False, True])) >>> z = ivy.bitwise_and(x, y) >>> print(z) { a: ivy.array([True, False]), b: ivy.array([False, True]) }
- ivy.bitwise_invert(x, /, *, out=None)[source]#
Inverts (flips) each bit for each element
x_i
of the input arrayx
.- Parameters:
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have the same data type as x.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([1, 6, 9]) >>> y = ivy.bitwise_invert(x) >>> print(y) ivy.array([-2, -7, -10])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([False, True, False]), ... b=ivy.array([True, True, False])) >>> y = ivy.bitwise_invert(x) >>> print(y) { a: ivy.array([True, False, True]), b: ivy.array([False, False, True]) }
With
int
input:>>> x = -8 >>> y = ivy.bitwise_invert(x) >>> print(y) ivy.array(7)
With
bool
input:>>> x = False >>> y = ivy.bitwise_invert(x) >>> print(y) True
- ivy.bitwise_left_shift(x1, x2, /, *, out=None)[source]#
Shifts the bits of each element
x1_i
of the input arrayx1
to the left by appendingx2_i
(i.e., the respective element in the input arrayx2
) zeros to the right ofx1_i
.- Parameters:
x1 (
Union
[int
,Array
,NativeArray
]) – first input array. Should have an integer data type.x2 (
Union
[int
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have an integer data type. Each element must be greater than or equal to0
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments
- ivy.bitwise_or(x1, x2, /, *, out=None)[source]#
Compute the bitwise OR of the underlying binary representation of each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.- Parameters:
x1 (
Union
[int
,bool
,Array
,NativeArray
]) – first input array. Should have an integer or boolean data type.x2 (
Union
[int
,bool
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have an integer or boolean data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([1, 2, 3]) >>> y = ivy.array([4, 5, 6]) >>> z = ivy.bitwise_or(x, y) >>> print(z) ivy.array([5, 7, 7])
>>> x = ivy.array([[[1], [2], [3], [4]]]) >>> y = ivy.array([[[4], [5], [6], [7]]]) >>> ivy.bitwise_or(x, y, out=x) >>> print(x) ivy.array([[[5], [7], [7], [7]]])
>>> x = ivy.array([[[1], [2], [3], [4]]]) >>> y = ivy.array([4, 5, 6, 7]) >>> z = ivy.bitwise_or(x, y) >>> print(z) ivy.array([[[5, 5, 7, 7], [6, 7, 6, 7], [7, 7, 7, 7], [4, 5, 6, 7]]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([1, 2, 3]),b=ivy.array([2, 3, 4])) >>> y = ivy.Container(a=ivy.array([4, 5, 6]),b=ivy.array([5, 6, 7])) >>> z = ivy.bitwise_or(x, y) >>> print(z) { a: ivy.array([5, 7, 7]), b: ivy.array([7, 7, 7]) }
With a mix of
ivy.Array
andivy.Container
inputs:>>> x = ivy.array([1, 2, 3]) >>> y = ivy.Container(a=ivy.array([4, 5, 6]),b=ivy.array([5, 6, 7])) >>> z = ivy.bitwise_or(x, y) >>> print(z) { a: ivy.array([5,7,7]), b: ivy.array([5,6,7]) }
- ivy.bitwise_right_shift(x1, x2, /, *, out=None)[source]#
Shifts the bits of each element
x1_i
of the input arrayx1
to the right according to the respective elementx2_i
of the input arrayx2
.Note
This operation must be an arithmetic shift (i.e., sign-propagating) and thus equivalent to floor division by a power of two.
- Parameters:
x1 (
Union
[int
,Array
,NativeArray
]) – first input array. Should have an integer data type.x2 (
Union
[int
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have an integer data type. Each element must be greater than or equal to0
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> a = ivy.array([2, 9, 16, 31]) >>> b = ivy.array([0, 1, 2, 3]) >>> y = ivy.bitwise_right_shift(a, b) >>> print(y) ivy.array([2, 4, 4, 3])
>>> a = ivy.array([[32, 40, 55], [16, 33, 170]]) >>> b = ivy.array([5, 2, 1]) >>> y = ivy.zeros((2, 3)) >>> ivy.bitwise_right_shift(a, b, out=y) >>> print(y) ivy.array([[ 1., 10., 27.], [ 0., 8., 85.]])
>>> a = ivy.array([[10, 64],[43, 87],[5, 37]]) >>> b = ivy.array([1, 3]) >>> ivy.bitwise_right_shift(a, b, out=a) >>> print(a) ivy.array([[ 5, 8], [21, 10], [ 2, 4]])
With a mix of
ivy.Array
andivy.NativeArray
inputs:>>> a = ivy.array([[10, 64],[43, 87],[5, 37]]) >>> b = ivy.native_array([1, 3]) >>> y = ivy.bitwise_right_shift(a, b) >>> print(y) ivy.array([[ 5, 8],[21, 10],[ 2, 4]])
With one
ivy.Container
input:>>> a = ivy.Container(a = ivy.array([100, 200]), ... b = ivy.array([125, 243])) >>> b = ivy.array([3, 6]) >>> y = ivy.bitwise_right_shift(a, b) >>> print(y) { a: ivy.array([12, 3]), b: ivy.array([15, 3]) }
With multiple
ivy.Container
inputs:>>> a = ivy.Container(a = ivy.array([10, 25, 42]), ... b = ivy.array([64, 65]), ... c = ivy.array([200, 225, 255])) >>> b = ivy.Container(a = ivy.array([0, 1, 2]), ... b = ivy.array([6]), ... c = ivy.array([4, 5, 6])) >>> y = ivy.bitwise_right_shift(a, b) >>> print(y) { a: ivy.array([10, 12, 10]), b: ivy.array([1, 1]), c: ivy.array([12, 7, 3]) }
- ivy.bitwise_xor(x1, x2, /, *, out=None)[source]#
Compute the bitwise XOR of the underlying binary representation of each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.- Parameters:
x1 (
Union
[int
,bool
,Array
,NativeArray
]) – first input array. Should have an integer or boolean data type.x2 (
Union
[int
,bool
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have an integer or boolean data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assume an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
int
input:>>> x1 = 4 >>> x2 = 5 >>> y = ivy.bitwise_xor(x1, x2) >>> print(y) ivy.array(1)
With
bool
input:>>> x1 = True >>> x2 = False >>> y = ivy.bitwise_xor(x1, x2) >>> print(y) ivy.array(True)
With
ivy.Array
inputs:>>> x1 = ivy.array([1, 2, 3]) >>> x2 = ivy.array([3, 5, 7]) >>> y = ivy.zeros(3, dtype=ivy.int32) >>> ivy.bitwise_xor(x1, x2, out=y) >>> print(y) ivy.array([2, 7, 4])
>>> x1 = ivy.array([[True], [True]]) >>> x2 = ivy.array([[False], [True]]) >>> ivy.bitwise_xor(x1, x2, out=x2) >>> print(x2) ivy.array([[True], [False]])
With
ivy.Container
input:>>> x1 = ivy.Container(a=ivy.array([1, 2, 3]), b=ivy.array([4, 5, 6])) >>> x2 = ivy.Container(a=ivy.array([7, 8, 9]), b=ivy.array([10, 11, 12])) >>> y = ivy.bitwise_xor(x1, x2) >>> print(y) { a: ivy.array([6, 10, 10]), b: ivy.array([14, 14, 10]) }
With a mix of
ivy.Array
andivy.Container
inputs:>>> x1 = ivy.array([True, True]) >>> x2 = ivy.Container(a=ivy.array([True, False]), b=ivy.array([False, True])) >>> y = ivy.bitwise_xor(x1, x2) >>> print(y) { a: ivy.array([False, True]), b: ivy.array([True, False]) }
- ivy.ceil(x, /, *, out=None)[source]#
Round each element
x_i
of the input arrayx
to the smallest (i.e., closest to-infinity
) integer-valued number that is not less thanx_i
.Special cases
If
x_i
is already integer-valued, the result isx_i
.
For floating-point operands,
If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is-infinity
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
isNaN
, the result isNaN
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the rounded result for each element in
x
. The returned array must have the same data type asx
.
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([0.1, 0, -0.1]) >>> y = ivy.ceil(x) >>> print(y) ivy.array([1., 0., -0.])
>>> x = ivy.array([2.5, -3.5, 0, -3, -0]) >>> y = ivy.ones(5) >>> ivy.ceil(x, out=y) >>> print(y) ivy.array([ 3., -3., 0., -3., 0.])
>>> x = ivy.array([[3.3, 4.4, 5.5], [-6.6, -7.7, -8.8]]) >>> ivy.ceil(x, out=x) >>> print(x) ivy.array([[ 4., 5., 6.], [-6., -7., -8.]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([2.5, 0.5, -1.4]), ... b=ivy.array([5.4, -3.2, -0, 5.2])) >>> y = ivy.ceil(x) >>> print(y) { a: ivy.array([3., 1., -1.]), b: ivy.array([6., -3., 0., 6.]) }
- ivy.cos(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the cosine, having domain
(-infinity, +infinity)
and codomain[-1, +1]
, for each elementx_i
of the input arrayx
. Each elementx_i
is assumed to be expressed in radians.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is1
.If
x_i
is-0
, the result is1
.If
x_i
is+infinity
, the result isNaN
.If
x_i
is-infinity
, the result isNaN
.
For complex floating-point operands, special cases must be handled as if the operation is implemented as
cosh(x*1j)
.- Parameters:
- Return type:
- Returns:
ret – an array containing the cosine of each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([0., 1., 2.]) >>> y = ivy.cos(x) >>> print(y) ivy.array([1., 0.54, -0.416])
>>> x = ivy.array([4., 0., -6.]) >>> y = ivy.zeros(3) >>> ivy.cos(x, out=y) >>> print(y) ivy.array([-0.654, 1., 0.96])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., -1, 1]), b=ivy.array([1., 0., -6])) >>> y = ivy.cos(x) >>> print(y) { a: ivy.array([1., 0.54, 0.54]), b: ivy.array([0.54, 1., 0.96]) }
- ivy.cosh(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the hyperbolic cosine, having domain
[-infinity, +infinity]
and codomain[-infinity, +infinity]
, for each elementx_i
in the input arrayx
.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is1
.If
x_i
is-0
, the result is1
.If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is+infinity
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andNote
For complex floating-point operands,
cosh(conj(x))
must equalconj(cosh(x))
.If
a
is+0
andb
is+0
, the result is1 + 0j
.If
a
is+0
andb
is+infinity
, the result isNaN + 0j
(sign of the imaginary component is unspecified).If
a
is+0
andb
isNaN
, the result isNaN + 0j
(sign of the imaginary component is unspecified).If
a
is a nonzero finite number andb
is+infinity
, the result isNaN + NaN j
.If
a
is a nonzero finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is+infinity
andb
is+0
, the result is+infinity + 0j
.If
a
is+infinity
andb
is a nonzero finite number, the result is+infinity * cis(b)
.If
a
is+infinity
andb
is+infinity
, the result is ``+infinity + NaN j``(sign of the real component is unspecified).If
a
is+infinity
andb
isNaN
, the result is+infinity + NaN j
.If
a
isNaN
andb
is either+0
or-0
, the result isNaN + 0j
(sign of the imaginary component is unspecified).If
a
isNaN
andb
is a nonzero finite number, the result isNaN + NaN j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
where
cis(v)
iscos(v) + sin(v)*1j
.- Parameters:
- Return type:
- Returns:
ret – an array containing the hyperbolic cosine of each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([1., 2., 3., 4.]) >>> y = ivy.cosh(x) >>> print(y) ivy.array([1.54,3.76,10.1,27.3])
>>> x = ivy.array([0.2, -1.7, -5.4, 1.1]) >>> y = ivy.zeros(4) >>> ivy.cosh(x, out=y) ivy.array([[1.67,4.57,13.6,12.3],[40.7,122.,368.,670.]])
>>> x = ivy.array([[1.1, 2.2, 3.3, 3.2], ... [-4.4, -5.5, -6.6, -7.2]]) >>> y = ivy.cosh(x) >>> print(y) ivy.array([[1.67,4.57,13.6,12.3],[40.7,122.,368.,670.]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([1., 2., 3.]), b=ivy.array([6., 7., 8.])) >>> y = ivy.cosh(x) >>> print(y) { a:ivy.array([1.54,3.76,10.1]), b:ivy.array([202.,548.,1490.]) }
- ivy.deg2rad(x, /, *, out=None)[source]#
Convert the input from degrees to radians.
- Parameters:
- Return type:
- Returns:
ret – an array with each element in
x
converted from degrees to radians.
Examples
With
ivy.Array
input:>>> x=ivy.array([0,90,180,270,360], dtype=ivy.float32) >>> y=ivy.deg2rad(x) >>> print(y) ivy.array([0., 1.57079633, 3.14159265, 4.71238898, 6.28318531])
>>> x=ivy.array([0,-1.5,-50,ivy.nan]) >>> y=ivy.zeros(4) >>> ivy.deg2rad(x,out=y) >>> print(y) ivy.array([ 0., -0.02617994, -0.87266463, nan])
>>> x = ivy.array([[1.1, 2.2, 3.3],[-4.4, -5.5, -6.6]]) >>> ivy.deg2rad(x, out=x) >>> print(x) ivy.array([[ 0.01919862, 0.03839725, 0.05759586], [-0.07679449, -0.09599311, -0.11519173]])
>>> x=ivy.native_array([-0,20.1,ivy.nan]) >>> y=ivy.zeros(3) >>> ivy.deg2rad(x,out=y) >>> print(y) ivy.array([0., 0.35081118, nan])
With
ivy.Container
input:>>> x=ivy.Container(a=ivy.array([-0,20.1,-50.5,-ivy.nan]), ... b=ivy.array([0,90.,180,270,360], dtype=ivy.float32)) >>> y=ivy.deg2rad(x) >>> print(y) { a: ivy.array([0., 0.35081118, -0.88139129, nan]), b: ivy.array([0., 1.57079633, 3.14159265, 4.71238898, 6.28318531]) }
>>> x=ivy.Container(a=ivy.array([0,90,180,270,360], dtype=ivy.float32), ... b=ivy.native_array([0,-1.5,-50,ivy.nan])) >>> y=ivy.deg2rad(x) >>> print(y) { a: ivy.array([0., 1.57079633, 3.14159265, 4.71238898, 6.28318531]), b: ivy.array([0., -0.02617994, -0.87266463, nan]) }
- ivy.divide(x1, x2, /, *, out=None)[source]#
Calculate 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 real-valued floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is either+infinity
or-infinity
andx2_i
is either+infinity
or-infinity
, the result isNaN
.If
x1_i
is either+0
or-0
andx2_i
is either+0
or-0
, the result isNaN
.If
x1_i
is+0
andx2_i
is greater than0
, 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-0
.If
x1_i
is-0
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
is-0
, the result is-infinity
.If
x1_i
is less than0
andx2_i
is+0
, the result is-infinity
.If
x1_i
is less than0
andx2_i
is-0
, 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 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 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
is-infinity
, the result is-0
.If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is+infinity
, the result is-0
.If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is-infinity
, 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 754-2019 and a supported rounding mode. If the magnitude is too large 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.
For complex floating-point operands, division is defined according to the following table. For real components
a
andc
and imaginary componentsb
andd
,c
dj
c + dj
a
a / c
-(a/d)j
special rules
bj
(b/c)j
b/d
special rules
a + bj
(a/c) + (b/c)j
b/d - (a/d)j
special rules
In general, for complex floating-point operands, real-valued floating-point special cases must independently apply to the real and imaginary component operations involving real numbers as described in the above table.
When
a
,b
,c
, ord
are all finite numbers (i.e., a value other thanNaN
,+infinity
, or-infinity
), division of complex floating-point operands should be computed as if calculated according to the textbook formula for complex number division\[\frac{a + bj}{c + dj} = \frac{(ac + bd) + (bc - ad)j}{c^2 + d^2}\]When at least one of
a
,b
,c
, ord
isNaN
,+infinity
, or-infinity
,If
a
,b
,c
, andd
are allNaN
, the result isNaN + NaN j
.In the remaining cases, the result is implementation dependent.
Note
For complex floating-point operands, the results of special cases may be implementation dependent depending on how an implementation chooses to model complex numbers and complex infinity (e.g., complex plane versus Riemann sphere). For those implementations following C99 and its one-infinity model, when at least one component is infinite, even if the other component is
NaN
, the complex value is infinite, and the usual arithmetic rules do not apply to complex-complex division. In the interest of performance, other implementations may want to avoid the complex branching logic necessary to implement the one-infinity model and choose to implement all complex-complex division according to the textbook formula. Accordingly, special case behavior is unlikely to be consistent across implementations.This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.- Parameters:
x1 (
Union
[float
,Array
,NativeArray
]) – dividend input array. Should have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
]) – divisor input array. Must be compatible with x1 (see Broadcasting). Should have a numeric data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a floating-point data type determined by Type Promotion Rules.
Examples
With
ivy.Array
inputs:>>> x1 = ivy.array([2., 7., 9.]) >>> x2 = ivy.array([3., 4., 0.6]) >>> y = ivy.divide(x1, x2) >>> print(y) ivy.array([0.667, 1.75, 15.])
With mixed
ivy.Array
andivy.NativeArray
inputs:>>> x1 = ivy.array([5., 6., 9.]) >>> x2 = ivy.native_array([2., 2., 2.]) >>> y = ivy.divide(x1, x2) >>> print(y) ivy.array([2.5, 3., 4.5])
With
ivy.Container
inputs:>>> x1 = ivy.Container(a=ivy.array([12., 3.5, 6.3]), b=ivy.array([3., 1., 0.9])) >>> x2 = ivy.Container(a=ivy.array([1., 2.3, 3]), b=ivy.array([2.4, 3., 2.])) >>> y = ivy.divide(x1, x2) >>> print(y) { a: ivy.array([12., 1.52, 2.1]), b: ivy.array([1.25, 0.333, 0.45]) }
With mixed
ivy.Container
andivy.Array
inputs:>>> x1 = ivy.Container(a=ivy.array([12., 3.5, 6.3]), b=ivy.array([3., 1., 0.9])) >>> x2 = ivy.array([4.3, 3., 5.]) >>> y = ivy.divide(x1, x2) { a: ivy.array([2.79, 1.17, 1.26]), b: ivy.array([0.698, 0.333, 0.18]) }
- ivy.equal(x1, x2, /, *, out=None)[source]#
Compute 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 (
Union
[float
,Array
,NativeArray
,Container
]) – first input array. May have any data type.x2 (
Union
[float
,Array
,NativeArray
,Container
]) – second input array. Must be compatible with x1 (with Broadcasting). May have any data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of bool.
Special cases
For real-valued floating-point operands,
If
x1_i
isNaN
orx2_i
isNaN
, the result isFalse
.If
x1_i
is+infinity
andx2_i
is+infinity
, the result isTrue
.If
x1_i
is-infinity
andx2_i
is-infinity
, the result isTrue
.If
x1_i
is-0
andx2_i
is either+0
or-0
, the result isTrue
.If
x1_i
is+0
andx2_i
is either+0
or-0
, the result isTrue
.If
x1_i
is a finite number,x2_i
is a finite number, andx1_i
equalsx2_i
, the result isTrue
.In the remaining cases, the result is
False
.
For complex floating-point operands, let
a = real(x1_i)
,b = imag(x1_i)
,c = real(x2_i)
,d = imag(x2_i)
, andIf
a
,b
,c
, ord
isNaN
, the result isFalse
.In the remaining cases, the result is the logical AND of the equality comparison between the real values
a
andc
(real components) and between the real valuesb
andd
(imaginary components), as described above for real-valued floating-point operands (i.e.,a == c AND b == d
).
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
inputs:>>> x1 = ivy.array([2., 7., 9.]) >>> x2 = ivy.array([1., 7., 9.]) >>> y = ivy.equal(x1, x2) >>> print(y) ivy.array([False, True, True])
With mixed
ivy.Array
andivy.NativeArray
inputs:>>> x1 = ivy.array([5, 6, 9]) >>> x2 = ivy.native_array([2, 6, 2]) >>> y = ivy.equal(x1, x2) >>> print(y) ivy.array([False, True, False])
With
ivy.Container
inputs:>>> x1 = ivy.Container(a=ivy.array([12, 3.5, 6.3]), b=ivy.array([3., 1., 0.9])) >>> x2 = ivy.Container(a=ivy.array([12, 2.3, 3]), b=ivy.array([2.4, 3., 2.])) >>> y = ivy.equal(x1, x2) >>> print(y) { a: ivy.array([True, False, False]), b: ivy.array([False, False, False]) }
With mixed
ivy.Container
andivy.Array
inputs:>>> x1 = ivy.Container(a=ivy.array([12., 3.5, 6.3]), b=ivy.array([3., 1., 0.9])) >>> x2 = ivy.array([3., 1., 0.9]) >>> y = ivy.equal(x1, x2) >>> print(y) { a: ivy.array([False, False, False]), b: ivy.array([True, True, True]) }
- ivy.erf(x, /, *, out=None)[source]#
Compute the Gauss error function of
x
element-wise.- Parameters:
- Return type:
- Returns:
ret – The Gauss error function of x.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([0, 0.3, 0.7]) >>> y = ivy.erf(x) >>> print(y) ivy.array([0., 0.32862675, 0.67780113])
>>> x = ivy.array([0.1, 0.3, 0.4, 0.5]) >>> ivy.erf(x, out=x) >>> print(x) ivy.array([0.11246294, 0.32862675, 0.42839241, 0.52050018])
>>> x = ivy.array([[0.15, 0.28], [0.41, 1.75]]) >>> y = ivy.zeros((2, 2)) >>> ivy.erf(x, out=y) >>> print(y) ivy.array([[0.16799599, 0.30787992], [0.43796915, 0.98667163]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0.9, 1.1, 1.2]), b=ivy.array([1.3, 1.4, 1.5])) >>> y = ivy.erf(x) >>> print(y) { a: ivy.array([0.79690808, 0.88020504, 0.91031402]), b: ivy.array([0.934008, 0.95228523, 0.96610528]) }
- ivy.exp(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the exponential function, having domain
[-infinity, +infinity]
and codomain[+0, +infinity]
, for each elementx_i
of the input arrayx
(e
raised to the power ofx_i
, wheree
is the base of the natural logarithm).Note
For complex floating-point operands,
exp(conj(x))
must equalconj(exp(x))
.Note
The exponential function is an entire function in the complex plane and has no branch cuts.
Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is1
.If
x_i
is-0
, the result is1
.If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is+0
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is either+0
or-0
andb
is+0
, the result is1 + 0j
.If
a
is a finite number andb
is+infinity
, the result isNaN + NaN j
.If
a
is a finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is+infinity
andb
is+0
, the result isinfinity + 0j
.If
a
is-infinity
andb
is a finite number, the result is+0 * cis(b)
.If
a
is+infinity
andb
is a nonzero finite number, the result is+infinity * cis(b)
.If
a
is-infinity
andb
is+infinity
, the result is0 + 0j
(signs of real and imaginary components are unspecified).If
a
is+infinity
andb
is+infinity
, the result isinfinity + NaN j
(sign of real component is unspecified).If
a
is-infinity
andb
isNaN
, the result is0 + 0j
(signs of real and imaginary components are unspecified).If
a
is+infinity
andb
isNaN
, the result isinfinity + NaN j
(sign of real component is unspecified).If
a
isNaN
andb
is+0
, the result isNaN + 0j
.If
a
isNaN
andb
is not equal to0
, the result isNaN + NaN j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
where
cis(v)
iscos(v) + sin(v)*1j
.- Parameters:
- Return type:
- Returns:
ret – an array containing the evaluated exponential function result for each element in
x
. The returned array must have a floating-point data type determined by type-promotion.This method conforms to the
This docstring is an extension of the
`docstring <https (//data-apis.org/array-api/latest/)
API_specification/generated/array_api.exp.html>`_
in the standard.
Both the description and the type hints above assumes an array input for simplicity,
but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.
Examples
With :class:Number:
>>> x = 3. >>> y = ivy.exp(x) >>> print(y) ivy.array(20.08553692)
With
ivy.Array
input:>>> x = ivy.array([1., 2., 3.]) >>> y = ivy.exp(x) >>> print(y) ivy.array([ 2.71828175, 7.38905621, 20.08553696])
With nested inputs in
ivy.Array
:>>> x = ivy.array([[-5.67], [ivy.nan], [0.567]]) >>> y = ivy.exp(x) >>> print(y) ivy.array([[0.00344786], [ nan], [1.76297021]])
With
ivy.NativeArray
input:>>> x = ivy.native_array([0., 4., 2.]) >>> y = ivy.exp(x) >>> print(y) ivy.array([ 1. , 54.59814835, 7.38905621])
With
ivy.Container
input:>>> x = ivy.Container(a=3.1, b=ivy.array([3.2, 1.])) >>> y = ivy.exp(x) >>> print(y) { a: ivy.array(22.197948), b: ivy.array([24.53253174, 2.71828175]) }
- ivy.exp2(x, /, *, out=None)[source]#
Calculate 2**p for all p in the input array.
- Parameters:
- Return type:
- Returns:
ret – Element-wise 2 to the power x. This is a scalar if x is a scalar.
Examples
>>> x = ivy.array([1, 2, 3]) >>> ivy.exp2(x) ivy.array([2., 4., 8.]) >>> x = [5, 6, 7] >>> ivy.exp2(x) ivy.array([32., 64., 128.])
- ivy.expm1(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to
exp(x)-1
, having domain[-infinity, +infinity]
and codomain[-1, +infinity]
, for each elementx_i
of the input arrayx
.Note
The purpose of this function is to calculate
exp(x)-1.0
more accurately whenx
is close to zero. Accordingly, conforming implementations should avoid implementing this function as simplyexp(x)-1.0
. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation.Note
For complex floating-point operands,
expm1(conj(x))
must equalconj(expm1(x))
.Note
The exponential function is an entire function in the complex plane and has no branch cuts.
Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is-1
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is either+0
or-0
andb
is+0
, the result is0 + 0j
.If
a
is a finite number andb
is+infinity
, the result isNaN + NaN j
.If
a
is a finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is+infinity
andb
is+0
, the result is+infinity + 0j
.If
a
is-infinity
andb
is a finite number, the result is+0 * cis(b) - 1.0
.If
a
is+infinity
andb
is a nonzero finite number, the result is+infinity * cis(b) - 1.0
.If
a
is-infinity
andb
is+infinity
, the result is-1 + 0j
(sign of imaginary component is unspecified).If
a
is+infinity
andb
is+infinity
, the result isinfinity + NaN j
(sign of real component is unspecified).If
a
is-infinity
andb
isNaN
, the result is-1 + 0j
(sign of imaginary component is unspecified).If
a
is+infinity
andb
isNaN
, the result isinfinity + NaN j
(sign of real component is unspecified).If
a
isNaN
andb
is+0
, the result isNaN + 0j
.If
a
isNaN
andb
is not equal to0
, the result isNaN + NaN j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
where
cis(v)
iscos(v) + sin(v)*1j
.- Parameters:
- Return type:
- Returns:
ret – an array containing the evaluated result for each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
inputs:>>> x = ivy.array([[0, 5, float('-0'), ivy.nan]]) >>> ivy.expm1(x) ivy.array([[ 0., 147., -0., nan]])
>>> x = ivy.array([ivy.inf, 1, float('-inf')]) >>> y = ivy.zeros(3) >>> ivy.expm1(x, out=y) ivy.array([ inf, 1.72, -1. ])
With
ivy.Container
inputs:>>> x = ivy.Container(a=ivy.array([-1, 0,]), ... b=ivy.array([10, 1])) >>> ivy.expm1(x) { a: ivy.array([-0.632, 0.]), b: ivy.array([2.20e+04, 1.72e+00]) }
- ivy.floor(x, /, *, out=None)[source]#
Round each element
x_i
of the input arrayx
to the greatest (i.e., closest to+infinity
) integer-valued number that is not greater thanx_i
.Special cases
If
x_i
is already integer-valued, the result isx_i
.
For floating-point operands,
If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is-infinity
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
isNaN
, the result isNaN
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the rounded result for each element in
x
. The returned array must have the same data type asx
.
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([2,3,4]) >>> y = ivy.floor(x) >>> print(y) ivy.array([2, 3, 4])
>>> x = ivy.array([1.5, -5.5, 0, -1, -0]) >>> y = ivy.zeros(5) >>> ivy.floor(x, out=y) >>> print(y) ivy.array([ 1., -6., 0., -1., 0.])
>>> x = ivy.array([[1.1, 2.2, 3.3], [-4.4, -5.5, -6.6]]) >>> ivy.floor(x, out=x) >>> print(x) ivy.array([[ 1., 2., 3.], [-5., -6., -7.]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 1.5, -2.4]), ... b=ivy.array([3.4, -4.2, -0, -1.2])) >>> y = ivy.floor(x) >>> print(y) { a: ivy.array([0., 1., -3.]), b: ivy.array([3., -5., 0., -2.]) }
- ivy.floor_divide(x1, x2, /, *, out=None)[source]#
Round 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.
Note
For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined.
Special cases
Note
Floor division was introduced in Python via PEP 238 with the goal to disambiguate “true division” (i.e., computing an approximation to the mathematical operation of division) from “floor division” (i.e., rounding the result of division toward negative infinity). The former was computed when one of the operands was a
float
, while the latter was computed when both operands wereint
s. Overloading the/
operator to support both behaviors led to subtle numerical bugs when integers are possible, but not expected.To resolve this ambiguity,
/
was designated for true division, and//
was designated for floor division. Semantically, floor division was defined as equivalent toa // b == floor(a/b)
; however, special floating-point cases were left ill-defined.Accordingly, floor division is not implemented consistently across array libraries for some of the special cases documented below. Namely, when one of the operands is
infinity
, libraries may diverge with some choosing to strictly followfloor(a/b)
and others choosing to pair//
with%
according to the relationb = a % b + b * (a // b)
. The special cases leading to divergent behavior are documented below.This specification prefers floor division to match
floor(divide(x1, x2))
in order to avoid surprising and unexpected results; however, array libraries may choose to more strictly follow Python behavior.For floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is either+infinity
or-infinity
andx2_i
is either+infinity
or-infinity
, the result isNaN
.If
x1_i
is either+0
or-0
andx2_i
is either+0
or-0
, the result isNaN
.If
x1_i
is+0
andx2_i
is greater than0
, 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-0
.If
x1_i
is-0
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
is-0
, the result is-infinity
.If
x1_i
is less than0
andx2_i
is+0
, the result is-infinity
.If
x1_i
is less than0
andx2_i
is-0
, the result is+infinity
.If
x1_i
is+infinity
andx2_i
is a positive (i.e., greater than0
) finite number, the result is+infinity
. (note: libraries may returnNaN
to match Python behavior.)If
x1_i
is+infinity
andx2_i
is a negative (i.e., less than0
) finite number, the result is-infinity
. (note: libraries may returnNaN
to match Python behavior.)If
x1_i
is-infinity
andx2_i
is a positive (i.e., greater than0
) finite number, the result is-infinity
. (note: libraries may returnNaN
to match Python behavior.)If
x1_i
is-infinity
andx2_i
is a negative (i.e., less than0
) finite number, the result is+infinity
. (note: libraries may returnNaN
to match Python behavior.)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
is-infinity
, the result is-0
. (note: libraries may return-1.0
to match Python behavior.)If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is+infinity
, the result is-0
. (note: libraries may return-1.0
to match Python behavior.)If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is-infinity
, 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 greatest (i.e., closest to +infinity) representable integer-value number that is not greater than the division result. If the magnitude is too large 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 (
Union
[float
,Array
,NativeArray
]) – first input array. Must have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
]) – second input array. Must be compatible with x1 (with Broadcasting). Must have a numeric data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a numeric data type.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
inputs:>>> x1 = ivy.array([13., 7., 8.]) >>> x2 = ivy.array([3., 2., 7.]) >>> y = ivy.floor_divide(x1, x2) >>> print(y) ivy.array([4., 3., 1.])
>>> x1 = ivy.array([13., 7., 8.]) >>> x2 = ivy.array([3., 2., 7.]) >>> y = ivy.zeros((2, 3)) >>> ivy.floor_divide(x1, x2, out=y) >>> print(y) ivy.array([4., 3., 1.])
>>> x1 = ivy.array([13., 7., 8.]) >>> x2 = ivy.array([3., 2., 7.]) >>> ivy.floor_divide(x1, x2, out=x1) >>> print(x1) ivy.array([4., 3., 1.])
With a mix of
ivy.Array
andivy.NativeArray
inputs:>>> x1 = ivy.array([3., 4., 5.]) >>> x2 = ivy.native_array([5., 2., 1.]) >>> y = ivy.floor_divide(x1, x2) >>> print(y) ivy.array([0., 2., 5.])
With
ivy.Container
inputs:>>> x1 = ivy.Container(a=ivy.array([4., 5., 6.]), b=ivy.array([7., 8., 9.])) >>> x2 = ivy.Container(a=ivy.array([5., 4., 2.5]), b=ivy.array([2.3, 3.7, 5])) >>> y = ivy.floor_divide(x1, x2) >>> print(y) { a: ivy.array([0., 1., 2.]), b: ivy.array([3., 2., 1.]) }
With mixed
ivy.Container
andivy.Array
inputs:>>> x1 = ivy.Container(a=ivy.array([4., 5., 6.]), b=ivy.array([7., 8., 9.])) >>> x2 = ivy.array([2., 2., 2.]) >>> y = ivy.floor_divide(x1, x2) >>> print(y) { a: ivy.array([2., 2., 3.]), b: ivy.array([3., 4., 4.]) }
- ivy.fmin(x1, x2, /, *, out=None)[source]#
Compute the element-wise minimums of two arrays. Differs from ivy.minimum in the case where one of the elements is NaN. ivy.minimum returns the NaN element while ivy.fmin returns the non-NaN element.
- Parameters:
- Return type:
Union
[Array
,NativeArray
]- Returns:
ret – Array with element-wise minimums.
Examples
>>> x1 = ivy.array([2, 3, 4]) >>> x2 = ivy.array([1, 5, 2]) >>> ivy.fmin(x1, x2) ivy.array([1, 3, 2])
>>> x1 = ivy.array([ivy.nan, 0, ivy.nan]) >>> x2 = ivy.array([0, ivy.nan, ivy.nan]) >>> ivy.fmin(x1, x2) ivy.array([ 0., 0., nan])
- ivy.fmod(x1, x2, /, *, out=None)[source]#
Compute the element-wise remainder of divisions of two arrays.
- Parameters:
- Return type:
Union
[Array
,NativeArray
]- Returns:
ret – Array with element-wise remainder of divisions.
Examples
>>> x1 = ivy.array([2, 3, 4]) >>> x2 = ivy.array([1, 5, 2]) >>> ivy.fmod(x1, x2) ivy.array([ 0, 3, 0])
>>> x1 = ivy.array([ivy.nan, 0, ivy.nan]) >>> x2 = ivy.array([0, ivy.nan, ivy.nan]) >>> ivy.fmod(x1, x2) ivy.array([ nan, nan, nan])
- ivy.gcd(x1, x2, /, *, out=None)[source]#
Return the greatest common divisor of |x1| and |x2|.
- Parameters:
- Return type:
- Returns:
Examples
>>> x1 = ivy.array([1, 2, 3]) >>> x2 = ivy.array([4, 5, 6]) >>> ivy.gcd(x1, x2) ivy.array([1., 1., 3.]) >>> x1 = ivy.array([1, 2, 3]) >>> ivy.gcd(x1, 10) ivy.array([1., 2., 1.])
- ivy.greater(x1, x2, /, *, out=None)[source]#
Compute 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:
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of bool.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.greater(ivy.array([1,2,3]),ivy.array([2,2,2])) >>> print(x) ivy.array([False, False, True])
>>> x = ivy.array([[[1.1], [3.2], [-6.3]]]) >>> y = ivy.array([[8.4], [2.5], [1.6]]) >>> ivy.greater(x, y, out=x) >>> print(x) ivy.array([[[0.], [1.], [0.]]])
With a mix of
ivy.Array
andivy.NativeArray
inputs:>>> x = ivy.array([1, 2, 3]) >>> y = ivy.native_array([4, 5, 0]) >>> z = ivy.greater(x, y) >>> print(z) ivy.array([False, False, True])
With a mix of
ivy.Array
andivy.Container
inputs:>>> x = ivy.array([[5.1, 2.3, -3.6]]) >>> y = ivy.Container(a=ivy.array([[4.], [5.], [6.]]), ... b=ivy.array([[5.], [6.], [7.]])) >>> z = ivy.greater(x, y) >>> print(z) { a: ivy.array([[True, False, False], [True, False, False], [False, False, False]]), b: ivy.array([[True, False, False], [False, False, False], [False, False, False]]) }
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([4, 5, 6]), ... b=ivy.array([2, 3, 4])) >>> y = ivy.Container(a=ivy.array([1, 2, 3]), ... b=ivy.array([5, 6, 7])) >>> z = ivy.greater(x, y) >>> print(z) { a: ivy.array([True, True, True]), b: ivy.array([False, False, False]) }
- ivy.greater_equal(x1, x2, /, *, out=None)[source]#
Compute 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 (
Union
[Array
,NativeArray
]) – first input array. May have any data type.x2 (
Union
[Array
,NativeArray
]) – second input array. Must be compatible with x1 (with Broadcasting). May have any data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of bool.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.greater_equal(ivy.array([1,2,3]),ivy.array([2,2,2])) >>> print(x) ivy.array([False, True, True])
>>> x = ivy.array([[10.1, 2.3, -3.6]]) >>> y = ivy.array([[4.8], [5.2], [6.1]]) >>> shape = (3,3) >>> fill_value = False >>> z = ivy.full(shape, fill_value) >>> ivy.greater_equal(x, y, out=z) >>> print(z) ivy.array([[ True, False, False], [ True, False, False], [ True, False, False]])
>>> x = ivy.array([[[1.1], [3.2], [-6.3]]]) >>> y = ivy.array([[8.4], [2.5], [1.6]]) >>> ivy.greater_equal(x, y, out=x) >>> print(x) ivy.array([[[0.], [1.], [0.]]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([4, 5, 6]),b=ivy.array([2, 3, 4])) >>> y = ivy.Container(a=ivy.array([1, 2, 3]),b=ivy.array([5, 6, 7])) >>> z = ivy.greater_equal(x, y) >>> print(z) { a:ivy.array([True,True,True]), b:ivy.array([False,False,False]) }
- ivy.imag(val, /, *, out=None)[source]#
Return the imaginary part of a complex number for each element
x_i
of the input arrayval
.- Parameters:
- Return type:
- Returns:
ret – Returns an array with the imaginary part of complex numbers. The returned arrau must have a floating-point data type determined by the precision of
val
(e.g., ifval
iscomplex64
, the returned array must befloat32
).This method conforms to the
This docstring is an extension of the
`docstring <https (//data-apis.org/array-api/latest/)
API_specification/generated/array_api.imag.html>`_
in the standard.
Both the description and the type hints above assumes an array input for simplicity,
but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.
Examples
>>> b = ivy.array(np.array([1+2j, 3+4j, 5+6j])) >>> b ivy.array([1.+2.j, 3.+4.j, 5.+6.j]) >>> ivy.imag(b) ivy.array([2., 4., 6.])
- ivy.isfinite(x, /, *, out=None)[source]#
Test each element
x_i
of the input arrayx
to determine if finite (i.e., notNaN
and not equal to positive or negative infinity).- Parameters:
- Return type:
- Returns:
ret – 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
.
Special Cases
For real-valued floating-point operands,
If
x_i
is either+infinity
or-infinity
, the result isFalse
.if
x_i
isNaN
, the result isFalse
.if
x_i
is a finite number, the result isTrue
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
isNaN
orb
isNaN
, the result isFalse
.
- _ If
a
is either+infinity
or-infinity
andb
is any value, the result is
False
.
If
a
is any value andb
is either+infinity
or-infinity
, the result isFalse
.If
a
is a finite number andb
is a finite number, the result isTrue
.
This method conforms to the `Array API Standard<https://data-apis.org/array-api/latest/>`_. This docstring is an extension of the docstring <https://data-apis.org/array-api/latest/ API_specification/generated/array_api.isfinite.html> _ in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([0, ivy.nan, -ivy.inf, float('inf')]) >>> y = ivy.isfinite(x) >>> print(y) ivy.array([ True, False, False, False])
>>> x = ivy.array([0, ivy.nan, -ivy.inf]) >>> y = ivy.zeros(3) >>> ivy.isfinite(x, out=y) >>> print(y) ivy.array([1., 0., 0.])
>>> x = ivy.array([[9, float('-0')], [ivy.nan, ivy.inf]]) >>> ivy.isfinite(x, out=x) >>> print(x) ivy.array([[1., 1.], [0., 0.]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 999999999999]), ... b=ivy.array([float('-0'), ivy.nan])) >>> y = ivy.isfinite(x) >>> print(y) { a: ivy.array([True, True]), b: ivy.array([True, False]) }
- ivy.isinf(x, /, *, detect_positive=True, detect_negative=True, out=None)[source]#
Test each element x_i of the input array x to determine if equal to positive or negative infinity.
- Parameters:
x (
Union
[Array
,NativeArray
]) – input array. Should have a numeric data type.detect_positive (
bool
, default:True
) – ifTrue
, positive infinity is detected.detect_negative (
bool
, default:True
) – ifTrue
, negative infinity is detected.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing test results. An element out_i is True if x_i is either positive or negative infinity and False otherwise. The returned array must have a data type of bool.
Special Cases
For real-valued floating-point operands,
If x_i is either +infinity or -infinity, the result is
True
.In the remaining cases, the result is
False
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is either+infinity
or-infinity
andb
is any value (includingNaN
), the result isTrue
.If
a
is either a finite number orNaN
andb
is either+infinity
or-infinity
, the result isTrue
.In the remaining cases, the result is
False
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
inputs:>>> x = ivy.array([1, 2, 3]) >>> z = ivy.isinf(x) >>> print(z) ivy.array([False, False, False])
>>> x = ivy.array([[1.1, 2.3, -3.6]]) >>> z = ivy.isinf(x) >>> print(z) ivy.array([[False, False, False]])
>>> x = ivy.array([[[1.1], [float('inf')], [-6.3]]]) >>> z = ivy.isinf(x) >>> print(z) ivy.array([[[False], [True], [False]]])
>>> x = ivy.array([[-float('inf'), float('inf'), 0.0]]) >>> z = ivy.isinf(x) >>> print(z) ivy.array([[ True, True, False]])
>>> x = ivy.zeros((3, 3)) >>> z = ivy.isinf(x) >>> print(z) ivy.array([[False, False, False], [False, False, False], [False, False, False]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([-1, -float('inf'), 1.23]), ... b=ivy.array([float('inf'), 3.3, -4.2])) >>> z = ivy.isinf(x) >>> print(z) { a: ivy.array([False, True, False]), b: ivy.array([True, False, False]) }
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([-1, -float('inf'), 1.23]), ... b=ivy.array([float('inf'), 3.3, -4.2])) >>> x.isinf() { a: ivy.array([False, True, False]), b: ivy.array([True, False, False]) }
- ivy.isnan(x, /, *, out=None)[source]#
Test each element
x_i
of the input arrayx
to determine whether the element isNaN
.- Parameters:
- Return type:
- Returns:
ret – an array containing test results. An element
out_i
isTrue
ifx_i
isNaN
andFalse
otherwise. The returned array should have a data type ofbool
.
Special Cases
For real-valued floating-point operands,
If
x_i
isNaN
, the result isTrue
.In the remaining cases, the result is
False
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
orb
isNaN
, the result isTrue
.In the remaining cases, the result is
False
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
inputs:>>> x = ivy.array([1, 2, 3]) >>> z = ivy.isnan(x) >>> print(z) ivy.array([False, False, False])
>>> x = ivy.array([[1.1, 2.3, -3.6]]) >>> z = ivy.isnan(x) >>> print(z) ivy.array([[False, False, False]])
>>> x = ivy.array([[[1.1], [float('inf')], [-6.3]]]) >>> z = ivy.isnan(x) >>> print(z) ivy.array([[[False], [False], [False]]])
>>> x = ivy.array([[-float('nan'), float('nan'), 0.0]]) >>> z = ivy.isnan(x) >>> print(z) ivy.array([[ True, True, False]])
>>> x = ivy.array([[-float('nan'), float('inf'), float('nan'), 0.0]]) >>> z = ivy.isnan(x) >>> print(z) ivy.array([[ True, False, True, False]])
>>> x = ivy.zeros((3, 3)) >>> z = ivy.isnan(x) >>> print(z) ivy.array([[False, False, False], [False, False, False], [False, False, False]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([-1, -float('nan'), 1.23]), ... b=ivy.array([float('nan'), 3.3, -4.2])) >>> z = ivy.isnan(x) >>> print(z) { a: ivy.array([False, True, False]), b: ivy.array([True, False, False]) }
- ivy.isreal(x, /, *, out=None)[source]#
Test each element
x_i
of the input arrayx
to determine whether the element is real number. Returns a bool array, where True if input element is real. If element has complex type with zero complex part, the return value for that element is True.- Parameters:
- Return type:
- Returns:
ret – an array containing test results. An element
out_i
isTrue
ifx_i
is real number andFalse
otherwise. The returned array should have a data type ofbool
.The descriptions above assume an array input for simplicity, but
the method also accepts
ivy.Container
instances in place ofivy.Array
orivy.NativeArray
instances, as shown in the type hintsand also the examples below.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([[[1.1], [float('inf')], [-6.3]]]) >>> z = ivy.isreal(x) >>> print(z) ivy.array([[[True], [True], [True]]])
>>> x = ivy.array([1-0j, 3j, 7+5j]) >>> z = ivy.isreal(x) >>> print(z) ivy.array([ True, False, False])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([-6.7-7j, -np.inf, 1.23]), b=ivy.array([5j, 5-6j, 3])) >>> z = ivy.isreal(x) >>> print(z) { a: ivy.array([False, True, True]), b: ivy.array([False, False, True]) }
- ivy.lcm(x1, x2, /, *, out=None)[source]#
Compute the element-wise least common multiple (LCM) of x1 and x2.
- Parameters:
- Return type:
- Returns:
ret – an array that includes the element-wise least common multiples of x1 and x2
Examples
With
ivy.Array
input:>>> x1=ivy.array([2, 3, 4]) >>> x2=ivy.array([5, 7, 15]) >>> x1.lcm(x1, x2) ivy.array([10, 21, 60])
- ivy.less(x1, x2, /, *, out=None)[source]#
Compute the truth value of
x1_i < x2_i
for each elementx1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.- Parameters:
x1 (
Union
[float
,Array
,NativeArray
]) – first input array. Should have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see ref:broadcasting). Should have a numeric data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of
bool
.
Examples
With
ivy.Array
input:>>> x = ivy.less(ivy.array([1,2,3]),ivy.array([2,2,2])) >>> print(x) ivy.array([ True, False, False])
>>> x = ivy.array([[[1.1], [3.2], [-6.3]]]) >>> y = ivy.array([[8.4], [2.5], [1.6]]) >>> ivy.less(x, y, out=x) >>> print(x) ivy.array([[[1.], [0.], [1.]]])
With a mix of
ivy.Array
andivy.NativeArray
inputs:>>> x = ivy.array([1, 2, 3]) >>> y = ivy.native_array([4, 5, 0]) >>> z = ivy.less(x, y) >>> print(z) ivy.array([ True, True, False])
With a mix of
ivy.Array
andivy.Container
inputs:>>> x = ivy.array([[5.1, 2.3, -3.6]]) >>> y = ivy.Container(a=ivy.array([[4.], [5.], [6.]]), ... b=ivy.array([[5.], [6.], [7.]])) >>> z = ivy.less(x, y) >>> print(z) { a: ivy.array([[False, True, True], [False, True, True], [True, True, True]]), b: ivy.array([[False, True, True], [True, True, True], [True, True, True]]) }
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([4, 5, 6]),b=ivy.array([2, 3, 4])) >>> y = ivy.Container(a=ivy.array([1, 2, 3]),b=ivy.array([5, 6, 7])) >>> z = ivy.less(x, y) >>> print(z) { a: ivy.array([False, False, False]), b: ivy.array([True, True, True]) }
- ivy.less_equal(x1, x2, /, *, out=None)[source]#
Compute 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 (
Union
[Array
,NativeArray
]) – first input array. May have any data type.x2 (
Union
[Array
,NativeArray
]) – second input array. Must be compatible with x1 (with Broadcasting). May have any data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
- ret
an array containing the element-wise results. The returned array must have a data type of bool.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.less_equal(ivy.array([1,2,3]),ivy.array([2,2,2])) >>> print(x) ivy.array([True, True, False])
>>> x = ivy.array([[10.1, 2.3, -3.6]]) >>> y = ivy.array([[4.8], [5.2], [6.1]]) >>> shape = (3,3) >>> fill_value = False >>> z = ivy.full(shape, fill_value) >>> ivy.less_equal(x, y, out=z) >>> print(z) ivy.array([[False, True, True], [False, True, True], [False, True, True]])
>>> x = ivy.array([[[1.1], [3.2], [-6.3]]]) >>> y = ivy.array([[8.4], [2.5], [1.6]]) >>> ivy.less_equal(x, y, out=x) >>> print(x) ivy.array([[[1.], [0.], [1.]]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([4, 5, 6]),b=ivy.array([2, 3, 4])) >>> y = ivy.Container(a=ivy.array([1, 2, 3]),b=ivy.array([5, 6, 7])) >>> z = ivy.less_equal(x, y) >>> print(z) { a: ivy.array([False, False, False]), b: ivy.array([True, True, True]) }
- ivy.log(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the natural (base
e
) logarithm, having domain[0, +infinity]
and codomain[-infinity, +infinity]
, for each elementx_i
of the input arrayx
.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is less than0
, the result isNaN
.If
x_i
is either+0
or-0
, the result is-infinity
.If
x_i
is1
, the result is+0
.If
x_i
is+infinity
, the result is+infinity
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is-0
andb
is+0
, the result is-infinity + πj
.If
a
is+0
andb
is+0
, the result is-infinity + 0j
.If
a
is a finite number andb
is+infinity
, the result is+infinity + πj/2
.If
a
is a finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is-infinity
andb
is a positive (i.e., greater than0
) finite number, the result is+infinity + πj
.If
a
is+infinity
andb
is a positive (i.e., greater than0
) finite number, the result is+infinity + 0j
.If
a
is-infinity
andb
is+infinity
, the result is+infinity + 3πj/4
.If
a
is+infinity
andb
is+infinity
, the result is+infinity + πj/4
.If
a
is either+infinity
or-infinity
andb
isNaN
, the result is+infinity + NaN j
.If
a
isNaN
andb
is a finite number, the result isNaN + NaN j
.If
a
isNaN
andb
is+infinity
, the result is+infinity + NaN j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the evaluated natural logarithm for each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
Examples
With
ivy.Array
input:>>> x = ivy.array([4.0, 1, -0.0, -5.0]) >>> y = ivy.log(x) >>> print(y) ivy.array([1.39, 0., -inf, nan])
>>> x = ivy.array([[float('nan'), 1, 5.0, float('+inf')], ... [+0, -1.0, -5, float('-inf')]]) >>> y = ivy.log(x) >>> print(y) ivy.array([[nan, 0., 1.61, inf], [-inf, nan, nan, nan]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0.0, float('nan')]), ... b=ivy.array([-0., -3.9, float('+inf')]), ... c=ivy.array([7.9, 1.1, 1.])) >>> y = ivy.log(x) >>> print(y) { a: ivy.array([-inf, nan]), b: ivy.array([-inf, nan, inf]), c: ivy.array([2.07, 0.0953, 0.]) }
- ivy.log10(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the base
10
logarithm, having domain[0, +infinity]
and codomain[-infinity, +infinity]
, for each elementx_i
of the input arrayx
.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is less than0
, the result isNaN
.If
x_i
is either+0
or-0
, the result is-infinity
.If
x_i
is1
, the result is+0
.If
x_i
is+infinity
, the result is+infinity
.
For complex floating-point operands, special cases must be handled as if the operation is implemented using the standard change of base formula
\[\log_{10} x = \frac{\log_{e} x}{\log_{e} 10}\]where \(\log_{e}\) is the natural logarithm.
- Parameters:
- Return type:
- Returns:
ret – an array containing the evaluated base
10
logarithm for each element inx
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([4.0, 1, -0.0, -5.0]) >>> y = ivy.log10(x) >>> print(y) ivy.array([0.602, 0., -inf, nan])
>>> x = ivy.array([[float('nan'), 1, 5.0, float('+inf')], ... [+0, -1.0, -5, float('-inf')]]) >>> y = ivy.log10(x) >>> print(y) ivy.array([[nan, 0., 0.699, inf], [-inf, nan, nan, nan]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0.0, float('nan')]), ... b=ivy.array([-0., -3.9, float('+inf')]), ... c=ivy.array([7.9, 1.1, 1.])) >>> y = ivy.log10(x) >>> print(y) { a: ivy.array([-inf, nan]), b: ivy.array([-inf, nan, inf]), c: ivy.array([0.898, 0.0414, 0.]) }
- ivy.log1p(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to log(1+x), where log refers to the natural (base e) logarithm.
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 simplylog(1+x)
. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is less than-1
, the result isNaN
.If
x_i
is-1
, the result is-infinity
.If
x_i
is-0
, the result is-0
.If
x_i
is+0
, the result is+0
.If
x_i
is+infinity
, the result is+infinity
.
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is-1
andb
is+0
, the result is-infinity + 0j
.If
a
is a finite number andb
is+infinity
, the result is+infinity + πj/2
.If
a
is a finite number andb
isNaN
, the result isNaN + NaN j
.If
a
is-infinity
andb
is a positive (i.e., greater than0
) finite number, the result is+infinity + πj
.If
a
is+infinity
andb
is a positive (i.e., greater than0
) finite number, the result is+infinity + 0j
.If
a
is-infinity
andb
is+infinity
, the result is+infinity + 3πj/4
.If
a
is+infinity
andb
is+infinity
, the result is+infinity + πj/4
.If
a
is either+infinity
or-infinity
andb
isNaN
, the result is+infinity + NaN j
.If
a
isNaN
andb
is a finite number, the result isNaN + NaN j
.If
a
isNaN
andb
is+infinity
, the result is+infinity + NaN j
.If
a
isNaN
andb
isNaN
, the result isNaN + NaN j
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the evaluated Natural logarithm of 1 + x for each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([1., 2., 3.]) >>> y = x.log1p() >>> print(y) ivy.array([0.693, 1.1 , 1.39 ])
>>> x = ivy.array([0. , 1.]) >>> y = ivy.zeros(2) >>> ivy.log1p(x , out = y) >>> print(y) ivy.array([0. , 0.693])
>>> x = ivy.array([[1.1, 2.2, 3.3],[4.4, 5.5, 6.6]]) >>> ivy.log1p(x, out = x) >>> print(x) ivy.array([[0.742, 1.16 , 1.46 ],[1.69 , 1.87 , 2.03 ]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 1., 2.]), b=ivy.array([3., 4., 5.1])) >>> y = ivy.log1p(x) >>> print(y) { a: ivy.array([0., 0.693, 1.1]), b: ivy.array([1.39, 1.61, 1.81]) }
- ivy.log2(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the base
2
logarithm, having domain[0, +infinity]
and codomain[-infinity, +infinity]
, for each elementx_i
of the input arrayx
.Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is less than0
, the result isNaN
.If
x_i
is either+0
or-0
, the result is-infinity
.If
x_i
is1
, the result is+0
.If
x_i
is+infinity
, the result is+infinity
.
For complex floating-point operands, special cases must be handled as if the operation is implemented using the standard change of base formula
\[\log_{2} x = \frac{\log_{e} x}{\log_{e} 2}\]where \(\log_{e}\) is the natural logarithm.
- Parameters:
- Return type:
- Returns:
ret – an array containing the evaluated base
2
logarithm for each element inx
. The returned array must have a floating-point data type determined by type-promotion.
This method conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input: >>> x = ivy.array([5.0, 1, -0.0, -6.0]) >>> y = ivy.log2(x) >>> print(y) ivy.array([2.32, 0., -inf, nan]) >>> x = ivy.array([[float(‘nan’), 1, 6.0, float(‘+inf’)], … [+0, -2.0, -7, float(‘-inf’)]]) >>> y = ivy.empty_like(x) >>> ivy.log2(x, out=y) >>> print(y) ivy.array([[nan, 0., 2.58, inf],[-inf, nan, nan, nan]]) >>> x = ivy.array([[float(‘nan’), 1, 7.0, float(‘+inf’)], … [+0, -3.0, -8, float(‘-inf’)]]) >>> ivy.log2(x, out=x) >>> print(x) ivy.array([[nan, 0., 2.81, inf],[-inf, nan, nan, nan]])With
ivy.Container
input: >>> x = ivy.Container(a=ivy.array([0.0, float(‘nan’)]), … b=ivy.array([-0., -4.9, float(‘+inf’)]), … c=ivy.array([8.9, 2.1, 1.])) >>> y = ivy.log2(x) >>> print(y) {a: ivy.array([-inf, nan]), b: ivy.array([-inf, nan, inf]), c: ivy.array([3.15, 1.07, 0.])
}
- ivy.logaddexp(x1, x2, /, *, out=None)[source]#
Calculate the logarithm of the sum of exponentiations
log(exp(x1) + exp(x2))
for each elementx1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.Special cases
For floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is+infinity
andx2_i
is notNaN
, the result is+infinity
.If
x1_i
is notNaN
andx2_i
is+infinity
, the result is+infinity
.
- Parameters:
x1 (
Union
[Array
,NativeArray
]) – first input array. Should have a floating-point data type.x2 (
Union
[Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have a floating-point data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([2., 5., 15.]) >>> y = ivy.array([3., 2., 4.]) >>> z = ivy.logaddexp(x, y) >>> print(z) ivy.array([ 3.31, 5.05, 15. ])
>>> x = ivy.array([[[1.1], [3.2], [-6.3]]]) >>> y = ivy.array([[8.4], [2.5], [1.6]]) >>> ivy.logaddexp(x, y, out=x) >>> print(x) ivy.array([[[8.4], [3.6], [1.6]]])
With one
ivy.Container
input:>>> x = ivy.array([[5.1, 2.3, -3.6]]) >>> y = ivy.Container(a=ivy.array([[4.], [5.], [6.]]), ... b=ivy.array([[5.], [6.], [7.]])) >>> z = ivy.logaddexp(x, y) >>> print(z) { a: ivy.array([[5.39, 4.17, 4.], [5.74, 5.07, 5.], [6.34, 6.02, 6.]]), b: ivy.array([[5.74, 5.07, 5.], [6.34, 6.02, 6.], [7.14, 7.01, 7.]]) }
With multiple
ivy.Container
inputs:>>> x = ivy.Container(a=ivy.array([4., 5., 6.]),b=ivy.array([2., 3., 4.])) >>> y = ivy.Container(a=ivy.array([1., 2., 3.]),b=ivy.array([5., 6., 7.])) >>> z = ivy.logaddexp(y,x) >>> print(z) { a: ivy.array([4.05, 5.05, 6.05]), b: ivy.array([5.05, 6.05, 7.05]) }
- ivy.logaddexp2(x1, x2, /, *, out=None)[source]#
Calculate log2(2**x1 + 2**x2).
- Parameters:
- Return type:
- Returns:
ret – Element-wise logaddexp2 of x1 and x2.
Examples
>>> x1 = ivy.array([1, 2, 3]) >>> x2 = ivy.array([4, 5, 6]) >>> ivy.logaddexp2(x1, x2) ivy.array([4.169925, 5.169925, 6.169925])
- ivy.logical_and(x1, x2, /, *, out=None)[source]#
Compute the logical AND for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.
- Parameters:
x1 (
Union
[Array
,NativeArray
]) – first input array. Should have a boolean data type.x2 (
Union
[Array
,NativeArray
]) – second input array. Must be compatible with x1. Should have a boolean data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of bool.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([True, True, False]) >>> y = ivy.array([True, False, True]) >>> print(ivy.logical_and(x, y)) ivy.array([True,False,False])
>>> ivy.logical_and(x, y, out=y) >>> print(y) ivy.array([True,False,False])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([False, True, True]), ... b=ivy.array([True, False, False])) >>> y = ivy.Container(a=ivy.array([True, True, False]), ... b=ivy.array([False, False, True])) >>> print(ivy.logical_and(y, x)) { a: ivy.array([False, True, False]), b: ivy.array([False, False, False]) }
>>> ivy.logical_and(y, x, out=y) >>> print(y) { a: ivy.array([False, True, False]), b: ivy.array([False, False, False]) }
>>> x = ivy.Container(a=ivy.array([False, True, True]), ... b=ivy.array([True, False, False])) >>> y = ivy.array([True, False, True]) >>> print(ivy.logical_and(y, x)) { a: ivy.array([False, False, True]), b: ivy.array([True, False, False]) }
>>> x = ivy.Container(a=ivy.array([False, True, True]), ... b=ivy.array([True, False, False])) >>> y = ivy.array([True, False, True]) >>> ivy.logical_and(y, x, out=x) >>> print(x) { a: ivy.array([False, False, True]), b: ivy.array([True, False, False]) }
- ivy.logical_not(x, /, *, out=None)[source]#
Compute the logical NOT for each element
x_i
of the input arrayx
.Note
While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of
False
, while non-zeros must be considered the equivalent ofTrue
.Special cases
For this particular case,
If
x_i
isNaN
, the result isFalse
.If
x_i
is-0
, the result isTrue
.If
x_i
is-infinity
, the result isFalse
.If
x_i
is+infinity
, the result isFalse
.
- Parameters:
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of
bool
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x=ivy.array([1,0,1,1,0]) >>> y=ivy.logical_not(x) >>> print(y) ivy.array([False, True, False, False, True])
>>> x=ivy.array([2,0,3,5]) >>> y=ivy.logical_not(x) >>> print(y) ivy.array([False, True, False, False])
>>> x=ivy.native_array([1,0,6,5]) >>> y=ivy.logical_not(x) >>> print(y) ivy.array([False, True, False, False])
With
ivy.Container
input:>>> x=ivy.Container(a=ivy.array([1,0,1,1]), b=ivy.array([1,0,8,9])) >>> y=ivy.logical_not(x) >>> print(y) { a: ivy.array([False, True, False, False]), b: ivy.array([False, True, False, False]) }
>>> x=ivy.Container(a=ivy.array([1,0,1,0]), b=ivy.native_array([5,2,0,3])) >>> y=ivy.logical_not(x) >>> print(y) { a: ivy.array([False, True, False, True]), b: ivy.array([False, False, True, False]) }
- ivy.logical_or(x1, x2, /, *, out=None)[source]#
Compute the logical OR for each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.Note
While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of
False
, while non-zeros must be considered the equivalent ofTrue
.- Parameters:
x1 (
Union
[Array
,NativeArray
]) – first input array. Should have a boolean data type.x2 (
Union
[Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have a boolean data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of
bool
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([True, False, True]) >>> y = ivy.array([True, True, False]) >>> print(ivy.logical_or(x, y)) ivy.array([ True, True, True])
>>> x = ivy.array([[False, False, True], [True, False, True]]) >>> y = ivy.array([[False, True, False], [True, True, False]]) >>> z = ivy.zeros_like(x) >>> ivy.logical_or(x, y, out=z) >>> print(z) ivy.array([[False, True, True], [ True, True, True]])
>>> x = ivy.array([False, 3, 0]) >>> y = ivy.array([2, True, False]) >>> ivy.logical_or(x, y, out=x) >>> print(x) ivy.array([1, 1, 0])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([False, False, True]), ... b=ivy.array([True, False, True])) >>> y = ivy.Container(a=ivy.array([False, True, False]), ... b=ivy.array([True, True, False])) >>> z = ivy.logical_or(x, y) >>> print(z) { a: ivy.array([False, True, True]), b: ivy.array([True, True, True]) }
- ivy.logical_xor(x1, x2, /, *, out=None)[source]#
Compute the bitwise XOR of the underlying binary representation of each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.- Parameters:
x1 (
Union
[Array
,NativeArray
]) – first input array. Should have an integer or boolean data type.x2 (
Union
[Array
,NativeArray
]) – second input array. Must be compatible withx1
(see broadcasting). Should have an integer or boolean data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([1,0,1,1,0]) >>> y = ivy.array([1,0,1,1,0]) >>> z = ivy.logical_xor(x,y) >>> print(z) ivy.array([False, False, False, False, False])
>>> x = ivy.array([[[1], [2], [3], [4]]]) >>> y = ivy.array([[[4], [5], [6], [7]]]) >>> z = ivy.logical_xor(x,y) >>> print(z) ivy.array([[[False], [False], [False], [False]]])
>>> x = ivy.array([[[1], [2], [3], [4]]]) >>> y = ivy.array([4, 5, 6, 7]) >>> z = ivy.logical_xor(x,y) >>> print(z) ivy.array([[[False, False, False, False], [False, False, False, False], [False, False, False, False], [False, False, False, False]]])
With
ivy.Container
inputs:>>> x = ivy.Container(a=ivy.array([1,0,0,1,0]), b=ivy.array([1,0,1,0,0])) >>> y = ivy.Container(a=ivy.array([0,0,1,1,0]), b=ivy.array([1,0,1,1,0])) >>> z = ivy.logical_xor(x,y) >>> print(z) { a: ivy.array([True, False, True, False, False]), b: ivy.array([False, False, False, True, False]) }
With a mix of
ivy.Array
andivy.Container
inputs:>>> x = ivy.Container(a=ivy.array([1,0,0,1,0]), b=ivy.array([1,0,1,0,0])) >>> y = ivy.array([0,0,1,1,0]) >>> z = ivy.logical_xor(x,y) >>> print(z) { a: ivy.array([True, False, True, False, False]), b: ivy.array([True, False, False, True, False]) }
- ivy.maximum(x1, x2, /, *, use_where=True, out=None)[source]#
Return the max of x1 and x2 (i.e. x1 > x2 ? x1 : x2) element-wise.
- Parameters:
x1 (
Union
[Array
,NativeArray
,Number
]) – Input array containing elements to maximum threshold.x2 (
Union
[Array
,NativeArray
,Number
]) – Tensor containing maximum values, must be broadcastable to x1.use_where (
bool
, default:True
) – Whether to usewhere()
to calculate the maximum. IfFalse
, the maximum is calculated using the(x + y + |x - y|)/2
formula. Default isTrue
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – An array with the elements of x1, but clipped to not be lower than the x2 values.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([7, 9, 5]) >>> y = ivy.array([9, 3, 2]) >>> z = ivy.maximum(x, y) >>> print(z) ivy.array([9, 9, 5])
>>> x = ivy.array([1, 5, 9, 8, 3, 7]) >>> y = ivy.array([[9], [3], [2]]) >>> z = ivy.zeros((3, 6), dtype=ivy.int32) >>> ivy.maximum(x, y, out=z) >>> print(z) ivy.array([[9, 9, 9, 9, 9, 9], [3, 5, 9, 8, 3, 7], [2, 5, 9, 8, 3, 7]])
>>> x = ivy.array([[7, 3]]) >>> y = ivy.array([0, 7]) >>> ivy.maximum(x, y, out=x) >>> print(x) ivy.array([[7, 7]])
With one
ivy.Container
input:>>> x = ivy.array([[1, 3], [2, 4], [3, 7]]) >>> y = ivy.Container(a=ivy.array([1, 0,]), ... b=ivy.array([-5, 9])) >>> z = ivy.maximum(x, y) >>> print(z) { a: ivy.array([[1, 3], [2, 4], [3, 7]]), b: ivy.array([[1, 9], [2, 9], [3, 9]]) }
With multiple
ivy.Container
inputs:>>> x = ivy.Container(a=ivy.array([1, 3, 1]),b=ivy.array([2, 8, 5])) >>> y = ivy.Container(a=ivy.array([1, 5, 6]),b=ivy.array([5, 9, 7])) >>> z = ivy.maximum(x, y) >>> print(z) { a: ivy.array([1, 5, 6]), b: ivy.array([5, 9, 7]) }
- ivy.minimum(x1, x2, /, *, use_where=True, out=None)[source]#
Return the min of x1 and x2 (i.e. x1 < x2 ? x1 : x2) element-wise.
- Parameters:
x1 (
Union
[Array
,NativeArray
]) – Input array containing elements to minimum threshold.x2 (
Union
[Array
,NativeArray
]) – Tensor containing minimum values, must be broadcastable to x1.use_where (
bool
, default:True
) – Whether to usewhere()
to calculate the minimum. IfFalse
, the minimum is calculated using the(x + y - |x - y|)/2
formula. Default isTrue
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – An array with the elements of x1, but clipped to not exceed the x2 values.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([7, 9, 5]) >>> y = ivy.array([9, 3, 2]) >>> z = ivy.minimum(x, y) >>> print(z) ivy.array([7, 3, 2])
>>> x = ivy.array([1, 5, 9, 8, 3, 7]) >>> y = ivy.array([[9], [3], [2]]) >>> z = ivy.zeros((3, 6), dtype=ivy.int32) >>> ivy.minimum(x, y, out=z) >>> print(z) ivy.array([[1, 5, 9, 8, 3, 7], [1, 3, 3, 3, 3, 3], [1, 2, 2, 2, 2, 2]])
>>> x = ivy.array([[7, 3]]) >>> y = ivy.array([0, 7]) >>> ivy.minimum(x, y, out=x) >>> print(x) ivy.array([[0, 3]])
With one
ivy.Container
input:>>> x = ivy.array([[1, 3], [2, 4], [3, 7]]) >>> y = ivy.Container(a=ivy.array([1, 0,]),b=ivy.array([-5, 9])) >>> z = ivy.minimum(x, y) >>> print(z) { a: ivy.array([[1, 0], [1, 0], [1, 0]]), b: ivy.array([[-5, 3], [-5, 4], [-5, 7]]) }
With multiple
ivy.Container
inputs:>>> x = ivy.Container(a=ivy.array([1, 3, 1]), ... b=ivy.array([2, 8, 5])) >>> y = ivy.Container(a=ivy.array([1, 5, 6]), ... b=ivy.array([5, 9, 7])) >>> z = ivy.minimum(x, y) >>> print(z) { a: ivy.array([1, 3, 1]), b: ivy.array([2, 8, 5]) }
- ivy.multiply(x1, x2, /, *, out=None)[source]#
Calculate the product for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.
Note
Floating-point multiplication is not always associative due to finite precision.
Special Cases
For real-valued floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is either+infinity
or-infinity
andx2_i
is either+0
or-0
, the result isNaN
.If
x1_i
is either+0
or-0
andx2_i
is either+infinity
or-infinity
, 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 implementation-defined.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 implementation-defined.If
x1_i
is either+infinity
or-infinity
andx2_i
is either+infinity
or-infinity
, the result is a signed infinity with the mathematical sign determined by the rule already stated above.If
x1_i
is either+infinity
or-infinity
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
or-infinity
, 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 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an infinity of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign.
For complex floating-point operands, multiplication is defined according to the following table. For real components
a
andc
and imaginary componentsb
andd
,c
dj
c + dj
a
a * c
(a*d)j
(a*c) + (a*d)j
bj
(b*c)j
-(b*d)
-(b*d) + (b*c)j
a + bj
(a*c) + (b*c)j
-(b*d) + (a*d)j
special rules
In general, for complex floating-point operands, real-valued floating-point special cases must independently apply to the real and imaginary component operations involving real numbers as described in the above table.
When
a
,b
,c
, ord
are all finite numbers (i.e., a value other thanNaN
,+infinity
, or-infinity
), multiplication of complex floating-point operands should be computed as if calculated according to the textbook formula for complex number multiplication\[(a + bj) \cdot (c + dj) = (ac - bd) + (bc + ad)j\]When at least one of
a
,b
,c
, ord
isNaN
,+infinity
, or-infinity
,If
a
,b
,c
, andd
are allNaN
, the result isNaN + NaN j
.In the remaining cases, the result is implementation dependent.
Note
For complex floating-point operands, the results of special cases may be implementation dependent depending on how an implementation chooses to model complex numbers and complex infinity (e.g., complex plane versus Riemann sphere). For those implementations following C99 and its one-infinity model, when at least one component is infinite, even if the other component is
NaN
, the complex value is infinite, and the usual arithmetic rules do not apply to complex-complex multiplication. In the interest of performance, other implementations may want to avoid the complex branching logic necessary to implement the one-infinity model and choose to implement all complex-complex multiplication according to the textbook formula. Accordingly, special case behavior is unlikely to be consistent across implementations.- Parameters:
x1 (
Union
[float
,Array
,NativeArray
]) – first input array. Should have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
]) – second input array. Must be compatible withx1
(see :ref’broadcasting). Should have a numeric data typeout (
Optional
[Array
], default:None
) – optional output array, for writing the array result to. It must have a shape that the inputs broadcast to.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.- Return type:
- Returns:
ret – an array containing the element-wise products. The returned array must have a data type determined by Type Promotion Rules.
Examples
With
ivy.Array
inputs:>>> x1 = ivy.array([3., 5., 7.]) >>> x2 = ivy.array([4., 6., 8.]) >>> y = ivy.multiply(x1, x2) >>> print(y) ivy.array([12., 30., 56.])
With
ivy.NativeArray
inputs:>>> x1 = ivy.native_array([1., 3., 9.]) >>> x2 = ivy.native_array([4., 7.2, 1.]) >>> y = ivy.multiply(x1, x2) >>> print(y) ivy.array([ 4. , 21.6, 9. ])
With mixed
ivy.Array
andivy.NativeArray
inputs:>>> x1 = ivy.array([8., 6., 7.]) >>> x2 = ivy.native_array([1., 2., 3.]) >>> y = ivy.multiply(x1, x2) >>> print(y) ivy.array([ 8., 12., 21.])
With
ivy.Container
inputs:>>> x1 = ivy.Container(a=ivy.array([12.,4.,6.]), b=ivy.array([3.,1.,5.])) >>> x2 = ivy.Container(a=ivy.array([1.,3.,4.]), b=ivy.array([3.,3.,2.])) >>> y = ivy.multiply(x1, x2) >>> print(y) { a: ivy.array([12.,12.,24.]), b: ivy.array([9.,3.,10.]) }
With mixed
ivy.Container
andivy.Array
inputs:>>> x1 = ivy.Container(a=ivy.array([3., 4., 5.]), b=ivy.array([2., 2., 1.])) >>> x2 = ivy.array([1.,2.,3.]) >>> y = ivy.multiply(x1, x2) >>> print(y) { a: ivy.array([3.,8.,15.]), b: ivy.array([2.,4.,3.]) }
- ivy.nan_to_num(x, /, *, copy=True, nan=0.0, posinf=None, neginf=None, out=None)[source]#
Replace NaN with zero and infinity with large finite numbers (default behaviour) or with the numbers defined by the user using the nan, posinf and/or neginf keywords.
- Parameters:
x (
Union
[Array
,NativeArray
]) – Array input.copy (
bool
, default:True
) – Whether to create a copy of x (True) or to replace values in-place (False). The in-place operation only occurs if casting to an array does not require a copy. Default is True.nan (
Union
[float
,int
], default:0.0
) – Value to be used to fill NaN values. If no value is passed then NaN values will be replaced with 0.0.posinf (
Optional
[Union
[int
,float
]], default:None
) – Value to be used to fill positive infinity values. If no value is passed then positive infinity values will be replaced with a very large number.neginf (
Optional
[Union
[int
,float
]], default:None
) – Value to be used to fill negative infinity values. If no value is passed then negative infinity values will be replaced with a very small (or negative) number.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to.
- Return type:
- Returns:
ret – Array with the non-finite values replaced. If copy is False, this may be x itself.
Examples
>>> x = ivy.array([1, 2, 3, nan]) >>> ivy.nan_to_num(x) ivy.array([1., 1., 3., 0.0]) >>> x = ivy.array([1, 2, 3, inf]) >>> ivy.nan_to_num(x, posinf=5e+100) ivy.array([1., 2., 3., 5e+100])
- ivy.negative(x, /, *, out=None)[source]#
Return a new array with the negative value of each element in
x
.Note
For signed integer data types, the numerical negative of the minimum representable integer is implementation-dependent.
Note
If
x
has a complex floating-point data type, both the real and imaginary components for eachx_i
must be negated (a result which follows from the rules of complex number multiplication).- Parameters:
- Return type:
- Returns:
ret – A new array with the negative value of each element in
x
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([0,1,1,2]) >>> y = ivy.negative(x) >>> print(y) ivy.array([ 0, -1, -1, -2])
>>> x = ivy.array([0,-1,-0.5,2,3]) >>> y = ivy.zeros(5) >>> ivy.negative(x, out=y) >>> print(y) ivy.array([-0. , 1. , 0.5, -2. , -3. ])
>>> x = ivy.array([[1.1, 2.2, 3.3], ... [-4.4, -5.5, -6.6]]) >>> ivy.negative(x,out=x) >>> print(x) ivy.array([[-1.1, -2.2, -3.3], [4.4, 5.5, 6.6]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 1., 2.]), ... b=ivy.array([3., 4., -5.])) >>> y = ivy.negative(x) >>> print(y) { a: ivy.array([-0., -1., -2.]), b: ivy.array([-3., -4., 5.]) }
- ivy.not_equal(x1, x2, /, *, out=None)[source]#
Compute the truth value of
x1_i != x2_i
for each elementx1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.Special Cases
For real-valued floating-point operands,
If
x1_i
isNaN
orx2_i
isNaN
, the result isTrue
.If
x1_i
is+infinity
andx2_i
is-infinity
, the result isTrue
.If
x1_i
is-infinity
andx2_i
is+infinity
, the result isTrue
.If
x1_i
is a finite number,x2_i
is a finite number, andx1_i
does not equalx2_i
, the result isTrue
.In the remaining cases, the result is
False
.
For complex floating-point operands, let
a = real(x1_i)
,b = imag(x1_i)
,c = real(x2_i)
,d = imag(x2_i)
, andIf
a
,b
,c
, ord
isNaN
, the result isTrue
.In the remaining cases, the result is the logical OR of the equality comparison between the real values
a
andc
(real components) and between the real valuesb
andd
(imaginary components), as described above for real-valued floating-point operands (i.e.,a != c OR b != d
).
- Parameters:
x1 (
Union
[float
,Array
,NativeArray
,Container
]) – first input array. Should have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
,Container
]) – second input array. Must be compatible withx1
(see ref:broadcasting). Should have a numeric data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type of
bool
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
inputs:>>> x1 = ivy.array([1, 0, 1, 1]) >>> x2 = ivy.array([1, 0, 0, -1]) >>> y = ivy.not_equal(x1, x2) >>> print(y) ivy.array([False, False, True, True])
>>> x1 = ivy.array([1, 0, 1, 0]) >>> x2 = ivy.array([0, 1, 0, 1]) >>> y = ivy.not_equal(x1, x2) >>> print(y) ivy.array([True, True, True, True])
>>> x1 = ivy.array([1, -1, 1, -1]) >>> x2 = ivy.array([0, -1, 1, 0]) >>> y = ivy.zeros(4) >>> ivy.not_equal(x1, x2, out=y) >>> print(y) ivy.array([1., 0., 0., 1.])
>>> x1 = ivy.array([1, -1, 1, -1]) >>> x2 = ivy.array([0, -1, 1, 0]) >>> y = ivy.not_equal(x1, x2, out=x1) >>> print(y) ivy.array([1, 0, 0, 1])
With a mix of
ivy.Array
andivy.NativeArray
inputs:>>> x1 = ivy.native_array([1, 2]) >>> x2 = ivy.array([1, 2]) >>> y = ivy.not_equal(x1, x2) >>> print(y) ivy.array([False, False])
>>> x1 = ivy.native_array([1, -1]) >>> x2 = ivy.array([0, 1]) >>> y = ivy.not_equal(x1, x2) >>> print(y) ivy.array([True, True])
>>> x1 = ivy.native_array([1, -1, 1, -1]) >>> x2 = ivy.native_array([0, -1, 1, 0]) >>> y = ivy.zeros(4) >>> ivy.not_equal(x1, x2, out=y) >>> print(y) ivy.array([1., 0., 0., 1.])
>>> x1 = ivy.native_array([1, 2, 3, 4]) >>> x2 = ivy.native_array([0, 2, 3, 4]) >>> y = ivy.zeros(4) >>> ivy.not_equal(x1, x2, out=y) >>> print(y) ivy.array([1., 0., 0., 0.])
With
ivy.Container
input:>>> x1 = ivy.Container(a=ivy.array([1, 0, 3]), ... b=ivy.array([1, 2, 3]), ... c=ivy.native_array([1, 2, 4])) >>> x2 = ivy.Container(a=ivy.array([1, 2, 3]), ... b=ivy.array([1, 2, 3]), ... c=ivy.native_array([1, 2, 4])) >>> y = ivy.not_equal(x1, x2) >>> print(y) { a: ivy.array([False, True, False]), b: ivy.array([False, False, False]), c: ivy.array([False, False, False]) }
>>> x1 = ivy.Container(a=ivy.native_array([0, 1, 0]), ... b=ivy.array([1, 2, 3]), ... c=ivy.native_array([1.0, 2.0, 4.0])) >>> x2 = ivy.Container(a=ivy.array([1, 2, 3]), ... b=ivy.native_array([1.1, 2.1, 3.1]), ... c=ivy.native_array([1, 2, 4])) >>> y = ivy.not_equal(x1, x2) >>> print(y) { a: ivy.array([True, True, True]), b: ivy.array([True, True, True]), c: ivy.array([False, False, False]) }
With a mix of
ivy.Array
andivy.Container
inputs:>>> x1 = ivy.Container(a=ivy.array([1, 2, 3]), ... b=ivy.array([1, 3, 5])) >>> x2 = ivy.Container(a=ivy.array([1, 2, 3]), ... b=ivy.array([1, 4, 5])) >>> y = ivy.not_equal(x1, x2) >>> print(y) { a: ivy.array([False, False, False]), b: ivy.array([False, True, False]) }
>>> x1 = ivy.Container(a=ivy.array([1.0, 2.0, 3.0]), ... b=ivy.array([1, 4, 5])) >>> x2 = ivy.Container(a=ivy.array([1, 2, 3.0]), ... b=ivy.array([1.0, 4.0, 5.0])) >>> y = ivy.not_equal(x1, x2) >>> print(y) { a: ivy.array([False, False, False]), b: ivy.array([False, False, False]) }
- ivy.positive(x, /, *, out=None)[source]#
Return a new array with the positive value of each element in
x
.- Parameters:
- Return type:
- Returns:
ret – A new array with the positive value of each element in
x
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([2, 3 ,5, 7]) >>> y = ivy.positive(x) >>> print(y) ivy.array([2, 3, 5, 7])
>>> x = ivy.array([0, -1, -0.5, 2, 3]) >>> y = ivy.zeros(5) >>> ivy.positive(x, out=y) >>> print(y) ivy.array([0., -1., -0.5, 2., 3.])
>>> x = ivy.array([[1.1, 2.2, 3.3], ... [-4.4, -5.5, -6.6]]) >>> ivy.positive(x,out=x) >>> print(x) ivy.array([[ 1.1, 2.2, 3.3], [-4.4, -5.5, -6.6]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 1., 2.]), ... b=ivy.array([3., 4., -5.])) >>> y = ivy.positive(x) >>> print(y) { a: ivy.array([0., 1., 2.]), b: ivy.array([3., 4., -5.]) }
- ivy.pow(x1, x2, /, *, out=None)[source]#
Calculate an implementation-dependent approximation of exponentiation by raising each element
x1_i
(the base) of the input arrayx1
to the power ofx2_i
(the exponent), wherex2_i
is the corresponding element of the input arrayx2
.Special cases
For floating-point 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
is-0
, 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
is-infinity
, the result is+0
.If
abs(x1_i)
is1
andx2_i
is+infinity
, the result is1
.If
abs(x1_i)
is1
andx2_i
is-infinity
, 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
is-infinity
, 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
is-infinity
,x2_i
is greater than0
, andx2_i
is an odd integer value, the result is-infinity
.If
x1_i
is-infinity
,x2_i
is greater than0
, andx2_i
is not an odd integer value, the result is+infinity
.If
x1_i
is-infinity
,x2_i
is less than0
, andx2_i
is an odd integer value, the result is-0
.If
x1_i
is-infinity
,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
is-0
,x2_i
is greater than0
, andx2_i
is an odd integer value, the result is-0
.If
x1_i
is-0
,x2_i
is greater than0
, andx2_i
is not an odd integer value, the result is+0
.If
x1_i
is-0
,x2_i
is less than0
, andx2_i
is an odd integer value, the result is-infinity
.If
x1_i
is-0
,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
.
For complex floating-point operands, special cases should be handled as if the operation is implemented as
exp(x2*log(x1))
.Note
Conforming implementations are allowed to treat special cases involving complex floating-point operands more carefully than as described in this specification.
- Parameters:
x1 (
Union
[Array
,NativeArray
]) – first input array whose elements correspond to the exponentiation base. Should have a numeric data type.x2 (
Union
[int
,float
,Array
,NativeArray
]) – second input array whose elements correspond to the exponentiation exponent. Must be compatible withx1
(see broadcasting). Should have a numeric data type.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. The returned array must have a data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([1, 2, 3]) >>> y = ivy.pow(x, 3) >>> print(y) ivy.array([1, 8, 27])
>>> x = ivy.array([1.5, -0.8, 0.3]) >>> y = ivy.zeros(3) >>> ivy.pow(x, 2, out=y) >>> print(y) ivy.array([2.25, 0.64, 0.09])
>>> x = ivy.array([[1.2, 2, 3.1], [1, 2.5, 9]]) >>> ivy.pow(x, 2.3, out=x) >>> print(x) ivy.array([[ 1.52095687, 4.92457771, 13.49372482], [ 1. , 8.22738838, 156.5877228 ]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0, 1]), b=ivy.array([2, 3])) >>> y = ivy.pow(x, 3) >>> print(y) { a:ivy.array([0,1]), b:ivy.array([8,27]) }
- ivy.rad2deg(x, /, *, out=None)[source]#
Convert the input from radians to degrees.
- Parameters:
- Return type:
- Returns:
ret – an array with each element in
x
converted from radians to degrees.
Examples
With
ivy.Array
input:>>> x=ivy.array([0.,1.57,3.14,4.71,6.28]) >>> y=ivy.rad2deg(x) >>> print(y) ivy.array([ 0., 90., 180., 270., 360.])
>>> x=ivy.array([0.,-0.0262,-0.873,ivy.nan]) >>> y=ivy.zeros(4) >>> ivy.rad2deg(x,out=y) >>> print(y) ivy.array([ 0. , -1.5, -50. , nan])
>>> x = ivy.array([[1.1, 2.2, 3.3],[-4.4, -5.5, -6.6]]) >>> ivy.rad2deg(x, out=x) >>> print(x) ivy.array([[ 63., 126., 189.], [-252., -315., -378.]])
>>> x=ivy.native_array([-0,20.1,ivy.nan]) >>> y=ivy.zeros(3) >>> ivy.rad2deg(x,out=y) >>> print(y) ivy.array([ 0., 1150., nan])
With
ivy.Container
input:>>> x=ivy.Container(a=ivy.array([-0., 20.1, -50.5, -ivy.nan]), ... b=ivy.array([0., 1., 2., 3., 4.])) >>> y=ivy.rad2deg(x) >>> print(y) { a: ivy.array([0., 1150., -2890., nan]), b: ivy.array([0., 57.3, 115., 172., 229.]) }
>>> x=ivy.Container(a=ivy.array([0,10,180,8.5,6]), ... b=ivy.native_array([0,-1.5,0.5,ivy.nan])) >>> y=ivy.rad2deg(x) >>> print(y) { a: ivy.array([0., 573., 10300., 487., 344.]), b: ivy.array([0., -85.9, 28.6, nan]) }
- ivy.real(x, /, *, out=None)[source]#
Test each element
x_i
of the input arrayx
to take only real part from it. Returns a float array, where it only contains . If element has complex type with zero complex part, the return value will be that element, else it only returns real part.- Parameters:
- Return type:
- Returns:
ret – an array containing test results. An element
out_i
isreal number
ifx_i
contain real number part only and if it isreal number with complex part also
then it returns the real number part. The returned array must have a floating-point data type with the same floating-point precision asx
(e.g., ifx
iscomplex64
, the returned array must have the floating-point precision offloat32
).The descriptions above assume an array input for simplicity, but
the method also accepts
ivy.Container
instancesin place of (class:ivy.Array or
ivy.NativeArray
)instances, as shown in the type hints and also the examples below.
Examples
With
ivy.Array
inputs:>>> x = ivy.array([[[1.1], [2], [-6.3]]]) >>> z = ivy.real(x) >>> print(z) ivy.array([[[1.1], [2.], [-6.3]]])
>>> x = ivy.array([4.2-0j, 3j, 7+5j]) >>> z = ivy.real(x) >>> print(z) ivy.array([4.2, 0., 7.])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([-6.7-7j, 0.314+0.355j, 1.23]), b=ivy.array([5j, 5.32-6.55j, 3.001])) >>> z = ivy.real(x) >>> print(z) { a: ivy.array([-6.7, 0.314, 1.23]), b: ivy.array([0., 5.32, 3.001]) }
- ivy.reciprocal(x, /, *, out=None)[source]#
Return a new array with the reciprocal of each element in
x
.- Parameters:
- Return type:
- Returns:
ret – A new array with the positive value of each element in
x
.
Examples
>>> x = ivy.array([1, 2, 3]) >>> y = ivy.reciprocal(x) >>> print(y) ivy.array([1. , 0.5 , 0.33333333])
- ivy.remainder(x1, x2, /, *, modulus=True, out=None)[source]#
Return the remainder of division for each element
x1_i
of the input arrayx1
and the respective elementx2_i
of the input arrayx2
.Note
This function is equivalent to the Python modulus operator
x1_i % x2_i
. For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined. In general, similar to Python’s%
operator, this function is not recommended for floating-point operands as semantics do not follow IEEE 754. That this function is specified to accept floating-point operands is primarily for reasons of backward compatibility.Special Cases
For floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is either+infinity
or-infinity
andx2_i
is either+infinity
or-infinity
, the result isNaN
.If
x1_i
is either+0
or-0
andx2_i
is either+0
or-0
, the result isNaN
.If
x1_i
is+0
andx2_i
is greater than0
, 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-0
.If
x1_i
is-0
andx2_i
is less than0
, the result is-0
.If
x1_i
is greater than0
andx2_i
is+0
, the result isNaN
.If
x1_i
is greater than0
andx2_i
is-0
, the result isNaN
.If
x1_i
is less than0
andx2_i
is+0
, the result isNaN
.If
x1_i
is less than0
andx2_i
is-0
, the result isNaN
.If
x1_i
is+infinity
andx2_i
is a positive (i.e., greater than0
) finite number, the result isNaN
.If
x1_i
is+infinity
andx2_i
is a negative (i.e., less than0
) finite number, the result isNaN
.If
x1_i
is-infinity
andx2_i
is a positive (i.e., greater than0
) finite number, the result isNaN
.If
x1_i
is-infinity
andx2_i
is a negative (i.e., less than0
) finite number, the result isNaN
.If
x1_i
is a positive (i.e., greater than0
) finite number andx2_i
is+infinity
, the result isx1_i
. (note: this result matches Python behavior.)If
x1_i
is a positive (i.e., greater than0
) finite number andx2_i
is-infinity
, the result isx2_i
. (note: this result matches Python behavior.)If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is+infinity
, the result isx2_i
. (note: this results matches Python behavior.)If
x1_i
is a negative (i.e., less than0
) finite number andx2_i
is-infinity
, the result isx1_i
. (note: this result matches Python behavior.)In the remaining cases, the result must match that of the Python
%
operator.
- Parameters:
x1 (
Union
[float
,Array
,NativeArray
]) – dividend input array. Should have a numeric data type.x2 (
Union
[float
,Array
,NativeArray
]) – divisor input array. Must be compatible withx1
(see ref:Broadcasting). Should have a numeric data type.modulus (
bool
, default:True
) – whether to compute the modulus instead of the remainder. Default isTrue
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the element-wise results. Each element-wise result must have the same sign as the respective element
x2_i
. The returned array must have a data type determined by Type Promotion Rules.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
inputs:>>> x1 = ivy.array([2., 5., 15.]) >>> x2 = ivy.array([3., 2., 4.]) >>> y = ivy.remainder(x1, x2) >>> print(y) ivy.array([2., 1., 3.])
With mixed
ivy.Array
andivy.NativeArray
inputs:>>> x1 = ivy.array([23., 1., 6.]) >>> x2 = ivy.native_array([11., 2., 4.]) >>> y = ivy.remainder(x1, x2) >>> print(y) ivy.array([1., 1., 2.])
With
ivy.Container
inputs:>>> x1 = ivy.Container(a=ivy.array([2., 3., 5.]), b=ivy.array([2., 2., 4.])) >>> x2 = ivy.Container(a=ivy.array([1., 3., 4.]), b=ivy.array([1., 3., 3.])) >>> y = ivy.remainder(x1, x2) >>> print(y) { a: ivy.array([0., 0., 1.]), b: ivy.array([0., 2., 1.]) }
- ivy.round(x, /, *, decimals=0, out=None)[source]#
Round each element
x_i
of the input arrayx
to the nearest integer-valued number.Note
For complex floating-point operands, real and imaginary components must be independently rounded to the nearest integer-valued number.
Rounded real and imaginary components must be equal to their equivalent rounded real-valued floating-point counterparts (i.e., for complex-valued
x
,real(round(x))
must equalround(real(x)))
andimag(round(x))
must equalround(imag(x))
).Special cases
If
x_i
is already an integer-valued, the result isx_i
.
For floating-point operands,
If
x_i
is+infinity
, the result is+infinity
.If
x_i
is-infinity
, the result is-infinity
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
isNaN
, the result isNaN
.If two integers are equally close to
x_i
, the result is the even integer closest tox_i
.
Note
For complex floating-point operands, the following special cases apply to real and imaginary components independently (e.g., if
real(x_i)
isNaN
, the rounded real component isNaN
).If
x_i
is already integer-valued, the result isx_i
.
- Parameters:
x (
Union
[Array
,NativeArray
]) – input array containing elements to round.decimals (
Optional
[int
], default:0
) – number of decimal places to round to. Default is0
.out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – An array of the same shape and type as x, with the elements rounded to integers.
Note: PyTorch supports an additional argument
decimals
for the round function. It has been deliberately omitted here due to the imprecise nature of the argument intorch.round
.This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([1.2, 2.4, 3.6]) >>> y = ivy.round(x) >>> print(y) ivy.array([1.,2.,4.])
>>> x = ivy.array([-0, 5, 4.5]) >>> y = ivy.round(x) >>> print(y) ivy.array([0.,5.,4.])
>>> x = ivy.array([1.5654, 2.034, 15.1, -5.0]) >>> y = ivy.zeros(4) >>> ivy.round(x, out=y) >>> print(y) ivy.array([2.,2.,15.,-5.])
>>> x = ivy.array([[0, 5.433, -343.3, 1.5], ... [-5.5, 44.2, 11.5, 12.01]]) >>> ivy.round(x, out=x) >>> print(x) ivy.array([[0.,5.,-343.,2.],[-6.,44.,12.,12.]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([4.20, 8.6, 6.90, 0.0]), ... b=ivy.array([-300.9, -527.3, 4.5])) >>> y = ivy.round(x) >>> print(y) { a:ivy.array([4.,9.,7.,0.]), b:ivy.array([-301.,-527.,4.]) }
- ivy.sign(x, /, *, np_variant=True, out=None)[source]#
Return an indication of the sign of a number for each element
x_i
of the input arrayx
.The sign function (also known as the signum function) of a number \(x_{i}\) is defined as
\[\begin{split}\operatorname{sign}(x_i) = \begin{cases} 0 & \textrm{if } x_i = 0 \\ \frac{x}{|x|} & \textrm{otherwise} \end{cases}\end{split}\]where \(|x_i|\) is the absolute value of \(x_i\).
Special cases
If
x_i
is less than0
, the result is-1
.If
x_i
is either-0
or+0
, the result is0
.If
x_i
is greater than0
, the result is+1
.For complex numbers
sign(x.real) + 0j if x.real != 0 else sign(x.imag) + 0j
For complex floating-point operands, let
a = real(x_i)
,b = imag(x_i)
, andIf
a
is either-0
or+0
andb
is either-0
or+0
, the result is0 + 0j
.If
a
isNaN
orb
isNaN
, the result isNaN + NaN j
.In the remaining cases, special cases must be handled according to the rules of complex number division.
- Parameters:
x (
Union
[Array
,NativeArray
]) – input array. Should have a numeric data type.np_variant (
Optional
[bool
], default:True
) – Handles complex numbers like numpy does IfTrue
,sign(x.real) + 0j if x.real != 0 else sign(x.imag) + 0j
. otherwise, For complex numbers,y = sign(x) = x / |x| if x != 0, otherwise y = 0.
out (
Optional
[Array
], default:None
) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – an array containing the evaluated result for each element in
x
. The returned array must have the same data type asx
.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the arguments.Examples
With
ivy.Array
input:>>> x = ivy.array([8.3, -0, 6.8, 0.07]) >>> y = ivy.sign(x) >>> print(y) ivy.array([1., 0., 1., 1.])
>>> x = ivy.array([[5.78, -4., -6.9, 0], ... [-.4, 0.5, 8, -0.01]]) >>> y = ivy.sign(x) >>> print(y) ivy.array([[ 1., -1., -1., 0.], [-1., 1., 1., -1.]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., -0.]), ... b=ivy.array([1.46, 5.9, -0.0]), ... c=ivy.array([-8.23, -4.9, -2.6, 7.4])) >>> y = ivy.sign(x) >>> print(y) { a: ivy.array([0., 0.]), b: ivy.array([1., 1., 0.]), c: ivy.array([-1., -1., -1., 1.]) }
- ivy.sin(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the sine, having domain
(-infinity, +infinity)
and codomain[-1, +1]
, for each elementx_i
of the input arrayx
. Each elementx_i
is assumed to be expressed in radians.Note
The sine is an entire function on the complex plane and has no branch cuts.
Special cases
For floating-point operands,
If
x_i
isNaN
, the result isNaN
.If
x_i
is+0
, the result is+0
.If
x_i
is-0
, the result is-0
.If
x_i
is either+infinity
or-infinity
, the result isNaN
.
For complex floating-point operands, special cases must be handled as if the operation is implemented as
-1j * sinh(x*1j)
.- Parameters:
- Return type:
- Returns:
ret – an array containing the sine of each element in
x
. The returned array must have a floating-point data type determined by type-promotion.
This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.
Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts
ivy.Container
instances in place of any of the argumentsExamples
With
ivy.Array
input:>>> x = ivy.array([0., 1., 2.]) >>> y = ivy.sin(x) >>> print(y) ivy.array([0., 0.841, 0.909])
>>> x = ivy.array([0., 1.2, -2.3, 3.6]) >>> y = ivy.zeros(4) >>> ivy.sin(x, out=y) >>> print(y) ivy.array([0., 0.932, -0.746, -0.443])
>>> x = ivy.array([[1., 2., 3.], [-4., -5., -6.]]) >>> ivy.sin(x, out=x) >>> print(x) ivy.array([[0.841, 0.909, 0.141], [0.757, 0.959, 0.279]])
With
ivy.Container
input:>>> x = ivy.Container(a=ivy.array([0., 1., 2., 3.]), ... b=ivy.array([-4., -5., -6., -7.])) >>> y = ivy.sin(x) >>> print(y) { a: ivy.array([0., 0.841, 0.909, 0.141]), b: ivy.array([0.757, 0.959, 0.279, -0.657]) }
- ivy.sinh(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation to the hyperbolic sine, having domain
[-infinity, +infinity]
and codomain[-infinity, +infinity]
, for each elementx_i
of the input arrayx
.\[\operatorname{sinh}(x) = \frac{e^x - e^{-x}}{2}\]Note
The hyperbolic sine is an entire function in the complex plane and has no branch cuts. The function is periodic, with period \(2\pi j\), with respect to the imaginary component.
Special cases
For floating-point operands,
If
x_i
isNaN