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

[shinaoka]

Summary

This PR does four things:

• Tests. It brings the test suite up to the mandatory coverage of spm-agent-rules/testing.md, and runs the dormant :cinterface items (Tests tagged :cinterface do not compile against the current C_API (8 errors on main) #155) and Aqua in Pkg.test() again.
• Oracle tests. It adds 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.
• Documentation. It documents the conventions the code implements, with the notation shared by the sparse-ir documentation, the tutorial and the Python wrapper.

Behavior changes (user-visible)

• Invalid parameters: these throw DomainError / ArgumentError before the C call:

  • β, ωmax, ε or Λ that is not positive and finite (Λ = 0 is now rejected too)
  • a max_size other than -1 or a positive integer
  • a kernel or SVE that does not match β ωmax
  • DLR poles outside [-ωmax, ωmax]

  Before, these gave an ErrorException, a misleading kernel-cutoff message, or a wrong basis built silently. The kernel/sve_result keyword defaults are now nothing, and the default objects are built after validation.

• Evaluation domains: u(τ) outside [-β, β] and v(ω) outside [-ωmax, ωmax] throw DomainError. Before, this was a Rust panic (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).

• uhat: it now checks its argument:

  • a MatsubaraFreq of the other statistics throws ArgumentError
  • an integer of the wrong parity throws DomainError
  • integers are accepted (they raised FieldError)

  uhat[l], uhat[a:b], length and zeta now work; all raised MethodError before, although they were documented. The DLR gains u and uhat (its single-pole functions).

• Input arrays: evaluate, fit, evaluate!, fit!, from_IR and to_IR accept any AbstractArray with a real or complex element type. The input is converted to Float64/ComplexF64 explicitly; before, views raised MethodError and Float32/integer input raised ArgumentError. Non-finite input and wrong lengths are reported before the call.

• Matsubara sampling points: they must be exact integers of the right parity; 1.9 used to raise InexactError. A MatsubaraFreq of the other statistics throws ArgumentError. With positive_only=true, negative points and genuinely complex coefficients in evaluate throw ArgumentError.

• Augmented positive_only sampling: MatsubaraSampling(AugmentedBasis(...); positive_only=true) with the default points works now. The positive-only default points of augmented bases were a truncated set followed by uninitialized memory, so the sampling either failed or, for a bosonic vertex basis, sampled silently at garbage frequencies. They are now the non-negative half of the full set, as for a plain basis.

• Basis truncation: basis[1:n] now truncates a FiniteTempBasis to its n most significant singular values. It raised MethodError, which also broke AugmentedBasis truncation.

• Function sets:

  • size of u, v and uhat is a tuple, as Base.size requires; it was an Int.
  • Empty selections throw ArgumentError before the call (fix(capi): spir_funcs_get_slice with nslice = 0 panics ("Cannot create empty PiecewiseLegendrePolyVector"), collapsed to SPIR_INTERNAL_ERROR sparse-ir-rs#269).
  • u(x) accepts untyped vectors of real points.

• MatsubaraSampling of an AugmentedBasis: it checks its points like that of a plain basis. TauConst and TauLinear throw ArgumentError at a frequency of the other statistics; they used to raise MethodError.

• TauConst and TauLinear are bosonic-only: TauConst{Fermionic} and TauLinear{Fermionic} throw ArgumentError, and so does augmenting a fermionic basis with them. For fermions their Matsubara values were not the Fourier transforms of their τ functions; e.g. TauConst gave 0 at every odd n, where the transform is 2i√β/(πn).

• Augmentation instances: an instance passed to AugmentedBasis must have the basis's β, and TauConst/TauLinear a bosonic basis. MatsubaraConst takes the statistics of the basis.

  • Before, a β mismatch was accepted silently, and an instance of the other statistics failed with a MethodError from create(::Tuple, …).
  • The existing test create(MatsubaraConst(42), basis) with β = 1000 pinned the silent pass-through. It now uses the basis's β and checks that a mismatch throws.

• Accessors: s(basis), u(basis), v(basis) and uhat(basis) work. They were documented but had no methods.

• RegularizedBoseKernel is deprecated (Base.depwarn); LogisticKernel is the default for both statistics. Its docstring had the sign of the denominator wrong and called it fermionic.

• DLR: MatsubaraSampling(dlr) without points uses the default points of the IR basis, as in the Python wrapper; it used to fail. A DLR on anything but a FiniteTempBasis, or an SVE of another kernel type, throws ArgumentError.

• evaluate!/fit!: they reject an output that shares memory with the input.

• cond with positive_only=true: it is now the condition number of the real least-squares problem that fit solves (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).

• Local libsparseir builds (Pkg.build() with ../sparse-ir-rs, as in CI_with_latest_rust_backend) now load the bindings generated from that library's header, deps/C_API.jl.

  • Since a5d08b9 the generator wrote them there, but the package kept loading src/C_API.jl. The latest-backend CI therefore tested stale bindings against a newer library.
  • Against sparse-ir-rs main, whose spir_basis_get_default_matsus_ext takes the buffer capacity separately since sparse-ir-rs#274, this gave 7 errors.
  • default_matsubara_sampling_points(::AugmentedBasis) now calls that getter in whichever form the loaded bindings have.

• Matsubara sampling points in any order: the C library orders them ascending.

  • MatsubaraSampling kept sampling_points in the caller's order, but evaluate/fit worked in the sorted order. Custom points given in another order therefore silently mismatched the data, for plain, positive-only, augmented and DLR bases alike.
  • The points are now passed sorted, and the data is reordered along dim, as TauSampling already follows the given order.
  • Found while fixing the tutorials; the Python fix is Keep the given order of Matsubara sampling points sparse-ir#87.

• Docstrings: every export now has one.

  • The MatsubaraFreq docstring had the statistics labels swapped.
  • README and docs link to the v2 tutorial and sparse-ir-rs.

• Error types: generic error(...) calls became SparseIRError (with the status), ArgumentError, DomainError or BoundsError.

Documentation

The docstrings, README, docs/src/guide.md and the docs index 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, and src/C_API.jl (generated) is untouched.

• Conventions now stated:
  • the parity ζ and G(τ+β) = (−1)^ζ G(τ);
  • Matsubara frequencies ν = nπ/β with the reduced frequency n, and the Fourier transform with its inverse;
  • U_l, S_l and V_l with l from 0 (basis.u[l+1] is U_l), orthonormality and the sign rule U_l(β⁻) > 0;
  • G_l = −S_l ρ_l, with ρ = A for fermions and A/tanh(βω/2) for bosons;
  • the τ domain [−β, β] with the four endpoint rules;
  • default points: the roots of U_L and V_L, and Matsubara sign changes with n = 0 in bosonic sets;
  • positive_only (n ≥ 0, G(−iν) = G(iν)*), and the DLR coefficients and functions.
• Wrong statements fixed:
  • the DLR frequency formula held for fermions only;
  • "extrema" for the default points;
  • the SVEResult signature, and the claim that ε truncates the SVE;
  • FiniteTempBasisSet field types and getters;
  • a factorize keyword that does not exist, and l < naug in the AugmentedBasis formula;
  • Λ ≥ βωmax in the README (the code requires equality);
  • "Matsubura" and "Fredhold".
• guide.md: rewritten for the wrapper over libsparseir.
  • The pure-Julia internals, the fabricated show output, the inverted iω formula and the "4 additional sampling frequencies" are gone.
  • All REPL outputs are regenerated with the current package.
• Checks:
  • JuliaFormatter, typos with the CI config, and Pkg.test() (unchanged counts) all pass.
  • Documenter (non-draft) builds with only the two pre-existing git-remote warnings, and all @refs resolve.
  • The README and guide code blocks run.

Backend defects found

All were reported to SpM-lab/sparse-ir-rs. All but #273 are fixed on its main branch.

CI tests both the released libsparseir_jll and sparse-ir-rs main (CI_with_latest_rust_backend), so a pinned defect can be present on one backend and fixed on the other. The pins therefore test two states:

• the known defect is recorded as @test_broken;
• any other result must pass.

Once every tested backend has the fix, the broken branch can go.

• 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 #276.
  • Pinned by 4 checks in test/spir/oracle_tests.jl. The defect gives errors of 1e6 to 1e7 times the tolerance; errors above 1e3 × tol are recorded as broken.
• 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. In v0.8.4 a mismatch writes past the buffer.
  • Fixed upstream by #274.
  • The wrapper no longer asks C for the positive-only set.
• 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.
• 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.
• 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 by oracle item O6, which records exactly the kernel divided by ωmax² as broken.
  • Built against that branch, the check passes with an error of 2.2e-11.

Tests

• Counts: before, 871 passed, 23 items, :julia only (runtests 8m28s). After, 17672 passed, 5 broken, 54 items (runtests 4m30s) with libsparseir_jll 0.8.4; 17677 passed with a local build of sparse-ir-rs main, as in CI_with_latest_rust_backend. Julia 1.10 and 1.13 were run on an earlier commit of this branch.
• :cinterface: repaired; 21 call sites lacked the backend argument. Closes Tests tagged :cinterface do not compile against the current C_API (8 errors on main) #155. Their progress prints were removed and their random coefficients seeded.
• New files: sir_testsetup.jl (SVE/basis cache), oracle_tests.jl, boundary_tests.jl and public_surface_tests.jl. The surface test also checks that every export is documented, which restored the lost LogisticKernel docstring.
• Existing tests: @test true, #== ==# blocks and ErrorException expectations were replaced. The DLR tests now check pole-sum data at 300ε instead of a 10 % relative error.
• Formatting: JuliaFormatter was applied to the changed files (REPOSITORY_RULES). Commit 3b59198 is formatter-only, and the later fix commits are formatted too.
• Oracle mutation check: every broken reference must fail by at least 1e3 × atol.

O1 pole sign (tau)                       max error/atol = 3.33e7  ok
O1 statistics swapped (iv)               max error/atol = 6.67e7  ok
O1 n -> n+2 (iv)                         max error/atol = 1.05e8  ok
O2 Fourier sign                          max error/atol = 1.09e10  ok
O2 n -> n+2                              max error/atol = 1.09e10  ok
O3 u(tau) instead of u(beta - tau)       max error/atol = 6.67e7  ok
O3 Re/Im parity swapped                  max error/atol = 3.23e7  ok
O3 periodicity sign swapped              max error/atol = 2.0e10  ok
O4 DLR statistics swapped                max error/atol = 2.21e10  ok
O4 DLR pole sign                         max error/atol = 1.0e10  ok

Companion PRs: SpM-lab/sparse-ir#86 (Python, merged), SpM-lab/sparse-ir-doc#5 (notation page), SpM-lab/sparse-ir-rs#286 (#273 fix, merged).

🤖 Generated with Claude Code