Add public same_sparsity_structure(A, B)

[ChrisRackauckas-Claude]

Draft — please ignore until reviewed by @ChrisRackauckas.

What

Adds a public, documented same_sparsity_structure(A, B) -> Bool: an allocation-free query that returns true when A and B store their nonzeros in exactly the same structural positions (same pattern and shape). That's the condition under which a preallocated sparse structure — or a cached symbolic factorization — can be reused for a values-only update without rebuilding the structure.

Why

This check is currently reinvented in several places:

• LinearSolve.jl's internal pattern_changed(fact, A) (colptr/rowval comparison, run on every sparse solve, with GPU methods) — but it's not public and is shaped as factorization-vs-matrix.
• A local helper in OrdinaryDiffEq's calc_J! (Skip redundant sparse-Jacobian structure rebuild in calc_J! SciML/OrdinaryDiffEq.jl#3980) guarding a per-Jacobian-eval sparse-structure rebuild.

ArrayInterface already owns the generic sparse-structure interface (has_sparsestruct, findstructralnz), so the matrix-vs-matrix structural-equality query belongs here. Unlike findstructralnz (which allocates (rowind, colind) via findnz), this allocates nothing on its fast paths, so it's usable in hot loops.

Semantics

• Dense arrays store every position → same structure iff same shape.
• Structured / sparse matrices compare by pattern: shape (plus uplo/format) for Diagonal/Bidiagonal/Tridiagonal/SymTridiagonal; stored index arrays (colptr/rowval and GPU equivalents) for CSC/CSR. These dispatch on the base type, so differing type parameters (e.g. Tridiagonal{Float64} vs Tridiagonal{Int}) still compare as the same structure.
• Different base types (a structured matrix vs a dense one, or two different structured types) → false: a layout isn't reused across categories.
• Same base type, no specialized method → MethodError, not false. We don't fabricate an answer for a type we haven't been taught about (e.g. two UpperTriangular, which do share a structure); the type should define its own method. has_sparsestruct can gate applicability.

This avoids the two failure modes of a naive f(A,B) = false catch-all: reporting identical dense matrices as differing, and silently guessing false for a same-type pair whose structure it can't actually determine.

Methods

• AbstractArray fallback → different base type false, same base type MethodError; DenseArray → shape
• Diagonal / Bidiagonal (with uplo) / Tridiagonal / SymTridiagonal — by shape (core)
• AbstractSparseMatrixCSC — via getcolptr/rowvals (SparseArrays ext)
• CuSparseMatrixCSC / CuSparseMatrixCSR — via their device index arrays (CUDA ext)

Validation

• public declaration + docstring + docs/src/sparsearrays.md entry (public and documented together)
• Tests (test/core.jl): dense same/diff-shape/vector, structured same + cross-eltype, different-base-type → false, same-base-no-method → @test_throws MethodError, CSC same/different/similar/size
• Full GROUP=Core suite passes locally (214/214); fast paths confirmed allocation-free (@allocated == 0 for CSC / Diagonal / dense in a function barrier)
• Minor version bump 7.27.0 → 7.28.0 (additive public API)
• GPU (CUDA CSC/CSR) methods are correct-by-construction against the CUSPARSE field/interface but not locally tested (no GPU here) — rely on the repo's GPU CI

Note: AbstractGPUSparseMatrixCSC does not subtype SparseArrays.AbstractSparseMatrixCSC, so GPU CSC needs the explicit CUDA-ext method rather than being covered by the SparseArrays one. A future GPUArrays-level method could cover CUDA/AMDGPU/Metal generically via the shared getcolptr/rowvals interface; I kept this to the existing per-backend pattern to avoid a new weakdep.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LWooL8qipuUf7nTrDUUzqY

[codecov]

Codecov Report

❌ Patch coverage is 73.33333% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.56%. Comparing base (3b48690) to head (c488273).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
ext/ArrayInterfaceCUDAExt.jl	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #496      +/-   ##
==========================================
+ Coverage   59.89%   60.56%   +0.66%     
==========================================
  Files          15       15              
  Lines         591      606      +15     
==========================================
+ Hits          354      367      +13     
- Misses        237      239       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.