Big picture plans for moving from spmatrix to sparray

Contributor & Development Discussion scipy
1

SciPy coordinating issue for deprecation of spmatrix in favor of sparray

The project to move from the sparse matrix API to the sparse array API
is ready for its next step. The sparray feature set has been
complete and stable since v1.15. Most features were implemented
well before that, as early as v1.8. The migration guide has
been available since v1.15. We have helped a number of libraries
make the conversion to using sparray, including networkx, sksparse, dipy, scikit-image, cvxpy, pyamg, many pysal libraries, scikit-learn.

This forum post is a step in the deprecation process. Please provide feedback.

Plan for a general order of changes:

  1. docstrings warnings and deemphasizing spmatrix
  2. deprecation warnings and adapt tests to filter warnings
  3. removal of spmatrix

More details are included in a “tracking issue” for the process. Issue 24802

Doc warnings will happen first – with suggested replacements for the spmatrix classes, some utility functions and the construction functions (like eye) which return spmatrix only.

We will separate the spmatrix api description from the central sparse landing page with a link to it from the main page. Pointers to spmatrix-only functions will move to this page, hopefully making it clear that these are Lagacy Features.

We hope to have these doc changes in place for v1.18.
We will have a draft PR for adding the deprecation warnings soon. This allows us to track what parts of the library are affected by spmatrix and where attention is needed. That will be updated to prepare for deprecation, and also to track new code additions that use spmatrix. The goal is to have everyone comfortable with deprecation warnings in 1.19. The warnings would state that removal will not occur before 1.21.

Removal in 1.21 with normal release cadence would be Jan 2028. This can change of course.

Please leave feedback here or in the issue

2

Here’ a follow-up post about big-picture plans for moving from spmatrix to sparray. It lays out 3 decisions that need to be made, and 2 others that have recently been made. This helps to lay out the full story. The Issue tracking this discussion and its implementation is: “tracking issue” 24802

Deprecation Decisions Needed:
Decisions need to be made about the approach to be taken for the following deprecations
that occur before the main deprecation. There are 3 deprecation decisions that are as yet undecided.

  1. Some construct.py functions (block, vstack, hstack, kron, triu, tril) base output type on input type. Currently: if any input is sparse array, output is sparray. If all are ndarrays, or mixed ndarray and spmatrix, output is spmatrix. The decision is: when to switch the case of all-ndarrays. Currently the all-ndarray case results in spmatrix.

    • Proposal: create deprecated warnings for the all-ndarray case in 1.18, change in 1.20.

    • Alternative: change to sparray for all-ndarray case when spmatrix is removed.

  2. IVP/BVP: The internally used (and helper) functions for jacobian currently use only spmatrix for sparse.

  3. stats/crosstab.py:

Two decisions have recently been made in smaller PRs about deprecations:

  1. io: spmatrix= kwargs in loadmat, hb_read, mmread (two such functions)

  2. KDTree: kwarg output_type has values “dok_matrix” or “csr_matrix”.

    • add support for “dok_array”, “csr_array” in v1.18,

    • deprecate default value in 1.19,

    • deprecation warnings for “dok_matrix” and “csr_matrix” in v1.19,

    • change default value and remove spmatrix v1.21.

dschult