docs: restructure README around the nested subpackage layout#90
Merged
Conversation
The README still described the pre-0.9 flat module layout: function links pointed at deleted files (src/cvx/linalg/norm.py etc.) and the operators, kkt, norm, and covariance additions were missing entirely. Reorganize the function reference by subpackage (core, covariance, decomposition, kkt, norm, operators, solve) with working links, and document the newly public norm, cov_to_corr, warn_ill_conditioned, DEFAULT_COND_THRESHOLD, the SymmetricOperator protocol with its backends, bordered_solve, and AffineProjection. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the README’s API reference to match the project’s nested subpackage layout (core, covariance, decomposition, kkt, norm, operators, solve), and updates documentation links accordingly so users can navigate the new structure while still using the top-level cvx.linalg re-exports.
Changes:
- Restructures the README function/type reference by subpackage and updates source links to the new paths.
- Adds a subpackage structure table and clarifies that the public API is re-exported from
cvx.linalg(withewm_covarianceas a documented exception). - Documents additional previously-missing public API items (norms, covariance conversion, ill-conditioning helpers/constants, operator backends, and KKT utilities).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+123
to
+127
| protocol captures exactly that contract (including `rcond_free` for detecting | ||
| rank-deficient free blocks and `restricted(free)` for a pre-sliced free-block | ||
| view), and the backends implement it at very different cost: | ||
|
|
||
| - **[`SymmetricOperator`](https://github.com/Jebel-Quant/linalg/blob/main/src/cvx/linalg/operators/base.py)** — Protocol exposing a symmetric matrix through `matvec`, `block_matvec`, `solve_free`, `apply_free`, `rcond_free`, `restricted`, and `diag` |
Comment on lines
+136
to
+138
| Building blocks for active-set and path-tracing solvers, built on top of the | ||
| operator protocol: | ||
|
|
| - **[`valid(matrix)`](https://github.com/Jebel-Quant/linalg/blob/main/src/cvx/linalg/core/valid.py)** — Return a boolean mask and valid submatrix by removing rows/columns with non-finite diagonal entries | ||
| - **[`cond(matrix, p=None)`](https://github.com/Jebel-Quant/linalg/blob/main/src/cvx/linalg/core/exceptions.py)** — Condition number of a matrix (NaN-aware); accepts the same `p` norm values as `numpy.linalg.cond` | ||
| - **[`check_and_warn_condition(matrix, threshold)`](https://github.com/Jebel-Quant/linalg/blob/main/src/cvx/linalg/core/exceptions.py)** — Emit `IllConditionedMatrixWarning` when the condition number exceeds the threshold | ||
| - **[`warn_ill_conditioned(cond_value, threshold)`](https://github.com/Jebel-Quant/linalg/blob/main/src/cvx/linalg/core/exceptions.py)** — Emit `IllConditionedMatrixWarning` for an already-computed condition number |
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
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.
Summary
core,covariance,decomposition,kkt,norm,operators,solve), fixing all source links that still pointed at the deleted flat-layout filescvx.linalgtop levelnorm,cov_to_corr,warn_ill_conditioned,DEFAULT_COND_THRESHOLD, theSymmetricOperatorprotocol and its backends (DenseOperator,IncrementalDenseOperator,GramOperator,FactorOperator,SumOperator),bordered_solve, andAffineProjection🤖 Generated with Claude Code