contrib.linalg.LinearOperator
tf.contrib.linalg.LinearOperator
class tf.contrib.linalg.LinearOperator
Defined in tensorflow/contrib/linalg/python/ops/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:
- 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
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]
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 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. If is_X == False
, callers should expect the operator to not have X
. * If is_X == None
(the default), callers should have no expectation either way.
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 this `Op.
Returns:
Python integer, or None if the tensor rank is undefined.
Methods
__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_matrices -
is_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.
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
.
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 thisOp
.
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
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
: Ifself.is_square
isFalse
.
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.
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
log_abs_determinant
log_abs_determinant(name='log_abs_det')
Log absolute value of 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
: Ifself.is_square
isFalse
.
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
:Tensor
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 this `Op.
Returns:
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]
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 this `Op.
Returns:
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
.
Args:
-
name
: A name for thisOp
.
Returns:
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)
.
Args:
-
name
: A name for this `Op.
Returns:
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
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.
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.
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 this `Op.
Returns:
int32
Tensor
, determined at runtime.
to_dense
to_dense(name='to_dense')
Return a dense (batch) matrix representing this operator.
© 2017 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/contrib/linalg/LinearOperator