![]() |
![]() |
Base class defining a [batch of] linear operator[s].
Inherits From: Module
tf.linalg.LinearOperator(
dtype, graph_parents=None, is_non_singular=None, is_self_adjoint=None,
is_positive_definite=None, is_square=None, name=None
)
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.
Args | |
---|---|
dtype
|
The type of the this LinearOperator . Arguments to matmul and
solve will have to be this type.
|
graph_parents
|
Python list of graph prerequisites of this LinearOperator
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. If dtype is real, this is equivalent to being symmetric.
|
is_positive_definite
|
Expect that this operator is positive definite,
meaning 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. See:
https://en.wikipedia.org/wiki/Positive-definite_matrix#Extension_for_non-symmetric_matrices
|
is_square
|
Expect that this operator acts like square [batch] matrices. |
name
|
A name for this LinearOperator .
|
Raises | |
---|---|
ValueError
|
If any member of graph_parents is None or not a Tensor .
|
ValueError
|
If hints are set incorrectly. |
Attributes | |
---|---|
H
|
Returns the adjoint of the current LinearOperator .
Given |
batch_shape
|
TensorShape of batch dimensions of this LinearOperator .
If this operator acts like the batch matrix |
domain_dimension
|
Dimension (in the sense of vector spaces) of the domain of this operator.
If this operator acts like the batch matrix |
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.
|
range_dimension
|
Dimension (in the sense of vector spaces) of the range of this operator.
If this operator acts like the batch matrix |
shape
|
TensorShape of this LinearOperator .
If this operator acts like the batch matrix |
tensor_rank
|
Rank (in the sense of tensors) of matrix corresponding to this operator.
If this operator acts like the batch matrix |
Methods
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 same dtype and shape broadcastable to self.shape .
|
name
|
A name to give this Op .
|
Returns | |
---|---|
A Tensor with broadcast shape and same dtype as self .
|
adjoint
adjoint(
name='adjoint'
)
Returns the adjoint of the current LinearOperator
.
Given A
representing this LinearOperator
, return A*
.
Note that calling self.adjoint()
and self.H
are equivalent.
Args | |
---|---|
name
|
A name for this Op .
|
Returns | |
---|---|
LinearOperator which represents the adjoint of this 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.
|
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 this Op .
|
Returns | |
---|---|
An Assert Op , that, when run, will raise an InvalidArgumentError if
the operator is not positive definite.
|
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.
|
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 this Op .
|
Returns | |
---|---|
int32 Tensor
|
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 this Op .
|
Returns | |
---|---|
LinearOperator which represents the lower triangular matrix
in the Cholesky decomposition.
|
Raises | |
---|---|
ValueError
|
When the LinearOperator is not hinted to be positive
definite and self adjoint.
|
determinant
determinant(
name='det'
)
Determinant for every batch member.
Args | |
---|---|
name
|
A name for this Op .
|
Returns | |
---|---|
Tensor with shape self.batch_shape and same dtype as self .
|
Raises | |
---|---|
NotImplementedError
|
If self.is_square is False .
|
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.linalg.diag_part(my_operator.to_dense())
==> [1., 2.]
Args | |
---|---|
name
|
A name for this Op .
|
Returns | |
---|---|
diag_part
|
A Tensor of same dtype as self.
|
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 this Op .
|
Returns | |
---|---|
int32 Tensor
|
inverse
inverse(
name='inverse'
)
Returns the Inverse of this LinearOperator
.
Given A
representing this LinearOperator
, return a LinearOperator
representing A^-1
.
Args | |
---|---|
name
|
A name scope to use for ops added by this method. |
Returns | |
---|---|
LinearOperator representing inverse of this matrix.
|
Raises | |
---|---|
ValueError
|
When the LinearOperator is not hinted to be non_singular .
|
log_abs_determinant
log_abs_determinant(
name='log_abs_det'
)
Log absolute value of det