Skip to main content

Crate sparse_ir

Crate sparse_ir 

Source
Expand description

§sparse-ir

Crates.io Documentation License: MIT OR Apache-2.0

IR basis, DLR, ESPRIT/MiniPole and sparse sampling for imaginary-time Green’s functions, in pure Rust.

§Features

All of these are in the current release on crates.io:

  • Intermediate representation (IR) basis for fermionic and bosonic statistics
  • Discrete Lehmann representation (DLR), built independently of an IR basis (DiscreteLehmannRepresentation::new, DlrBuilder) or from one (from_ir)
  • ESPRIT and MiniPole pole reconstruction (sparse_ir::esprit, sparse_ir::minipole)
  • Sparse sampling in imaginary time and Matsubara frequencies

§Documentation

The Rust User Guide has tutorials with figures and runnable examples, written against the current release; start with its installation and conventions pages. The API reference for the release is on docs.rs/sparse-ir; the guide also hosts the API reference built from main. For AI-assisted Rust use, load the SparseIR Rust usage skill when choosing crates, imports, or numerical conventions.

§Installation

sparse-ir requires Rust 1.96 or newer. Add it to your Cargo.toml:

[dependencies]
sparse-ir = "0.16.0"

§Optional: system BLAS

By default, sparse-ir uses faer (pure Rust) for the matrix products in fit and evaluate. To route them through the LP64 BLAS installed on your system (e.g. OpenBLAS, Intel MKL), enable the system-blas feature:

[dependencies]
sparse-ir = { version = "0.16.0", features = ["system-blas"] }

