# matrix_norm#

ivy.matrix_norm(x, /, *, ord='fro', axis=(-2, -1), keepdims=False, out=None)[source]#

Compute the matrix p-norm.

Parameters:
• x (`Union`[`Array`, `NativeArray`]) – Input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices. Should have a floating-point data type.

• ord (`Union`[`int`, `float`, `Literal`[`inf`, `-inf`, `'fro'`, `'nuc'`]], default: `'fro'`) –

order of the norm. The following mathematical norms must be supported:

ord

description

’fro’

Frobenius norm

’nuc’

nuclear norm

1

max(sum(abs(x), axis=0))

2

largest singular value

inf

max(sum(abs(x), axis=1))

The following non-mathematical “norms” must be supported:

ord

description

-1

min(sum(abs(x), axis=0))

-2

smallest singular value

-inf

min(sum(abs(x), axis=1))

If `ord=1`, the norm corresponds to the induced matrix norm where `p=1` (i.e., the maximum absolute value column sum).

If `ord=2`, the norm corresponds to the induced matrix norm where `p=inf` (i.e., the maximum absolute value row sum).

If `ord=inf`, the norm corresponds to the induced matrix norm where `p=2` (i.e., the largest singular value).

Default: “fro”.

• axis (`Tuple`[`int`, `int`], default: `(-2, -1)`) – specifies the axes that hold 2-D matrices. Default: (-2, -1).

• keepdims (`bool`, default: `False`) – If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original x. Default is `False`.

• 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 – Matrix norm of the array at specified axes. If `keepdims` is `False`, the returned array must have a rank which is two less than the ranl of `x`. If `x` has a real-valued data type, the returned array must have a real-valued floating-point data type based on Type promotion. If `x` has a complex-valued data type, the returned array must have a real-valued floating-point data type whose precision matches the precision of `x` (e.g., if `x` is `complex128`, then the returned array must have a float64` 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 arguments.

Examples

With `ivy.Array` inputs:

```>>> x = ivy.array([[1., 2.], [3., 4.]])
>>> y = ivy.matrix_norm(x)
>>> print(y)
ivy.array(5.47722558)
```
```>>> x = ivy.arange(8, dtype=float).reshape((2, 2, 2))
>>> y = ivy.zeros(2)
>>> ivy.matrix_norm(x, ord=1, out=y)
>>> print(y)
ivy.array([ 4., 12.])
```
```>>> x = ivy.arange(12, dtype=float).reshape((3, 2, 2))
>>> y = ivy.zeros((3,))
>>> ivy.matrix_norm(x, ord=ivy.inf, axis=(2, 1), out=y)
>>> print(y)
ivy.array([ 4., 12., 20.])
```
```>>> x = ivy.array([[1.1, 2.2], [3.3, 4.4], [5.5, 6.6]])
>>> y = ivy.matrix_norm(x, ord='nuc', keepdims=True)
>>> print(y)
ivy.array([[11.]])
```
```>>> x = ivy.array([[[1.1, 2.2, 3.3], [4.4, 5.5, 6.6]],
...                 [[1., 0., 1.1], [1., 1., 0.]]])
>>> y = ivy.zeros((2,))
>>> ivy.matrix_norm(x, ord='fro', out=y)
>>> print(y)
ivy.array([10.5 ,  2.05])
```

With `ivy.Container` input:

```>>> x = ivy.Container(a=ivy.array([[0.666, 9.11],
...                                [42.69, 9.23]]),
...                   b=ivy.array([[1.1, 2.2, 3.3],
...                                [4.4, 5.5, 6.6]]))
>>> y = ivy.matrix_norm(x, ord=-ivy.inf)
>>> print(y)
{
a: ivy.array(9.776),
b: ivy.array(6.6000004)
}
```

With multiple `ivy:Container` inputs:

```>>> x = ivy.Container(a=ivy.arange(12, dtype=float).reshape((3, 2, 2)),
...                   b=ivy.arange(8, dtype=float).reshape((2, 2, 2)))
>>> ord = ivy.Container(a=1, b=float('inf'))
>>> axis = ivy.Container(a=(1, 2), b=(2, 1))
>>> k = ivy.Container(a=False, b=True)
>>> y = ivy.matrix_norm(x, ord=ord, axis=axis, keepdims=k)
>>> print(y)
{
a: ivy.array([4., 12., 20.]),
b: ivy.array([[[4.]],
[[12.]]])
}
```
Array.matrix_norm(self, /, *, ord='fro', axis=(-2, -1), keepdims=False, out=None)[source]#

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

Parameters:
• self (`Array`) – Input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices. Should have a floating-point data type.

• ord (`Union`[`int`, `float`, `Literal`[`inf`, `-inf`, `'fro'`, `'nuc'`]], default: `'fro'`) – Order of the norm. Default is “fro”.

• axis (`Tuple`[`int`, `int`], default: `(-2, -1)`) – specifies the axes that hold 2-D matrices. Default: (-2, -1).

• keepdims (`bool`, default: `False`) – If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original x. Default is False.

• 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 – Matrix norm of the array at specified axes.

Examples

```>>> x = ivy.array([[1.1, 2.2, 3.3], [1.0, 2.0, 3.0]])
>>> y = x.matrix_norm(ord=1)
>>> print(y)
ivy.array(6.3)
```
```>>> x = ivy.arange(8, dtype=float).reshape((2, 2, 2))
>>> y = x.matrix_norm(ord="nuc", keepdims=True)
>>> print(y)
ivy.array([[[ 4.24]],
[[11.4 ]]])
```
Container.matrix_norm(self, /, *, ord='fro', axis=(-2, -1), keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

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

Parameters:
• self (`Container`) – Container having shape (…, M, N) and whose innermost two dimensions form MxN matrices. Should have a floating-point data type.

• ord (`Union`[`int`, `float`, `Literal`[`inf`, `-inf`, `'fro'`, `'nuc'`], `Container`], default: `'fro'`) – Order of the norm. Default is “fro”.

• axis (`Tuple`[`int`, `int`, `Container`], default: `(-2, -1)`) – specifies the axes that hold 2-D matrices. Default: (-2, -1).

• keepdims (`Union`[`bool`, `Container`], default: `False`) – If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original x. Default is `False`.

• 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 array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

`Container`

Returns:

ret – Matrix norm of the array at specified axes.

Examples

```>>> x = ivy.Container(a=ivy.array([[1.1, 2.2], [1., 2.]]),                               b=ivy.array([[1., 2.], [3., 4.]]))
>>> y = x.matrix_norm(ord=1)
>>> print(y)
{
a: ivy.array(4.2),
b: ivy.array(6.)
}
```
```>>> x = ivy.Container(a=ivy.arange(12, dtype=float).reshape((3, 2, 2)),                               b=ivy.arange(8, dtype=float).reshape((2, 2, 2)))
>>> ord = ivy.Container(a="nuc", b=ivy.inf)
>>> axis = ivy.Container(a=(1, 2), b=(2, 1))
>>> k = ivy.Container(a=True, b=False)
>>> y = x.matrix_norm(ord=ord, axis=axis, keepdims=k)
>>> print(y)
{
a: ivy.array([[[4.24]],
[[11.4]],
[[19.2]]]),
b: ivy.array([4., 12.])
}
```