Update document about SVD

rust-ndarray · Sep 8, 2022 · a739565 · a739565
1 parent 0d89696
commit a739565
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 11 deletions.
diff --git a/lax/src/least_squares.rs b/lax/src/least_squares.rs
@@ -12,14 +12,19 @@ pub struct LeastSquaresOutput<A: Scalar> {
     pub rank: i32,
 }
 
-/// Wraps `*gelsd`
+#[cfg_attr(doc, katexit::katexit)]
+/// Solve least square problem
 pub trait LeastSquaresSvdDivideConquer_: Scalar {
+    /// Compute a vector $x \in \mathbb{R}^n$
+    /// which minimizes Euclidian norm $\| Ax - b\|$
+    /// for a given matrix $A$ and a vector $b$.
     fn least_squares(
         a_layout: MatrixLayout,
         a: &mut [Self],
         b: &mut [Self],
     ) -> Result<LeastSquaresOutput<Self>>;
 
+    /// Solve least square problems $\argmin_X \| AX - B\|$
     fn least_squares_nrhs(
         a_layout: MatrixLayout,
         a: &mut [Self],

diff --git a/lax/src/lib.rs b/lax/src/lib.rs
@@ -61,16 +61,15 @@
 //! - [Eig_] trait provides methods for eigenvalue problem for general matrix.
 //! - [Eigh_] trait provides methods for eigenvalue problem for symmetric/hermite matrix.
 //!
-//! Singular Value Decomposition (SVD), Least square problem
-//! ----------------------------------------------------------
+//! Singular Value Decomposition
+//! -----------------------------
 //!
-//! | matrix type  | Singular Value Decomposition (SVD) | SVD with divided-and-conquer (SDD) | Least square problem (LSD) |
-//! |:-------------|:-----------------------------------|:-----------------------------------|:---------------------------|
-//! | General (GE) | [svd]                              | [svddc]                            | [least_squares]            |
+//! - [SVD_] trait provides methods for singular value decomposition for general matrix
+//! - [SVDDC_] trait provides methods for singular value decomposition for general matrix
+//!   with divided-and-conquer algorithm
+//! - [LeastSquaresSvdDivideConquer_] trait provides methods
+//!   for solving least square problem by SVD
 //!
-//! [svd]:   svd/trait.SVD_.html#tymethod.svd
-//! [svddc]: svddck/trait.SVDDC_.html#tymethod.svddc
-//! [least_squares]: least_squares/trait.LeastSquaresSvdDivideConquer_.html#tymethod.least_squares
 
 #[cfg(any(feature = "intel-mkl-system", feature = "intel-mkl-static"))]
 extern crate intel_mkl_src as _src;

diff --git a/lax/src/svd.rs b/lax/src/svd.rs
@@ -14,9 +14,18 @@ pub struct SVDOutput<A: Scalar> {
     pub vt: Option<Vec<A>>,
 }
 
-/// Wraps `*gesvd`
+#[cfg_attr(doc, katexit::katexit)]
+/// Singular value decomposition
 pub trait SVD_: Scalar {
-    /// Calculate singular value decomposition $ A = U \Sigma V^T $
+    /// Compute singular value decomposition $A = U \Sigma V^T$
+    ///
+    /// LAPACK correspondance
+    /// ----------------------
+    ///
+    /// | f32    | f64    | c32    | c64    |
+    /// |:-------|:-------|:-------|:-------|
+    /// | sgesvd | dgesvd | cgesvd | zgesvd |
+    ///
     fn svd(l: MatrixLayout, calc_u: bool, calc_vt: bool, a: &mut [Self])
         -> Result<SVDOutput<Self>>;
 }

diff --git a/lax/src/svddc.rs b/lax/src/svddc.rs
@@ -2,7 +2,18 @@ use crate::{error::*, layout::MatrixLayout, *};
 use cauchy::*;
 use num_traits::{ToPrimitive, Zero};
 
+#[cfg_attr(doc, katexit::katexit)]
+/// Singular value decomposition with divide-and-conquer method
 pub trait SVDDC_: Scalar {
+    /// Compute singular value decomposition $A = U \Sigma V^T$
+    ///
+    /// LAPACK correspondance
+    /// ----------------------
+    ///
+    /// | f32    | f64    | c32    | c64    |
+    /// |:-------|:-------|:-------|:-------|
+    /// | sgesdd | dgesdd | cgesdd | zgesdd |
+    ///
     fn svddc(l: MatrixLayout, jobz: JobSvd, a: &mut [Self]) -> Result<SVDOutput<Self>>;
 }