Enrich the tests, fix the wrapper defects they expose, and document the conventions

[shinaoka]

Summary

This PR does three things:

• Tests. It brings the test suite up to the mandatory coverage of spm-agent-rules/testing.md, including oracle tests whose reference values do not come from libsparseir.
• Defects. It fixes the wrapper defects the new tests exposed. Backend defects are reported upstream and pinned with strict xfails.
• Documentation. It documents the conventions the code implements, with the notation shared by the sparse-ir documentation, the tutorial and SparseIR.jl.

Behavior changes (user-visible)

• Out-of-domain input: u(τ), v(ω), DLR poles and TauSampling points outside their domain raise ValueError before the C call. Before, this was a Rust panic surfacing as RuntimeError with status -7 (Out-of-domain τ/ω in spir_funcs_eval/spir_funcs_batch_eval and out-of-range points in spir_tau_sampling_new panic, collapsed to SPIR_INTERNAL_ERROR instead of SPIR_INVALID_ARGUMENT (core Rust + C ABI) sparse-ir-rs#266).

• Parity: uhat(n) with the wrong parity raises ValueError (was status -5).

• Empty input: empty evaluation arrays return an empty result of the right shape (was status -6).

• TauSampling order: user-supplied points keep the given order. They used to be sorted silently, so evaluate() returned values in a different order from the points given.

• Sampling points: these raise ValueError:

  • duplicated sampling points
  • negative points with positive_only=True
  • genuinely complex coefficients in evaluate() with positive_only=True

• Parameters: these raise ValueError:

  • wmax <= 0 or eps <= 0
  • non-finite beta, wmax, eps or lambda_
  • max_size = 0
  • a kernel or SVE that does not match beta * wmax
  • RegularizedBoseKernel with fermionic statistics

• Statistics: an invalid statistics string with kernel= given used to be accepted silently and built a bosonic basis. It now raises ValueError.

• Augmented function sets: these now work:

  • AugmentedTauFunction.xmin/xmax and AugmentedMatsubaraFunction.zeta
  • the size, shape and slicing of augmented function sets
  • TauLinear.hat(scalar)

  aug.u[-1] now returns the last function; it used to return an augmentation.

• Augmented positive_only sampling: MatsubaraSampling(AugmentedBasis(...), positive_only=True) with the default points works now. It always failed before, because the positive-only default points of augmented bases were a truncated set padded with zeros. They are now the non-negative half of the full set, as for a plain basis.

• Basis truncation: basis[:n] now truncates a FiniteTempBasis to its n most significant singular values. It raised NotImplementedError, which also made AugmentedBasis slicing unusable. Closes Basis truncation (basis[:n]) is unimplemented, which makes AugmentedBasis slicing unusable #84.

• Selections of basis functions:

  • Empty selections raise ValueError before the call; the C library panics on them (fix(capi): spir_funcs_get_slice with nslice = 0 panics ("Cannot create empty PiecewiseLegendrePolyVector"), collapsed to SPIR_INTERNAL_ERROR sparse-ir-rs#269).
  • Selections of uhat by list give a set; a list used to give a single-function object holding several functions.
  • Single functions have deriv.
  • Augmented function sets reject index lists with TypeError, and truncation to only the augmentations with ValueError.

• MatsubaraSampling.cond with positive_only=True: it is now the condition number of the real least-squares problem that fit solves. The C library reports that of the complex matrix, for example 55 instead of 2e7 for an augmented basis (fix(capi): spir_sampling_get_cond_num reports the condition number of the complex half matrix for positive-only Matsubara samplings, not of the real least-squares problem that fit solves sparse-ir-rs#270).

• Other checks:

  • A DLR on anything but a FiniteTempBasis raises TypeError; it used to be an AttributeError.
  • SVEResult raises TypeError for a non-numeric eps.
  • Matsubara indices beyond the int64 range raise ValueError without an overflow warning.

• overlap: it checks its interval once instead of at every quadrature point (0.011 s → 0.007 s). It probes the integrand with a NumPy scalar and accepts Python-float results, so the README's GF(2) example runs again; it failed with AttributeError on w.clip.

• TauConst and TauLinear are bosonic-only: statistics='F' raises ValueError.

  • For fermions, TauLinear.hat returned the bosonic transform, so its τ and Matsubara columns disagreed.
  • TauConst's docstring listed fermions while its constructor refused them, giving a false reason.

• Augmentation instances: an instance passed to AugmentedBasis must have the basis's β, and TauConst/TauLinear a bosonic basis. They were passed through unchecked, so e.g. TauConst(5.0) augmented a β = 10 basis.

• FiniteTempBasisSet.rescale keeps eps. It passed the basis accuracy, so eps shrank and the basis could grow (20 → 21 functions at eps = 1e-6).

• RegularizedBoseKernel is deprecated and emits a DeprecationWarning; LogisticKernel is the default for both statistics. Its docstring had the sign of the denominator wrong and called it fermionic.

• Documentation:

  • README and doc/tutorial.rst link to the v2 tutorial and sparse-ir-rs.
  • The stale copies in tutorials/ are removed.
  • doc/kernels.rst marks RegularizedBoseKernel deprecated and fixes the bosonic weight of LogisticKernel (1/tanh(βω/2), not 1/tanh(ω/ωmax)).

Documentation

The docstrings, README.rst and doc/ now state the conventions the code implements, with the notation of the new sparse-ir-doc page Notation and conventions (SpM-lab/sparse-ir-doc#5). Library code is unchanged: with docstrings removed, the syntax trees of the changed modules are identical.

• Conventions now stated:
  • G(τ) = −⟨T c c†⟩ and G_l = −S_l ρ_l, with ρ = A for fermions and A/tanh(βω/2) for bosons;
  • the Fourier transform and its inverse;
  • orthonormality on [0, β] and [−ωmax, ωmax], and the sign rule U_l(β⁻) > 0;
  • S_l = √(βωmax/2) s_l;
  • the τ domain [−β, β] with its endpoints (+0.0 = 0⁺, β = β⁻, −0.0 = 0⁻, −β = (−β)⁺);
  • the reduced Matsubara frequency n (ν = nπ/β), positive_only (n ≥ 0), and the DLR functions u_p = −K(τ, ω̄_p) and û_p.
• Wrong statements fixed:
  • the FiniteTempBasis example computed −G (gl = +s·v);
  • DLR poles are the roots of V_L, not "extrema";
  • dlr.py's formula omitted the bosonic tanh factor;
  • unfolded τ points are symmetric about 0, not about β/2;
  • SVEResult does not truncate at eps;
  • "fit only exists in the complex flavour";
  • "(scaled/unscaled)", the attribute V, "kernel inferred from statistics", ω points called "imaginary time", the reduced-frequency formula in _util.py and the −0.0 case of normalize_tau.
• doc/kernels.rst: the section on custom kernels described an API that does not exist; it now lists the two supported kernels and how to pass one.
• doc/conf.py: autoclass_content = "both", so constructor parameters render. The Parameters headers are in NumPy style.
• Checks:
  • Every stated convention was checked numerically, e.g. the endpoint rules exactly, orthonormality to 3e−15, and the DLR formulas to 1e−15.
  • The examples in the text run and give what the text says; the FiniteTempBasis example reproduces 1/(iν − 2.5) to 4.5e−16.
  • Sphinx builds with 0 warnings.

Backend defects found

All were reported to SpM-lab/sparse-ir-rs. All but #273 are fixed on its main branch; the fixes reach this package with the next pylibsparseir release.

• fix(polyfourier): asymptotic uhat (|n| >= n_asymp = 40Λ) is wrong for basis functions l ≡ 1, 2 (mod 4) — power_moments uses the block-local index l from the centrosymmetric SVE (core Rust) sparse-ir-rs#265: uhat is wrong for l ≡ 1, 2 (mod 4) at |n| ≥ 40Λ.
  • Fixed upstream by Renumber merged SVE functions to fix asymptotic uhat parity sparse-ir-rs#276.
  • Pinned here by 4 strict xfails in tests/test_oracle.py. They turn into unexpected passes, to be removed, once a fixed pylibsparseir is used.
• Out-of-domain τ/ω in spir_funcs_eval/spir_funcs_batch_eval and out-of-range points in spir_tau_sampling_new panic, collapsed to SPIR_INTERNAL_ERROR instead of SPIR_INVALID_ARGUMENT (core Rust + C ABI) sparse-ir-rs#266: out-of-domain τ/ω panic in the C library. Fixed upstream by #281; the wrapper validates first anyway.
• fix(capi): spir_basis_get_default_matsus_ext uses n_points as both the basis size and the output capacity, so the count-then-fill protocol returns a truncated or different point set (C ABI + pylibsparseir) sparse-ir-rs#268: spir_basis_get_default_matsus_ext used n_points both as the basis size and as the output capacity, which gave the positive-only point sets above.
  • Fixed upstream by #274.
  • The wrapper no longer asks C for these sets.
• fix(capi): spir_funcs_get_slice with nslice = 0 panics ("Cannot create empty PiecewiseLegendrePolyVector"), collapsed to SPIR_INTERNAL_ERROR sparse-ir-rs#269: an empty spir_funcs_get_slice panics. Fixed upstream by #281; the wrapper rejects empty selections first.
• fix(capi): spir_sampling_get_cond_num reports the condition number of the complex half matrix for positive-only Matsubara samplings, not of the real least-squares problem that fit solves sparse-ir-rs#270: cond of positive-only samplings is understated. Fixed upstream by #280; the wrapper computes it itself.
• RegularizedBoseKernel: FiniteTempBasis scales its singular values by ωmax^(-ypower), so the basis represents K(τ,ω)/ωmax² instead of the irbasis kernel — fix the scale, then deprecate (core Rust + C ABI) sparse-ir-rs#273: for ωmax ≠ 1, a RegularizedBoseKernel basis carries S_l ∝ ωmax⁻¹ instead of ωmax⁺¹ (irbasis paper, Eq. (25)).
  • Fix in Fix the RegularizedBoseKernel basis scale, deprecate the kernel, and correct the C API docs sparse-ir-rs#286, which also deprecates the kernel.
  • Pinned here by a strict xfail in tests/test_oracle.py.

Tests

• Counts: before, 181 passed (45 s). After, 345 passed, 5 xfailed (57 s). The suite passes on Python 3.10, 3.11, 3.12 and 3.13.
• New files:
  • test_oracle.py
  • test_boundary.py
  • test_public_surface.py
  • test_integration.py (a port of SparseIR.jl's integration test)
  • _helpers.py
• Existing tests: weak, commented-out and unseeded tests are rewritten.
• Oracle mutation check: every broken reference must fail by at least 1e3 × atol.

O1 pole sign (tau)                       max error/atol = 3.33e+07  ok
O1 statistics swapped (iv)               max error/atol = 6.67e+07  ok
O1 n -> n+2 (iv)                         max error/atol = 2.44e+07  ok
O2 Fourier sign                          max error/atol = 1.09e+10  ok
O2 n -> n+2                              max error/atol = 8.12e+09  ok
O3 u(tau) instead of u(beta - tau)       max error/atol = 6.67e+07  ok
O3 Re/Im parity swapped                  max error/atol = 3.23e+07  ok
O3 periodicity sign swapped              max error/atol = 2.00e+10  ok
O4 DLR statistics swapped                max error/atol = 2.21e+10  ok
O4 DLR pole sign                         max error/atol = 1.00e+10  ok

Companion PRs: SpM-lab/SparseIR.jl#158 (Julia), SpM-lab/sparse-ir-doc#5 (notation page), SpM-lab/sparse-ir-rs#286 (#273 fix, merged).

🤖 Generated with Claude Code