Skip to main content
`Ctrl`+`K`
scipy.sparse.linalg.

# LinearOperator

class scipy.sparse.linalg.LinearOperator(*args, **kwargs)

  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:
    shape tuple

      Matrix dimensions `(..., M, N)`, where `...` represents any additional batch dimensions.

    matvec callable f(v)

      Applies `A` to `v`, where `v` is a dense vector with shape `(..., N)`.

    rmatvec callable 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)`.

    matmat callable f(V)

      Returns `A @ V`, where `V` is a dense matrix with dimensions `(..., N, K)`.

    rmatmat callable 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)`.

    dtype dtype

      Data type of the matrix or matrices.

    xp array_namespace, optional

      A namespace compatible with the array API standard for use in array operations. Default: `numpy`.

  Attributes:
    args tuple

      For linear operators describing products etc. of other linear operators, the operands of the binary operation.

    ndim int

      Number of dimensions (greater than 2 in the case of batch dimensions).

    `T` LinearOperator

      Transpose.

    `H` LinearOperator

      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.])