Add SVD function specification (#114)

* Add SVD spec

* Update spec

* Update to follow NumPy

* Fix annotation

* Update type

* Update descriptions

* Update annotation

* Return a tuple only when `compute_uv` is `True`

* Fix type annotation

* Update copy

Co-authored-by: Leo Fang <[email protected]>

* Update copy

Co-authored-by: Leo Fang <[email protected]>

* Update copy

Co-authored-by: Leo Fang <[email protected]>

* Update copy

Co-authored-by: Leo Fang <[email protected]>

* Fix docs

* Update dtype requirements

* Update copy

* Always return u and v singular vectors

* Update return type

* Add article

* Move API to submodule

Co-authored-by: Leo Fang <[email protected]>

Author: kgryte

spec/API_specification/linear_algebra_functions.md

@@ -343,10 +343,32 @@ Returns the solution to the system of linear equations represented by the well-d
 
     -   an array containing the solution to the system `AX = B` for each square matrix. The returned array must have the same shape as `x2` (i.e., the array corresponding to `B`) and must have a floating-point data type determined by {ref}`type-promotion`.
 
-(function-svd)=
-### svd()
+(function-linalg-svd)=
+### linalg.svd(x, /, *, full_matrices=True)
 
-TODO
+Computes the singular value decomposition `A = USV` of a matrix (or a stack of matrices) `x`.
+
+#### Parameters
+
+-   **x**: _<array>_
+
+    -   input array having shape `(..., M, N)` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a floating-point data type.
+
+-   **full_matrices**: _bool_
+
+    -   If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., K, N)` and where `K = min(M, N)`. Default: `True`.
+
+#### Returns
+
+-   **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_
+
+    -   a namedtuple `(u, s, v)` whose
+    
+        -   first element must be an array whose shape depends on the value of `full_matrices` and contain unitary array(s) (i.e., the left singular vectors). The left singular vectors must be stored as columns. If `full_matrices` is `True`, the array must have shape `(..., M, M)`. If `full_matrices` is `False`, the array must have shape `(..., M, K)`, where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`.
+        -   second element must be an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`. For each vector, the singular values must be sorted in descending order by magnitude, such that `s[..., 0]` is the largest value, `s[..., 1]` is the second largest value, et cetera. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`.
+        -   third element must be an array whose shape depends on the value of `full_matrices` and contain unitary array(s) (i.e., the right singular vectors). The right singular vectors must be stored as rows (i.e., the array is the adjoint). If `full_matrices` is `True`, the array must have shape `(..., N, N)`. If `full_matrices` is `False`, the array must have shape `(..., K, N)` where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`.
+
+        Each returned array must have the same floating-point data type as `x`.
 
 (function-tensordot)=
 ### tensordot(x1, x2, /, *, axes=2)