Skip to content

Commit 991a744

Browse files
termoshtttermoshtt
authored
Merge pull request #330 from rust-ndarray/katexit
Revise lax document with katexit
2 parents a4b3118 + c25cc23 commit 991a744

16 files changed

+257
-121
lines changed

‎.github/workflows/gh-pages.yml

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,6 @@ jobs:
4040
with:
4141
command: doc
4242
args: --no-deps
43-
env:
44-
RUSTDOCFLAGS: "--html-in-header ndarray-linalg/katex-header.html"
4543

4644
- name: Setup Pages
4745
uses: actions/configure-pages@v2

‎lax/Cargo.toml

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ thiserror = "1.0.24"
3333
cauchy = "0.4.0"
3434
num-traits = "0.2.14"
3535
lapack-sys = "0.14.0"
36+
katexit = "0.1.2"
3637

3738
[dependencies.intel-mkl-src]
3839
version = "0.7.0"
@@ -50,6 +51,3 @@ version = "0.10.4"
5051
optional = true
5152
default-features = false
5253
features = ["cblas"]
53-
54-
[package.metadata.docs.rs]
55-
rustdoc-args = ["--html-in-header", "katex-header.html"]

‎lax/katex-header.html

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎lax/src/cholesky.rs

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,53 @@
1-
//! Cholesky decomposition
2-
31
use super::*;
42
use crate::{error::*, layout::*};
53
use cauchy::*;
64

5+
#[cfg_attr(doc, katexit::katexit)]
6+
/// Solve symmetric/hermite positive-definite linear equations using Cholesky decomposition
7+
///
8+
/// For a given positive definite matrix $A$,
9+
/// Cholesky decomposition is described as $A = U^T U$ or $A = LL^T$ where
10+
///
11+
/// - $L$ is lower matrix
12+
/// - $U$ is upper matrix
13+
///
14+
/// This is designed as two step computation according to LAPACK API
15+
///
16+
/// 1. Factorize input matrix $A$ into $L$ or $U$
17+
/// 2. Solve linear equation $Ax = b$ or compute inverse matrix $A^{-1}$
18+
/// using $U$ or $L$.
719
pub trait Cholesky_: Sized {
8-
/// Cholesky: wrapper of `*potrf`
20+
/// Compute Cholesky decomposition $A = U^T U$ or $A = L L^T$ according to [UPLO]
21+
///
22+
/// LAPACK correspondance
23+
/// ----------------------
24+
///
25+
/// | f32 | f64 | c32 | c64 |
26+
/// |:-------|:-------|:-------|:-------|
27+
/// | spotrf | dpotrf | cpotrf | zpotrf |
928
///
10-
/// **Warning: Only the portion of `a` corresponding to `UPLO` is written.**
1129
fn cholesky(l: MatrixLayout, uplo: UPLO, a: &mut [Self]) -> Result<()>;
1230

13-
/// Wrapper of `*potri`
31+
/// Compute inverse matrix $A^{-1}$ using $U$ or $L$
32+
///
33+
/// LAPACK correspondance
34+
/// ----------------------
35+
///
36+
/// | f32 | f64 | c32 | c64 |
37+
/// |:-------|:-------|:-------|:-------|
38+
/// | spotri | dpotri | cpotri | zpotri |
1439
///
15-
/// **Warning: Only the portion of `a` corresponding to `UPLO` is written.**
1640
fn inv_cholesky(l: MatrixLayout, uplo: UPLO, a: &mut [Self]) -> Result<()>;
1741

18-
/// Wrapper of `*potrs`
42+
/// Solve linear equation $Ax = b$ using $U$ or $L$
43+
///
44+
/// LAPACK correspondance
45+
/// ----------------------
46+
///
47+
/// | f32 | f64 | c32 | c64 |
48+
/// |:-------|:-------|:-------|:-------|
49+
/// | spotrs | dpotrs | cpotrs | zpotrs |
50+
///
1951
fn solve_cholesky(l: MatrixLayout, uplo: UPLO, a: &[Self], b: &mut [Self]) -> Result<()>;
2052
}
2153

