diff --git a/ivy/array/linear_algebra.py b/ivy/array/linear_algebra.py index 8ca5b248a1c7f..624063290ca39 100644 --- a/ivy/array/linear_algebra.py +++ b/ivy/array/linear_algebra.py @@ -878,6 +878,82 @@ def vector_norm( dtype: Optional[Union[ivy.Dtype, ivy.NativeDtype]] = None, out: Optional[ivy.Array] = None, ) -> ivy.Array: + """ + ivy.Array instance method variant of ivy.vector_norm. + This method computes the vector norm of a vector (or batch of vectors). + + Parameters + ---------- + self + Input array. Should have a floating-point data type. + axis + If an integer, ``axis`` specifies the axis (dimension) along which to + compute vector norms. If an n-tuple, ``axis`` specifies the axes + (dimensions) along which to compute batched vector norms. If ``None``, + the vector norm must be computed over all array values (i.e., equivalent + to computing the vector norm of a flattened array). Negative indices are + also supported. Default: ``None``. + keepdims + If ``True``, the axes (dimensions) specified by ``axis`` must be included + in the result as singleton dimensions, and, accordingly, the result must be + compatible with the input array (see :ref:`broadcasting`). Otherwise, if + ``False``, the axes (dimensions) specified by ``axis`` must not be included + in the result. + Default: ``False``. + ord + order of the norm. The following mathematical norms are supported: + + +------------------+----------------------------+ + | ord | description | + +==================+============================+ + | 1 | L1-norm (Manhattan) | + +------------------+----------------------------+ + | 2 | L2-norm (Euclidean) | + +------------------+----------------------------+ + | inf | infinity norm | + +------------------+----------------------------+ + | (int,float >= 1) | p-norm | + +------------------+----------------------------+ + + The following non-mathematical "norms" are also supported: + + +------------------+--------------------------------+ + | ord | description | + +==================+================================+ + | 0 | sum(a != 0) | + +------------------+--------------------------------+ + | -inf | min(abs(a)) | + +------------------+--------------------------------+ + | (int,float < 1) | sum(abs(a)**ord)**(1./ord) | + +------------------+--------------------------------+ + + Default: ``2``. + dtype + data type that may be used to perform the computation more precisely. + The input array ``self`` gets cast to ``dtype`` before the function's + computations. + out + optional output array, for writing the result to. It must have a shape + that the inputs broadcast to. + + Returns + ------- + ret + an array containing the vector norms. If ``axis`` is ``None``, the returned + array must be a zero-dimensional array containing a vector norm. If ``axis`` + is a scalar value (``int`` or ``float``), the returned array must have a + rank which is one less than the rank of ``self``. If ``axis`` is a + ``n``-tuple, the returned array must have a rank which is ``n`` less than + the rank of ``self``. The returned array must have a floating-point data + type determined by :ref:`type-promotion`. + + Examples + -------- + >>> x = ivy.array([1., 2., 3.]) + >>> y = x.vector_norm() + >>> print(y) + ivy.array([3.7416575]) + """ return ivy.vector_norm( self._data, axis=axis, keepdims=keepdims, ord=ord, dtype=dtype, out=out ) diff --git a/ivy/container/linear_algebra.py b/ivy/container/linear_algebra.py index 1e2637f552eeb..68468b290da9f 100644 --- a/ivy/container/linear_algebra.py +++ b/ivy/container/linear_algebra.py @@ -2698,6 +2698,15 @@ def static_vector_norm( array must have a floating-point data type determined by :ref:`type-promotion`. + Examples + -------- + >>> x = ivy.Container(a = [1., 2., 3.], b = [-2., 0., 3.2]) + >>> y = ivy.Container.static_vector_norm(x) + >>> print(y) + { + a: ivy.array([3.7416575]), + b: ivy.array([3.77359247]) + } """ return ContainerBase.cont_multi_map_in_function( "vector_norm", @@ -2802,6 +2811,15 @@ def vector_norm( ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + Examples + -------- + >>> x = ivy.Container(a = [1., 2., 3.], b = [-2., 0., 3.2]) + >>> y = x.vector_norm() + >>> print(y) + { + a: ivy.array([3.7416575]), + b: ivy.array([3.77359247]) + } """ return self.static_vector_norm( self, diff --git a/ivy/functional/ivy/linear_algebra.py b/ivy/functional/ivy/linear_algebra.py index 7b5a6a5fbd3ec..d80125c8760e1 100644 --- a/ivy/functional/ivy/linear_algebra.py +++ b/ivy/functional/ivy/linear_algebra.py @@ -2448,6 +2448,53 @@ def vector_norm( but this function is *nestable*, and therefore also accepts :class:`ivy.Container` instances in place of any of the arguments. + Examples + -------- + >>> x = ivy.array([1., 2., 3.]) + >>> y = ivy.vector_norm(x) + >>> print(y) + ivy.array([3.7416575]) + + >>> x = ivy.array([[1, 2, 3], [1.3, 2.4, -1.2]]) + >>> y = ivy.vector_norm(x, axis = 1, ord = 1, dtype = ivy.float32) + >>> print(y) + ivy.array([6., 4.9000001]) + + >>> x = ivy.array([[1, 2, 3], [1.3, 2.4, -1.2]]) + >>> y = ivy.vector_norm(x, axis = 0, keepdims = True, ord = float("inf")) + >>> print(y) + + ivy.array([[1.3, 2.4, 3.]]) + + >>> x = ivy.native_array([1, 2, 3, 4], dtype = ivy.float32) + >>> y = ivy.vector_norm(x, ord = 3.) + >>> print(y) + + ivy.array([4.64158917]) + + >>> x = ivy.array([1,2,3,4], dtype = ivy.float16) + >>> z = ivy.empty(shape = 1) + >>> print(z) + ivy.array([0. , 2. , 0. , 2.25]) + >>> y = ivy.vector_norm(x, ord = 0, out = z) + >>> print(z) + ivy.array([4.]) + >>> print(y) + ivy.array([4.]) + + >>> x = ivy.arange(8).reshape((2,2,2)) + >>> y = ivy.vector_norm(x, axis = (0,1), ord = float("-inf")) + >>> print(y) + ivy.array([2, 4]) + + >>> x = ivy.Container(a = [-1., 1., -2., 2.], b = [0., 1.2, 2.3, -3.1]) + >>> y = ivy.vector_norm(x, ord = -1) + >>> print(y) + { + a: ivy.array([0.33333334]), + b: ivy.array([0.]) + } + """ return current_backend(x).vector_norm( x, axis=axis, keepdims=keepdims, ord=ord, dtype=dtype, out=out