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}