‎lax/src/eig.rs

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,19 @@
1-
//! Eigenvalue decomposition for general matrices
2-
31
use crate::{error::*, layout::MatrixLayout, *};
42
use cauchy::*;
53
use num_traits::{ToPrimitive, Zero};
64

7-
/// Wraps `*geev` for general matrices
5+
#[cfg_attr(doc, katexit::katexit)]
6+
/// Eigenvalue problem for general matrix
87
pub trait Eig_: Scalar {
9-
/// Calculate Right eigenvalue
8+
/// Compute right eigenvalue and eigenvectors $Ax = \lambda x$
9+
///
10+
/// LAPACK correspondance
11+
/// ----------------------
12+
///
13+
/// | f32 | f64 | c32 | c64 |
14+
/// |:------|:------|:------|:------|
15+
/// | sgeev | dgeev | cgeev | zgeev |
16+
///
1017
fn eig(
1118
calc_v: bool,
1219
l: MatrixLayout,

‎lax/src/eigh.rs

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,36 @@
1-
//! Eigenvalue decomposition for Symmetric/Hermite matrices
2-
31
use super::*;
42
use crate::{error::*, layout::MatrixLayout};
53
use cauchy::*;
64
use num_traits::{ToPrimitive, Zero};
75

6+
#[cfg_attr(doc, katexit::katexit)]
7+
/// Eigenvalue problem for symmetric/hermite matrix
88
pub trait Eigh_: Scalar {
9-
/// Wraps `*syev` for real and `*heev` for complex
9+
/// Compute right eigenvalue and eigenvectors $Ax = \lambda x$
10+
///
11+
/// LAPACK correspondance
12+
/// ----------------------
13+
///
14+
/// | f32 | f64 | c32 | c64 |
15+
/// |:------|:------|:------|:------|
16+
/// | ssyev | dsyev | cheev | zheev |
17+
///
1018
fn eigh(
1119
calc_eigenvec: bool,
1220
layout: MatrixLayout,
1321
uplo: UPLO,
1422
a: &mut [Self],
1523
) -> Result<Vec<Self::Real>>;
1624

17-
/// Wraps `*sygv` for real and `*hegv` for complex
25+
/// Compute generalized right eigenvalue and eigenvectors $Ax = \lambda B x$
26+
///
27+
/// LAPACK correspondance
28+
/// ----------------------
29+
///
30+
/// | f32 | f64 | c32 | c64 |
31+
/// |:------|:------|:------|:------|
32+
/// | ssygv | dsygv | chegv | zhegv |
33+
///
1834
fn eigh_generalized(
1935
calc_eigenvec: bool,
2036
layout: MatrixLayout,

‎lax/src/flags.rs

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,17 +92,19 @@ impl JobEv {
9292
}
9393
}
9494

95-
/// Specifies how many of the columns of *U* and rows of *V*ᵀ are computed and returned.
95+
/// Specifies how many singular vectors are computed
9696
///
97-
/// For an input array of shape *m*×*n*, the following are computed:
97+
/// For an input matrix $A$ of shape $m \times n$,
98+
/// the following are computed on the singular value decomposition $A = U\Sigma V^T$:
99+
#[cfg_attr(doc, katexit::katexit)]
98100
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
99101
#[repr(u8)]
100102
pub enum JobSvd {
101-
/// All *m* columns of *U* and all *n* rows of *V*ᵀ.
103+
/// All $m$ columns of $U$, and/or all $n$ rows of $V^T$.
102104
All = b'A',
103-
/// The first min(*m*,*n*) columns of *U* and the first min(*m*,*n*) rows of *V*ᵀ.
105+
/// The first $\min(m, n)$ columns of $U$ and/or the first $\min(m, n)$ rows of $V^T$.
104106
Some = b'S',
105-
/// No columns of *U* or rows of *V*ᵀ.
107+
/// No columns of $U$ and/or rows of $V^T$.
106108
None = b'N',
107109
}
108110

‎lax/src/least_squares.rs

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,18 @@ pub struct LeastSquaresOutput<A: Scalar> {
1212
pub rank: i32,
1313
}
1414

15-
/// Wraps `*gelsd`
15+
#[cfg_attr(doc, katexit::katexit)]
16+
/// Solve least square problem
1617
pub trait LeastSquaresSvdDivideConquer_: Scalar {
18+
/// Compute a vector $x$ which minimizes Euclidian norm $\| Ax - b\|$
19+
/// for a given matrix $A$ and a vector $b$.
1720
fn least_squares(
1821
a_layout: MatrixLayout,
1922
a: &mut [Self],
2023
b: &mut [Self],
2124
) -> Result<LeastSquaresOutput<Self>>;
2225

26+
/// Solve least square problems $\argmin_X \| AX - B\|$
2327
fn least_squares_nrhs(
2428
a_layout: MatrixLayout,
2529
a: &mut [Self],

‎lax/src/lib.rs

Lines changed: 55 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,75 @@
1-
//! Linear Algebra eXtension (LAX)
2-
//! ===============================
3-
//!
41
//! ndarray-free safe Rust wrapper for LAPACK FFI
52
//!
6-
//! Linear equation, Inverse matrix, Condition number
7-
//! --------------------------------------------------
3+
//! `Lapack` trait and sub-traits
4+
//! -------------------------------
85
//!
9-
//! As the property of $A$, several types of triangular factorization are used:
6+
//! This crates provides LAPACK wrapper as `impl` of traits to base scalar types.
7+
//! For example, LU decomposition to double-precision matrix is provided like:
108
//!
11-
//! - LU-decomposition for general matrix
12-
//! - $PA = LU$, where $L$ is lower matrix, $U$ is upper matrix, and $P$ is permutation matrix
13-
//! - Bunch-Kaufman diagonal pivoting method for nonpositive-definite Hermitian matrix
14-
//! - $A = U D U^\dagger$, where $U$ is upper matrix,
15-
//! $D$ is Hermitian and block diagonal with 1-by-1 and 2-by-2 diagonal blocks.
9+
//! ```ignore
10+
//! impl Solve_ for f64 {
11+
//! fn lu(l: MatrixLayout, a: &mut [Self]) -> Result<Pivot> { ... }
12+
//! }
13+
//! ```
1614
//!
17-
//! | matrix type | Triangler factorization (TRF) | Solve (TRS) | Inverse matrix (TRI) | Reciprocal condition number (CON) |
18-
//! |:--------------------------------|:------------------------------|:------------|:---------------------|:----------------------------------|
19-
//! | General (GE) | [lu] | [solve] | [inv] | [rcond] |
20-
//! | Symmetric (SY) / Hermitian (HE) | [bk] | [solveh] | [invh] | - |
15+
//! see [Solve_] for detail. You can use it like `f64::lu`:
2116
//!
22-
//! [lu]: solve/trait.Solve_.html#tymethod.lu
23-
//! [solve]: solve/trait.Solve_.html#tymethod.solve
24-
//! [inv]: solve/trait.Solve_.html#tymethod.inv
25-
//! [rcond]: solve/trait.Solve_.html#tymethod.rcond
17+
//! ```
18+
//! use lax::{Solve_, layout::MatrixLayout, Transpose};
2619
//!
27-
//! [bk]: solveh/trait.Solveh_.html#tymethod.bk
28-
//! [solveh]: solveh/trait.Solveh_.html#tymethod.solveh
29-
//! [invh]: solveh/trait.Solveh_.html#tymethod.invh
20+
//! let mut a = vec![
21+
//! 1.0, 2.0,
22+
//! 3.0, 4.0
23+
//! ];
24+
//! let mut b = vec![1.0, 2.0];
25+
//! let layout = MatrixLayout::C { row: 2, lda: 2 };
26+
//! let pivot = f64::lu(layout, &mut a).unwrap();
27+
//! f64::solve(layout, Transpose::No, &a, &pivot, &mut b).unwrap();
28+
//! ```
3029
//!
31-
//! Eigenvalue Problem
32-
//! -------------------
30+
//! When you want to write generic algorithm for real and complex matrices,
31+
//! this trait can be used as a trait bound:
32+
//!
33+
//! ```
34+
//! use lax::{Solve_, layout::MatrixLayout, Transpose};
3335
//!
34-
//! Solve eigenvalue problem for a matrix $A$
36+
//! fn solve_at_once<T: Solve_>(layout: MatrixLayout, a: &mut [T], b: &mut [T]) -> Result<(), lax::error::Error> {
37+
//! let pivot = T::lu(layout, a)?;
38+
//! T::solve(layout, Transpose::No, a, &pivot, b)?;
39+
//! Ok(())
40+
//! }
41+
//! ```
3542
//!
36-
//! $$ Av_i = \lambda_i v_i $$
43+
//! There are several similar traits as described below to keep development easy.
44+
//! They are merged into a single trait, [Lapack].
3745
//!
38-
//! or generalized eigenvalue problem
46+
//! Linear equation, Inverse matrix, Condition number
47+
//! --------------------------------------------------
48+
//!
49+
//! According to the property input metrix, several types of triangular decomposition are used:
3950
//!
40-
//! $$ Av_i = \lambda_i B v_i $$
51+
//! - [Solve_] trait provides methods for LU-decomposition for general matrix.
52+
//! - [Solveh_] triat provides methods for Bunch-Kaufman diagonal pivoting method for symmetric/hermite indefinite matrix.
53+
//! - [Cholesky_] triat provides methods for Cholesky decomposition for symmetric/hermite positive dinite matrix.
54+
//!
55+
//! Eigenvalue Problem
56+
//! -------------------
4157
//!
42-
//! | matrix type | Eigenvalue (EV) | Generalized Eigenvalue Problem (EG) |
43-
//! |:--------------------------------|:----------------|:------------------------------------|
44-
//! | General (GE) |[eig] | - |
45-
//! | Symmetric (SY) / Hermitian (HE) |[eigh] |[eigh_generalized] |
58+
//! According to the property input metrix,
59+
//! there are several types of eigenvalue problem API
4660
//!
47-
//! [eig]: eig/trait.Eig_.html#tymethod.eig
48-
//! [eigh]: eigh/trait.Eigh_.html#tymethod.eigh
49-
//! [eigh_generalized]: eigh/trait.Eigh_.html#tymethod.eigh_generalized
61+
//! - [Eig_] trait provides methods for eigenvalue problem for general matrix.
62+
//! - [Eigh_] trait provides methods for eigenvalue problem for symmetric/hermite matrix.
5063
//!
51-
//! Singular Value Decomposition (SVD), Least square problem
52-
//! ----------------------------------------------------------
64+
//! Singular Value Decomposition
65+
//! -----------------------------
5366
//!
54-
//! | matrix type | Singular Value Decomposition (SVD) | SVD with divided-and-conquer (SDD) | Least square problem (LSD) |
55-
//! |:-------------|:-----------------------------------|:-----------------------------------|:---------------------------|
56-
//! | General (GE) | [svd] | [svddc] | [least_squares] |
67+
//! - [SVD_] trait provides methods for singular value decomposition for general matrix
68+
//! - [SVDDC_] trait provides methods for singular value decomposition for general matrix
69+
//! with divided-and-conquer algorithm
70+
//! - [LeastSquaresSvdDivideConquer_] trait provides methods
71+
//! for solving least square problem by SVD
5772
//!
58-
//! [svd]: svd/trait.SVD_.html#tymethod.svd
59-
//! [svddc]: svddck/trait.SVDDC_.html#tymethod.svddc
60-
//! [least_squares]: least_squares/trait.LeastSquaresSvdDivideConquer_.html#tymethod.least_squares
6173
6274
#[cfg(any(feature = "intel-mkl-system", feature = "intel-mkl-static"))]
6375
extern crate intel_mkl_src as _src;

0 commit comments

Comments
 (0)