Class LinearOperator
Defined in tensorflow/python/ops/linalg/linear_operator.py
.
Base class defining a [batch of] linear operator[s].
Subclasses of LinearOperator
provide access to common methods on a
(batch) matrix, without the need to materialize the matrix. This allows:
- Matrix free computations
- Operators that take advantage of special structure, while providing a consistent API to users.
Subclassing
To enable a public method, subclasses should implement the leading-underscore
version of the method. The argument signature should be identical except for
the omission of name="..."
. For example, to enable
matmul(x, adjoint=False, name="matmul")
a subclass should implement
_matmul(x, adjoint=False)
.
Performance contract
Subclasses should only implement the assert methods
(e.g. assert_non_singular
) if they can be done in less than O(N^3)
time.
Class docstrings should contain an explanation of computational complexity. Since this is a high-performance library, attention should be paid to detail, and explanations can include constants as well as Big-O notation.
Shape compatibility
LinearOperator
subclasses should operate on a [batch] matrix with
compatible shape. Class docstrings should define what is meant by compatible
shape. Some subclasses may not support batching.
Examples:
x
is a batch matrix with compatible shape for matmul
if
operator.shape = [B1,...,Bb] + [M, N], b >= 0,
x.shape = [B1,...,Bb] + [N, R]
rhs
is a batch matrix with compatible shape for solve
if
operator.shape = [B1,...,Bb] + [M, N], b >= 0,
rhs.shape = [B1,...,Bb] + [M, R]
Example docstring for subclasses.
This operator acts like a (batch) matrix A
with shape
[B1,...,Bb, M, N]
for some b >= 0
. The first b
indices index a
batch member. For every batch index (i1,...,ib)
, A[i1,...,ib, : :]
is
an m x n
matrix. Again, this matrix A
may not be materialized, but for
purposes of identifying and working with compatible arguments the shape is
relevant.
Examples:
some_tensor = ... shape = ????
operator = MyLinOp(some_tensor)
operator.shape()
==> [2, 4, 4]
operator.log_abs_determinant()
==> Shape [2] Tensor
x = ... Shape [2, 4, 5] Tensor
operator.matmul(x)
==> Shape [2, 4, 5] Tensor
Shape compatibility
This operator acts on batch matrices with compatible shape. FILL IN WHAT IS MEANT BY COMPATIBLE SHAPE
Performance
FILL THIS IN
Matrix property hints
This LinearOperator
is initialized with boolean flags of the form is_X
,
for X = non_singular, self_adjoint, positive_definite, square
.
These have the following meaning:
- If
is_X == True
, callers should expect the operator to have the propertyX
. This is a promise that should be fulfilled, but is not a runtime assert. For example, finite floating point precision may result in these promises being violated. - If
is_X == False
, callers should expect the operator to not haveX
. - If
is_X == None
(the default), callers should have no expectation either way.
__init__
__init__(
dtype,
graph_parents=None,
is_non_singular=None,
is_self_adjoint=None,
is_positive_definite=None,
is_square=None,
name=None
)
Initialize the LinearOperator
.
This is a private method for subclass use.
Subclasses should copy-paste this __init__
documentation.
Args:
dtype
: The type of the thisLinearOperator
. Arguments tomatmul
andsolve
will have to be this type.graph_parents
: Python list of graph prerequisites of thisLinearOperator
Typically tensors that are passed during initialization.is_non_singular
: Expect that this operator is non-singular.is_self_adjoint
: Expect that this operator is equal to its hermitian transpose. Ifdtype
is real, this is equivalent to being symmetric.is_positive_definite
: Expect that this operator is positive definite, meaning the quadratic formx^H A x
has positive real part for all nonzerox
. Note that we do not require the operator to be self-adjoint to be positive-definite. See: https://en.wikipedia.org/wiki/Positive-definite_matrix#Extension_for_non-symmetric_matricesis_square
: Expect that this operator acts like square [batch] matrices.name
: A name for thisLinearOperator
.
Raises:
ValueError
: If any member of graph_parents isNone
or not aTensor
.ValueError
: If hints are set incorrectly.
Properties
batch_shape
TensorShape
of batch dimensions of this LinearOperator
.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns
TensorShape([B1,...,Bb])
, equivalent to A.get_shape()[:-2]
Returns:
TensorShape
, statically determined, may be undefined.
domain_dimension
Dimension (in the sense of vector spaces) of the domain of this operator.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns N
.
Returns:
Dimension
object.
dtype
The DType
of Tensor
s handled by this LinearOperator
.
graph_parents
List of graph dependencies of this LinearOperator
.
is_non_singular
is_positive_definite
is_self_adjoint
is_square
Return True/False
depending on if this operator is square.
name
Name prepended to all ops created by this LinearOperator
.
range_dimension
Dimension (in the sense of vector spaces) of the range of this operator.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns M
.
Returns:
Dimension
object.
shape
TensorShape
of this LinearOperator
.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns
TensorShape([B1,...,Bb, M, N])
, equivalent to A.get_shape()
.
Returns:
TensorShape
, statically determined, may be undefined.
tensor_rank
Rank (in the sense of tensors) of matrix corresponding to this operator.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns b + 2
.
Args:
name
: A name for thisOp
.
Returns:
Python integer, or None if the tensor rank is undefined.
Methods
tf.linalg.LinearOperator.add_to_tensor
add_to_tensor(
x,
name='add_to_tensor'
)
Add matrix represented by this operator to x
. Equivalent to A + x
.
Args:
x
:Tensor
with samedtype
and shape broadcastable toself.shape
.name
: A name to give thisOp
.
Returns:
A Tensor
with broadcast shape and same dtype
as self
.
tf.linalg.LinearOperator.assert_non_singular
assert_non_singular(name='assert_non_singular')
Returns an Op
that asserts this operator is non singular.
This operator is considered non-singular if
ConditionNumber < max{100, range_dimension, domain_dimension} * eps,
eps := np.finfo(self.dtype.as_numpy_dtype).eps
Args:
name
: A string name to prepend to created ops.
Returns:
An Assert
Op
, that, when run, will raise an InvalidArgumentError
if
the operator is singular.
tf.linalg.LinearOperator.assert_positive_definite
assert_positive_definite(name='assert_positive_definite')
Returns an Op
that asserts this operator is positive definite.
Here, positive definite means that the quadratic form x^H A x
has positive
real part for all nonzero x
. Note that we do not require the operator to
be self-adjoint to be positive definite.
Args:
name
: A name to give thisOp
.
Returns:
An Assert
Op
, that, when run, will raise an InvalidArgumentError
if
the operator is not positive definite.
tf.linalg.LinearOperator.assert_self_adjoint
assert_self_adjoint(name='assert_self_adjoint')
Returns an Op
that asserts this operator is self-adjoint.
Here we check that this operator is exactly equal to its hermitian transpose.
Args:
name
: A string name to prepend to created ops.
Returns:
An Assert
Op
, that, when run, will raise an InvalidArgumentError
if
the operator is not self-adjoint.
tf.linalg.LinearOperator.batch_shape_tensor
batch_shape_tensor(name='batch_shape_tensor')
Shape of batch dimensions of this operator, determined at runtime.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns a Tensor
holding
[B1,...,Bb]
.
Args:
name
: A name for thisOp
.
Returns:
int32
Tensor
tf.linalg.LinearOperator.cholesky
cholesky(name='cholesky')
Returns a Cholesky factor as a LinearOperator
.
Given A
representing this LinearOperator
, if A
is positive definite
self-adjoint, return L
, where A = L L^T
, i.e. the cholesky
decomposition.
Args:
name
: A name for thisOp
.
Returns:
LinearOperator
which represents the lower triangular matrix
in the Cholesky decomposition.
Raises:
ValueError
: When theLinearOperator
is not hinted to be positive definite and self adjoint.
tf.linalg.LinearOperator.determinant
determinant(name='det')
Determinant for every batch member.
Args:
name
: A name for thisOp
.
Returns:
Tensor
with shape self.batch_shape
and same dtype
as self
.
Raises:
NotImplementedError
: Ifself.is_square
isFalse
.
tf.linalg.LinearOperator.diag_part
diag_part(name='diag_part')
Efficiently get the [batch] diagonal part of this operator.
If this operator has shape [B1,...,Bb, M, N]
, this returns a
Tensor
diagonal
, of shape [B1,...,Bb, min(M, N)]
, where
diagonal[b1,...,bb, i] = self.to_dense()[b1,...,bb, i, i]
.
my_operator = LinearOperatorDiag([1., 2.])
# Efficiently get the diagonal
my_operator.diag_part()
==> [1., 2.]
# Equivalent, but inefficient method
tf.matrix_diag_part(my_operator.to_dense())
==> [1., 2.]
Args:
name
: A name for thisOp
.
Returns:
diag_part
: ATensor
of samedtype
as self.
tf.linalg.LinearOperator.domain_dimension_tensor
domain_dimension_tensor(name='domain_dimension_tensor')
Dimension (in the sense of vector spaces) of the domain of this operator.
Determined at runtime.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns N
.
Args:
name
: A name for thisOp
.
Returns:
int32
Tensor
tf.linalg.LinearOperator.log_abs_determinant
log_abs_determinant(name='log_abs_det')
Log absolute value of determinant for every batch member.
Args:
name
: A name for thisOp
.
Returns:
Tensor
with shape self.batch_shape
and same dtype
as self
.
Raises:
NotImplementedError
: Ifself.is_square
isFalse
.
tf.linalg.LinearOperator.matmul
matmul(
x,
adjoint=False,
adjoint_arg=False,
name='matmul'
)
Transform [batch] matrix x
with left multiplication: x --> Ax
.
# Make an operator acting like batch matrix A. Assume A.shape = [..., M, N]
operator = LinearOperator(...)
operator.shape = [..., M, N]
X = ... # shape [..., N, R], batch matrix, R > 0.
Y = operator.matmul(X)
Y.shape
==> [..., M, R]
Y[..., :, r] = sum_j A[..., :, j] X[j, r]
Args:
x
:LinearOperator
orTensor
with compatible shape and samedtype
asself
. See class docstring for definition of compatibility.adjoint
: Pythonbool
. IfTrue
, left multiply by the adjoint:A^H x
.adjoint_arg
: Pythonbool
. IfTrue
, computeA x^H
wherex^H
is the hermitian transpose (transposition and complex conjugation).name
: A name for thisOp
.
Returns:
A LinearOperator
or Tensor
with shape [..., M, R]
and same dtype
as self
.
tf.linalg.LinearOperator.matvec
matvec(
x,
adjoint=False,
name='matvec'
)
Transform [batch] vector x
with left multiplication: x --> Ax
.
# Make an operator acting like batch matric A. Assume A.shape = [..., M, N]
operator = LinearOperator(...)
X = ... # shape [..., N], batch vector
Y = operator.matvec(X)
Y.shape
==> [..., M]
Y[..., :] = sum_j A[..., :, j] X[..., j]
Args:
x
:Tensor
with compatible shape and samedtype
asself
.x
is treated as a [batch] vector meaning for every set of leading dimensions, the last dimension defines a vector. See class docstring for definition of compatibility.adjoint
: Pythonbool
. IfTrue
, left multiply by the adjoint:A^H x
.name
: A name for thisOp
.
Returns:
A Tensor
with shape [..., M]
and same dtype
as self
.
tf.linalg.LinearOperator.range_dimension_tensor
range_dimension_tensor(name='range_dimension_tensor')
Dimension (in the sense of vector spaces) of the range of this operator.
Determined at runtime.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns M
.
Args:
name
: A name for thisOp
.
Returns:
int32
Tensor
tf.linalg.LinearOperator.shape_tensor
shape_tensor(name='shape_tensor')
Shape of this LinearOperator
, determined at runtime.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns a Tensor
holding
[B1,...,Bb, M, N]
, equivalent to tf.shape(A)
.
Args:
name
: A name for thisOp
.
Returns:
int32
Tensor
tf.linalg.LinearOperator.solve
solve(
rhs,
adjoint=False,
adjoint_arg=False,
name='solve'
)
Solve (exact or approx) R
(batch) systems of equations: A X = rhs
.
The returned Tensor
will be close to an exact solution if A
is well
conditioned. Otherwise closeness will vary. See class docstring for details.
Examples:
# Make an operator acting like batch matrix A. Assume A.shape = [..., M, N]
operator = LinearOperator(...)
operator.shape = [..., M, N]
# Solve R > 0 linear systems for every member of the batch.
RHS = ... # shape [..., M, R]
X = operator.solve(RHS)
# X[..., :, r] is the solution to the r'th linear system
# sum_j A[..., :, j] X[..., j, r] = RHS[..., :, r]
operator.matmul(X)
==> RHS
Args:
rhs
:Tensor
with samedtype
as this operator and compatible shape.rhs
is treated like a [batch] matrix meaning for every set of leading dimensions, the last two dimensions defines a matrix. See class docstring for definition of compatibility.adjoint
: Pythonbool
. IfTrue
, solve the system involving the adjoint of thisLinearOperator
:A^H X = rhs
.adjoint_arg
: Pythonbool
. IfTrue
, solveA X = rhs^H
whererhs^H
is the hermitian transpose (transposition and complex conjugation).name
: A name scope to use for ops added by this method.
Returns:
Tensor
with shape [...,N, R]
and same dtype
as rhs
.
Raises:
NotImplementedError
: Ifself.is_non_singular
oris_square
is False.
tf.linalg.LinearOperator.solvevec
solvevec(
rhs,
adjoint=False,
name='solve'
)
Solve single equation with best effort: A X = rhs
.
The returned Tensor
will be close to an exact solution if A
is well
conditioned. Otherwise closeness will vary. See class docstring for details.
Examples:
# Make an operator acting like batch matrix A. Assume A.shape = [..., M, N]
operator = LinearOperator(...)
operator.shape = [..., M, N]
# Solve one linear system for every member of the batch.
RHS = ... # shape [..., M]
X = operator.solvevec(RHS)
# X is the solution to the linear system
# sum_j A[..., :, j] X[..., j] = RHS[..., :]
operator.matvec(X)
==> RHS
Args:
rhs
:Tensor
with samedtype
as this operator.rhs
is treated like a [batch] vector meaning for every set of leading dimensions, the last dimension defines a vector. See class docstring for definition of compatibility regarding batch dimensions.adjoint
: Pythonbool
. IfTrue
, solve the system involving the adjoint of thisLinearOperator
:A^H X = rhs
.name
: A name scope to use for ops added by this method.
Returns:
Tensor
with shape [...,N]
and same dtype
as rhs
.
Raises:
NotImplementedError
: Ifself.is_non_singular
oris_square
is False.
tf.linalg.LinearOperator.tensor_rank_tensor
tensor_rank_tensor(name='tensor_rank_tensor')
Rank (in the sense of tensors) of matrix corresponding to this operator.
If this operator acts like the batch matrix A
with
A.shape = [B1,...,Bb, M, N]
, then this returns b + 2
.
Args:
name
: A name for thisOp
.
Returns:
int32
Tensor
, determined at runtime.
tf.linalg.LinearOperator.to_dense
to_dense(name='to_dense')
Return a dense (batch) matrix representing this operator.
tf.linalg.LinearOperator.trace
trace(name='trace')
Trace of the linear operator, equal to sum of self.diag_part()
.
If the operator is square, this is also the sum of the eigenvalues.
Args:
name
: A name for thisOp
.
Returns:
Shape [B1,...,Bb]
Tensor
of same dtype
as self
.