Elementwise#
- ivy.allclose(a, b, /, *, rtol=1e-05, atol=1e-08, equal_nan=False, out=None)[source]#
Return a True if the two arrays are element-wise equal within given tolerance; otherwise False.
The tolerance values are positive, typically very small numbers. The relative difference (rtol * abs(x2)) and the absolute difference atol are added together to compare against the absolute difference between x1 and x2. The default atol is not appropriate for comparing numbers that are much smaller than one
- Parameters:
x1 – First input array.
x2 – Second input array.
rtol (
float) – The relative tolerance parameter. (default:1e-05)atol (
float) – The absolute tolerance parameter. (default:1e-08)equal_nan (
bool) – Whether to compare NaN’s as equal. If True, NaN’s in x1 will be (default:False) considered equal to NaN’s in x2 in the output array.out (
Optional[Array]) – Alternate output array in which to place the result. (default:None) The default is None.
- Return type:
bool- Returns:
ret – Returns True if the two arrays are equal within the given tolerance; False otherwise.
Examples
>>> x1 = ivy.array([1e10, 1e-7]) >>> x2 = ivy.array([1.00001e10, 1e-8]) >>> y = ivy.allclose(x1, x2) >>> print(y) ivy.array(False)
>>> x1 = ivy.array([1.0, ivy.nan]) >>> x2 = ivy.array([1.0, ivy.nan]) >>> y = ivy.allclose(x1, x2, equal_nan=True) >>> print(y) ivy.array(True)
>>> x1 = ivy.array([1e-10, 1e-10]) >>> x2 = ivy.array([1.00001e-10, 1e-10]) >>> y = ivy.allclose(x1, x2, rtol=0.005, atol=0.0) >>> print(y) ivy.array(True)
- ivy.binarizer(x, /, *, threshold=0, out=None)[source]#
Map the values of the input tensor to either 0 or 1, element-wise, based on the outcome of a comparison against a threshold value.
- Parameters:
- Return type:
- Returns:
ret – Binarized output data
- ivy.conj(x, /, *, out=None)[source]#
Compute the complex conjugate of complex values in x.
- Parameters:
- Return type:
- Returns:
ret – an arrray of the same dtype as the input array with the complex conjugates of the complex values present in the input array. If x is a scalar then a scalar will be returned.
The descriptions above assume an array input for simplicity, but
the method also accepts
ivy.Containerinstancesin place of (class:ivy.Array or
ivy.NativeArray)instances, as shown in the type hints and also the examples below.
Examples
With
ivy.Arrayinputs: >>> x = ivy.array([4.2-0j, 3j, 7+5j]) >>> z = ivy.conj(x) >>> print(z) ivy.array([4.2+0j, -3j, 7+5j])With
ivy.Containerinput: >>> 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.conj(x) >>> print(z) {a: ivy.array([-6.7+7j, 0.314-0.355j, 1.23]), b: ivy.array([-5j, 5.32+6.55j, 3.001])
}
- ivy.copysign(x1, x2, /, *, out=None)[source]#
Change the signs of x1 to match x2 x1 and x2 must be broadcastable to a common shape.
- Parameters:
x1 (
Union[Array,NativeArray,Number]) – Array or scalar to change the sign ofx2 (
Union[Array,NativeArray,Number]) – Array or scalar from which the new signs are applied Unsigned zeroes are considered positive.out (
Optional[Union[Array,NativeArray]]) – optional output array, for writing the result to. (default:None)
- Return type:
- Returns:
ret – x1 with the signs of x2. This is a scalar if both x1 and x2 are scalars.
Examples
>>> x1 = ivy.array([-1, 0, 23, 2]) >>> x2 = ivy.array([1, -1, -10, 44]) >>> ivy.copysign(x1, x2) ivy.array([ 1., -0., -23., 2.]) >>> ivy.copysign(x1, -1) ivy.array([ -1., -0., -23., -2.]) >>> ivy.copysign(-10, 1) ivy.array(10.)
- ivy.count_nonzero(a, /, *, axis=None, keepdims=False, dtype=None, out=None)[source]#
Count the number of non-zero values in the array a.
- Parameters:
a (
Union[Array,NativeArray]) – array for which to count non-zeros.axis (
Optional[Union[int,Tuple[int,...]]]) – optional axis or tuple of axes along which to count non-zeros. Default is (default:None) None, meaning that non-zeros will be counted along a flattened version of the input array.keepdims (
bool) – optional, if this is set to True, the axes that are counted are left in the (default:False) result as dimensions with size one. With this option, the result will broadcast correctly against the input array.dtype (
Optional[Union[Dtype,NativeDtype]]) – optional output dtype. Default is of type integer. (default:None)out (
Optional[Union[Array,NativeArray]]) – optional output array, for writing the result to. (default:None)
- Return type:
- Returns:
ret – Number of non-zero values in the array along a given axis. Otherwise, the total number of non-zero values in the array is returned.
Examples
>>> a = ivy.array([[0, 1, 2, 3],[4, 5, 6, 7]]) >>> ivy.count_nonzero(a) ivy.array(7) >>> a = ivy.array([[0, 1, 2, 3],[4, 5, 6, 7]]) >>> ivy.count_nonzero(a, axis=0) ivy.array([1, 2, 2, 2]) >>> a = ivy.array([[[0,1],[2,3]],[[4,5],[6,7]]]) >>> ivy.count_nonzero(a, axis=(0,1), keepdims=True) ivy.array([[[3, 4]]])
- ivy.diff(x, /, *, n=1, axis=-1, prepend=None, append=None, out=None)[source]#
Return the n-th discrete difference along the given axis.
- Parameters:
x (
Union[Array,NativeArray,list,tuple]) – Array-like input.n (
int) – The number of times values are differenced. If zero, the input is returned (default:1) as-is.axis (
int) – The axis along which the difference is taken, default is the last axis. (default:-1)prepend (
Optional[Union[Array,NativeArray,int,list,tuple]]) – Values to prepend/append to x along given axis prior to performing the (default:None) difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match x except along axis.append (
Optional[Union[Array,NativeArray,int,list,tuple]]) – Values to prepend/append to x along given axis prior to performing the (default:None) difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match x except along axis.out (
Optional[Array]) – optional output array, for writing the result to. (default:None)
- Return type:
- Returns:
ret – Returns the n-th discrete difference along the given axis.
Both the description and the type hints above assumes an array input for simplicity,
but this function is nestable, and therefore also accepts
ivy.Containerinstances in place of any of the arguments.
Examples
>>> x = ivy.array([1, 2, 4, 7, 0]) >>> ivy.diff(x) ivy.array([ 1, 2, 3, -7])
- ivy.fix(x, /, *, out=None)[source]#
Round an array of floats element-wise to nearest integer towards zero. The rounded values are returned as floats.
- Parameters:
- Return type:
- Returns:
ret – Array of floats with elements corresponding to input elements rounded to nearest integer towards zero, element-wise.
Examples
>>> x = ivy.array([2.1, 2.9, -2.1]) >>> ivy.fix(x) ivy.array([ 2., 2., -2.])
- ivy.float_power(x1, x2, /, *, out=None)[source]#
Raise each base in x1 to the positionally-corresponding power in x2. x1 and x2 must be broadcastable to the same shape. This differs from the power function in that integers, float16, and float32 are promoted to floats with a minimum precision of float64 so that the result is always inexact.
- Parameters:
x1 (
Union[Array,float,list,tuple]) – Array-like with elements to raise in power.x2 (
Union[Array,float,list,tuple]) – Array-like of exponents. If x1.shape != x2.shape, they must be broadcastable to a common shape (which becomes the shape of the output).out (
Optional[Array]) – optional output array, for writing the result to. (default:None)
- Return type:
- Returns:
ret – The bases in x1 raised to the exponents in x2. This is a scalar if both x1 and x2 are scalars
Examples
>>> x1 = ivy.array([1, 2, 3, 4, 5]) >>> ivy.float_power(x1, 3) ivy.array([1., 8., 27., 64., 125.]) >>> x1 = ivy.array([1, 2, 3, 4, 5]) >>> x2 = ivy.array([2, 3, 3, 2, 1]) >>> ivy.float_power(x1, x2) ivy.array([1., 8., 27., 16., 5.])
- ivy.fmax(x1, x2, /, *, out=None)[source]#
Compute the element-wise maximums of two arrays. Differs from ivy.maximum in the case where one of the elements is NaN. ivy.maximum returns the NaN element while ivy.fmax returns the non-NaN element.
- Parameters:
- Return type:
Union[Array,NativeArray]- Returns:
ret – Array with element-wise maximums.
Examples
>>> x1 = ivy.array([2, 3, 4]) >>> x2 = ivy.array([1, 5, 2]) >>> ivy.fmax(x1, x2) ivy.array([ 2., 5., 4.])
>>> x1 = ivy.array([ivy.nan, 0, ivy.nan]) >>> x2 = ivy.array([0, ivy.nan, ivy.nan]) >>> ivy.fmax(x1, x2) ivy.array([ 0., 0., nan])
- ivy.frexp(x, /, *, out=None)[source]#
Decompose the elements of x into mantissa and twos exponent.
- Parameters:
- Return type:
- Returns:
ret – A tuple of two arrays, the mantissa and the twos exponent.
Examples
>>> x = ivy.array([1, 2, 3]) >>> ivy.frexp(x) (ivy.array([0.5, 0.5, 0.75]), ivy.array([1, 2, 2]))
- ivy.gradient(x, /, *, spacing=1, edge_order=1, axis=None)[source]#
Calculate gradient of x with respect to (w.r.t.) spacing.
- Parameters:
x (
Union[Array,NativeArray]) – input array representing outcomes of the functionspacing (
Union[int,list,tuple]) – if not given, indices of x will be used (default:1) if scalar indices of x will be scaled with this value if array gradient of x w.r.t. spacingedge_order (
int) – 1 or 2, for ‘frist order’ and ‘second order’ estimation (default:1) of boundary values of gradient respectively. Note: jax supports edge_order=1 case onlyaxis (
Optional[Union[int,list,tuple]]) – dimension(s) to approximate the gradient over (default:None) by default partial gradient is computed in every dimention
- Return type:
- Returns:
ret – Array with values computed from gradient function from inputs
Examples
>>> spacing = (ivy.array([-2., -1., 1., 4.]),) >>> x = ivy.array([4., 1., 1., 16.], ) >>> ivy.gradient(x, spacing=spacing) ivy.array([-3., -2., 2., 5.])
>>> x = ivy.array([[1, 2, 4, 8], [10, 20, 40, 80]]) >>> ivy.gradient(x) [ivy.array([[ 9., 18., 36., 72.], [ 9., 18., 36., 72.]]), ivy.array([[ 1. , 1.5, 3. , 4. ], [10. , 15. , 30. , 40. ]])]
>>> x = ivy.array([[1, 2, 4, 8], [10, 20, 40, 80]]) >>> ivy.gradient(x, spacing=2.0) [ivy.array([[ 4.5, 9. , 18. , 36. ], [ 4.5, 9. , 18. , 36. ]]), ivy.array([[ 0.5 , 0.75, 1.5 , 2. ], [ 5. , 7.5 , 15. , 20. ]])]
>>> x = ivy.array([[1, 2, 4, 8], [10, 20, 40, 80]]) >>> ivy.gradient(x, axis=1) ivy.array([[ 1. , 1.5, 3. , 4. ], [10. , 15. , 30. , 40. ]])
>>> x = ivy.array([[1, 2, 4, 8], [10, 20, 40, 80]]) >>> ivy.gradient(x, spacing=[3., 2.]) [ivy.array([[ 3., 6., 12., 24.], [ 3., 6., 12., 24.]]), ivy.array([[ 0.5 , 0.75, 1.5 , 2. ], [ 5. , 7.5 , 15. , 20. ]])]
>>> spacing = (ivy.array([0, 2]), ivy.array([0, 3, 6, 9])) >>> ivy.gradient(x, spacing=spacing) [ivy.array([[ 4.5, 9. , 18. , 36. ], [ 4.5, 9. , 18. , 36. ]]), ivy.array([[ 0.33333333, 0.5, 1., 1.33333333], [ 3.33333333, 5. , 10. , 13.33333333]])]
- ivy.hypot(x1, x2, /, *, out=None)[source]#
Return the hypotenuse given the two sides of a right angle triangle.
- Parameters:
- Return type:
Union[Array,NativeArray]- Returns:
ret – An array with the hypotenuse
Examples
>>> a = ivy.array([3.0, 4.0, 5.0]) >>> b = ivy.array([4.0, 5.0, 6.0]) >>> ivy.hypot(a, b) ivy.array([5.0, 6.4031, 7.8102])
- ivy.isclose(a, b, /, *, rtol=1e-05, atol=1e-08, equal_nan=False, out=None)[source]#
Return a boolean array where two arrays are element-wise equal within a tolerance.
The tolerance values are positive, typically very small numbers. The relative difference (rtol * abs(b)) and the absolute difference atol are added together to compare against the absolute difference between a and b. The default atol is not appropriate for comparing numbers that are much smaller than one
- Parameters:
a (
Union[Array,NativeArray]) – First input array.b (
Union[Array,NativeArray]) – Second input array.rtol (
float) – The relative tolerance parameter. (default:1e-05)atol (
float) – The absolute tolerance parameter. (default:1e-08)equal_nan (
bool) – Whether to compare NaN’s as equal. If True, NaN’s in a will be (default:False) considered equal to NaN’s in b in the output array.out (
Optional[Array]) – Alternate output array in which to place the result. (default:None) The default is None.
- Return type:
- Returns:
ret – Returns a boolean array of where a and b are equal within the given tolerance. If both a and b are scalars, returns a single boolean value.
Examples
>>> ivy.isclose([1e10,1e-7], [1.00001e10,1e-8]) ivy.array([True, False]) >>> ivy.isclose([1.0, ivy.nan], [1.0, ivy.nan], equal_nan=True) ivy.array([True, True]) >>> ivy.isclose([1e-100, 1e-7], [0.0, 0.0], atol=0.0) ivy.array([False, False]) >>> ivy.isclose([1e-10, 1e-10], [1e-20, 0.999999e-10], rtol=0.005, atol=0.0) ivy.array([False, True])
- ivy.ldexp(x1, x2, /, *, out=None)[source]#
Return x1 * (2**x2), element-wise.
- Parameters:
- Return type:
- Returns:
ret – The next representable values of x1 in the direction of x2.
Examples
>>> x1 = ivy.array([1, 2, 3]) >>> x2 = ivy.array([0, 1, 2]) >>> ivy.ldexp(x1, x2) ivy.array([1, 4, 12])
- ivy.lerp(input, end, weight, /, *, out=None)[source]#
Return a linear interpolation of two arrays start (given by input) and end.
- based on a scalar or array weight.
input + weight * (end - input), element-wise.
- Parameters:
input (
Union[Array,NativeArray]) – array of starting pointsend (
Union[Array,NativeArray]) – array of ending pointsweight (
Union[Array,NativeArray,float]) – the weight for the interpolation formula. Scalar or Array.out (
Optional[Array]) – optional output array, for writing the result to. (default:None) It must have a shape that the inputs broadcast to.
- Return type:
- Returns:
ret – The result of input + ((end - input) * weight)
Examples
With
ivy.Arrayinputs: >>> input = ivy.array([1, 2, 3]) >>> end = ivy.array([10, 10, 10]) >>> weight = 0.5 >>> ivy.lerp(input, end, weight) ivy.array([5.5, 6. , 6.5]) >>> input = ivy.array([1.1, 1.2, 1.3]) >>> end = ivy.array([20]) >>> weight = ivy.array([0.4, 0.5, 0.6]) >>> y = ivy.zeros(3) >>> ivy.lerp(input, end, weight, out=y) ivy.array([ 8.65999985, 10.59999943, 12.52000141]) >>> input = ivy.array([[4, 5, 6],[4.1, 4.2, 4.3]]) >>> end = ivy.array([10]) >>> weight = ivy.array([0.5]) >>> ivy.lerp(input, end, weight, out=input) ivy.array([[7. , 7.5 , 8. ], … [7.05000019, 7.0999999 , 7.1500001 ]]) Withivy.Containerinput: >>> input = ivy.Container(a=ivy.array([0., 1., 2.]), b=ivy.array([3., 4., 5.])) >>> end = ivy.array([10.]) >>> weight = 1.1 >>> y = input.lerp(end, weight) >>> print(y) {a: ivy.array([11., 10.90000057, 10.80000019]), b: ivy.array([10.70000076, 10.60000038, 10.5])
} >>> input = ivy.Container(a=ivy.array([10.1, 11.1]), b=ivy.array([10, 11])) >>> end = ivy.Container(a=ivy.array([5]), b=ivy.array([0])) >>> weight = ivy.Container(a=0.5) >>> y = input.lerp(end, weight) >>> print(y) {
a: ivy.array([7.55000019, 8.05000019]), b: {
a: ivy.array([5., 5.5])
}
}
- ivy.nansum(x, /, *, axis=None, dtype=None, keepdims=False, out=None)[source]#
Return the sum of array elements over a given axis treating Not a Numbers (NaNs) as zero.
- Parameters:
x (
Union[Array,NativeArray]) – Input array.axis (
Optional[Union[int,Tuple[int,...]]]) – Axis or axes along which the sum is computed. (default:None) The default is to compute the sum of the flattened array.dtype (
Optional[Union[Dtype,NativeDtype]]) – The type of the returned array and of the accumulator in (default:None) which the elements are summed. By default, the dtype of input is used.keepdims (
bool) – If this is set to True, the axes which are reduced are left (default:False) in the result as dimensions with size one.out (
Optional[Array]) – Alternate output array in which to place the result. (default:None) The default is None.
- Return type:
- Returns:
ret – A new array holding the result is returned unless out is specified, in which it is returned.
Examples
>>> a = ivy.array([[ 2.1, 3.4, ivy.nan], [ivy.nan, 2.4, 2.1]]) >>> ivy.nansum(a) 10.0 >>> ivy.nansum(a, axis=0) ivy.array([2.1, 5.8, 2.1]) >>> ivy.nansum(a, axis=1) ivy.array([5.5, 4.5])
- ivy.nextafter(x1, x2, /, *, out=None)[source]#
Return the next floating-point value after x1 towards x2, element-wise.
- Parameters:
- Return type:
bool- Returns:
ret – The next representable values of x1 in the direction of x2.
Examples
>>> x1 = ivy.array([1.0e-50, 2.0e+50]) >>> x2 = ivy.array([2.0, 1.0]) >>> ivy.nextafter(x1, x2) ivy.array([1.4013e-45., 3.4028e+38])
- ivy.signbit(x, /, *, out=None)[source]#
Return element-wise True where signbit is set (less than zero).
- Parameters:
- Return type:
- Returns:
ret – Output array, or reference to out if that was supplied. This is a scalar if x is a scalar.
Examples
>>> x = ivy.array([1, -2, 3]) >>> ivy.signbit(x) ivy.array([False, True, False])
- ivy.sinc(x, /, *, out=None)[source]#
Calculate an implementation-dependent approximation of the principal value of the normalized sinc function, having domain
(-infinity, +infinity)and codomain[-0.217234, 1], for each elementx_iof the input arrayx. Each elementx_iis assumed to be expressed in radians.Special cases
For floating-point operands,
If x_i is NaN, the result is NaN.
If
x_iis0, the result is1.If
x_iis either+infinityor-infinity, the result isNaN.
- Parameters:
- Return type:
- Returns:
ret – an array containing the normalized sinc function of each element in x. The returned array must have a floating-point data type determined by type-promotion.
Examples
With
ivy.Arrayinput:>>> x = ivy.array([0.5, 1.5, 2.5, 3.5]) >>> y = x.sinc() >>> print(y) ivy.array([0.637,-0.212,0.127,-0.0909])
>>> x = ivy.array([1.5, 0.5, -1.5]) >>> y = ivy.zeros(3) >>> ivy.sinc(x, out=y) >>> print(y) ivy.array([-0.212,0.637,-0.212])
With
ivy.NativeArrayinput:>>> x = ivy.array([0.5, 1.5, 2.5, 3.5]) >>> y = ivy.sinc(x) >>> print(y) ivy.array([0.637,-0.212,0.127,-0.0909])
With
ivy.Containerinput:>>> x = ivy.Container(a=ivy.array([0.5, 1.5, 2.5]), ... b=ivy.array([3.5, 4.5, 5.5])) >>> y = x.sinc() >>> print(y) { a: ivy.array([0.637,-0.212,0.127]), b: ivy.array([-0.0909,0.0707,-0.0579]) }
- ivy.xlogy(x, y, /, *, out=None)[source]#
Compute x*log(y) element-wise so that the result is 0 if x = 0.
- Parameters:
- Return type:
bool- Returns:
ret – The next representable values of x1 in the direction of x2.
Examples
>>> x = ivy.zeros(3) >>> y = ivy.array([-1.0, 0.0, 1.0]) >>> ivy.xlogy(x, y) ivy.array([0.0, 0.0, 0.0])
>>> x = ivy.array([1.0, 2.0, 3.0]) >>> y = ivy.array([3.0, 2.0, 1.0]) >>> ivy.xlogy(x, y) ivy.array([1.0986, 1.3863, 0.0000])
- ivy.zeta(x, q, /, *, out=None)[source]#
Compute the Hurwitz zeta function elementwisely with each pair of floats in two arrays.
- Parameters:
- Return type:
bool- Returns:
ret – Array with values computed from zeta function from input arrays’ values.
Examples
>>> x = ivy.array([5.0, 3.0]) >>> q = ivy.array([2.0, 2.0]) >>> ivy.zeta(x, q) ivy.array([0.0369, 0.2021])