Merge branch 'main' into 217

data-apis · kgryte · Sep 20, 2021 · Jul 14, 2021 · Jul 15, 2021 · Sep 20, 2021
commit 093b226c2836bd936d057227ffb436d463da1b2e
diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md
@@ -563,3 +563,49 @@ Returns the sum along the specified diagonals of a matrix (or a stack of matrice
 ### linalg.vecdot(x1, x2, /, *, axis=None)
 
 Alias for {ref}`function-vecdot`.
+
+(function-linalg-vector-norm)=
+### linalg.vector_norm(x, /, *, axis=None, keepdims=False, ord=2)
+
+Computes the vector norm of a vector (or batch of vectors) `x`.
+
+#### Parameters
+
+-   **x**: _&lt;array&gt;_
+
+    -   input array. Should have a floating-point data type.
+
+-   **axis**: _Optional\[ Union\[ int, Tuple\[ int, int ] ] ]_
+
+    -   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 must be supported. Default: `None`.
+
+-   **keepdims**: _bool_
+
+    -   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**: _Optional\[ Union\[  int, float, Literal\[ inf, -inf ] ] ]_
+
+    -   order of the norm. The following mathematical norms must be supported:
+        | ord              | description                |
+        | ---------------- | -------------------------- |
+        | 1                | L1-norm (Manhattan)        |
+        | 2                | L2-norm (Euclidean)        |
+        | inf              | infinity norm              |
+        | (int,float >= 1) | p-norm                     |
+
+        The following non-mathematical "norms" must be supported:
+        | ord              | description                    |
+        | ---------------- | ------------------------------ |
+        | 0                | sum(a != 0)                    |
+        | -1               | 1./sum(1./abs(a))              |
+        | -2               | 1./sqrt(sum(1./abs(a)\*\*2))   |
+        | -inf             | min(abs(a))                    |
+        | (int,float < 1)  | sum(abs(a)\*\*ord)\*\*(1./ord) |
+
+        Default: `2`.
+
+#### Returns
+
+-   **out**: _&lt;array&gt;_
+
+    -   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 `x`. If `axis` is a `n`-tuple, the returned array must have a rank which is `n` less than the rank of `x`. The returned array must have a floating-point data type determined by {ref}`type-promotion`.