docs: document symbolic factorization reuse for sparse matrices (#1060)#1067
Merged
ChrisRackauckas merged 2 commits intoJun 28, 2026
Merged
Conversation
Add a "Reusing the Symbolic Factorization with Sparse Matrices" section to the caching interface tutorial. Explains reuse_symbolic/check_pattern, and the key gotcha that in-place edits to A's values are not seen by the cache: the change must be signaled with `linsolve.A = A` (or, internally, isfresh). Addresses SciML#1060. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
|
@ChrisRackauckas |
Member
|
No depends. I usually see it's like 20-25% |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Please ignore until reviewed by @ChrisRackauckas.
What
Addresses #1060 (and the follow-up comment). Adds a "Reusing the Symbolic Factorization with Sparse Matrices" section to
docs/src/tutorials/caching_interface.md. The existing tutorial only covered changingband replacing a denseA;reuse_symbolicwas not mentioned anywhere in it.The new section covers:
reuse_symbolic/check_patterndo forUMFPACKFactorization/KLUFactorization, and why reusing the symbolic part matters (symbolic analysis is the expensive part; numeric refactor is cheap) — the common FE/Newton/implicit-timestepping case of fixed pattern, changing values.A.nzvalare not seen by the cache, so the nextsolve!silently reuses the stale factorization and returns a wrong result.linsolve.A = A(reassigning the same mutated object is fine and still reuses the symbolic factorization when the pattern is unchanged). A note documents the internalisfreshflag as an equivalent-but-not-preferred escape hatch.Verification
Ran the new
@exampleblock locally against this branch:i.e. the post-update solve is correct (tiny residual) and the solution actually changed after the in-place value edit +
linsolve.A = A(confirming the numeric refactorization fired while the symbolic factorization was reused).Docs-only change; no source modified.
🤖 Generated with Claude Code