Both backends implement the same transforms and memory-order contract; the feature only changes which implementation multiplies the matrices. The results are not guaranteed to be bit-identical: rounding can differ, and an ill-conditioned step such as the DLR coefficient transforms can amplify the difference (about 1e-12 was measured, SpM-lab/sparse-ir-rs#326).

§Usage

Matsubara frequencies are indexed by the reduced integer n, with iν_n = i n π/β (n odd for fermions, even for bosons). Imaginary-time sampling points lie in [−β/2, β/2]. See the guide’s conventions page for details.

§Quick start: fit and evaluate with the IR basis

Build an IR basis, sample a Green’s function G(τ) on the basis’s τ points, fit its IR coefficients g_l, and evaluate them on the Matsubara sampling points. The model is a single pole at ω = 0.5, whose exact values are known on both axes.

use sparse_ir::{
    FermionicBasis, LogisticKernel, MatsubaraSampling, TauSampling, fermionic_single_pole,
    giwn_single_pole,
};

fn main() -> Result<(), sparse_ir::Error> {
    let (beta, wmax, omega) = (10.0, 1.0, 0.5);

    // IR basis for Λ = β ω_max, truncated at s_l / s_0 < 1e-10
    let kernel = LogisticKernel::new(beta * wmax)?;
    let basis = FermionicBasis::new(kernel, beta, Some(1e-10), None)?;

    // G(τ) on the τ sampling points → IR coefficients g_l
    let tau_sampling = TauSampling::new(&basis)?;
    let g_tau = tau_sampling
        .sampling_points()
        .iter()
        .map(|&tau| fermionic_single_pole(tau, omega, beta))
        .collect::<Result<Vec<_>, _>>()?;
    let g_l = tau_sampling.fit(&g_tau)?;

    // g_l → G(iν_n) on the Matsubara sampling points
    let matsubara_sampling = MatsubaraSampling::new(&basis)?;
    let g_iw = matsubara_sampling.evaluate_real(&g_l)?;
    for (freq, value) in matsubara_sampling.sampling_points().iter().zip(&g_iw) {
        let exact = giwn_single_pole(freq, omega, beta)?;
        assert!((value - exact).norm() < 1e-8);
    }
    Ok(())
}

§DLR without an IR basis

The DLR represents G as a sum of poles ω_p with coefficients c_p. DiscreteLehmannRepresentation::new(beta, wmax, eps) chooses the poles directly, without building an IR basis, and works with the same sampling types.

use sparse_ir::{
    DiscreteLehmannRepresentation, Fermionic, MatsubaraSampling, TauSampling,
    fermionic_single_pole, giwn_single_pole,
};

fn main() -> Result<(), sparse_ir::Error> {
    let (beta, wmax, omega) = (10.0, 1.0, 0.5);

    let dlr = DiscreteLehmannRepresentation::<Fermionic>::new(beta, wmax, 1e-10)?;
    println!("{} poles", dlr.poles().len());

    // G(τ) on the DLR's τ nodes → pole coefficients c_p
    let tau_sampling = TauSampling::new(&dlr)?;
    let g_tau = tau_sampling
        .sampling_points()
        .iter()
        .map(|&tau| fermionic_single_pole(tau, omega, beta))
        .collect::<Result<Vec<_>, _>>()?;
    let c_p = tau_sampling.fit(&g_tau)?;

    // c_p → G(iν_n) on the DLR's Matsubara nodes
    let matsubara_sampling = MatsubaraSampling::new(&dlr)?;
    let g_iw = matsubara_sampling.evaluate_real(&c_p)?;
    for (freq, value) in matsubara_sampling.sampling_points().iter().zip(&g_iw) {
        let exact = giwn_single_pole(freq, omega, beta)?;
        assert!((value - exact).norm() < 1e-8);
    }
    Ok(())
}

More examples, including IR ↔ DLR transforms, MiniPole and applied calculations, are in the user guide.

§Crate layout

sparse-ir re-exports the crates it is made of, under their usual paths; you can also depend on them directly:

  • sparse-ir-sve: the singular value expansion of integral kernels, with the ACA-accelerated truncated SVD;
  • sparse-ir-core: statistics, errors, GEMM, fitters, the Basis trait and sparse sampling;
  • sparse-ir-basis: the kernels and the IR basis FiniteTempBasis;
  • sparse-ir-dlr: the discrete Lehmann representation;
  • sparse-ir-minipole: ESPRIT and minimal pole representations.

§Dependencies

§License

This crate is dual-licensed under the terms of the MIT license and the Apache License (Version 2.0).

§Third-party licenses

The col_piv_qr module of sparse-ir-sve is based on code from the nalgebra library, which is licensed under the Apache License 2.0:

  • nalgebra: Apache License 2.0
    • Original source: nalgebra/src/linalg/col_piv_qr.rs
    • Copyright 2020 Sébastien Crozet
    • See Apache License 2.0 for details

Modifications and additions to the nalgebra code (including early termination support) are available under the same dual license as this crate (MIT OR Apache-2.0); see sparse-ir-sve/LICENSE-THIRD-PARTY.

The ESPRIT and MiniPole code of sparse-ir-minipole is a port of MiniPole (MIT License); see sparse-ir-minipole/LICENSE-THIRD-PARTY.

§Contributing

Contributions are welcome! Please see the development guide for details.

§References

  • sparse-ir: optimal compression and sparse sampling of many-body propagators
    Markus Wallerberger, Samuel Badr, Shintaro Hoshino, Fumiya Kakizawa, Takashi Koretsune, Yuki Nagai, Kosuke Nogaki, Takuya Nomoto, Hitoshi Mori, Junya Otsuki, Soshun Ozaki, Rihito Sakurai, Constanze Vogel, Niklas Witt, Kazuyoshi Yoshimi, Hiroshi Shinaoka
    arXiv:2206.11762 | SoftwareX 21, 101266 (2023)
  • Python wrapper: sparse-ir
  • Julia wrapper: SparseIR.jl

§Where to go next

Modules§

basis
Finite temperature basis for SparseIR
basis_trait
Basis trait for IR and DLR representations
dlr
Discrete Lehmann Representation (DLR)
error
Error type of the public API
esprit
Matrix ESPRIT (port of mini_pole/esprit.py).
fitters
Fitters for least-squares problems with various matrix types
fpu_check
FPU state checking for Intel Fortran compatibility
freq
Matsubara frequency implementation for SparseIR
gauss
Gauss quadrature rules for numerical integration
gemm
Column-major GEMM with a pluggable BLAS backend.
hints
SVE hints given by the segments of the domain
ir_dlr
Discrete Lehmann representations built from an IR basis
kernel
Kernel implementations for SparseIR
kernelmatrix
Kernel matrices on the Gauss points of the SVE
matrix
Small column-major dense containers for internal numerics.
matsubara_sampling
Sparse sampling in Matsubara frequencies
minipole
Port of the minimal pole method of Green-Phys/MiniPole.
numeric
Custom numeric traits for high-precision computation
poly
Piecewise Legendre polynomials
polyfourier
Piecewise Legendre polynomial Fourier transform implementation for SparseIR
sampling
Sparse sampling in imaginary time
special_functions
Special functions implementation ported from C++ libsparseir
sve
Singular value expansion (SVE) of the kernels, from sparse-ir-sve
taufuncs
Imaginary time τ normalization utilities
traits
Common trait definitions for SparseIR
tsvd
Truncated SVD in f64 and double-double, by nalgebra

Macros§

debug_warn
Print a warning to stderr only when the SPARSEIR_DEBUG environment variable enables debug diagnostics (see is_debug_enabled for the accepted values).

Structs§

Bosonic
Bosonic statistics marker type
CentrosymmSVE
Centrosymmetric SVE computation
DiscreteLehmannRepresentation
Discrete Lehmann Representation (DLR)
DiscretizedKernel
This structure stores a discrete kernel matrix along with the corresponding Gauss quadrature rules for x and y coordinates. This enables easy application of weights for SVE computation and maintains the relationship between matrix elements and their corresponding quadrature points.
DlrBuilder
Builder for the independent (interpolative-decomposition) DLR.
DynRank
Dynamic tensor rank marker.
Fermionic
Fermionic statistics marker type
FiniteTempBasis
Finite temperature basis for imaginary time/frequency Green’s functions
IrDlrTransform
Linear map between the coefficients of an IR basis and of a DLR on the same domain.
KernelBlock
A discretized, weighted kernel matrix A[i, j] = K(x_i, y_j) √w_i √w'_j (Gauss points x_i, y_j, weights w_i, w'_j) whose entries are evaluated on demand
LogisticKernel
Logistic kernel for fermionic and bosonic analytical continuation
LogisticKernelWindowed
Logistic kernel restricted to an asymmetric frequency window
LogisticSVEHints
SVE hints for LogisticKernel
LogisticWindowedSVEHints
SVE hints for LogisticKernelWindowed on its full domain
MatsubaraFreq
Matsubara frequency for a specific statistics type
MatsubaraSampling
Matsubara sampling for full frequency range (positive and negative)
MatsubaraSamplingPositiveOnly
Matsubara sampling for positive frequencies only
PiecewiseLegendreFT
Piecewise Legendre polynomial with Fourier transform capability
PiecewiseLegendreFTVector
Vector of PiecewiseLegendreFT polynomials
PiecewiseLegendrePoly
A single piecewise Legendre polynomial
PiecewiseLegendrePolyVector
Vector of piecewise Legendre polynomials
PowerModel
Power model for asymptotic behavior
Rank
Static tensor rank marker.
RegularizedBoseKernel
Regularized bosonic analytical continuation kernel
RegularizedBoseSVEHints
SVE hints for RegularizedBoseKernel
Rule
Quadrature rule for numerical integration.
SVDResult
Result of SVD decomposition
SVEOptions
Options of compute_sve_with
SVEResult
Result of Singular Value Expansion computation
SamplingSVE
Sampling-based SVE computation
SegmentHints
SVEHints given by the segment boundaries of the domain
TSVDConfig
Configuration for TSVD computation
TauSampling
Sparse sampling in imaginary time
TypedTensor
TypedTensorView
Read-only borrowed view of typed tensor storage with arbitrary strides.
TypedTensorViewMut
Mutable borrowed view of typed tensor storage with arbitrary strides.

