---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.18.0-dev
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
---

# Storage Schemes

## Sparse Array Classes

- There are seven sparse array types in scipy.sparse:
  1. [csr_array](csr_array): Compressed Sparse Row format
  2. [csc_array](csc_array): Compressed Sparse Column format
  3. [bsr_array](csc_array): Block Sparse Row format
  4. [lil_array](csc_array): List of Lists format
  5. [dok_array](dok_array): Dictionary of Keys format
  6. [coo_array](coo_array): COOrdinate format (aka IJV,
     triplet format)
  7. [dia_array](dia_array): DIAgonal format

- each suitable for some tasks

- many employ sparsetools C++ module by Nathan Bell

- assume the following is imported:

```{code-cell}
import numpy as np
import scipy as sp
import matplotlib.pyplot as plt
```

- **warning** for Numpy users:
  - passing a sparse array object to NumPy functions that expect
    ndarray/matrix does not work. Use sparse functions.
  - the older csr_matrix classes use '\*' for matrix multiplication (dot
    product) and 'A.multiply(B)' for elementwise multiplication.
  - the newer csr_array uses '@' for dot product and '\*' for elementwise
    multiplication
  - sparse arrays can be 1D or 2D, but not nD for n > 2 (unlike Numpy arrays).

## Common Methods

- all scipy.sparse array classes are subclasses of {class}`sparray`
  - default implementation of arithmetic operations
    - always converts to CSR
    - subclasses override for efficiency
  - shape, data type, set/get
  - indices of nonzero values in the array
  - format conversion, interaction with NumPy (`toarray()`)
  - ...
- attributes:
  - `mtx.T` - transpose (same as mtx.transpose())
  - `mtx.real` - real part of complex matrix
  - `mtx.imag` - imaginary part of complex matrix
  - `mtx.size` - the number of nonzeros (same as self.getnnz())
  - `mtx.shape` - the number of rows and columns (tuple)
- data and indices usually stored in 1D NumPy arrays

## Summary

| format | matrix \* vector | get item | fancy get     | set item | fancy set | solvers     | note                                                        |
| ------ | ---------------- | -------- | ------------- | -------- | --------- | ----------- | ----------------------------------------------------------- |
| CSR    | sparsetools      | yes      | yes           | slow     | .         | any         | has data array, fast row-wise ops                           |
| CSC    | sparsetools      | yes      | yes           | slow     | .         | any         | has data array, fast column-wise ops                        |
| BSR    | sparsetools      | .        | .             | .        | .         | specialized | has data array, specialized                                 |
| COO    | sparsetools      | .        | .             | .        | .         | iterative   | has data array, facilitates fast conversion                 |
| DIA    | sparsetools      | .        | .             | .        | .         | iterative   | has data array, specialized                                 |
| LIL    | via CSR          | yes      | yes           | yes      | yes       | iterative   | arithmetic via CSR, incremental construction                |
| DOK    | Python           | yes      | one axis only | yes      | yes       | iterative   | O(1) item access, incremental construction, slow arithmetic |