Private names index

Int(freq::MatsubaraFreq)

The reduced frequency n of the Matsubara frequency ν = nπ/β.

Integer(freq::MatsubaraFreq)

The reduced frequency n of the Matsubara frequency ν = nπ/β.

AbstractAugmentation

Scalar function in imaginary time/frequency.

This represents a single function in imaginary time and frequency, together with some auxiliary methods that make it suitable for augmenting a basis.

See also: AugmentedBasis

AbstractBasis

Abstract base class for bases on the imaginary-time axis.

Let basis be an abstract basis with L = length(basis) functions. Then we can expand a two-point propagator G(τ), where τ is imaginary time, into the basis functions U_l(τ), l = 0, …, L-1:

G(τ) ≈ sum(basis.u[l+1](τ) * g[l+1] for l in 0:L-1),

where Julia's basis.u[l+1] is U_l and g[l+1] is the associated expansion coefficient G_l; the difference is the truncation error of the basis. Similarly, the Fourier transform G(iν), where ν = nπ/β is a Matsubara frequency with reduced frequency n, can be expanded as follows:

G(iν) ≈ sum(basis.uhat[l+1](n) * g[l+1] for l in 0:L-1),

where basis.uhat[l+1] is Û_l, the Fourier transform of U_l.

AbstractKernel

Integral kernel K(x, y).

Abstract base type for an integral kernel, i.e. a real-valued function $K(x, y)$ of the dimensionless variables $x$ and $y$, used in a Fredholm integral equation of the first kind:

\[ u(x) = ∫ K(x, y) v(y) dy\]

where $x ∈ [x_\mathrm{min}, x_\mathrm{max}]$ and $y ∈ [y_\mathrm{min}, y_\mathrm{max}]$. For its SVE to exist, the kernel must be square-integrable, for its singular values to decay exponentially, it must be smooth.

In general, the kernel is applied to a weighted spectral function $ρ(y)$ as:

\[ ∫ K(x, y) ρ(y) dy,\]

where $ρ(y) = w(y) A(y)$ is the spectral function $A$ times a weight $w$ that depends on the kernel and the statistics (see LogisticKernel).

AbstractSVEHints

Discretization hints for singular value expansion of a given kernel.

AbstractSampling

Abstract type for sparse sampling.

Encodes the "basis transformation" of a propagator from the truncated IR basis coefficients G_l to its values G(τ_i) or G(iν_i) on sparse sampling points in imaginary time or Matsubara frequency, together with its inverse, a least squares fit:

     ________________                   ___________________
    |                |    evaluate     |                   |
    |     Basis      |---------------->|     Value on      |
    |  coefficients  |<----------------|  sampling points  |
    |________________|      fit        |___________________|

PiecewiseLegendreFT

A single function of a PiecewiseLegendreFTVector; calling it returns a ComplexF64.

PiecewiseLegendreFTVector

Fourier transforms of a set of piecewise Legendre polynomials, evaluated at Matsubara frequencies.

For a reduced frequency n, i.e. the Matsubara frequency ν = nπ/β, the transform of the basis function U_l is

Û_l(iν) == ∫₀^β dτ exp(iντ) U_l(τ),

and polys[l+1](n) returns Û_l(iν).

The object knows the statistics of its basis: it accepts MatsubaraFreqs of that statistics or integers of the matching parity (odd for fermions, even for bosons). A frequency of the other statistics throws ArgumentError, an integer of the wrong parity DomainError. polys[i] returns a single PiecewiseLegendreFT, polys[range] another vector.

(polys::PiecewiseLegendreFTVector)(x::AbstractVector)

length(polys) × length(x) matrix of the functions at the frequencies x (MatsubaraFreqs or integers, see PiecewiseLegendreFTVector).

PiecewiseLegendrePoly <: Function

Piecewise Legendre polynomial.

Models a function on the interval $[xmin, xmax]$ as a set of segments on the intervals $S[i] = [a[i], a[i+1]]$, where on each interval the function is expanded in scaled Legendre polynomials.

(poly::PiecewiseLegendrePoly)(x::AbstractVector)