Enums§

ArrayRole
Which array of an operation has the wrong shape, in Error::ShapeMismatch
Error
Error returned by the fallible public functions of this crate
ErrorKind
Category of an Error
MatsubaraPointMethod
How the Matsubara sampling points of a basis are chosen
Statistics
Statistics type enumeration
SymmetryType
TworkType
Working precision type for SVE computations

Traits§

AbstractKernel
Trait for general kernels (both centrosymmetric and non-centrosymmetric)
Basis
Common trait for basis representations in imaginary-time/frequency domains
BasisKernel
Kernel of a finite-temperature basis: the kernels that FiniteTempBasis accepts
CentrosymmKernel
Trait for centrosymmetric kernels
CustomNumeric
Custom numeric trait for high-precision numerical computation
DlrFromIr
Constructors of a DiscreteLehmannRepresentation from an IR basis
ExpandableKernel
The kernels whose SVE compute_sve computes
InplaceFitter
Evaluation and fitting along one axis of an N-dimensional tensor, writing into a caller-provided output view.
IrBasis
A basis with a kernel: the IR basis FiniteTempBasis
KernelProperties
The physical properties of a kernel, on top of its SVE (SVEKernel)
ReducedKernel
Trait for centrosymmetric kernels, through their reduced kernels
SVEHints
Trait for SVE (Singular Value Expansion) hints
SVEKernel
The domain of a kernel and the discretization hints of its SVE
SVEStrategy
Trait for SVE computation strategies
StatisticsMarker
Trait for types that can represent statistics at runtime
StatisticsType
Statistics type trait for compile-time type-level distinction
TensorScalar
Sealed trait for scalar types that can be stored in a [Tensor].

