rusty_compression/
lib.rs

1//! This library provides routines to compute low-rank approximations of matrices.
2//! 
3//! - [Overview](#overview)
4//! - [Random sampling of operators](random_sampling)
5//! - [Examples](examples)
6
7//! # Overview
8//! Let $A\in\mathbb{C}^{m\times n}$ be a given matrix. A low-rank approximation is
9//! a representation of the form
10//! $$
11//! A\approx UV^H
12//! $$
13//! with $U\in\mathbb{C}^{m\times k}$ and $V\in\mathbb{C}^{n\times k}$, where $k$ is
14//! sufficiently small for the required application. A frequently used
15//! representation is also
16//! $$
17//! A\approx \tilde{U}X\tilde{V}^H
18//! $$
19//! with a $k\times k$ matrix $X$.
20//! 
21//! The basis of the library is a pivoted QR decomposition of $A$ of the form
22//! $$
23//! AP = QR
24//! $$
25//! with $P$ a permutation matrix, $Q\in\mathbb{C}^{m\times \ell}$ a matrix
26//! with orthogonal columns of unit norm, $R\in\mathbb{C}^{\ell\times n}$
27//! upper triangular, and $\ell=\min\\{m, n\\}$.
28//! 
29//! In a pivoted QR decomposition the diagonal elements of $R$
30//! are sorted in non-increasing order, that is $|r_{11}|\geq |r_{22}|\geq \dots$. 
31//! We can therefore compress $A$ by choosing an index $k$ and only keeping the first
32//! $k$ columns of $Q$ and the first $k$ rows of $R$. The library allows to choose the
33//! parameter $k$ directly or by a given tolerance $\tau$ such that 
34//! $\langle|\frac{r_{kk}}{r_{11}}\rangle|< \tau$.
35//! 
36//! Alternatively, one can also low-rank compress by first computing the Singular Value
37//! Decomposition. This is more accurate but also more costly.
38//! 
39//! From the compressed QR decomposition we can compute a column pivoted interpolative
40//! decomposition of the form
41//! $$
42//! A \approx CZ
43//! $$
44//! The matrix $C$ is defined as
45//! $$
46//! C = A[:, [i_1, i_2, \dots]],
47//! $$
48//! that is a selection of columns of $A$ with
49//! indices $i_1, i_2, \dots$.
50//! 
51//! The column pivoted interpolative decomposition has
52//! the advantage that we are using columns of $A$ as low-rank basis, which in
53//! applications often have physical meaning as opposed to the columns of $Q$.
54//! 
55//! From the column pivoted interpolative decomposition we can also compute a two-sided
56//! decomposition of the form
57//! $$
58//! A\approx C X R
59//! $$
60//! Here, $X$ is a $k\times k$ matrix, which is the submatrix of $A$ formed of the column indices
61//! $i_1, i_2, \dots$ and row indices $j_1, j_2, \dots$.
62//! 
63//! Similarly to a column interpolative decomposition, a corresponding row interpolative decomposition
64//! is available that selects rows of $A$ for the low rank approximation.
65//!
66
67pub mod examples;
68pub mod col_interp_decomp;
69pub mod compute_svd;
70pub mod types;
71pub mod permutation;
72
73pub mod random_matrix;
74pub mod random_sampling;
75pub mod row_interp_decomp;
76pub mod svd;
77pub mod two_sided_interp_decomp;
78
79pub(crate) mod pivoted_qr;
80pub mod qr;
81
82pub enum CompressionType {
83    /// Adaptive compression with a specified tolerance
84    ADAPTIVE(f64),
85    /// Rank based compression with specified rank
86    RANK(usize),
87}
88
89
90pub use qr::{QR, LQ, QRTraits, LQTraits};
91pub use col_interp_decomp::{ColumnID, ColumnIDTraits};
92pub use row_interp_decomp::{RowID, RowIDTraits};
93pub use two_sided_interp_decomp::{TwoSidedID, TwoSidedIDTraits};
94pub use svd::{SVD, SVDTraits};
95pub use random_matrix::RandomMatrix;
96pub use permutation::*;
97pub use types::RelDiff;
98pub use random_sampling::*;
99
100pub use types::{c32, c64, Scalar};
101
102pub use types::Result;
rusty_compression/lib.rs

rusty_compression/
lib.rs