Values of the single function poly at the points x.

PiecewiseLegendrePolyVector

Contains a Vector{PiecewiseLegendrePoly}.

(polys::PiecewiseLegendrePolyVector)(x::AbstractVector)

length(polys) × length(x) matrix of the functions at the points x (imaginary times for basis.u, real frequencies for basis.v).

SVEResult(kernel::AbstractKernel, ε=eps(Float64);
    lmax=typemax(Int32), n_gauss=-1, Twork=SPIR_TWORK_AUTO)

Perform the singular value expansion (SVE) of a kernel, computed by libsparseir.

The SVE of an integral kernel kernel : [xmin, xmax] x [ymin, ymax] -> ℝ in the dimensionless variables x and y reads

kernel(x, y) == sum(s[l+1] * u_l(x) * v_l(y) for l in 0, 1, 2, ...),

where s[l+1] is the singular value s_l, ordered in non-increasing fashion, the left singular functions u_l(x) form an orthonormal system on [xmin, xmax], and the right singular functions v_l(y) form an orthonormal system on [ymin, ymax] (both [-1, 1] for the kernels of this package). A FiniteTempBasis built from the result scales them to U_l(τ), S_l and V_l(ω).

The SVE is mapped onto the singular value decomposition (SVD) of a matrix by expanding the kernel in piecewise Legendre polynomials.

Arguments

• kernel::AbstractKernel: Integral kernel to take SVE from.

• ε::Real: Accuracy target (positive and finite). It selects the working precision (see Twork) and the discretization. It does not truncate the expansion: the result keeps the singular values down to about twice the machine epsilon of the working precision relative to the largest one (for example 38 values for LogisticKernel(80.0) and ε = 1e-6). The truncation to s_l/s_0 ≥ ε is done by FiniteTempBasis. Defaults to eps(Float64) (≈ 2.22e-16).

• lmax::Integer: Maximum number of singular values. Passed to libsparseir, which currently ignores it.

• n_gauss::Integer: Number of Gauss points of the discretization; -1 lets the library choose. Passed to libsparseir, which currently ignores it and always chooses the number itself.

• Twork::Integer: Working precision. Available options:

  • SPIR_TWORK_AUTO (default): double precision for ε ≥ 1e-8, extended precision below
  • SPIR_TWORK_FLOAT64: Use double precision (64-bit)
  • SPIR_TWORK_FLOAT64X2: Use extended precision (128-bit, double-double)

  The constants are available as SparseIR.SPIR_TWORK_AUTO etc.

Returns: An SVEResult, whose field s holds the singular values s_l of the dimensionless expansion.

SparseIRError <: Exception

Raised when a call into libsparseir fails. Carries a human-readable message naming the failing C entry point and, where available, the raw numeric status code returned by that entry point (status, nothing for failures that are not reported through a status code, such as a null handle).

Statistics(zeta)

Abstract type for quantum statistics. The argument is the parity ζ of the statistics (see zeta): Statistics(1) is Fermionic() and Statistics(0) is Bosonic(); any other value throws DomainError.

basis[1:n]

Truncate the basis to its n most significant singular values and functions. The truncated basis shares the kernel and the SVE of basis; only ranges 1:n with 1 ≤ n ≤ length(basis) are supported.

cond(sampling::MatsubaraSampling)