Functions§

bosonic_single_pole
Compute bosonic single-pole Green’s function at imaginary time τ
compute_logistic_kernel
compute_sve
Main SVE computation function
compute_sve_with
The SVE of kernel with options
fermionic_single_pole
Compute fermionic single-pole Green’s function at imaginary time τ
giwn_single_pole
Generic single-pole Green’s function at Matsubara frequency
gtau_single_pole
Generic single-pole Green’s function at imaginary time τ
is_debug_enabled
Returns true if the SPARSEIR_DEBUG environment variable enables debug diagnostics.
legendre
The Gauss-Legendre rule with n points on [-1, 1], in T, by Newton’s method on the Legendre polynomial
matrix_from_gauss
Compute matrix from Gauss quadrature rules (legacy version without segments)
matrix_from_gauss_noncentrosymmetric
Compute matrix from Gauss quadrature rules for non-centrosymmetric kernels
matrix_from_gauss_with_segments
Compute matrix from Gauss quadrature rules with segments from SVEHints
svd_decompose
Perform SVD decomposition using nalgebra with sorted singular values
tsvd
Main TSVD function using QR + SVD approach
tsvd_df64
Convenience function for Df64 TSVD
tsvd_df64_from_f64
Convenience function for Df64 TSVD from f64 matrix
tsvd_f64
Convenience function for f64 TSVD

Type Aliases§

BosonicBasis
Type alias for bosonic basis with LogisticKernel
BosonicFreq
BosonicPiecewiseLegendreFT
BosonicPiecewiseLegendreFTVector
Df64
Compensated f64 (emulated quad precision) type.
FermionicBasis
Type alias for fermionic basis with LogisticKernel
FermionicFreq
FermionicPiecewiseLegendreFT
FermionicPiecewiseLegendreFTVector
Matrix
Dense column-major host matrix used by the public API.
Result
Result type of the fallible public functions of this crate