[Docs] Add user-guide page for matrix decompositions and solvers#643
[Docs] Add user-guide page for matrix decompositions and solvers#643hughperkins merged 26 commits intomainfrom
Conversation
Documents the per-thread small-matrix decomposition / solver entry points (qd.svd, qd.sym_eig, qd.polar_decompose, qd.eig, qd.solve). Companion to matrix_vector.md, which covers element-wise / arithmetic operations; this page covers the numerical-algorithm layer (Jacobi sweeps, Gauss elimination, etc.) sitting on top of those. Covers per-op semantics, the supported size set (2 / 3 only — 2 only for general qd.eig), the optional dt argument, sign-convention caveats for SVD / polar (det(R) handling), and what is missing (N>3 symmetric EVD, larger inverse, atomic_cas, 3×3 general eig). Worked examples include closest-rotation extraction (ARAP), 3×3 make_spd via sym_eig + clamp, per-thread linear solve, and 2×2 polar shape-matching. Adds decompositions.md to the Core concepts toctree (next to matrix_vector).
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5981faaea4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| - Sizes 2 and 3. | ||
| - The implementation asserts `A.n == A.m` and `A.m == b.n`. | ||
| - Singular `A` triggers an `assert` failure (`"Matrix is singular in linear solve."`); the assert is active by default and is your only signal of singularity. |
There was a problem hiding this comment.
In the default qd.init(..., debug=False) path, kernel assert statements are only checked when debug=True (see docs/source/user_guide/debug.md line 58), and the singularity checks inside _gauss_elimination_* are kernel asserts. This sentence tells users they can rely on qd.solve raising by default for singular inputs; in normal/default runs they may instead get divide-by-zero/NaN results with no signal, so this should be qualified as debug-mode behavior or paired with an explicit-singularity-check recommendation.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3d0fa3ef1d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| U, S, V = qd.svd(A, dt=qd.f64) | ||
| R = U @ V.transpose() | ||
| if R.determinant() < 0.0: | ||
| V[:, 2] *= -1.0 |
There was a problem hiding this comment.
For 3×3 inputs where Quadrants' SVD leaves the smallest singular value in a column other than column 2 (the page notes above that 3×3 singular values are not sorted), this handedness fix can flip a larger singular direction. That still makes det(R) > 0, but it is no longer the closest proper rotation used by ARAP; the example should either sort/select the minimum diagonal entry of S before flipping or avoid calling it the closest rotation.
Useful? React with 👍 / 👎.
2 participants
Summary
New user-guide page
docs/source/user_guide/decompositions.mddocumenting the per-thread small-matrix decomposition / solver entry points —qd.svd,qd.sym_eig,qd.polar_decompose,qd.eig,qd.solve.Companion to the in-flight subgroup (#639), block (#638), atomics (#640), grid (#641), and algorithms (#642) docs; this is one of a series of tier-by-tier user-guide pages.
This page is the linear-algebra-tier counterpart to
matrix_vector.md, which already covers the element-wise / arithmetic side. It clarifies the split:matrix_vector.md— closed-form ops (@,inverse≤ 4×4,determinant,transpose, dot, cross, norm,outer_product).decompositions.md(new) — numerical-algorithm ops (Jacobi sweeps, Gauss elimination with pivoting).Includes:
qd.eigwhich is 2-only).qd.sym_eigassumes the input is exactly symmetric (no symmetrize step),qd.solvetriggers an assert on singularA,qd.eigpacked-complex output layout.make_spdviasym_eig, per-thread 2×2 solve, polar shape-matching.f32vsf64, fully cross-backend.Matrix.inversesize cap,atomic_cas, 3×3 general eig.Adds
decompositionsto the Core-concepts toctree, next tomatrix_vector.Test plan
cd docs && make htmlbuilds without warnings.matrix_vector.mdresolves.Made with Cursor