Skip to main content

sparse_ir_core/
basis_trait.rs

1//! Basis trait for IR and DLR representations
2//!
3//! This module provides a common trait for different basis representations
4//! (IR basis, DLR basis, augmented basis, etc.) in imaginary-time/frequency domains.
5
6use crate::error::Error;
7use crate::freq::MatsubaraFreq;
8use crate::traits::StatisticsType;
9
10/// Common trait for basis representations in imaginary-time/frequency domains
11///
12/// This trait abstracts over different basis representations:
13/// - `FiniteTempBasis`: IR (Intermediate Representation) basis
14/// - `DiscreteLehmannRepresentation`: DLR basis
15///
16/// Each basis provides:
17/// - Physical parameters (β, ωmax, Λ)
18/// - Basis size and accuracy information
19/// - Default sampling points for τ and Matsubara frequencies
20///
21/// # Type Parameters
22/// * `S` - Statistics type (Fermionic or Bosonic)
23pub trait Basis<S: StatisticsType> {
24    /// Inverse temperature β
25    ///
26    /// # Returns
27    /// The inverse temperature in units where ℏ = kB = 1
28    fn beta(&self) -> f64;
29
30    /// Maximum frequency ωmax
31    ///
32    /// The basis functions are designed to accurately represent
33    /// spectral functions with support in [-ωmax, ωmax].
34    ///
35    /// # Returns
36    /// The maximum frequency cutoff
37    fn wmax(&self) -> f64;
38
39    /// Kernel parameter Λ = β × ωmax
40    ///
41    /// This is the dimensionless parameter that controls the basis.
42    ///
43    /// # Returns
44    /// The dimensionless parameter Λ
45    fn lambda(&self) -> f64 {
46        self.beta() * self.wmax()
47    }
48
49    /// Number of basis functions
50    ///
51    /// # Returns
52    /// The size of the basis (number of basis functions)
53    fn size(&self) -> usize;
54
55    /// Accuracy of the basis
56    ///
57    /// Upper bound to the relative error of representing a propagator
58    /// with the given number of basis functions.
59    ///
60    /// # Returns
61    /// A number between 0 and 1 representing the accuracy
62    fn accuracy(&self) -> f64;
63
64    /// Significance of each basis function
65    ///
66    /// Returns a vector where `σ[i]` (0 ≤ σ[i] ≤ 1) is the significance
67    /// level of the i-th basis function. If ε is the desired accuracy,
68    /// then any basis function where σ[i] < ε can be neglected.
69    ///
70    /// For the IR basis: σ[i] = s[i] / s[0]
71    /// For the DLR basis: σ[i] = 1.0 (all poles equally significant)
72    ///
73    /// # Returns
74    /// Vector of significance values for each basis function
75    fn significance(&self) -> Vec<f64>;
76
77    /// Get singular values (non-normalized)
78    ///
79    /// Returns the singular values S_l of the basis in physical units; for
80    /// `FiniteTempBasis`, S_l = sqrt(β ωmax/2) ωmax^ypower s_l with s_l those of
81    /// the SVE.
82    /// These are the absolute values, not normalized by s[0].
83    ///
84    /// # Returns
85    /// Vector of singular values
86    fn svals(&self) -> Vec<f64>;
87
88    /// Get default tau sampling points
89    ///
90    /// Returns sampling points in imaginary time τ ∈ [-β/2, β/2].
91    /// These are chosen to provide near-optimal conditioning of the
92    /// sampling matrix.
93    ///
94    /// # Returns
95    /// Vector of tau sampling points
96    ///
97    /// # Errors
98    ///
99    /// [`Error::NotSupported`] if the basis has no default tau sampling points,
100    /// e.g. an IR basis whose SVE has too few singular functions (see
101    /// `FiniteTempBasis::default_tau_sampling_points`)
102    fn default_tau_sampling_points(&self) -> Result<Vec<f64>, Error>;
103
104    /// Get default Matsubara sampling points
105    ///
106    /// Returns sampling points in Matsubara frequency space.
107    /// These are chosen to provide near-optimal conditioning.
108    ///
109    /// # Arguments
110    /// * `positive_only` - If true, only return non-negative frequencies
111    ///
112    /// # Returns
113    /// Vector of Matsubara frequency sampling points
114    ///
115    /// # Errors
116    ///
117    /// [`Error::NotSupported`] if the basis has no default Matsubara sampling
118    /// points
119    fn default_matsubara_sampling_points(
120        &self,
121        positive_only: bool,
122    ) -> Result<Vec<MatsubaraFreq<S>>, Error>
123    where
124        S: 'static;
125
126    /// Evaluate basis functions at imaginary time points
127    ///
128    /// Computes the value of basis functions at given τ points.
129    /// For IR basis: u_l(τ)
130    /// For DLR basis: the pole functions u_p(τ), one column per pole
131    ///
132    /// # Arguments
133    /// * `tau` - Imaginary time points τ ∈ [-β, β]; negative τ uses the
134    ///   (anti)periodicity of the statistics
135    ///
136    /// # Returns
137    /// Matrix of shape [tau.len(), self.size()] where result[i, l] = u_l(τ_i)
138    ///
139    /// An empty `tau` gives a `[0, size]` matrix.
140    ///
141    /// # Errors
142    ///
143    /// [`Error::OutOfDomain`] if a τ is outside [-β, β] or NaN; no value is
144    /// computed then.
145    fn evaluate_tau(&self, tau: &[f64]) -> Result<crate::Matrix<f64>, Error>;
146
147    /// Evaluate basis functions at Matsubara frequencies
148    ///
149    /// Computes the value of basis functions at given Matsubara frequencies.
150    /// For IR basis: û_l(iν)
151    /// For DLR basis: basis functions in Matsubara space
152    ///
153    /// # Arguments
154    /// * `freqs` - Matsubara frequencies
155    ///
156    /// # Returns
157    /// Matrix of shape [freqs.len(), self.size()] where result[i, l] = û_l(iν_i)
158    ///
159    /// An empty `freqs` gives a `[0, size]` matrix.
160    ///
161    /// # Errors
162    ///
163    /// Implementors may return errors. The bases of this crate
164    /// (`FiniteTempBasis` and `DiscreteLehmannRepresentation`)
165    /// never do: every `MatsubaraFreq<S>` has the parity of the statistics, so
166    /// every frequency can be evaluated.
167    fn evaluate_matsubara(
168        &self,
169        freqs: &[MatsubaraFreq<S>],
170    ) -> Result<crate::Matrix<num_complex::Complex<f64>>, Error>
171    where
172        S: 'static;
173
174    /// Evaluate spectral basis functions at real frequencies
175    ///
176    /// Computes the value of spectral basis functions at given real frequencies.
177    /// For IR basis: V_l(ω)
178    /// Not supported for the DLR basis (see Errors)
179    ///
180    /// # Arguments
181    /// * `omega` - Real frequency points in [-ωmax, ωmax]
182    ///
183    /// # Returns
184    /// Matrix of shape [omega.len(), self.size()] where result[i, l] = V_l(ω_i)
185    ///
186    /// An empty `omega` gives a `[0, size]` matrix.
187    ///
188    /// # Errors
189    ///
190    /// * [`Error::OutOfDomain`] if an ω is outside [-ωmax, ωmax] or NaN
191    /// * [`Error::NotSupported`] for the DLR basis
192    fn evaluate_omega(&self, omega: &[f64]) -> Result<crate::Matrix<f64>, Error>;
193
194    /// Get default omega (real frequency) sampling points
195    ///
196    /// Returns sampling points on the real-frequency axis ω ∈ [-ωmax, ωmax].
197    /// These are used as pole locations for the Discrete Lehmann Representation (DLR).
198    ///
199    /// The sampling points are chosen as the roots/extrema of the L-th basis function
200    /// in the spectral domain, providing near-optimal conditioning.
201    ///
202    /// # Returns
203    /// Vector of real-frequency sampling points in [-ωmax, ωmax]
204    ///
205    /// # Errors
206    ///
207    /// [`Error::NotSupported`] if the basis is an IR basis whose SVE has too
208    /// few singular functions (the DLR returns its poles)
209    fn default_omega_sampling_points(&self) -> Result<Vec<f64>, Error>;
210}