matrix_norm#

ivy.matrix_norm(x, /, *, ord='fro', axis=(-2, -1), keepdims=False, dtype=None, 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.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – If specified, the input tensor is cast to dtype before performing the operation, and the returned tensor’s type will be dtype. Default: None
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:

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

ord	description
-1	min(sum(abs(x), axis=0))
-2	smallest singular value
-inf	min(sum(abs(x), axis=1))

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, dtype=None, 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.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – If specified, the input tensor is cast to dtype before performingthe operation, and the returned tensor’s type will be dtype. Default: None
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, dtype=None, 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.
dtype (Optional[Union[Dtype, NativeDtype, Container]], default: None) – If specified, the input tensor is cast to dtype before performing the operation, and the returned tensor’s type will be dtype. Default: None
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.])
}