NonlinearSolveBase: add public get_linear_cache accessor (#1065)

Add `get_linear_cache(cache)`, a read-only accessor that returns the
`LinearSolve.jl` `LinearCache` the solver holds its Jacobian (and, for a
factorization, that factorization) in — the cache-level companion to the
existing public `get_linear_solver(alg)`. It lets a caller reuse the solver's
current Jacobian for an auxiliary linear solve `J x = b` (e.g. a smoothed error
estimate) instead of building and factorizing a second copy.

It walks the existing cache chain: `cache.descent_cache.lincache` ->
`LinearSolveJLCache.lincache` -> the raw `LinearCache`, and returns `nothing`
where there is no single reusable cache (polyalgorithms, and the native
`\`/`SMatrix`/`Number`/`Diagonal` paths). Read-only: it does not refactorize;
the returned cache is in the state the last `step!`/`solve!` left it, so reuse
it through the normal LinearSolve caching interface (set `b`/`u`, `solve!`, no
new `A`), which reuses the existing factorization for a direct solver and
re-runs the iterative solve for a Krylov cache.

Made `@compat public`, documented (docstring + devdocs `@docs` entry). Minor
version bump (new public API): NonlinearSolveBase 2.34.1 -> 2.35.0.



Claude-Session: https://claude.ai/code/session_01NB3oFTNzGW79UtDt8AyjsM

Co-authored-by: Christopher Rackauckas <accounts@chrisrackauckas.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

docs/src/devdocs/linear_solve.md

@@ -3,6 +3,7 @@
 ```@docs
 NonlinearSolveBase.AbstractLinearSolverCache
 NonlinearSolveBase.construct_linear_solver
+NonlinearSolveBase.get_linear_cache
 NonlinearSolveBase.needs_square_A
 NonlinearSolveBase.needs_concrete_A
 ```

lib/NonlinearSolveBase/Project.toml

@@ -1,6 +1,6 @@
 name = "NonlinearSolveBase"
 uuid = "be0214bd-f91f-a760-ac4e-3421ce2b2da0"
-version = "2.34.3"
+version = "2.35.0"
 authors = ["Avik Pal <avikpal@mit.edu> and contributors"]
 
 [deps]

lib/NonlinearSolveBase/src/NonlinearSolveBase.jl

@@ -96,7 +96,7 @@ include("forward_diff.jl")
 
 # public for NonlinearSolve.jl and subpackages to use
 @compat(public, (InternalAPI, supports_line_search, supports_trust_region, set_du!))
-@compat(public, (construct_linear_solver, needs_square_A, needs_concrete_A))
+@compat(public, (construct_linear_solver, needs_square_A, needs_concrete_A, get_linear_cache))
 @compat(public, (construct_jacobian_cache, reused_jacobian))
 @compat(
     public,

lib/NonlinearSolveBase/src/linear_solve.jl

@@ -161,6 +161,36 @@ function set_lincache_u!(cache, u::SArray)
     return cache.lincache.u = u
 end
 
+"""
+    get_linear_cache(cache) -> Union{Nothing, LinearSolve.LinearCache}
+
+Return the `LinearSolve.jl` `LinearCache` the solver holds its Jacobian (and, for a
+factorization, that factorization) in, or `nothing` when there is no single reusable linear
+cache.
+
+This is a read-only accessor: it hands back the cache the solver already maintains so a
+caller can reuse the current Jacobian for an auxiliary linear solve `J x = b` (for example a
+smoothed error estimate) instead of building and factorizing a second copy. It does **not**
+refactorize; the returned cache is in exactly the state the last `step!`/`solve!` left it, so
+call it after the solve for the current point. Reuse it through the normal LinearSolve caching
+interface (set `b`/`u` and `solve!`, passing no new `A`), which reuses the existing
+factorization for a direct solver and re-runs the iterative solve for a Krylov cache.
+
+Returns `nothing` for algorithms with no single descent linear solve (e.g. polyalgorithms)
+and for the native `\\`/`SMatrix`/`Number`/`Diagonal` paths that hold no reusable
+`LinearCache`; callers should fall back accordingly.
+"""
+get_linear_cache(::Any) = nothing
+function get_linear_cache(cache::AbstractNonlinearSolveCache)
+    return hasproperty(cache, :descent_cache) ? get_linear_cache(cache.descent_cache) :
+        nothing
+end
+function get_linear_cache(cache::AbstractDescentCache)
+    return hasproperty(cache, :lincache) ? get_linear_cache(cache.lincache) : nothing
+end
+get_linear_cache(cache::LinearSolveJLCache) = cache.lincache
+get_linear_cache(::NativeJLLinearSolveCache) = nothing
+
 function wrap_preconditioners(Pl, Pr, u)
     Pl = Pl === nothing ? IdentityOperator(length(u)) : Pl
     Pr = Pr === nothing ? IdentityOperator(length(u)) : Pr