LinearOperator
tf.contrib.linalg.LinearOperator
tf.linalg.LinearOperator
Defined in tensorflow/python/ops/linalg/linear_operator.py
.
See the guide: Linear Algebra (contrib) > LinearOperator
Base class defining a [batch of] linear operator[s].
Subclasses of LinearOperator
provide a access to common methods on a (batch) matrix, without the need to materialize the matrix. This allows:
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)
.
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.
LinearOperator
sub classes should operate on a [batch] matrix with compatible shape. Class docstrings should define what is meant by compatible shape. Some sub-classes may not support batching.
An example is:
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]
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
This operator acts on batch matrices with compatible shape. FILL IN WHAT IS MEANT BY COMPATIBLE SHAPE
FILL THIS IN
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:
is_X == True
, callers should expect the operator to have the property X
. 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.is_X == False
, callers should expect the operator to not have X
.is_X == None
(the default), callers should have no expectation either way.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]
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
.
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
.
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()
.
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
.
name
: A name for this `Op.Python integer, or None if the tensor rank is undefined.
__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.
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_matricesis_square
: Expect that this operator acts like square [batch] matrices.name
: A name for this LinearOperator
.ValueError
: If any member of graph_parents is None
or not a Tensor
.ValueError
: If hints are set incorrectly.add_to_tensor
add_to_tensor( x, name='add_to_tensor' )
Add matrix represented by this operator to x
. Equivalent to A + x
.
x
: Tensor
with same dtype
and shape broadcastable to self.shape
.name
: A name to give this Op
.A Tensor
with broadcast shape and same dtype
as self
.
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
name
: A string name to prepend to created ops.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.
name
: A name to give this Op
.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.
name
: A string name to prepend to created ops.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]
.
name
: A name for this `Op.int32
Tensor
determinant
determinant(name='det')
Determinant for every batch member.
name
: A name for this `Op.Tensor
with shape self.batch_shape
and same dtype
as self
.
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.matrix_diag_part(my_operator.to_dense()) ==> [1., 2.]
name
: A name for this Op
.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
.
name
: A name for this Op
.int32
Tensor
log_abs_determinant
log_abs_determinant(name='log_abs_det')
Log absolute value of determinant for every batch member.
name
: A name for this `Op.Tensor
with shape self.batch_shape
and same dtype
as self
.
NotImplementedError
: If self.is_square
is False
.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]
x
: Tensor
with compatible shape and same dtype
as self
. See class docstring for definition of compatibility.adjoint
: Python bool
. If True
, left multiply by the adjoint: A^H x
.adjoint_arg
: Python bool
. If True
, compute A x^H
where x^H
is the hermitian transpose (transposition and complex conjugation).name
: A name for this `Op.A Tensor
with shape [..., M, R]
and same dtype
as self
.
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]
x
: Tensor
with compatible shape and same dtype
as self
. 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
: Python bool
. If True
, left multiply by the adjoint: A^H x
.name
: A name for this `Op.A Tensor
with shape [..., M]
and same dtype
as self
.
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
.
name
: A name for this Op
.int32
Tensor
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)
.
name
: A name for this `Op.int32
Tensor
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
rhs
: Tensor
with same dtype
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
: Python bool
. If True
, solve the system involving the adjoint of this LinearOperator
: A^H X = rhs
.adjoint_arg
: Python bool
. If True
, solve A X = rhs^H
where rhs^H
is the hermitian transpose (transposition and complex conjugation).name
: A name scope to use for ops added by this method.Tensor
with shape [...,N, R]
and same dtype
as rhs
.
NotImplementedError
: If self.is_non_singular
or is_square
is False.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
rhs
: Tensor
with same dtype
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
: Python bool
. If True
, solve the system involving the adjoint of this LinearOperator
: A^H X = rhs
.name
: A name scope to use for ops added by this method.Tensor
with shape [...,N]
and same dtype
as rhs
.
NotImplementedError
: If self.is_non_singular
or is_square
is False.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
.
name
: A name for this `Op.int32
Tensor
, determined at runtime.
to_dense
to_dense(name='to_dense')
Return a dense (batch) matrix representing this operator.
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.
name
: A name for this Op
.Shape [B1,...,Bb]
Tensor
of same dtype
as self
.
© 2018 The TensorFlow Authors. All rights reserved.
Licensed under the Creative Commons Attribution License 3.0.
Code samples licensed under the Apache 2.0 License.
https://www.tensorflow.org/api_docs/python/tf/linalg/LinearOperator