The linop Module

Base Class for Linear Operators

All linear operators derive from the base class BaseLinearOperator. This base class is not meant to be used directly to define linear operators, other than by subclassing to define classes of more specific linear operators.

class linop.linop.BaseLinearOperator(nargin, nargout, symmetric=False, **kwargs)

Bases: object

Base class defining the common interface shared by all linear operators.

A linear operator is a linear mapping x -> A(x) such that the size of the input vector x is nargin and the size of the output is nargout. It can be visualized as a matrix of shape (nargout, nargin). Its type is any valid Numpy dtype. By default, it has dtype numpy.float but this can be changed to, e.g., numpy.complex via the dtype keyword argument and attribute.

A logger may be attached to the linear operator via the logger keyword argument.

dot(x)

Numpy-like dot() method.

dtype

The data type of the operator.

nMatvec

The number of products with vectors computed so far.

nargin

The size of an input vector.

nargout

The size of an output vector.

reset_counters()

Reset operator/vector product counter to zero.

shape

The shape of the operator.

symmetric

Indicate whether the operator is symmetric or not.

Linear Operators Defined by Functions

It is intuitive to define an operator by its action on vectors. The LinearOperator class takes arguments matvec and rmatvec to define the action of the operator and of its transpose.

Here is a simple example:

import numpy as np
A = LinearOperator(nargin=3, nargout=3, matvec=lambda v: 2*v, symmetric=True)
B = LinearOperator(nargin=4, nargout=3, matvec=lambda v: np.arange(3)*v[:3],
                   rmatvec=lambda v: np.concatenate((np.arange(3)*v, np.zeros(1))))

The API also supports using the keyword argument matvec_transp to replace to maintain compatibility with pysparse-style instantiation.

Here, A represents the operator \(2I\), where \(I\) is the identity and B could be represented by the matrix

\[\begin{split}\begin{bmatrix} 1 & & & \\ & 2 & & \\ & & 3 & 0 \\ \end{bmatrix}.\end{split}\]

Note that any callable object can be used to pass values for matvec and rmatvec. For example :

def func(v):
    return np.arange(3) * v

class MyClass(object):
    def __call__(self, u):
        return np.concatenate((np.arange(3)*v, np.zeros(1)))

myobject = MyClass()
B = LinearOperator(nargin=4, nargout=3, matvec=func, rmatvec=myobject)

is perfectly valid. Based on this example, arbitrarily complex operators may be built.

class linop.linop.LinearOperator(nargin, nargout, matvec, rmatvec=None, **kwargs)

Bases: linop.linop.BaseLinearOperator

Generic linear operator class.

A linear operator constructed from a matvec and (possibly) a rmatvec function. If symmetric is True, rmatvec is ignored. All other keyword arguments are passed directly to the superclass.

H

The adjoint operator.

T

The transpose operator.

Note

this is an alias to the adjoint operator

dot(x)

Numpy-like dot() method.

dtype

The data type of the operator.

matvec(x)

Matrix-vector multiplication.

The matvec property encapsulates the matvec routine specified at construct time, to ensure the consistency of the input and output arrays with the operator’s shape.

nMatvec

The number of products with vectors computed so far.

nargin

The size of an input vector.

nargout

The size of an output vector.

reset_counters()

Reset operator/vector product counter to zero.

shape

The shape of the operator.

symmetric

Indicate whether the operator is symmetric or not.

to_array()

Simple Common Predefined Linear Operators

A few common operators are predefined, such as the identity, the zero operator, and a class for diagonal operators.

class linop.linop.IdentityOperator(nargin, **kwargs)

Bases: linop.linop.LinearOperator

Class representing the identity operator of size nargin.

H

The adjoint operator.

T

The transpose operator.

Note

this is an alias to the adjoint operator

dot(x)

Numpy-like dot() method.

dtype

The data type of the operator.

matvec(x)

Matrix-vector multiplication.

The matvec property encapsulates the matvec routine specified at construct time, to ensure the consistency of the input and output arrays with the operator’s shape.

nMatvec

The number of products with vectors computed so far.

nargin

The size of an input vector.

nargout

The size of an output vector.

reset_counters()

Reset operator/vector product counter to zero.

shape

The shape of the operator.

symmetric

Indicate whether the operator is symmetric or not.

to_array()

class linop.linop.ZeroOperator(nargin, nargout, **kwargs)

Bases: linop.linop.LinearOperator

Class representing the zero operator of shape nargout-by-nargin.

H

The adjoint operator.

T

The transpose operator.

Note

this is an alias to the adjoint operator

dot(x)

Numpy-like dot() method.

dtype

The data type of the operator.

matvec(x)

Matrix-vector multiplication.

The matvec property encapsulates the matvec routine specified at construct time, to ensure the consistency of the input and output arrays with the operator’s shape.

nMatvec

The number of products with vectors computed so far.

nargin

The size of an input vector.

nargout

The size of an output vector.

reset_counters()

Reset operator/vector product counter to zero.

shape

The shape of the operator.

symmetric

Indicate whether the operator is symmetric or not.

to_array()

Diagonal operators are simply defined by their diagonal as a Numpy array. For example:

d = np.random.random(10)
D = DiagonalOperator(d)

class linop.linop.DiagonalOperator(diag, **kwargs)

Bases: linop.linop.LinearOperator

Class representing a diagonal operator.