Condition number of the sampling problem. With positive_only = true this is the condition number of the real least-squares problem [Re A; Im A] x = [Re g; Im g] that fit solves; the C library reports that of the complex matrix A instead, which understates it (SpM-lab/sparse-ir-rs#270).

_as_input_array(a, name)

a as an Array{Float64} (real element types) or Array{ComplexF64} (complex element types), the element types the C entry points read. The conversion is explicit, so Float32, integer or Rational input and views, transposes or other wrappers are copied into a new array; an Array that already has the right element type is returned as is. Throws ArgumentError for other element types and for non-finite entries.

_check_all_finite(A, name)

Throw ArgumentError naming the first offending index if A contains a NaN or an infinity. Called at construction time for every array this wrapper hands to a C entry point that factorizes, decomposes or solves with it.

_check_handle(ptr, operation)

Throw SparseIRError if a C entry point returned a null handle.

_check_status(status, operation)

Check a libsparseir status code exhaustively: return nothing on SPIR_COMPUTATION_SUCCESS, throw DimensionMismatch for the dimension-related codes and SparseIRError for every other value, including codes this wrapper does not know about.

_check_unique(points, name)

Throw ArgumentError if points contains an exact duplicate. Duplicated sampling points make the sampling matrix rank-deficient (infinite condition number), which the C API accepts silently and which produces meaningless fit coefficients.

_status_name(status)

Name of a known libsparseir status code, or a marker for an unrecognized one.

accuracy(basis::AbstractBasis)

Accuracy of the basis.

Upper bound to the relative error of representing a propagator with the given number of basis functions (number between 0 and 1). For an IR basis of size L it is S_L/S_0, the first discarded singular value relative to the largest one.

basis(sampling::AbstractSampling)

Return the IR basis associated with sampling.

cover_domain(knots::Vector{Float64}, xmin::Float64, xmax::Float64, period::Float64, poly_xmin::Float64, poly_xmax::Float64)

Generate knots that cover the integration domain, handling periodic functions.

This function extends the basic knots to cover the entire integration domain, taking into account periodicity if applicable.

default_matsubara_sampling_points(basis::AbstractBasis; positive_only=false)

Default sampling points on the imaginary frequency axis, as a Vector{Int} of reduced frequencies n (ν = nπ/β, odd for fermions, even for bosons).

The points are the sign changes of the first discarded transform Û_l, with l ≥ L = length(basis) chosen to fit the parity. Bosonic sets always include n = 0. A DLR uses the points of its IR basis.

Arguments

• positive_only::Bool: Only return non-negative frequencies, n ≥ 0. This is useful if the object to be fitted is symmetric in Matsubara frequency, G(-iν) == conj(G(iν)), or, equivalently, real in imaginary time.

default_tau_sampling_points(basis::AbstractBasis; use_positive_taus=true)

Default sampling points in imaginary time: the roots of U_L, the first basis function beyond a basis of size L = length(basis).

With use_positive_taus=true (the default) the points are folded into (0, β) and sorted, so that reversing them maps τ to β - τ. With use_positive_taus=false they are returned unfolded, in (-β/2, β/2]: pairs ±τ, plus β/2 when their number is odd, so reversing them maps τ to -τ only for an even number. A DLR uses the points of its IR basis.

deriv(poly::PiecewiseLegendrePoly, n=1)
deriv(polys::PiecewiseLegendrePolyVector, n=1)

Return the n-th derivative of poly/polys as a new object of the same type, computed by libsparseir. n may be given as an Integer or as a Val, and must be non-negative; n == 0 returns a copy.

eval_matrix(T, basis, x)

Return evaluation matrix from coefficients to sampling points. T <: AbstractSampling.

finite_temp_bases(β::Real, ωmax::Real, ε;
                  kernel=LogisticKernel(β * ωmax), sve_result=SVEResult(kernel, ε))

Construct FiniteTempBasis objects for fermion and bosons using the same LogisticKernel instance and SVE. The two bases share U_l, S_l and V_l; the bosonic IR coefficients are those of ρ(ω) = A(ω)/tanh(βω/2) (see FiniteTempBasis).

Arguments

• β: Inverse temperature (must be positive)
• ωmax: Frequency cutoff (must be positive)
• ε: This parameter controls the number of basis functions. Only the singular values with S_l/S_0 ≥ ε are kept. Typical values are 1e-6 to 1e-12 depending on the desired accuracy for your calculations. If ε is smaller than 1e-8, the library will automatically use higher (double-double) precision for the singular value expansion, resulting in longer computation time for basis generation.

The number of basis functions grows logarithmically as log(1/ε) log (β * ωmax).

iswellconditioned(basis::AbstractBasis)

Returns true if the sampling is expected to be well-conditioned.

normalize_tau(S::Type{<:Statistics}, tau, beta) -> (tau_normalized, sign)

Normalize τ to the range [0, β] with statistics-dependent boundary conditions.

Handles boundary conditions based on statistics:

• Fermions: Anti-periodic G(τ + β) = -G(τ)
• Bosons: Periodic G(τ + β) = G(τ)

The endpoints are read as one-sided limits, as by basis.u: 0.0 is 0⁺ and β is β⁻ (both returned unchanged), -0.0 is 0⁻ and -β is (-β)⁺.

Arguments

• S: Statistics type (Fermionic or Bosonic)
• tau: Imaginary time in range [-β, β]; DomainError outside
• beta: Inverse temperature

Returns

• (tau_normalized, sign): Normalized τ ∈ [0, β] and sign factor

Special Cases

For Fermionic statistics:

• tau = -0.0 (negative zero) → (tau_normalized = β, sign = -1.0)
• tau ∈ [-β, 0) → wraps to tau + β ∈ [0, β) with sign = -1.0; in particular tau = -β → (0.0, -1.0)

For Bosonic statistics:

• tau = -0.0 (negative zero) → (tau_normalized = β, sign = 1.0)
• tau ∈ [-β, 0) → wraps to tau + β ∈ [0, β) with sign = 1.0; in particular tau = -β → (0.0, 1.0)

rescale(basis::FiniteTempBasis, new_beta)

Return a basis for different temperature.

Creates a new basis with the same accuracy $ε$ but different temperature. The new kernel is constructed with the same cutoff parameter $Λ = β * ωmax$, which implies a different frequency cutoff ωmax = Λ / new_beta since $Λ$ stays constant.

Arguments

• basis: The original basis to rescale
• new_beta: New inverse temperature

Returns

A new FiniteTempBasis with the same statistics type and accuracy but different temperature.

s(basis::AbstractBasis)

Get the singular values S_l of the basis, basis.s; s(basis)[l+1] is S_l.

significance(basis::AbstractBasis)

Return vector σ, where 0 ≤ σ[l+1] ≤ 1 is the significance level of the basis function U_l. If ε is the desired accuracy to which to represent a propagator, then any basis function where σ[l+1] < ε can be neglected.

For the IR basis, we simply have that σ[l+1] = S_l / S_0.

statistics(basis::AbstractBasis)

Quantum statistic (Statistics instance, Fermionic() or Bosonic()).

u(basis::AbstractBasis)

Get the basis functions in imaginary time, basis.u: for an IR basis the U_l(τ), with u(basis)[l+1] being U_l. They accept τ ∈ [-β, β]; see FiniteTempBasis for the extension to negative τ and the endpoints.

uhat(basis::AbstractBasis)

Get the basis functions in Matsubara frequency, basis.uhat, the Fourier transforms of those of u: for an IR basis the Û_l(iν), with uhat(basis)[l+1] being Û_l. They take the reduced frequency n (ν = nπ/β) or a MatsubaraFreq.

v(basis::AbstractBasis)

Get the basis functions V_l(ω) in real frequency, basis.v, for ω ∈ [-ωmax, ωmax]; v(basis)[l+1] is V_l.

value(freq::MatsubaraFreq, β)

The Matsubara frequency ν = nπ/β as a real number.

valueim(freq::MatsubaraFreq, β)

The imaginary frequency iν = i nπ/β as a complex number.

zeta(stat::Statistics)
zeta(freq::MatsubaraFreq)

Parity ζ of the statistics: 1 for Fermionic() and 0 for Bosonic(). A shift by β multiplies a function of imaginary time by (-1)^ζ, and the reduced frequency of a Matsubara frequency is n = 2m + ζ, where m is the ordinary Matsubara index, i.e. ν = (2m + ζ)π/β.

Λ(basis::AbstractBasis)
lambda(basis::AbstractBasis)

Basis cutoff parameter, Λ = β * ωmax.

β(basis::AbstractBasis)
beta(basis::AbstractBasis)

Inverse temperature of the basis.

Returns the inverse temperature parameter β used in the basis construction.

ωmax(basis::AbstractBasis)
wmax(basis::AbstractBasis)

Real frequency cutoff ωmax of the basis: the spectral function is represented on [-ωmax, ωmax].