Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/scipy/sparse/__init__.py: 10%
21 statements
« prev ^ index » next coverage.py v7.4.4, created at 2024-04-03 06:39 +0000
1"""
2=====================================
3Sparse matrices (:mod:`scipy.sparse`)
4=====================================
6.. currentmodule:: scipy.sparse
8.. toctree::
9 :hidden:
11 sparse.csgraph
12 sparse.linalg
14SciPy 2-D sparse array package for numeric data.
16.. note::
18 This package is switching to an array interface, compatible with
19 NumPy arrays, from the older matrix interface. We recommend that
20 you use the array objects (`bsr_array`, `coo_array`, etc.) for
21 all new work.
23 When using the array interface, please note that:
25 - ``x * y`` no longer performs matrix multiplication, but
26 element-wise multiplication (just like with NumPy arrays). To
27 make code work with both arrays and matrices, use ``x @ y`` for
28 matrix multiplication.
29 - Operations such as `sum`, that used to produce dense matrices, now
30 produce arrays, whose multiplication behavior differs similarly.
31 - Sparse arrays currently must be two-dimensional. This also means
32 that all *slicing* operations on these objects must produce
33 two-dimensional results, or they will result in an error. This
34 will be addressed in a future version.
36 The construction utilities (`eye`, `kron`, `random`, `diags`, etc.)
37 have not yet been ported, but their results can be wrapped into arrays::
39 A = csr_array(eye(3))
41Contents
42========
44Sparse array classes
45--------------------
47.. autosummary::
48 :toctree: generated/
50 bsr_array - Block Sparse Row array
51 coo_array - A sparse array in COOrdinate format
52 csc_array - Compressed Sparse Column array
53 csr_array - Compressed Sparse Row array
54 dia_array - Sparse array with DIAgonal storage
55 dok_array - Dictionary Of Keys based sparse array
56 lil_array - Row-based list of lists sparse array
57 sparray - Sparse array base class
59Sparse matrix classes
60---------------------
62.. autosummary::
63 :toctree: generated/
65 bsr_matrix - Block Sparse Row matrix
66 coo_matrix - A sparse matrix in COOrdinate format
67 csc_matrix - Compressed Sparse Column matrix
68 csr_matrix - Compressed Sparse Row matrix
69 dia_matrix - Sparse matrix with DIAgonal storage
70 dok_matrix - Dictionary Of Keys based sparse matrix
71 lil_matrix - Row-based list of lists sparse matrix
72 spmatrix - Sparse matrix base class
74Functions
75---------
77Building sparse arrays:
79.. autosummary::
80 :toctree: generated/
82 diags_array - Return a sparse array from diagonals
83 eye_array - Sparse MxN array whose k-th diagonal is all ones
84 random_array - Random values in a given shape array
85 block_array - Build a sparse array from sub-blocks
87Building sparse matrices:
89.. autosummary::
90 :toctree: generated/
92 eye - Sparse MxN matrix whose k-th diagonal is all ones
93 identity - Identity matrix in sparse matrix format
94 diags - Return a sparse matrix from diagonals
95 spdiags - Return a sparse matrix from diagonals
96 bmat - Build a sparse matrix from sparse sub-blocks
97 random - Random values in a given shape matrix
98 rand - Random values in a given shape matrix (old interface)
100Building larger structures from smaller (array or matrix)
102.. autosummary::
103 :toctree: generated/
105 kron - kronecker product of two sparse matrices
106 kronsum - kronecker sum of sparse matrices
107 block_diag - Build a block diagonal sparse matrix
108 tril - Lower triangular portion of a matrix in sparse format
109 triu - Upper triangular portion of a matrix in sparse format
110 hstack - Stack sparse matrices horizontally (column wise)
111 vstack - Stack sparse matrices vertically (row wise)
113Save and load sparse matrices:
115.. autosummary::
116 :toctree: generated/
118 save_npz - Save a sparse matrix/array to a file using ``.npz`` format.
119 load_npz - Load a sparse matrix/array from a file using ``.npz`` format.
121Sparse tools:
123.. autosummary::
124 :toctree: generated/
126 find
128Identifying sparse arrays:
130- use `isinstance(A, sp.sparse.sparray)` to check whether an array or matrix.
131- use `A.format == 'csr'` to check the sparse format
133Identifying sparse matrices:
135.. autosummary::
136 :toctree: generated/
138 issparse
139 isspmatrix
140 isspmatrix_csc
141 isspmatrix_csr
142 isspmatrix_bsr
143 isspmatrix_lil
144 isspmatrix_dok
145 isspmatrix_coo
146 isspmatrix_dia
148Submodules
149----------
151.. autosummary::
153 csgraph - Compressed sparse graph routines
154 linalg - sparse linear algebra routines
156Exceptions
157----------
159.. autosummary::
160 :toctree: generated/
162 SparseEfficiencyWarning
163 SparseWarning
166Usage information
167=================
169There are seven available sparse array types:
171 1. `csc_array`: Compressed Sparse Column format
172 2. `csr_array`: Compressed Sparse Row format
173 3. `bsr_array`: Block Sparse Row format
174 4. `lil_array`: List of Lists format
175 5. `dok_array`: Dictionary of Keys format
176 6. `coo_array`: COOrdinate format (aka IJV, triplet format)
177 7. `dia_array`: DIAgonal format
179To construct an array efficiently, use either `dok_array` or `lil_array`.
180The `lil_array` class supports basic slicing and fancy indexing with a
181similar syntax to NumPy arrays. As illustrated below, the COO format
182may also be used to efficiently construct arrays. Despite their
183similarity to NumPy arrays, it is **strongly discouraged** to use NumPy
184functions directly on these arrays because NumPy may not properly convert
185them for computations, leading to unexpected (and incorrect) results. If you
186do want to apply a NumPy function to these arrays, first check if SciPy has
187its own implementation for the given sparse array class, or **convert the
188sparse array to a NumPy array** (e.g., using the ``toarray`` method of the
189class) first before applying the method.
191To perform manipulations such as multiplication or inversion, first
192convert the array to either CSC or CSR format. The `lil_array` format is
193row-based, so conversion to CSR is efficient, whereas conversion to CSC
194is less so.
196All conversions among the CSR, CSC, and COO formats are efficient,
197linear-time operations.
199Matrix vector product
200---------------------
201To do a vector product between a sparse array and a vector simply use
202the array ``dot`` method, as described in its docstring:
204>>> import numpy as np
205>>> from scipy.sparse import csr_array
206>>> A = csr_array([[1, 2, 0], [0, 0, 3], [4, 0, 5]])
207>>> v = np.array([1, 0, -1])
208>>> A.dot(v)
209array([ 1, -3, -1], dtype=int64)
211.. warning:: As of NumPy 1.7, ``np.dot`` is not aware of sparse arrays,
212 therefore using it will result on unexpected results or errors.
213 The corresponding dense array should be obtained first instead:
215 >>> np.dot(A.toarray(), v)
216 array([ 1, -3, -1], dtype=int64)
218 but then all the performance advantages would be lost.
220The CSR format is especially suitable for fast matrix vector products.
222Example 1
223---------
224Construct a 1000x1000 `lil_array` and add some values to it:
226>>> from scipy.sparse import lil_array
227>>> from scipy.sparse.linalg import spsolve
228>>> from numpy.linalg import solve, norm
229>>> from numpy.random import rand
231>>> A = lil_array((1000, 1000))
232>>> A[0, :100] = rand(100)
233>>> A[1, 100:200] = A[0, :100]
234>>> A.setdiag(rand(1000))
236Now convert it to CSR format and solve A x = b for x:
238>>> A = A.tocsr()
239>>> b = rand(1000)
240>>> x = spsolve(A, b)
242Convert it to a dense array and solve, and check that the result
243is the same:
245>>> x_ = solve(A.toarray(), b)
247Now we can compute norm of the error with:
249>>> err = norm(x-x_)
250>>> err < 1e-10
251True
253It should be small :)
256Example 2
257---------
259Construct an array in COO format:
261>>> from scipy import sparse
262>>> from numpy import array
263>>> I = array([0,3,1,0])
264>>> J = array([0,3,1,2])
265>>> V = array([4,5,7,9])
266>>> A = sparse.coo_array((V,(I,J)),shape=(4,4))
268Notice that the indices do not need to be sorted.
270Duplicate (i,j) entries are summed when converting to CSR or CSC.
272>>> I = array([0,0,1,3,1,0,0])
273>>> J = array([0,2,1,3,1,0,0])
274>>> V = array([1,1,1,1,1,1,1])
275>>> B = sparse.coo_array((V,(I,J)),shape=(4,4)).tocsr()
277This is useful for constructing finite-element stiffness and mass matrices.
279Further details
280---------------
282CSR column indices are not necessarily sorted. Likewise for CSC row
283indices. Use the ``.sorted_indices()`` and ``.sort_indices()`` methods when
284sorted indices are required (e.g., when passing data to other libraries).
286"""
288# Original code by Travis Oliphant.
289# Modified and extended by Ed Schofield, Robert Cimrman,
290# Nathan Bell, and Jake Vanderplas.
292import warnings as _warnings
294from ._base import *
295from ._csr import *
296from ._csc import *
297from ._lil import *
298from ._dok import *
299from ._coo import *
300from ._dia import *
301from ._bsr import *
302from ._construct import *
303from ._extract import *
304from ._matrix import spmatrix
305from ._matrix_io import *
307# For backward compatibility with v0.19.
308from . import csgraph
310# Deprecated namespaces, to be removed in v2.0.0
311from . import (
312 base, bsr, compressed, construct, coo, csc, csr, data, dia, dok, extract,
313 lil, sparsetools, sputils
314)
316__all__ = [s for s in dir() if not s.startswith('_')]
318# Filter PendingDeprecationWarning for np.matrix introduced with numpy 1.15
319msg = 'the matrix subclass is not the recommended way'
320_warnings.filterwarnings('ignore', message=msg)
322from scipy._lib._testutils import PytestTester
323test = PytestTester(__name__)
324del PytestTester