Crate sparse_ir

Expand description

§sparse-ir

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

§Features

All of these are in the 0.11 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 0.11 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.11.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.11.0", features = ["system-blas"] }

Both backends compute the same numbers; the feature only changes which implementation multiplies the matrices.

§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-core: statistics, errors, GEMM, fitters, the Basis trait and sparse sampling;
sparse-ir-basis: kernels, the singular value expansion and the IR basis FiniteTempBasis;
sparse-ir-dlr: the discrete Lehmann representation;
sparse-ir-minipole: ESPRIT and minimal pole representations.

§Dependencies

Tensors and linear algebra: tenferro-rs (CPU) + faer
Extended precision: xprec-rs

§License

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

You may use this crate under the terms of either license, at your option:
- MIT License
- Apache License 2.0

§Third-party licenses

The col_piv_qr module of sparse-ir-basis 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).

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

The Rust User Guide walks through sparse sampling, IR/DLR transforms, MiniPole and applied calculations, with runnable examples.
FiniteTempBasis, TauSampling and MatsubaraSampling are the entry points for the IR basis; DiscreteLehmannRepresentation and DlrBuilder for the DLR; minipole and esprit for pole reconstruction.

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 and correction for numerical stability
freq: Matsubara frequency implementation for SparseIR
gauss: Gauss quadrature rules for numerical integration
gemm: Column-major GEMM with a pluggable BLAS backend.
ir_dlr: Discrete Lehmann representations built from an IR basis
kernel: Kernel implementations for SparseIR
kernelmatrix: Kernel matrix discretization for SparseIR
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 polynomial implementations for SparseIR
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) module
taufuncs: Imaginary time τ normalization utilities
traits: Common trait definitions for SparseIR
tsvd: High-precision truncated SVD implementation using 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.
LogisticKernel: Logistic kernel for fermionic and bosonic analytical continuation
LogisticSVEHints: SVE hints for LogisticKernel
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
SVEResult: Result of Singular Value Expansion computation
SamplingSVE: Sampling-based SVE computation
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
SVDStrategy: SVD computation strategy
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
CentrosymmKernel: Trait for centrosymmetric kernels
CustomNumeric: Custom numeric trait for high-precision numerical computation
DlrFromIr: Constructors of a DiscreteLehmannRepresentation from an IR basis
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: Trait for kernel type properties (static characteristics)
SVEHints: Trait for SVE (Singular Value Expansion) hints
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 for centrosymmetric kernels
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: Create a Gauss-Legendre quadrature rule with n points on [-1, 1].
legendre_custom: Create a Gauss-Legendre quadrature rule with n points on [-1, 1] (CustomNumeric version).
legendre_twofloat: Create a Gauss-Legendre quadrature rule with n points on [-1, 1] (Df64 version).
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

Crate sparse_ir

Crate sparse_ir Copy item path

§sparse-ir

§Features

§Documentation

§Installation

§Optional: system BLAS

§Usage

§Quick start: fit and evaluate with the IR basis

§DLR without an IR basis

§Crate layout

§Dependencies

§License

§Third-party licenses

§Contributing

§References

§Where to go next

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate sparse_ir