{"id":4264,"library":"sparse","title":"Sparse n-dimensional arrays","description":"Sparse is a Python library that provides n-dimensional arrays for the PyData ecosystem, optimized for data with a large number of zero or 'fill' values. It aims to offer a drop-in replacement for NumPy arrays with support for N-dimensional operations, following the Array API standard. The current version is 0.18.0, and it maintains an active development cycle with frequent releases.","status":"active","version":"0.18.0","language":"en","source_language":"en","source_url":"https://github.com/pydata/sparse/","tags":["sparse arrays","numpy","scipy","data science","pydata","linear algebra"],"install":[{"cmd":"pip install sparse","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for numerical operations and array compatibility.","package":"numpy"},{"reason":"Core dependency for sparse data structures and algorithms.","package":"scipy"},{"reason":"Used internally for performance optimization with typed lists.","package":"numba"}],"imports":[{"note":"The library is typically imported directly as 'sparse'.","symbol":"sparse","correct":"import sparse"},{"note":"Specific sparse array formats can be imported from the top-level package.","symbol":"COO","correct":"from sparse import COO"}],"quickstart":{"code":"import sparse\nimport numpy as np\n\n# Create a sparse array from a dictionary of coordinates and values\nx = sparse.COO({(0, 0): 1, (1, 2): 2}, shape=(3, 3))\nprint(\"Sparse array x:\\n\", x)\nprint(\"Dense representation of x:\\n\", x.todense())\n\n# Create a sparse array from a NumPy array\ny = np.arange(9).reshape((3, 3))\nz = sparse.COO.from_numpy(y)\nprint(\"Sparse array z from NumPy:\\n\", z)\n\n# Perform an operation (addition) and convert to dense\nprint(\"Dense representation of (x + z):\\n\", (x + z).todense())","lang":"python","description":"This quickstart demonstrates how to create sparse arrays using the `COO` format from a dictionary of coordinates and values, or by converting a dense NumPy array. It also shows a basic arithmetic operation and how to convert a sparse array back to a dense NumPy array."},"warnings":[{"fix":"Explicitly convert the sparse array to a dense NumPy array using `.todense()` or `.toarray()` before passing it to NumPy functions that do not have sparse-aware implementations. This prevents unintended memory exhaustion.","message":"Automatic densification of sparse arrays into NumPy functions now raises a RuntimeError.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Always use `@` for matrix multiplication with `sparse` arrays, consistent with NumPy's `ndarray` behavior. The `*` operator is reserved for element-wise operations.","message":"The `*` operator performs element-wise multiplication, while `@` performs matrix multiplication (dot product).","severity":"gotcha","affected_versions":"All versions (consistent with NumPy array semantics)"},{"fix":"Be mindful of the `fill_value` of sparse arrays (which is usually 0). If your logic depends on a different implicit value or specific handling of `fill_value` during operations, ensure it's explicitly managed or converted to dense where necessary.","message":"Operations on `sparse` arrays, especially element-wise functions like `np.where`, propagate the `fill_value` (defaulting to 0). Unexpected results can occur if your data or mask implicitly relies on a non-zero `fill_value` behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Before applying a NumPy function, check if `sparse` (or `scipy.sparse` for 2D cases) offers a specialized sparse implementation. Otherwise, convert the sparse array to a dense NumPy array using `.todense()` or `.toarray()` first.","message":"Directly applying general NumPy functions to `sparse` arrays without explicit conversion or a sparse-aware implementation can lead to inefficient computation or incorrect results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adopt the `_array` constructors (e.g., `csr_array`) for new code and when refactoring. Update matrix multiplication from `*` to `@`. Be aware that array-like operations might return 1D arrays where matrices used to return 2D.","message":"Migration from `scipy.sparse` matrix API (e.g., `csr_matrix`) to the array API (e.g., `csr_array`) involves changes in constructor names, operator behavior (`*` vs `@`), and potential changes in return dimensions.","severity":"gotcha","affected_versions":"Relevant when migrating from older `scipy.sparse` code."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}