sparse_ir_sve/lib.rs
1//! # sparse-ir-sve
2//!
3//! The singular value expansion (SVE) of integral kernels K(x, y), computed
4//! in extended precision with an ACA-accelerated truncated SVD, and the
5//! numerics it is built on: Gauss–Legendre quadrature, piecewise Legendre
6//! polynomials, dense column-major containers, the error type, the FPU guard,
7//! and the parallel execution on the rayon pool.
8//!
9//! A kernel implements [`AbstractKernel`] (its values) and [`SVEKernel`] (its
10//! domain and the discretization hints of its SVE), and either
11//! [`ReducedKernel`] (a centrosymmetric kernel, through its even and odd
12//! reduced kernels) or [`ExpandableKernel`] (any other kernel, no methods);
13//! [`compute_sve`] then returns its singular values and singular functions
14//! ([`SVEResult`]).
15//!
16//! In `f64`, [`compute_sve`] decomposes the discretized kernel by a dense
17//! column-pivoted QR; in double-double (`Df64`), where that is costly, by
18//! adaptive cross approximation (ACA), which reads only a few rows and
19//! columns of it. The one exception is the full-domain SVE of a
20//! centrosymmetric kernel ([`SVEOptions::full_domain`]), which keeps the
21//! dense QR in `Df64` too: its single block holds nearly degenerate pairs of
22//! singular values. [`unstable::sve::compute_sve_dense`] takes the dense
23//! path in both, to check the result on a new kernel.
24//!
25//! The crate is mathematics only: it defines no concrete kernel. The
26//! `sparse-ir` crates define the kernels of the IR basis and build the basis
27//! on top of it.
28//!
29//! # Example
30//!
31//! The SVE of K(x, y) = exp(xy) on [-1, 1] × [-1, 1]. The kernel is
32//! centrosymmetric, K(-x, -y) = K(x, y), so the SVE is computed in even and
33//! odd blocks: the even and odd reduced kernels K(x, y) ± K(x, -y) are
34//! 2 cosh(xy) and 2 sinh(xy). [`SegmentHints`] discretizes it on segments of
35//! equal length.
36//!
37//! ```
38//! use sparse_ir_sve::{
39//! AbstractKernel, CustomNumeric, ReducedKernel, SVEKernel, SegmentHints, SymmetryType,
40//! TworkType, compute_sve, sve_residual,
41//! };
42//! use std::fmt::Debug;
43//!
44//! #[derive(Debug, Clone, Copy)]
45//! struct ExpKernel;
46//!
47//! impl AbstractKernel for ExpKernel {
48//! fn compute<T: CustomNumeric + Copy + Debug>(&self, x: T, y: T) -> T {
49//! (x * y).exp()
50//! }
51//! }
52//!
53//! impl ReducedKernel for ExpKernel {
54//! fn compute_reduced<T: CustomNumeric + Copy + Debug>(
55//! &self,
56//! x: T,
57//! y: T,
58//! symmetry: SymmetryType,
59//! ) -> T {
60//! let two = T::from_f64_unchecked(2.0);
61//! match symmetry {
62//! SymmetryType::Even => two * (x * y).cosh(),
63//! SymmetryType::Odd => two * (x * y).sinh(),
64//! }
65//! }
66//! }
67//!
68//! impl SVEKernel for ExpKernel {
69//! type SVEHintsType<T>
70//! = SegmentHints
71//! where
72//! T: Copy + Debug + Send + Sync + CustomNumeric + 'static;
73//!
74//! fn xmax(&self) -> f64 {
75//! 1.0
76//! }
77//!
78//! fn ymax(&self) -> f64 {
79//! 1.0
80//! }
81//!
82//! fn sve_hints<T>(&self, _epsilon: f64) -> SegmentHints
83//! where
84//! T: Copy + Debug + Send + Sync + CustomNumeric + 'static,
85//! {
86//! // Four segments on each axis, 16 Gauss points on each segment
87//! SegmentHints::uniform(self, 4, 4, 16).unwrap()
88//! }
89//! }
90//!
91//! let sve = compute_sve(ExpKernel, Some(1e-10), None, None, TworkType::Auto)?;
92//! let s = sve.s();
93//! assert!(s.windows(2).all(|w| w[0] >= w[1]));
94//!
95//! // K(x, y) = Σ_l s_l u_l(x) v_l(y), to the requested accuracy
96//! let (x, y) = (0.3, -0.7);
97//! let k: f64 = (0..s.len())
98//! .map(|l| s[l] * sve.u()[l].evaluate(x) * sve.v()[l].evaluate(y))
99//! .sum();
100//! assert!((k - f64::exp(x * y)).abs() < 1e-8);
101//!
102//! // The segments resolve the kernel: the residual is far below 1e-10
103//! assert!(sve_residual(&ExpKernel, &sve) < 1e-12);
104//! # Ok::<(), sparse_ir_sve::Error>(())
105//! ```
106
107pub(crate) mod aca; // ACA-accelerated truncated SVD for the SVE kernel blocks
108mod checks; // Parameter checks, re-exported from `unstable`
109pub(crate) mod col_piv_qr; // Column-pivoted QR decomposition using nalgebra
110pub(crate) mod cost; // Work estimates for the threading decisions
111pub(crate) mod ddgemm; // Double-double matrix products
112pub mod error; // Error type of the public API
113mod fpu_check; // FPU state checking for Intel Fortran compatibility
114pub mod gauss;
115pub mod hints;
116pub(crate) mod interpolation1d;
117pub mod kernel;
118mod kernelmatrix; // Kernel matrices on Gauss points
119pub mod matrix; // Column-major dense containers for internal numerics
120pub mod numeric;
121mod parallel; // Parallel execution on the rayon pool
122pub mod poly;
123pub mod sve;
124mod tsvd; // High-precision truncated SVD using nalgebra
125pub mod unstable; // Items for the other sparse-ir crates, outside semver
126
127// Kernels for the tests of this crate
128#[cfg(test)]
129mod test_kernels;
130
131pub use error::{Error, ErrorKind, Result};
132pub use gauss::{Rule, legendre};
133pub use hints::SegmentHints;
134pub use kernel::{
135 AbstractKernel, ExpandableKernel, ReducedKernel, SVEHints, SVEKernel, SymmetryType,
136};
137pub use matrix::{Mat, Mat3};
138pub use numeric::CustomNumeric;
139pub use poly::{PiecewiseLegendrePoly, PiecewiseLegendrePolyVector};
140pub use sve::{SVEOptions, SVEResult, TworkType, compute_sve, compute_sve_with, sve_residual};
141pub use xprec::Df64;