Struct MatsubaraSampling 

pub struct MatsubaraSampling<S>
where
    S: StatisticsType,
{ /* private fields */ }

Matsubara sampling for full frequency range (positive and negative)

General complex problem without symmetry assumptions. Supports both real and complex coefficients.

Implementations

impl<S> MatsubaraSampling<S>

where S: StatisticsType,

pub fn new(basis: &impl Basis<S>) -> Result<MatsubaraSampling<S>, Error>

where S: 'static,

Create Matsubara sampling with default sampling points

Uses the default sampling points of the basis (symmetric: positive and negative frequencies).

Errors

The errors of Basis::default_matsubara_sampling_points (NotSupported for a DLR or for basis functions without a definite parity, #183)

pub fn with_sampling_points( basis: &impl Basis<S>, sampling_points: Vec<MatsubaraFreq<S>>, ) -> Result<MatsubaraSampling<S>, Error>

where S: 'static,

Create Matsubara sampling with custom sampling points

The points may be in any order, and are kept in the given order: Self::sampling_points returns them unchanged, and index i along the sampling-point axis of evaluate and fit refers to sampling_points[i].

Duplicate points are accepted; they only raise the condition number.

Errors

• Error::EmptyInput if sampling_points is empty
• The errors of Basis::evaluate_matsubara

pub fn from_matrix( sampling_points: Vec<MatsubaraFreq<S>>, matrix: &TypedTensor<Complex<f64>, Rank<2>>, ) -> Result<MatsubaraSampling<S>, Error>

Create Matsubara sampling with custom sampling points and pre-computed matrix

This constructor is useful when the sampling matrix is already computed (e.g., from external sources or for testing).

Arguments

• sampling_points - Matsubara frequency sampling points, in any order
• matrix - Pre-computed sampling matrix (n_points × basis_size); row i belongs to sampling_points[i]

The points are kept in the given order: Self::sampling_points returns them unchanged, and index i along the sampling-point axis of evaluate and fit refers to sampling_points[i].

Duplicate points are accepted; they only raise the condition number.

Errors

• Error::EmptyInput if sampling_points is empty, or matrix has no columns
• Error::ShapeMismatch of the input if matrix does not have one row per point
• Error::NonFiniteInput for the first entry of matrix with a NaN or infinite part

pub fn sampling_points(&self) -> &[MatsubaraFreq<S>]

Get sampling points

pub fn n_sampling_points(&self) -> usize

Number of sampling points

pub fn basis_size(&self) -> usize

Basis size

pub fn matrix(&self) -> &TypedTensor<Complex<f64>, Rank<2>>

Get the sampling matrix

pub fn condition_number(&self) -> Result<f64, Error>

Condition number of the sampling matrix, which fitting solves with

Returns σ_max / σ_min, the ratio of the largest to the smallest of the min(n_sampling_points, basis_size) singular values of the complex n_sampling_points × basis_size matrix Self::matrix. It bounds how much Self::fit can amplify relative errors in the values.

Returns f64::INFINITY if the smallest singular value is below 1e-15 (numerically singular matrix). The singular value decomposition is the one fitting uses: it is computed by the first call to this method or to a fit, then cached.

Errors

Error::DecompositionFailed if the singular value decomposition fails, which a matrix of finite entries does not cause in practice (the constructors reject non-finite entries)

pub fn evaluate( &self, coeffs: &[Complex<f64>], ) -> Result<Vec<Complex<f64>>, Error>

Evaluate complex basis coefficients at sampling points

Arguments

• coeffs - Complex basis coefficients (length = basis_size)

Returns

Complex values at Matsubara frequencies (length = n_sampling_points)

Errors

• Error::ShapeMismatch of the input if coeffs does not have length basis_size

pub fn evaluate_real(&self, coeffs: &[f64]) -> Result<Vec<Complex<f64>>, Error>

Evaluate real basis coefficients at sampling points

pub fn fit(&self, values: &[Complex<f64>]) -> Result<Vec<Complex<f64>>, Error>

Fit complex basis coefficients from values at sampling points

Arguments

• values - Complex values at Matsubara frequencies (length = n_sampling_points)

Returns

Fitted complex basis coefficients (length = basis_size)

Errors

• Error::ShapeMismatch of the input if values does not have length n_sampling_points
• Error::DecompositionFailed if the singular value decomposition fails

pub fn fit_real(&self, values: &[Complex<f64>]) -> Result<Vec<f64>, Error>

Fit real basis coefficients (real part of the complex solution)

pub fn evaluate_nd<T>( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensor<T>, dim: usize, ) -> Result<TypedTensor<Complex<f64>>, Error>

where T: MatsubaraCoeffs,

Evaluate N-dimensional coefficients at Matsubara sampling points

Supports both real (f64) and complex (Complex<f64>) coefficients and always returns complex values at the Matsubara frequencies. The implementation is selected at compile time through the MatsubaraCoeffs trait.

Type Parameter

• T - Must implement MatsubaraCoeffs (currently f64 or Complex<f64>)

Arguments

• backend - Optional GEMM backend handle (None uses the global dispatcher)
• coeffs - N-dimensional tensor of basis coefficients
• dim - Dimension along which to evaluate (must have size = basis_size)

Returns

N-dimensional tensor of complex values at Matsubara frequencies, with dimension dim of size n_sampling_points

Errors

• Error::AxisOutOfRange if dim is not an axis of coeffs
• Error::ShapeMismatch of the input if coeffs does not have basis_size along dim

Example

use num_complex::Complex;
use sparse_ir::{FermionicBasis, LogisticKernel, MatsubaraSampling, TypedTensor};

let beta = 10.0;
let wmax = 1.0;
let basis = FermionicBasis::new(LogisticKernel::new(beta * wmax).unwrap(), beta, Some(1e-6), None).unwrap();
let sampling = MatsubaraSampling::new(&basis).unwrap();
let (size, n_points) = (sampling.basis_size(), sampling.n_sampling_points());

// Real coefficients: two sets stacked along axis 1 (column-major), evaluated along axis 0
let real_data: Vec<f64> = (0..2 * size)
    .map(|k| 1.0 / (1.0 + (k % size + k / size) as f64))
    .collect();
let coeffs_real = TypedTensor::from_vec_col_major(vec![size, 2], real_data.clone()).unwrap();
let values = sampling.evaluate_nd::<f64>(None, &coeffs_real, 0).unwrap();
assert_eq!(values.shape(), &[n_points, 2]);

// Complex coefficients
let complex_data: Vec<Complex<f64>> =
    real_data.iter().map(|&x| Complex::new(x, -0.5 * x)).collect();
let coeffs_complex = TypedTensor::from_vec_col_major(vec![size, 2], complex_data.clone()).unwrap();
let values_z = sampling.evaluate_nd::<Complex<f64>>(None, &coeffs_complex, 0).unwrap();

// Each column matches the 1-D `evaluate` of the corresponding coefficient set
let (values, values_z) = (values.host_data().unwrap(), values_z.host_data().unwrap());
for j in 0..2 {
    let real: Vec<Complex<f64>> = real_data[j * size..(j + 1) * size].iter().map(|&x| x.into()).collect();
    let complex = &complex_data[j * size..(j + 1) * size];
    let (expected, expected_z) = (sampling.evaluate(&real).unwrap(), sampling.evaluate(complex).unwrap());
    for i in 0..n_points {
        assert!((values[i + n_points * j] - expected[i]).norm() < 1e-12);
        assert!((values_z[i + n_points * j] - expected_z[i]).norm() < 1e-12);
    }
}

pub fn evaluate_nd_real( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensor<f64>, dim: usize, ) -> Result<TypedTensor<Complex<f64>>, Error>

Evaluate real basis coefficients at Matsubara sampling points (N-dimensional)

This method takes real coefficients and produces complex values, useful when working with symmetry-exploiting representations or real-valued IR coefficients.

Arguments

• backend - Optional GEMM backend handle (None uses default)
• coeffs - N-dimensional tensor of real basis coefficients
• dim - Dimension along which to evaluate (must have size = basis_size)

Returns

N-dimensional tensor of complex values at Matsubara frequencies

Errors

• Error::AxisOutOfRange if dim is not an axis of coeffs
• Error::ShapeMismatch of the input if coeffs does not have basis_size along dim

pub fn fit_nd( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensor<Complex<f64>>, dim: usize, ) -> Result<TypedTensor<Complex<f64>>, Error>

Fit N-dimensional array of complex values to complex basis coefficients

Arguments

• backend - Optional GEMM backend handle (None uses default)
• values - N-dimensional tensor of complex values at Matsubara frequencies
• dim - Dimension along which to fit (must have size = n_sampling_points)

Returns

N-dimensional tensor of complex basis coefficients

Errors

• Error::AxisOutOfRange if dim is not an axis of values
• Error::ShapeMismatch of the input if values does not have n_sampling_points along dim
• Error::DecompositionFailed if the singular value decomposition fails

pub fn fit_nd_real( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensor<Complex<f64>>, dim: usize, ) -> Result<TypedTensor<f64>, Error>

Fit N-dimensional array of complex values to real basis coefficients

This method fits complex Matsubara values to real IR coefficients. Takes the real part of the least-squares solution.

Arguments

• backend - Optional GEMM backend handle (None uses default)
• values - N-dimensional tensor of complex values at Matsubara frequencies
• dim - Dimension along which to fit (must have size = n_sampling_points)

Returns

N-dimensional tensor of real basis coefficients

Errors

• Error::AxisOutOfRange if dim is not an axis of values
• Error::ShapeMismatch of the input if values does not have n_sampling_points along dim
• Error::DecompositionFailed if the singular value decomposition fails

pub fn evaluate_nd_to<T>( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensorView<'_, T>, dim: usize, out: &mut TypedTensorViewMut<'_, Complex<f64>>, ) -> Result<(), Error>

where T: MatsubaraCoeffs,

Evaluate basis coefficients at Matsubara sampling points (N-dimensional) with in-place output

Type Parameters

• T - Coefficient type (f64 or Complex)

Arguments

• coeffs - N-dimensional tensor with coeffs.shape().dim(dim) == basis_size
• dim - Dimension along which to evaluate (0-indexed)
• out - Output tensor with out.shape().dim(dim) == n_sampling_points (Complex)

Errors

• Error::AxisOutOfRange if dim is not an axis of coeffs
• Error::ShapeMismatch of the input if coeffs does not have basis_size along dim, and of the output if out does not have the shape of coeffs with n_sampling_points along dim

Nothing is written to out then.

pub fn fit_nd_to( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensorView<'_, Complex<f64>>, dim: usize, out: &mut TypedTensorViewMut<'_, Complex<f64>>, ) -> Result<(), Error>

Fit N-dimensional complex values to complex coefficients with in-place output

Arguments

• values - N-dimensional tensor with values.shape().dim(dim) == n_sampling_points
• dim - Dimension along which to fit (0-indexed)
• out - Output tensor with out.shape().dim(dim) == basis_size (Complex)

Errors

• Error::AxisOutOfRange if dim is not an axis of values
• Error::ShapeMismatch of the input if values does not have n_sampling_points along dim, and of the output if out does not have the shape of values with basis_size along dim
• Error::DecompositionFailed if the singular value decomposition fails

Nothing is written to out then.

Trait Implementations

impl<S> InplaceFitter for MatsubaraSampling<S>

where S: StatisticsType,

fn n_points(&self) -> usize

Number of sampling points.

fn basis_size(&self) -> usize

Number of basis functions.

fn evaluate_nd_dz_to( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensorView<'_, f64>, dim: usize, out: &mut TypedTensorViewMut<'_, Complex<f64>>, ) -> Result<(), Error>

Evaluate: f64 coefficients to Complex<f64> values.

fn evaluate_nd_zz_to( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensorView<'_, Complex<f64>>, dim: usize, out: &mut TypedTensorViewMut<'_, Complex<f64>>, ) -> Result<(), Error>

Evaluate: Complex<f64> coefficients to Complex<f64> values.

fn fit_nd_zd_to( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensorView<'_, Complex<f64>>, dim: usize, out: &mut TypedTensorViewMut<'_, f64>, ) -> Result<(), Error>

Fit: Complex<f64> values to f64 coefficients.

fn fit_nd_zz_to( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensorView<'_, Complex<f64>>, dim: usize, out: &mut TypedTensorViewMut<'_, Complex<f64>>, ) -> Result<(), Error>

Fit: Complex<f64> values to Complex<f64> coefficients.

fn evaluate_nd_dd_to( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensorView<'_, f64>, dim: usize, out: &mut TypedTensorViewMut<'_, f64>, ) -> Result<(), Error>

Evaluate: f64 coefficients to f64 values.

fn evaluate_nd_zd_to( &self, backend: Option<&GemmBackendHandle>, coeffs: &TypedTensorView<'_, Complex<f64>>, dim: usize, out: &mut TypedTensorViewMut<'_, f64>, ) -> Result<(), Error>

Evaluate: Complex<f64> coefficients to f64 values.

fn fit_nd_dd_to( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensorView<'_, f64>, dim: usize, out: &mut TypedTensorViewMut<'_, f64>, ) -> Result<(), Error>

Fit: f64 values to f64 coefficients.

fn fit_nd_dz_to( &self, backend: Option<&GemmBackendHandle>, values: &TypedTensorView<'_, f64>, dim: usize, out: &mut TypedTensorViewMut<'_, Complex<f64>>, ) -> Result<(), Error>

Fit: f64 values to Complex<f64> coefficients.