Better documentation on how to use reuse_symbolic

[lijas]

I think the documentation on how to use reuse_symbolic for some of the direct solvers is lacking. If I understand everything correctly, I think you have to manually trigger the isfresh field:

linsolve = LS.init(prob, solver)
sol1 = LS.solve!(linsolve)
# Update matrix but not pattern
# linsolve.A = 2 * K #BAD: This triggers new refactorization
linsolve.A.nzval .= 2 .* K.nzval #This does not update isfresh to true
linsolve.isfresh = true #Manually trigger isfresh
sol2 = LS.solve!(linsolve)

As far I can see, this is not described in the documentation. I would suggest adding a how-to here: https://docs.sciml.ai/LinearSolve/stable/tutorials/caching_interface/

[ChrisRackauckas]

I don't understand what you're trying to do here. If you change A, it will check if the pattern changes and symbolic refactorize when necessary (unless reuse_symbolic=false, in which case it will always retrigger that) and then it will do the factorization. If you don't change A... then you don't need to refactorize anyways so I don't see what's going on here?

[lijas]

In my FE-code, I have the same sparsity pattern in A for each time step (only the entries changes). As I understand, I should be able to get slighly better performance in the linear solve by reusing the symbolic factorization from the first linear solve, but in order to get this gain, I have to manually set isfresh=true (which is not documented).

I hope this example makes my issue clearer:

using SparseArrays, LinearAlgebra
import LinearSolve 

const LS = LinearSolve

function f()
    N = 100
    A1 = sprand(N, N, 0.01) + 10.0*I
    A1 = 0.5*(A1 + A1')
    b = rand(N)

    prob = LS.LinearProblem(A1, b)
    solver = LS.UMFPACKFactorization(; reuse_symbolic=true, check_pattern=false)
    linsolve = LS.init(prob, solver)

    #Solve 1
    print("First solve: ")
    @time sol1 = LS.solve!(linsolve)
    u_sol1 = copy(sol1.u)

    #New timestep: Update values of matrix (but use same pattern)
    linsolve.A.nzval .*= 2

    #Solve2 (reuses full factorization which is not what I want)
    print("Second solve: ")
    @time sol2 = LS.solve!(linsolve)
    @show norm(u_sol1) == norm(sol2.u) #True

    #Solve3 (this only reuses the symbolic factorization):
    linsolve.isfresh = true
    print("Third solve: ")
    @time sol3 = LS.solve!(linsolve)
    @show norm(u_sol1) == norm(sol3.u) #False
end

Output:

First solve:   0.000199 seconds (84 allocations: 123.172 KiB)
Second solve:   0.000003 seconds
norm(u_sol1) == norm(sol2.u) = true
Third solve:   0.000089 seconds (33 allocations: 79.391 KiB)
norm(u_sol1) == norm(sol3.u) = false

You can see that the third solve uses less allocation that then the first one, so I assume that it could reuse the symbolic factorization.

[ChrisRackauckas-Claude]

Thanks for the clear example — you're right, and this is a documentation gap rather than a bug.

The key detail your example surfaces: mutating A's values in place (linsolve.A.nzval .*= 2) is not observed by the cache. The caching interface marks the factorization stale via the linsolve.A = ... assignment (which sets the internal isfresh flag). Because the in-place edit never goes through that setter, the second solve! sees a "fresh" cache and reuses the full factorization — giving the stale result you saw. Setting linsolve.isfresh = true manually is exactly the workaround, but it's an internal field and was never documented.

The supported way to get what you want (reuse the symbolic factorization, redo only the numeric part) is to reassign A back into the cache after editing its values:

linsolve.A.nzval .*= 2   # or edit values however you like
linsolve.A = linsolve.A  # signals the change; symbolic factorization is still reused
sol2 = LS.solve!(linsolve)

Reassigning the same (mutated) object is fine — with reuse_symbolic=true (default) and an unchanged sparsity pattern, this still reuses the cached symbolic factorization and only redoes the numeric factorization. I verified locally that this path has the same low allocation profile as your manual isfresh=true third solve (32 allocations vs. 83 for the first full factorization), confirming the symbolic part is reused.

I've opened #1067 to document this in the caching interface tutorial — it adds a "Reusing the Symbolic Factorization with Sparse Matrices" section covering reuse_symbolic/check_pattern, the in-place-mutation gotcha, and the linsolve.A = A pattern (with isfresh noted as an internal escape hatch).