lax/
lib.rs

1//! Linear Algebra eXtension (LAX)
2//! ===============================
3//!
4//! ndarray-free safe Rust wrapper for LAPACK FFI
5//!
6//! Linear equation, Inverse matrix, Condition number
7//! --------------------------------------------------
8//!
9//! As the property of $A$, several types of triangular factorization are used:
10//!
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.
16//!
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]               | -                                 |
21//!
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
26//!
27//! [bk]:     solveh/trait.Solveh_.html#tymethod.bk
28//! [solveh]: solveh/trait.Solveh_.html#tymethod.solveh
29//! [invh]:   solveh/trait.Solveh_.html#tymethod.invh
30//!
31//! Eigenvalue Problem
32//! -------------------
33//!
34//! Solve eigenvalue problem for a matrix $A$
35//!
36//! $$ Av_i = \lambda_i v_i $$
37//!
38//! or generalized eigenvalue problem
39//!
40//! $$ Av_i = \lambda_i B v_i $$
41//!
42//! | matrix type                     | Eigenvalue (EV) | Generalized Eigenvalue Problem (EG) |
43//! |:--------------------------------|:----------------|:------------------------------------|
44//! | General (GE)                    |[eig]            | -                                   |
45//! | Symmetric (SY) / Hermitian (HE) |[eigh]           |[eigh_generalized]                   |
46//!
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
50//!
51//! Singular Value Decomposition (SVD), Least square problem
52//! ----------------------------------------------------------
53//!
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]            |
57//!
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
61
62#[cfg(any(feature = "intel-mkl-system", feature = "intel-mkl-static"))]
63extern crate intel_mkl_src as _src;
64
65#[cfg(any(feature = "openblas-system", feature = "openblas-static"))]
66extern crate openblas_src as _src;
67
68#[cfg(any(feature = "netlib-system", feature = "netlib-static"))]
69extern crate netlib_src as _src;
70
71pub mod error;
72pub mod layout;
73
74mod cholesky;
75mod eig;
76mod eigh;
77mod least_squares;
78mod opnorm;
79mod qr;
80mod rcond;
81mod solve;
82mod solveh;
83mod svd;
84mod svddc;
85mod triangular;
86mod tridiagonal;
87
88pub use self::cholesky::*;
89pub use self::eig::*;
90pub use self::eigh::*;
91pub use self::least_squares::*;
92pub use self::opnorm::*;
93pub use self::qr::*;
94pub use self::rcond::*;
95pub use self::solve::*;
96pub use self::solveh::*;
97pub use self::svd::*;
98pub use self::svddc::*;
99pub use self::triangular::*;
100pub use self::tridiagonal::*;
101
102use cauchy::*;
103
104pub type Pivot = Vec<i32>;
105
106/// Trait for primitive types which implements LAPACK subroutines
107pub trait Lapack:
108    OperatorNorm_
109    + QR_
110    + SVD_
111    + SVDDC_
112    + Solve_
113    + Solveh_
114    + Cholesky_
115    + Eig_
116    + Eigh_
117    + Triangular_
118    + Tridiagonal_
119    + Rcond_
120    + LeastSquaresSvdDivideConquer_
121{
122}
123
124impl Lapack for f32 {}
125impl Lapack for f64 {}
126impl Lapack for c32 {}
127impl Lapack for c64 {}
128
129/// Upper/Lower specification for seveal usages
130#[derive(Debug, Clone, Copy)]
131#[repr(u8)]
132pub enum UPLO {
133    Upper = b'U',
134    Lower = b'L',
135}
136
137impl UPLO {
138    pub fn t(self) -> Self {
139        match self {
140            UPLO::Upper => UPLO::Lower,
141            UPLO::Lower => UPLO::Upper,
142        }
143    }
144}
145
146#[derive(Debug, Clone, Copy)]
147#[repr(u8)]
148pub enum Transpose {
149    No = b'N',
150    Transpose = b'T',
151    Hermite = b'C',
152}
153
154#[derive(Debug, Clone, Copy)]
155#[repr(u8)]
156pub enum NormType {
157    One = b'O',
158    Infinity = b'I',
159    Frobenius = b'F',
160}
161
162impl NormType {
163    pub fn transpose(self) -> Self {
164        match self {
165            NormType::One => NormType::Infinity,
166            NormType::Infinity => NormType::One,
167            NormType::Frobenius => NormType::Frobenius,
168        }
169    }
170}
171
172/// Create a vector without initialization
173///
174/// Safety
175/// ------
176/// - Memory is not initialized. Do not read the memory before write.
177///
178unsafe fn vec_uninit<T: Sized>(n: usize) -> Vec<T> {
179    let mut v = Vec::with_capacity(n);
180    v.set_len(n);
181    v
182}