# pow#

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 array `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the input array `x2`.

Special cases

For floating-point operands,

• If `x1_i` is not equal to `1` and `x2_i` is `NaN`, the result is `NaN`.

• If `x2_i` is `+0`, the result is `1`, even if `x1_i` is `NaN`.

• If `x2_i` is `-0`, the result is `1`, even if `x1_i` is `NaN`.

• If `x1_i` is `NaN` and `x2_i` is not equal to `0`, the result is `NaN`.

• If `abs(x1_i)` is greater than `1` and `x2_i` is `+infinity`, the result is `+infinity`.

• If `abs(x1_i)` is greater than `1` and `x2_i` is `-infinity`, the result is `+0`.

• If `abs(x1_i)` is `1` and `x2_i` is `+infinity`, the result is `1`.

• If `abs(x1_i)` is `1` and `x2_i` is `-infinity`, the result is `1`.

• If `x1_i` is `1` and `x2_i` is not `NaN`, the result is `1`.

• If `abs(x1_i)` is less than `1` and `x2_i` is `+infinity`, the result is `+0`.

• If `abs(x1_i)` is less than `1` and `x2_i` is `-infinity`, the result is `+infinity`.

• If `x1_i` is `+infinity` and `x2_i` is greater than `0`, the result is `+infinity`.

• If `x1_i` is `+infinity` and `x2_i` is less than `0`, the result is `+0`.

• If `x1_i` is `-infinity`, `x2_i` is greater than `0`, and `x2_i` is an odd integer value, the result is `-infinity`.

• If `x1_i` is `-infinity`, `x2_i` is greater than `0`, and `x2_i` is not an odd integer value, the result is `+infinity`.

• If `x1_i` is `-infinity`, `x2_i` is less than `0`, and `x2_i` is an odd integer value, the result is `-0`.

• If `x1_i` is `-infinity`, `x2_i` is less than `0`, and `x2_i` is not an odd integer value, the result is `+0`.

• If `x1_i` is `+0` and `x2_i` is greater than `0`, the result is `+0`.

• If `x1_i` is `+0` and `x2_i` is less than `0`, the result is `+infinity`.

• If `x1_i` is `-0`, `x2_i` is greater than `0`, and `x2_i` is an odd integer value, the result is `-0`.

• If `x1_i` is `-0`, `x2_i` is greater than `0`, and `x2_i` is not an odd integer value, the result is `+0`.

• If `x1_i` is `-0`, `x2_i` is less than `0`, and `x2_i` is an odd integer value, the result is `-infinity`.

• If `x1_i` is `-0`, `x2_i` is less than `0`, and `x2_i` is not an odd integer value, the result is `+infinity`.

• If `x1_i` is less than `0`, `x1_i` is a finite number, `x2_i` is a finite number, and `x2_i` is not an integer value, the result is `NaN`.

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 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:

`Array`

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:

```>>> 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])
}
```
Array.pow(self, x2, /, *, out=None)[source]#

ivy.Array instance method variant of ivy.pow. This method simply wraps the function, and so the docstring for ivy.pow also applies to this method with minimal changes.

Parameters:
• self (`Array`) – first input array whose elements correspond to the exponentiation base. Should have a real-valued data type.

• x2 (`Union`[`int`, `float`, `Array`, `NativeArray`]) – second input array whose elements correspond to the exponentiation exponent. Must be compatible with `self` (see broadcasting). Should have a real-valued 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:

`Array`

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` input:

```>>> x = ivy.array([1, 2, 3])
>>> y = x.pow(3)
>>> print(y)
ivy.array([1, 8, 27])
```
```>>> x = ivy.array([1.5, -0.8, 0.3])
>>> y = ivy.zeros(3)
>>> x.pow(2, out=y)
>>> print(y)
ivy.array([2.25, 0.64, 0.09])
```
Container.pow(self, x2, /, *, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

ivy.Container instance method variant of ivy.pow. This method simply wraps the function, and so the docstring for ivy.pow also applies to this method with minimal changes.

Parameters:
• self (`Container`) – input array or container. Should have a real-valued data type.

• x2 (`Union`[`int`, `float`, `Container`, `Array`, `NativeArray`]) – input array or container. Must be compatible with `self` (see broadcasting). Should have a real-valued data type.

• key_chains (`Optional`[`Union`[`List`[`str`], `Dict`[`str`, `str`], `Container`]], default: `None`) – The key-chains to apply or not apply the method to. Default is `None`.

• to_apply (`Union`[`bool`, `Container`], default: `True`) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is `True`.

• prune_unapplied (`Union`[`bool`, `Container`], default: `False`) – Whether to prune key_chains for which the function was not applied. Default is `False`.

• map_sequences (`Union`[`bool`, `Container`], default: `False`) – Whether to also map method to sequences (lists, tuples). Default is `False`.

• out (`Optional`[`Container`], default: `None`) – optional output container, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

`Container`

Returns:

ret – a container containing the element-wise results. The returned container must have a data type determined by type-promotion.

Examples

With `ivy.Container` input:

```>>> x = ivy.Container(a=ivy.array([0, 1]), b=ivy.array([2, 3]))
>>> y = x.pow(3)
>>> print(y)
{
a:ivy.array([0,1]),
b:ivy.array([8,27])
}
```