scipy.sparse.linalg.

LinearOperator#

class scipy.sparse.linalg.LinearOperator(*args, **kwargs)[source]#

Common interface for performing matrix vector products.

Many iterative methods (e.g. cg, gmres) do not need to know the individual entries of a matrix to solve a linear system A@x = b. Such solvers only require the computation of matrix vector products, A@v, where v is a dense vector. This class serves as an abstract interface between iterative solvers and matrix-like objects.

To construct a concrete LinearOperator, either pass appropriate callables to the constructor of this class, or subclass it.

A subclass must implement either one of the methods _matvec and _matmat, and the attributes/properties shape (pair of integers, optionally with additional batch dimensions at the front) and dtype (may be None). It may call the __init__ on this class to have these attributes validated. Implementing _matvec automatically implements _matmat (using a naive algorithm) and vice-versa.

Optionally, a subclass may implement _rmatvec or _adjoint to implement the Hermitian adjoint (conjugate transpose). As with _matvec and _matmat, implementing either _rmatvec or _adjoint implements the other automatically. Implementing _adjoint is preferable; _rmatvec is mostly there for backwards compatibility.

The defined operator may have additional “batch” dimensions prepended to the core shape, to represent a batch of 2-D operators; see Batched Linear Operations for details.

Parameters:

shapetuple: Matrix dimensions (..., M, N), where ... represents any additional batch dimensions.
matveccallable f(v): Applies A to v, where v is a dense vector with shape (..., N).
rmatveccallable f(v): Applies A^H to v, where A^H is the conjugate transpose of A, and v is a dense vector of shape (..., M).
matmatcallable f(V): Returns A @ V, where V is a dense matrix with dimensions (..., N, K).
rmatmatcallable f(V): Returns A^H @ V, where A^H is the conjugate transpose of A, and where V is a dense matrix with dimensions (..., M, K).
dtypedtype: Data type of the matrix or matrices.

Attributes:

argstuple: For linear operators describing products etc. of other linear operators, the operands of the binary operation.
ndimint: Number of dimensions (greater than 2 in the case of batch dimensions).
TLinearOperator: Transpose.
HLinearOperator: Hermitian adjoint.

Methods

`matvec`(x)	Matrix-vector multiplication.
`matmat`(X)	Matrix-matrix multiplication.
`adjoint`()	Hermitian adjoint.
`transpose`()	Transpose.
`rmatvec`(x)	Adjoint matrix-vector multiplication.
`rmatmat`(X)	Adjoint matrix-matrix multiplication.
`dot`(x)	Multi-purpose multiplication method.
`rdot`(x)	Multi-purpose multiplication method from the right.
`__mul__`(x)	Multiplication.
`__matmul__`(other)	Matrix Multiplication.
`__call__`(x)	Apply this linear operator.
`__add__`(x)	Linear operator addition.
`__truediv__`(other)	Scalar Division.
`__rmul__`(x)	Multiplication from the right.
`__rmatmul__`(other)	Matrix Multiplication from the right.

See also

aslinearoperator: Construct a LinearOperator.

Notes

The user-defined matvec function must properly handle the case where v has shape (..., N).

It is highly recommended to explicitly specify the dtype, otherwise it is determined automatically at the cost of a single matvec application on int8 zero vector using the promoted dtype of the output. It is assumed that matmat, rmatvec, and rmatmat would result in the same dtype of the output given an int8 input as matvec.

LinearOperator instances can also be multiplied, added with each other, and raised to integral powers, all lazily: the result of these operations is always a new, composite LinearOperator, that defers linear operations to the original operators and combines the results.

More details regarding how to subclass a LinearOperator and several examples of concrete LinearOperator instances can be found in the external project PyLops.

Array API Standard Support

LinearOperator has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

Library	CPU	GPU
NumPy	✅	n/a
CuPy	n/a	⛔
PyTorch	⛔	⛔
JAX	⛔	⛔
Dask	⛔	n/a

See Support for the array API standard for more information.

Examples

>>> import numpy as np
>>> from scipy.sparse.linalg import LinearOperator
>>> def mv(v):
...     return np.array([2*v[0], 3*v[1]])
...
>>> A = LinearOperator((2,2), matvec=mv)
>>> A
<2x2 _CustomLinearOperator with dtype=int8>
>>> A.matvec(np.ones(2))
array([ 2.,  3.])
>>> A @ np.ones(2)
array([ 2.,  3.])