Document for Cholesky decomposition

Author: termoshtt

lax/src/cholesky.rs

@@ -1,21 +1,68 @@
-//! Cholesky decomposition
-
 use super::*;
 use crate::{error::*, layout::*};
 use cauchy::*;
 
+#[cfg_attr(doc, katexit::katexit)]
+/// Solve symmetric/hermite positive-definite linear equations using Cholesky decomposition
+///
+/// For a given positive definite matrix $A$,
+/// Cholesky decomposition is described as $A = U^T U$ or $A = LL^T$ where
+///
+/// - $L$ is lower matrix
+/// - $U$ is upper matrix
+///
+/// This is designed as two step computation according to LAPACK API
+///
+/// 1. Factorize input matrix $A$ into $L$ or $U$
+/// 2. Solve linear equation $Ax = b$ or compute inverse matrix $A^{-1}$
+///    using $U$ or $L$.
 pub trait Cholesky_: Sized {
-    /// Cholesky: wrapper of `*potrf`
+    /// Compute Cholesky decomposition $A = U^T U$ or $A = L L^T$ according to [UPLO]
+    ///
+    /// LAPACK correspondance
+    /// ----------------------
+    ///
+    /// | f32      | f64      | c32      | c64      |
+    /// |:---------|:---------|:---------|:---------|
+    /// | [spotrf] | [dpotrf] | [cpotrf] | [zpotrf] |
+    ///
+    /// [spotrf]: https://netlib.org/lapack/explore-html/d8/db2/group__real_p_ocomputational_gaaf31db7ab15b4f4ba527a3d31a15a58e.html
+    /// [dpotrf]: https://netlib.org/lapack/explore-html/d1/d7a/group__double_p_ocomputational_ga2f55f604a6003d03b5cd4a0adcfb74d6.html
+    /// [cpotrf]: https://netlib.org/lapack/explore-html/d8/d6c/group__variants_p_ocomputational_ga4e85f48dbd837ccbbf76aa077f33de19.html
+    /// [zpotrf]: https://netlib.org/lapack/explore-html/d3/d8d/group__complex16_p_ocomputational_ga93e22b682170873efb50df5a79c5e4eb.html
     ///
-    /// **Warning: Only the portion of `a` corresponding to `UPLO` is written.**
     fn cholesky(l: MatrixLayout, uplo: UPLO, a: &mut [Self]) -> Result<()>;
 
-    /// Wrapper of `*potri`
+    /// Compute inverse matrix $A^{-1}$ using $U$ or $L$
+    ///
+    /// LAPACK correspondance
+    /// ----------------------
+    ///
+    /// | f32      | f64      | c32      | c64      |
+    /// |:---------|:---------|:---------|:---------|
+    /// | [spotri] | [dpotri] | [cpotri] | [zpotri] |
+    ///
+    /// [spotri]: https://netlib.org/lapack/explore-html/d8/db2/group__real_p_ocomputational_ga4c381894bb34b1583fcc0dceafc5bea1.html
+    /// [dpotri]: https://netlib.org/lapack/explore-html/d1/d7a/group__double_p_ocomputational_ga9dfc04beae56a3b1c1f75eebc838c14c.html
+    /// [cpotri]: https://netlib.org/lapack/explore-html/d6/df6/group__complex_p_ocomputational_ga52b8da4d314abefaee93dd5c1ed7739e.html
+    /// [zpotri]: https://netlib.org/lapack/explore-html/d3/d8d/group__complex16_p_ocomputational_gaf37e3b8bbacd3332e83ffb3f1018bcf1.html
     ///
-    /// **Warning: Only the portion of `a` corresponding to `UPLO` is written.**
     fn inv_cholesky(l: MatrixLayout, uplo: UPLO, a: &mut [Self]) -> Result<()>;
 
-    /// Wrapper of `*potrs`
+    /// Solve linear equation $Ax = b$ using $U$ or $L$
+    ///
+    /// LAPACK correspondance
+    /// ----------------------
+    ///
+    /// | f32      | f64      | c32      | c64      |
+    /// |:---------|:---------|:---------|:---------|
+    /// | [spotrs] | [dpotrs] | [cpotrs] | [zpotrs] |
+    ///
+    /// [spotrs]: https://netlib.org/lapack/explore-html/d8/db2/group__real_p_ocomputational_gaf5cc1531aa5ffe706533fbca343d55dd.html
+    /// [dpotrs]: https://netlib.org/lapack/explore-html/d1/d7a/group__double_p_ocomputational_ga167aa0166c4ce726385f65e4ab05e7c1.html
+    /// [cpotrs]: https://netlib.org/lapack/explore-html/d6/df6/group__complex_p_ocomputational_gad9052b4b70569dfd6e8943971c9b38b2.html
+    /// [zpotrs]: https://netlib.org/lapack/explore-html/d3/d8d/group__complex16_p_ocomputational_gaa2116ea574b01efda584dff0b74c9fcd.html
+    ///
     fn solve_cholesky(l: MatrixLayout, uplo: UPLO, a: &[Self], b: &mut [Self]) -> Result<()>;
 }
 

lax/src/lib.rs

@@ -49,7 +49,8 @@
 //! According to the property input metrix, several types of triangular factorization are used:
 //!
 //! - [Solve_] trait provides methods for LU-decomposition for general matrix.
-//! - [Solveh_] triat provides methods for Bunch-Kaufman diagonal pivoting method for symmetric/hermite indefinite matrix
+//! - [Solveh_] triat provides methods for Bunch-Kaufman diagonal pivoting method for symmetric/hermite indefinite matrix.
+//! - [Cholesky_] triat provides methods for Cholesky decomposition for symmetric/hermite positive dinite matrix.
 //!
 //! Eigenvalue Problem
 //! -------------------