Skip to content

v.0.2.0

Choose a tag to compare

View all tags
@theo-barfoot theo-barfoot released this 10 Sep 18:03
· 46 commits to main since this release
v0.2.0
a958602
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's Changed

Full Changelog: v0.1.3...v0.2.0

torchsparsegradutils v0.2.0 Release Notes

TL;DR

Major expansion of sparse ops, probabilistic distributions, benchmarking, documentation, dtype support, and solver backends. Memory for sparse_mm improved (~15%), new SPD + conditioning utilities, JAX/CuPy enhancements, int32 index support (with caveats), broad doc + test overhaul, and deprecation of PairwiseVoxelEncoder in favor of the generalized PairwiseEncoder. Prepares project for JOSS submission.

Headline

This release delivers a substantial maturation of the library: richer sparse linear algebra primitives, enhanced probabilistic modeling, comprehensive benchmarking (random + SuiteSparse), expanded backend support (CuPy, JAX with float64), stronger numerical tooling, uniform documentation (NumPy style + examples), and publication-oriented artifacts (JOSS paper draft + final edits).

Breaking / Deprecations

  • PairwiseVoxelEncoder deprecated → use PairwiseEncoder (supports arbitrary spatial dimensions).
  • Extended parameterizations for SparseMultivariateNormal; review constructor usage if you relied on earlier covariance/precision forms.

New & Enhanced Features

  • SparseMultivariateNormal: now supports Cholesky (LL^T) for covariance AND precision.
  • SparseMultivariateNormalNative: demonstration of direct torch.sparse.mm with unbatched CSR.
  • make_spd_sparse: generate sparse symmetric positive definite matrices for tests & benchmarks.
  • rand_sparse / rand_sparse_tri: conditioning controls + non‑strict triangular option; improved numerical stability knobs.
  • Added well-conditioning (well_conditioned, min_diag_value) to random sparse generators.
  • Added non-strict (diagonal-including) triangular sparse matrix generators (COO + CSR).
  • Keyword passthrough (**kwargs) for CuPy & JAX solver wrappers.
  • Int32 COO / CSR index support (COO auto-upcasts in some PyTorch code paths—documented limitation).
  • JAX backend: enabled float64 execution.
  • Official PyTorch 2.5+ support (tests up to nightly 2.9).

Linear Algebra & Solvers

  • Expanded solver ecosystem: sparse_generic_solve with CG, MINRES, BICGSTAB; CuPy wrappers (CG, CGS, MINRES, GMRES, spsolve, spsolve_triangular); JAX wrappers (CG, BICGSTAB).
  • Issue #51 resolved across sparse_generic_solve, sparse_solve_c4t, sparse_solve_j4t.
  • Updated CuPy bindings (t2c_csr, t2c_coo) to handle shape correctly.
  • Added multi‑RHS handling for BICGSTAB (column-wise solve loop).

Performance

  • ~15% memory footprint reduction for sparse_mm.
  • Additional refinements tied to issue #31 for improved efficiency.

Benchmarking Suite

  • Benchmarks cover:
    • sparse_mm vs torch.sparse.mm vs dense torch.mm (batched & unbatched)
    • sparse_triangular_solve vs torch.triangular_solve vs cupy.spsolve_triangular
    • sparse_generic_solve vs CuPy (multiple Krylov solvers) vs JAX vs torch.linalg.solve
  • Includes SuiteSparse matrices (e.g. Rothberg/cfd2) + random generators.
  • Automated result artifacts + visualization scripts.

Probabilistic & Statistical Validation

  • Distribution sampling validated via One-sample Hotelling T² (mean) and Nagao covariance tests.
  • Mean/covariance statistical utilities factored into utils.
  • Integration tests for gradient stability (documents CSR backward edge cases with PairwiseEncoder).

Documentation

  • Full NumPy-style docstring unification with runnable examples.
  • Read the Docs configuration added (.readthedocs.yaml).
  • Doctest coverage for examples (test_doctests).
  • Expanded README with feature matrix, benchmarks, usage, known issues, citation.
  • JOSS paper draft + final formatting passes.

Testing & Tooling

  • Migration to PyTest (issue #43) + expanded parametrized tests & integration coverage.
  • Doctest execution integrated.
  • isort adoption for import normalization.
  • Devcontainer overhaul (stable + nightly variants, CUDA 12.8 toolchain, pre-installed extras, linting & formatting).
  • Added reproducible random sparse generation helpers (make_spd_sparse, conditioning toggles).

Quality & Stability

  • Enhanced gradient flow / memory stress tests for sparse backprop patterns.
  • Diagnostic utilities & documented limitations (index dtype behavior, CSR + PairwiseEncoder memory).
  • More explicit parameter validation in random sparse matrix factory functions.

Known Limitations (See README for details)

  • CSR backward with PairwiseEncoder may exhibit elevated memory usage in some integration scenarios.
  • COO int32 indices may be upcast to int64 by PyTorch internals (expected behavior for now).
  • LL^T precision parameterization can cause large gradients; LDL^T recommended.

Upgrade Guidance

  1. Replace any usage of PairwiseVoxelEncoder with PairwiseEncoder (check spatial dimension ordering & parameters).
  2. Revisit SparseMultivariateNormal calls if relying on prior parameter naming—new flexibility may alter validation paths.
  3. For solver wrappers, you may now pass backend-specific kwargs (tolerances, max iterations, etc.).
  4. If you depended on implicit float32-only JAX runs, ensure downstream code accommodates possible float64 now.
  5. Regenerate environments to pick up added docs + benchmarking extras.

Internal / Housekeeping

  • Version bump to 0.2.0.
  • Readme overhaul & citation block added.
  • Consolidated statistical test utilities.
  • Refined sparse generator API (conditioning + triangular variants).

Changelog Classification

Type Items
Added New parameterizations, native distribution variant, SPD generator, conditioning flags, non-strict triangular gen, float64 JAX, kwargs propagation, benchmarks, devcontainer variants
Changed Memory optimization sparse_mm, solver interfaces, docstring style, benchmarking harness
Deprecated PairwiseVoxelEncoder
Fixed Shape handling in CuPy bindings, issue #51, consistency in random generation
Docs RTD config, JOSS paper, README expansion, doctests
Tooling PyTest migration, isort, formatting, environment provisioning

References / Issues

  • PR: #60 (primary aggregation)
  • Issues: #31 (sparse_mm), #43 (PyTest migration), #51 (solver behavior), #61 (docstring standardization)

Links

Contributors

theo-barfoot
Assets 2
Loading