Skip to content

Commit 93cfaee

Browse files
committed
About trait design in crate level document
1 parent 1ea3a76 commit 93cfaee

File tree

1 file changed

+43
-22
lines changed

1 file changed

+43
-22
lines changed

lax/src/lib.rs

Lines changed: 43 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,53 @@
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+
//! -------------------------------
5+
//!
6+
//! This crates provides LAPACK wrapper as `impl` of traits to base scalar types.
7+
//! For example, LU factorization to double-precision matrix is provided like:
8+
//!
9+
//! ```ignore
10+
//! impl Solve_ for f64 {
11+
//! fn lu(l: MatrixLayout, a: &mut [Self]) -> Result<Pivot> { ... }
12+
//! }
13+
//! ```
14+
//!
15+
//! see [Solve_] for detail. You can use it like `f64::lu`:
816
//!
9-
//! As the property of $A$, several types of triangular factorization are used:
17+
//! ```
18+
//! use lax::{Solve_, layout::MatrixLayout};
1019
//!
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.
20+
//! let mut a = vec![
21+
//! 1.0, 2.0,
22+
//! 3.0, 4.0
23+
//! ];
24+
//! let layout = MatrixLayout::C { row: 2, lda: 2 };
25+
//! let pivot = f64::lu(layout, &mut a).unwrap();
26+
//! ```
1627
//!
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] | - |
28+
//! When you want to write generic algorithm for real and complex matrices,
29+
//! this trait can be used as a trait bound:
30+
//!
31+
//! ```
32+
//! use lax::{Solve_, layout::MatrixLayout, Transpose};
33+
//!
34+
//! fn solve_at_once<T: Solve_>(layout: MatrixLayout, a: &mut [T], b: &mut [T]) -> Result<(), lax::error::Error> {
35+
//! let pivot = T::lu(layout, a)?
36+
//! T::solve(layout, Transpose::No, a, pivot, b)?;
37+
//! Ok(())
38+
//! }
39+
//! ```
40+
//!
41+
//! There are several similar traits as described below to keep development easy.
42+
//! They are merged into a single trait, [Lapack].
43+
//!
44+
//! Linear equation, Inverse matrix, Condition number
45+
//! --------------------------------------------------
2146
//!
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
47+
//! According to the property input metrix, several types of triangular factorization are used:
2648
//!
27-
//! [bk]: solveh/trait.Solveh_.html#tymethod.bk
28-
//! [solveh]: solveh/trait.Solveh_.html#tymethod.solveh
29-
//! [invh]: solveh/trait.Solveh_.html#tymethod.invh
49+
//! - [Solve_] trait provides methods for LU-decomposition for general matrix.
50+
//! - [Solveh_] triat provides methods for Bunch-Kaufman diagonal pivoting method for symmetric/hermite indefinite matrix
3051
//!
3152
//! Eigenvalue Problem
3253
//! -------------------

0 commit comments

Comments
 (0)