forked from M-Labs/nalgebra
379 lines
16 KiB
Rust
379 lines
16 KiB
Rust
use crate::storage::Storage;
|
||
use crate::{
|
||
Allocator, Bidiagonal, Cholesky, ColPivQR, ComplexField, DefaultAllocator, Dim, DimDiff,
|
||
DimMin, DimMinimum, DimSub, FullPivLU, Hessenberg, Matrix, OMatrix, RealField, Schur,
|
||
SymmetricEigen, SymmetricTridiagonal, LU, QR, SVD, U1, UDU,
|
||
};
|
||
|
||
/// # Rectangular matrix decomposition
|
||
///
|
||
/// This section contains the methods for computing some common decompositions of rectangular
|
||
/// matrices with real or complex components. The following are currently supported:
|
||
///
|
||
/// | Decomposition | Factors | Details |
|
||
/// | -------------------------|---------------------|--------------|
|
||
/// | QR | `Q * R` | `Q` is an unitary matrix, and `R` is upper-triangular. |
|
||
/// | QR with column pivoting | `Q * R * P⁻¹` | `Q` is an unitary matrix, and `R` is upper-triangular. `P` is a permutation matrix. |
|
||
/// | LU with partial pivoting | `P⁻¹ * L * U` | `L` is lower-triangular with a diagonal filled with `1` and `U` is upper-triangular. `P` is a permutation matrix. |
|
||
/// | LU with full pivoting | `P⁻¹ * L * U * Q⁻¹` | `L` is lower-triangular with a diagonal filled with `1` and `U` is upper-triangular. `P` and `Q` are permutation matrices. |
|
||
/// | SVD | `U * Σ * Vᵀ` | `U` and `V` are two orthogonal matrices and `Σ` is a diagonal matrix containing the singular values. |
|
||
/// | Polar (Left Polar) | `P' * U` | `U` is semi-unitary/unitary and `P'` is a positive semi-definite Hermitian Matrix
|
||
impl<T: ComplexField, R: Dim, C: Dim, S: Storage<T, R, C>> Matrix<T, R, C, S> {
|
||
/// Computes the bidiagonalization using householder reflections.
|
||
pub fn bidiagonalize(self) -> Bidiagonal<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>,
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>,
|
||
{
|
||
Bidiagonal::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the LU decomposition with full pivoting of `matrix`.
|
||
///
|
||
/// This effectively computes `P, L, U, Q` such that `P * matrix * Q = LU`.
|
||
pub fn full_piv_lu(self) -> FullPivLU<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DefaultAllocator: Allocator<T, R, C> + Allocator<(usize, usize), DimMinimum<R, C>>,
|
||
{
|
||
FullPivLU::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the LU decomposition with partial (row) pivoting of `matrix`.
|
||
pub fn lu(self) -> LU<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DefaultAllocator: Allocator<T, R, C> + Allocator<(usize, usize), DimMinimum<R, C>>,
|
||
{
|
||
LU::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the QR decomposition of this matrix.
|
||
pub fn qr(self) -> QR<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DefaultAllocator: Allocator<T, R, C> + Allocator<T, R> + Allocator<T, DimMinimum<R, C>>,
|
||
{
|
||
QR::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the QR decomposition (with column pivoting) of this matrix.
|
||
pub fn col_piv_qr(self) -> ColPivQR<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<(usize, usize), DimMinimum<R, C>>,
|
||
{
|
||
ColPivQR::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the Singular Value Decomposition using implicit shift.
|
||
/// The singular values are guaranteed to be sorted in descending order.
|
||
/// If this order is not required consider using `svd_unordered`.
|
||
pub fn svd(self, compute_u: bool, compute_v: bool) -> SVD<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>, // for Bidiagonal.
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<T, DimMinimum<R, C>, C>
|
||
+ Allocator<T, R, DimMinimum<R, C>>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<(usize, usize), DimMinimum<R, C>>
|
||
+ Allocator<(T::RealField, usize), DimMinimum<R, C>>,
|
||
{
|
||
SVD::new(self.into_owned(), compute_u, compute_v)
|
||
}
|
||
|
||
/// Computes the Singular Value Decomposition using implicit shift.
|
||
/// The singular values are not guaranteed to be sorted in any particular order.
|
||
/// If a descending order is required, consider using `svd` instead.
|
||
pub fn svd_unordered(self, compute_u: bool, compute_v: bool) -> SVD<T, R, C>
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>, // for Bidiagonal.
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<T, DimMinimum<R, C>, C>
|
||
+ Allocator<T, R, DimMinimum<R, C>>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimDiff<DimMinimum<R, C>, U1>>,
|
||
{
|
||
SVD::new_unordered(self.into_owned(), compute_u, compute_v)
|
||
}
|
||
|
||
/// Attempts to compute the Singular Value Decomposition of `matrix` using implicit shift.
|
||
/// The singular values are guaranteed to be sorted in descending order.
|
||
/// If this order is not required consider using `try_svd_unordered`.
|
||
///
|
||
/// # Arguments
|
||
///
|
||
/// * `compute_u` − set this to `true` to enable the computation of left-singular vectors.
|
||
/// * `compute_v` − set this to `true` to enable the computation of right-singular vectors.
|
||
/// * `eps` − tolerance used to determine when a value converged to 0.
|
||
/// * `max_niter` − maximum total number of iterations performed by the algorithm. If this
|
||
/// number of iteration is exceeded, `None` is returned. If `niter == 0`, then the algorithm
|
||
/// continues indefinitely until convergence.
|
||
pub fn try_svd(
|
||
self,
|
||
compute_u: bool,
|
||
compute_v: bool,
|
||
eps: T::RealField,
|
||
max_niter: usize,
|
||
) -> Option<SVD<T, R, C>>
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>, // for Bidiagonal.
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<T, DimMinimum<R, C>, C>
|
||
+ Allocator<T, R, DimMinimum<R, C>>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<(usize, usize), DimMinimum<R, C>>
|
||
+ Allocator<(T::RealField, usize), DimMinimum<R, C>>,
|
||
{
|
||
SVD::try_new(self.into_owned(), compute_u, compute_v, eps, max_niter)
|
||
}
|
||
|
||
/// Attempts to compute the Singular Value Decomposition of `matrix` using implicit shift.
|
||
/// The singular values are not guaranteed to be sorted in any particular order.
|
||
/// If a descending order is required, consider using `try_svd` instead.
|
||
///
|
||
/// # Arguments
|
||
///
|
||
/// * `compute_u` − set this to `true` to enable the computation of left-singular vectors.
|
||
/// * `compute_v` − set this to `true` to enable the computation of right-singular vectors.
|
||
/// * `eps` − tolerance used to determine when a value converged to 0.
|
||
/// * `max_niter` − maximum total number of iterations performed by the algorithm. If this
|
||
/// number of iteration is exceeded, `None` is returned. If `niter == 0`, then the algorithm
|
||
/// continues indefinitely until convergence.
|
||
pub fn try_svd_unordered(
|
||
self,
|
||
compute_u: bool,
|
||
compute_v: bool,
|
||
eps: T::RealField,
|
||
max_niter: usize,
|
||
) -> Option<SVD<T, R, C>>
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>, // for Bidiagonal.
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<T, DimMinimum<R, C>, C>
|
||
+ Allocator<T, R, DimMinimum<R, C>>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimDiff<DimMinimum<R, C>, U1>>,
|
||
{
|
||
SVD::try_new_unordered(self.into_owned(), compute_u, compute_v, eps, max_niter)
|
||
}
|
||
|
||
/// Computes the Polar Decomposition of a `matrix` (indirectly uses SVD).
|
||
pub fn polar(self) -> (OMatrix<T, R, R>, OMatrix<T, R, C>)
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>, // for Bidiagonal.
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, DimMinimum<R, C>, R>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T, R, R>
|
||
+ Allocator<T, DimMinimum<R, C>, DimMinimum<R, C>>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<T, DimMinimum<R, C>, C>
|
||
+ Allocator<T, R, DimMinimum<R, C>>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimDiff<DimMinimum<R, C>, U1>>,
|
||
{
|
||
SVD::new_unordered(self.into_owned(), true, true)
|
||
.to_polar()
|
||
.unwrap()
|
||
}
|
||
|
||
/// Attempts to compute the Polar Decomposition of a `matrix` (indirectly uses SVD).
|
||
///
|
||
/// # Arguments
|
||
///
|
||
/// * `eps` − tolerance used to determine when a value converged to 0 when computing the SVD.
|
||
/// * `max_niter` − maximum total number of iterations performed by the SVD computation algorithm.
|
||
pub fn try_polar(
|
||
self,
|
||
eps: T::RealField,
|
||
max_niter: usize,
|
||
) -> Option<(OMatrix<T, R, R>, OMatrix<T, R, C>)>
|
||
where
|
||
R: DimMin<C>,
|
||
DimMinimum<R, C>: DimSub<U1>, // for Bidiagonal.
|
||
DefaultAllocator: Allocator<T, R, C>
|
||
+ Allocator<T, DimMinimum<R, C>, R>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T, R, R>
|
||
+ Allocator<T, DimMinimum<R, C>, DimMinimum<R, C>>
|
||
+ Allocator<T, C>
|
||
+ Allocator<T, R>
|
||
+ Allocator<T, DimDiff<DimMinimum<R, C>, U1>>
|
||
+ Allocator<T, DimMinimum<R, C>, C>
|
||
+ Allocator<T, R, DimMinimum<R, C>>
|
||
+ Allocator<T, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimMinimum<R, C>>
|
||
+ Allocator<T::RealField, DimDiff<DimMinimum<R, C>, U1>>,
|
||
{
|
||
SVD::try_new_unordered(self.into_owned(), true, true, eps, max_niter)
|
||
.and_then(|svd| svd.to_polar())
|
||
}
|
||
}
|
||
|
||
/// # Square matrix decomposition
|
||
///
|
||
/// This section contains the methods for computing some common decompositions of square
|
||
/// matrices with real or complex components. The following are currently supported:
|
||
///
|
||
/// | Decomposition | Factors | Details |
|
||
/// | -------------------------|---------------------------|--------------|
|
||
/// | Hessenberg | `Q * H * Qᵀ` | `Q` is a unitary matrix and `H` an upper-Hessenberg matrix. |
|
||
/// | Cholesky | `L * Lᵀ` | `L` is a lower-triangular matrix. |
|
||
/// | UDU | `U * D * Uᵀ` | `U` is a upper-triangular matrix, and `D` a diagonal matrix. |
|
||
/// | Schur decomposition | `Q * T * Qᵀ` | `Q` is an unitary matrix and `T` a quasi-upper-triangular matrix. |
|
||
/// | Symmetric eigendecomposition | `Q ~ Λ ~ Qᵀ` | `Q` is an unitary matrix, and `Λ` is a real diagonal matrix. |
|
||
/// | Symmetric tridiagonalization | `Q ~ T ~ Qᵀ` | `Q` is an unitary matrix, and `T` is a tridiagonal matrix. |
|
||
impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> Matrix<T, D, D, S> {
|
||
/// Attempts to compute the Cholesky decomposition of this matrix.
|
||
///
|
||
/// Returns `None` if the input matrix is not definite-positive. The input matrix is assumed
|
||
/// to be symmetric and only the lower-triangular part is read.
|
||
pub fn cholesky(self) -> Option<Cholesky<T, D>>
|
||
where
|
||
DefaultAllocator: Allocator<T, D, D>,
|
||
{
|
||
Cholesky::new(self.into_owned())
|
||
}
|
||
|
||
/// Attempts to compute the UDU decomposition of this matrix.
|
||
///
|
||
/// The input matrix `self` is assumed to be symmetric and this decomposition will only read
|
||
/// the upper-triangular part of `self`.
|
||
pub fn udu(self) -> Option<UDU<T, D>>
|
||
where
|
||
T: RealField,
|
||
DefaultAllocator: Allocator<T, D> + Allocator<T, D, D>,
|
||
{
|
||
UDU::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the Hessenberg decomposition of this matrix using householder reflections.
|
||
pub fn hessenberg(self) -> Hessenberg<T, D>
|
||
where
|
||
D: DimSub<U1>,
|
||
DefaultAllocator: Allocator<T, D, D> + Allocator<T, D> + Allocator<T, DimDiff<D, U1>>,
|
||
{
|
||
Hessenberg::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the Schur decomposition of a square matrix.
|
||
pub fn schur(self) -> Schur<T, D>
|
||
where
|
||
D: DimSub<U1>, // For Hessenberg.
|
||
DefaultAllocator: Allocator<T, D, DimDiff<D, U1>>
|
||
+ Allocator<T, DimDiff<D, U1>>
|
||
+ Allocator<T, D, D>
|
||
+ Allocator<T, D>,
|
||
{
|
||
Schur::new(self.into_owned())
|
||
}
|
||
|
||
/// Attempts to compute the Schur decomposition of a square matrix.
|
||
///
|
||
/// If only eigenvalues are needed, it is more efficient to call the matrix method
|
||
/// `.eigenvalues()` instead.
|
||
///
|
||
/// # Arguments
|
||
///
|
||
/// * `eps` − tolerance used to determine when a value converged to 0.
|
||
/// * `max_niter` − maximum total number of iterations performed by the algorithm. If this
|
||
/// number of iteration is exceeded, `None` is returned. If `niter == 0`, then the algorithm
|
||
/// continues indefinitely until convergence.
|
||
pub fn try_schur(self, eps: T::RealField, max_niter: usize) -> Option<Schur<T, D>>
|
||
where
|
||
D: DimSub<U1>, // For Hessenberg.
|
||
DefaultAllocator: Allocator<T, D, DimDiff<D, U1>>
|
||
+ Allocator<T, DimDiff<D, U1>>
|
||
+ Allocator<T, D, D>
|
||
+ Allocator<T, D>,
|
||
{
|
||
Schur::try_new(self.into_owned(), eps, max_niter)
|
||
}
|
||
|
||
/// Computes the eigendecomposition of this symmetric matrix.
|
||
///
|
||
/// Only the lower-triangular part (including the diagonal) of `m` is read.
|
||
pub fn symmetric_eigen(self) -> SymmetricEigen<T, D>
|
||
where
|
||
D: DimSub<U1>,
|
||
DefaultAllocator: Allocator<T, D, D>
|
||
+ Allocator<T, DimDiff<D, U1>>
|
||
+ Allocator<T::RealField, D>
|
||
+ Allocator<T::RealField, DimDiff<D, U1>>,
|
||
{
|
||
SymmetricEigen::new(self.into_owned())
|
||
}
|
||
|
||
/// Computes the eigendecomposition of the given symmetric matrix with user-specified
|
||
/// convergence parameters.
|
||
///
|
||
/// Only the lower-triangular part (including the diagonal) of `m` is read.
|
||
///
|
||
/// # Arguments
|
||
///
|
||
/// * `eps` − tolerance used to determine when a value converged to 0.
|
||
/// * `max_niter` − maximum total number of iterations performed by the algorithm. If this
|
||
/// number of iteration is exceeded, `None` is returned. If `niter == 0`, then the algorithm
|
||
/// continues indefinitely until convergence.
|
||
pub fn try_symmetric_eigen(
|
||
self,
|
||
eps: T::RealField,
|
||
max_niter: usize,
|
||
) -> Option<SymmetricEigen<T, D>>
|
||
where
|
||
D: DimSub<U1>,
|
||
DefaultAllocator: Allocator<T, D, D>
|
||
+ Allocator<T, DimDiff<D, U1>>
|
||
+ Allocator<T::RealField, D>
|
||
+ Allocator<T::RealField, DimDiff<D, U1>>,
|
||
{
|
||
SymmetricEigen::try_new(self.into_owned(), eps, max_niter)
|
||
}
|
||
|
||
/// Computes the tridiagonalization of this symmetric matrix.
|
||
///
|
||
/// Only the lower-triangular part (including the diagonal) of `m` is read.
|
||
pub fn symmetric_tridiagonalize(self) -> SymmetricTridiagonal<T, D>
|
||
where
|
||
D: DimSub<U1>,
|
||
DefaultAllocator: Allocator<T, D, D> + Allocator<T, DimDiff<D, U1>>,
|
||
{
|
||
SymmetricTridiagonal::new(self.into_owned())
|
||
}
|
||
}
|