A diagonal linear operator defined by its diagonal diag (a Numpy array.) The type must be specified in the diag argument, e.g., np.ones(5, dtype=np.complex) or np.ones(5).astype(np.complex).

H

The adjoint operator.

T

The transpose operator.

Note

this is an alias to the adjoint operator

dot(x)

Numpy-like dot() method.

dtype

The data type of the operator.

matvec(x)

Matrix-vector multiplication.

The matvec property encapsulates the matvec routine specified at construct time, to ensure the consistency of the input and output arrays with the operator’s shape.

nMatvec

The number of products with vectors computed so far.

nargin

The size of an input vector.

nargout

The size of an output vector.

reset_counters()

Reset operator/vector product counter to zero.

shape

The shape of the operator.

symmetric

Indicate whether the operator is symmetric or not.

to_array()

Matrix operators wraps calls to the dot and tranposed dot product of the provided Numpy array. For example:

m = np.arange(12).reshape([4, 3])
M = MatrixLinearOperator(m)

class linop.linop.MatrixLinearOperator(matrix, **kwargs)

Bases: linop.linop.LinearOperator

Class representing a matrix operator.

A linear operator wrapping the multiplication with a matrix and its transpose (real) or conjugate transpose (complex). The operator’s dtype is the same as the specified matrix argument.

New in version 0.3.

H

The adjoint operator.

T

The transpose operator.

Note

this is an alias to the adjoint operator

dot(x)

Numpy-like dot() method.

dtype

The data type of the operator.

matvec(x)

Matrix-vector multiplication.

The matvec property encapsulates the matvec routine specified at construct time, to ensure the consistency of the input and output arrays with the operator’s shape.

nMatvec

The number of products with vectors computed so far.

nargin

The size of an input vector.

nargout

The size of an output vector.

reset_counters()

Reset operator/vector product counter to zero.

shape

The shape of the operator.

symmetric

Indicate whether the operator is symmetric or not.

to_array()

Convenience Functions

Typically, linear operators don’t come alone and an operator is often used to define other operators. An example is reduction. Suppose \(A\) is a linear operator from \(\mathbb{R}^n\) into \(\mathbb{R^m}\), \(\mathcal{Z}\) is a subspace of \(\mathbb{R}^n\) and \(\mathcal{Y}\) is a subspace of \(\mathbb{R}^m\). Sometimes it is useful to consider \(A\) restricted to \(\mathcal{Z}\) and co-restricted to \(\mathcal{Y}\). Assuming that \(A\) is a matrix representing the linear operator and \(Z\) and \(Y\) are matrices whose columns form bases of the subspaces \(\mathcal{Z}\) and \(\mathcal{Y}\), respectively, then the restricted operator may be written \(Y^T A Z\).

A simple version of this type of reduction is where we only consider a subset of the rows and columns of the matrix \(A\), which corresponds to subspaces \(\mathcal{Z}\) and \(\mathcal{Y}\) aligned with the axes of coordinates.

Note that by default, the reduced linear operator is considered to be non-symmetric even if the original operator was symmetric.

linop.linop.ReducedLinearOperator(op, row_indices, col_indices)

Implement reduction of a linear operator (non symmetrical).

Reduce a linear operator by limiting its input to col_indices and its output to row_indices.

A special case of this type of reduction is when row_indices and col_indices are the same. This is often useful in combination with square symmetric operators. In this case, the reduced operator possesses the same symmetry as the original operator.

linop.linop.SymmetricallyReducedLinearOperator(op, indices)

Implement reduction of a linear operator (symmetrical).

Reduce a linear operator symmetrically by reducing boths its input and output to indices.

An obvious use case of linear operators is matrices themselves! The following convenience functions allows to build linear operators from various matrix-like input, such as Pysparse sparse matrices or Numpy arrays.

linop.linop.PysparseLinearOperator(A)

Return a linear operator from a Pysparse sparse matrix.

Deprecated since version 0.6: Use aslinearoperator() instead.

linop.linop.linop_from_ndarray(A)

Return a linear operator from a Numpy ndarray.

Deprecated since version 0.4: Use MatrixLinearOperator or aslinearoperator() instead.

linop.linop.aslinearoperator(A)

Return A as a LinearOperator.

‘A’ may be any of the following types: - linop.LinearOperator - scipy.LinearOperator - ndarray - matrix - sparse matrix (e.g. csr_matrix, lil_matrix, etc.) - any object with .shape and .matvec attributes

See the LinearOperator documentation for additonal information.

New in version 0.4.

Aliases

New in version 0.5.

Shorter aliases to some linear operators are now available and listed below:

• MatrixOperator for MatrixLinearOperator
• aslinop for aslinearoperator()

Exceptions

exception linop.linop.ShapeError(value)

Exception class for handling shape mismatch errors.

Exception raised when defining a linear operator of the wrong shape or multiplying a linear operator with a vector of the wrong shape.

Operations with operators

Linear operators, whether defined by blocks or not, may be added together or composed following the usual rules of linear algebra. An operator may be multiplied by a scalar or by another operator. Operators of the same shape may be added or subtracted. Those operations are essentially free in the sense that a new linear operator results of them, which encapsulates the appropriate rules for multiplication by a vector. It is only when the resulting operator is applied to a vector that the appropriate chain of operations is applied. For example:

AB = A * B
AA = A * A.T
G  = E + 2 * B.T * B