Umbrella: documentation audit of the SpM-lab ecosystem (IR-only / v1 / C++-era leftovers) #1

This is the umbrella issue for a documentation audit of the whole SpM-lab ecosystem, done on 2026-09-30 and 2026-10-01. Each item below will become an issue in its own repository; tick it off when the fix is merged. Cross-project items stay in this repository.

Background. The Rust backend (sparse-ir-rs) now provides three compact representations: the IR basis, a DLR built without an IR basis (the Kaye–Chen–Parcollet ID construction), and ESPRIT/MiniPole. So far these are on main only. Released versions (sparse-ir-rs 0.10.0, Python sparse-ir 2.1.x / pylibsparseir 0.10.0, Julia SparseIR.jl 2.2.0) build the DLR from an IR basis and have no MiniPole. Much of the documentation still assumes the old IR-only, C++-backend, v1 world.

Cross-project (this repository)

• Canonical entry point. sparse-ir-doc and sparse-ir-tutorial-v2 point at each other, and neither page has installation instructions. Proposal: make sparse-ir-doc the landing page (ecosystem, installation, theory) and keep sparse-ir-tutorial-v2 for examples only. The org profile page (profile/README.md) is the entry list for now.
• New page: "IR, DLR and MiniPole: history and comparison". In preparation. It will cover PRB 96, 035147 (2017), which found that the kernel is low rank and built a basis by decomposing the kernel; the sparse-pole construction from IR (arXiv:2007.03955); DLR as the same idea moved from SVD to ID; MiniPole; and a size and property comparison. Its home is to be decided: sparse-ir-doc, with a link from the Rust book. Tracked in Umbrella: IR, DLR and MiniPole — history and comparison page sparse-ir-doc#6.
• Org housekeeping (needs org admin).
  • Pin sparse-ir-rs and unpin the deprecated sparse-ir-tutorial (v1).
  • Set an org description.
  • Fix spm-lab.github.io, which returns 404.
  • Give each repository its own description; many share "On-the-fly computation of IR basis functions".
  • Create a GitHub Release and set a homepage for sparse-ir-rs.
• Archive, or add a successor banner to, the legacy repositories: libsparseir, LibSparseIR.jl, pysparseir, libsparseir-fortran-test, sparse-ir-fortran, sparse-ir-tutorial, sparse-ir-tutorial-v1, sparse-ir-binder, sparse-ir-docker, SparseIR_deprecated.jl, irbasis, irlib, sparse-x.
• Feature-parity table. Say which of the independent DLR and MiniPole is available in which release: Rust main, Rust release, Python, Julia and C API. Reuse the table on every README.
• Shared doc-audit skill in spm-agent-rules/skills/, following tensor4all-agent-rules. It should turn this audit into a repeatable procedure.

sparse-ir-rs (Rust user guide)

• docs(book): Rust user guide still states the pre-#263 raw Matsubara index ω=(2n+ζ)π/β, contradicting the implemented reduced index (mdBook) sparse-ir-rs#311: the Matsubara index is written as (2n+1)π/β, but the implementation uses the reduced index n with ν = nπ/β.
• docs(book): user guide still framed as an IR-only library — introduction, DLR page, conventions and TOC predate the independent DLR and MiniPole sparse-ir-rs#312: the guide is still framed as IR-only (introduction, DLR page, conventions, table of contents, installation vs release).
• docs(book): rewrite the MiniPole page around a complex-plane picture (semicircle DOS, poles in the lower half plane) sparse-ir-rs#313: rewrite the MiniPole page around a complex-plane picture.
• docs(book): physics and limit errors in applied examples dmft_ipt / tpsc / flex / eliashberg_holstein sparse-ir-rs#314: physics and limit errors in dmft_ipt, tpsc, flex and eliashberg_holstein.
• docs(book): errors in applied examples second_order_perturbation / gw / liechtenstein / orbital_magnetic_susceptibility sparse-ir-rs#315: errors in second_order_perturbation, gw, liechtenstein and orbital_magnetic_susceptibility.
• docs(book): hand-pasted snippets contradict 'every code block is compiled'; bosonic DLR formula, citations and consistency fixes sparse-ir-rs#316: hand-pasted snippets (43 rust,ignore blocks) contradict "every code block is compiled"; the bosonic DLR formula; smaller consistency fixes.
• docs(readme): READMEs and crates.io text advertise main-only features next to the 0.10.0 pin; stale C API / Fortran / Python READMEs sparse-ir-rs#317: the READMEs and crates.io text advertise features that are on main only next to the 0.10.0 pin; stale C API, Fortran and Python READMEs.

sparse-ir (Python)

• Read the Docs has failed every build since Sep 2025. .readthedocs.yaml uses extra_requirements: [doc], but doc is a PEP 735 dependency group. As a result, stable = 1.1.7 and latest = 2.0.0a3.
• The project URLs on PyPI point to SpM-lab/sparse-r (404).
• The docs do not say that the independent DLR and MiniPole are not yet available. otherbases.rst says any AbstractBasis works, which is too broad.
• There is no CHANGELOG or 1.x → 2.x migration notes.
• The README has stale version pins, and developer documentation sits on the landing page.
• "Somewhat restricted C library" and "bindings" wording; inconsistent statements about supported Python versions; a stray 1.85 conda build; a "refactoring" placeholder; missing autodoc entries; smaller nits.

SparseIR.jl (Julia)

• The stable docs are v1.0.14. Documenter CI runs only on pushes to main, never on tags, so /stable/ is outdated. The org page currently links /dev/.
• The docs do not say which backend features are missing (the independent DLR and MiniPole).
• guide.md:15 gives stale versions (2.1.5 / 0.8.4).
• Five PDF figures are embedded with <img> and do not render.
• The docs still make v1-era claims about "full precision" and coverage, and mention a stale #273 caveat that was fixed in 0.10.
• There is no NEWS file, and the migration guide was merged after the 2.2.0 tag.
• index.md is nearly empty, and the README example does not return anything.
• README.md:67 still links sparse-ir-fortran.

sparse-ir-doc (theory)

• greens_function.md calls imaginary time "a mere mathematical trick" and labels G(τ−τ′) as the Matsubara function.
• Stale #273 caveat; stale kernel.rs path.
• The DLR is described as IR-derived only.
• The index page has no installation instructions and no Rust or C links.

sparse-ir-tutorial-v2

• migration.md (published but not in the TOC) says v2 moved the backend to C++. It is Rust.
• The orphan Fortran page points to sparse-ir-fortran, a hidden comment links libsparseir, and api.md has broken ecosystem links.
• The v1 site (sparse-ir-tutorial) has no "superseded" banner.
• TOC and hygiene problems, typos, and outdated DLR notebooks. Some notebooks have external authors, so check with them before editing.