LostTech.TensorFlow : API Documentation

Type LinearOperator

Namespace tensorflow.linalg

Parent Module

Interfaces ILinearOperator

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: #### 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.
Show Example 
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

Methods

Properties

Public instance methods

object assert_non_singular(string name)

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 ```
Parameters
string name
A string name to prepend to created ops.
Returns
object
An `Assert` `Op`, that, when run, will raise an `InvalidArgumentError` if the operator is singular.

object assert_non_singular_dyn(ImplicitContainer<T> name)

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 ```
Parameters
ImplicitContainer<T> name
A string name to prepend to created ops.
Returns
object
An `Assert` `Op`, that, when run, will raise an `InvalidArgumentError` if the operator is singular.

object assert_positive_definite(string name)

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.
Parameters
string name
A name to give this `Op`.
Returns
object
An `Assert` `Op`, that, when run, will raise an `InvalidArgumentError` if the operator is not positive definite.

object assert_positive_definite_dyn(ImplicitContainer<T> name)

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.
Parameters
ImplicitContainer<T> name
A name to give this `Op`.
Returns
object
An `Assert` `Op`, that, when run, will raise an `InvalidArgumentError` if the operator is not positive definite.

object assert_self_adjoint(string name)

Returns an `Op` that asserts this operator is self-adjoint.

Here we check that this operator is *exactly* equal to its hermitian transpose.
Parameters
string name
A string name to prepend to created ops.
Returns
object
An `Assert` `Op`, that, when run, will raise an `InvalidArgumentError` if the operator is not self-adjoint.

object assert_self_adjoint_dyn(ImplicitContainer<T> name)

Returns an `Op` that asserts this operator is self-adjoint.

Here we check that this operator is *exactly* equal to its hermitian transpose.
Parameters
ImplicitContainer<T> name
A string name to prepend to created ops.
Returns
object
An `Assert` `Op`, that, when run, will raise an `InvalidArgumentError` if the operator is not self-adjoint.

Tensor batch_shape_tensor(string name)

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]`.
Parameters
string name
A name for this `Op`.
Returns
Tensor
`int32` `Tensor`

object batch_shape_tensor_dyn(ImplicitContainer<T> name)

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]`.
Parameters
ImplicitContainer<T> name
A name for this `Op`.
Returns
object
`int32` `Tensor`

Tensor domain_dimension_tensor(string name)

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`.
Parameters
string name
A name for this `Op`.
Returns
Tensor
`int32` `Tensor`

object domain_dimension_tensor_dyn(ImplicitContainer<T> name)

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`.
Parameters
ImplicitContainer<T> name
A name for this `Op`.
Returns
object
`int32` `Tensor`

object matmul(object x, bool adjoint, bool adjoint_arg, string name)

Transform [batch] matrix `x` with left multiplication: `x --> Ax`.
Parameters
object x
`LinearOperator` or `Tensor` with compatible shape and same `dtype` as `self`. See class docstring for definition of compatibility.
bool adjoint
Python `bool`. If `True`, left multiply by the adjoint: `A^H x`.
bool adjoint_arg
Python `bool`. If `True`, compute `A x^H` where `x^H` is the hermitian transpose (transposition and complex conjugation).
string name
A name for this `Op`.
Returns
object
A `LinearOperator` or `Tensor` with shape `[..., M, R]` and same `dtype` as `self`.
Show Example 
# 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]

Tensor range_dimension_tensor(string name)

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`.
Parameters
string name
A name for this `Op`.
Returns
Tensor
`int32` `Tensor`

object range_dimension_tensor_dyn(ImplicitContainer<T> name)

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`.
Parameters
ImplicitContainer<T> name
A name for this `Op`.
Returns
object
`int32` `Tensor`

Tensor shape_tensor(string name)

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)`.
Parameters
string name
A name for this `Op`.
Returns
Tensor
`int32` `Tensor`

object shape_tensor_dyn(ImplicitContainer<T> name)

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)`.
Parameters
ImplicitContainer<T> name
A name for this `Op`.
Returns
object
`int32` `Tensor`

Tensor tensor_rank_tensor(string name)

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`.
Parameters
string name
A name for this `Op`.
Returns
Tensor
`int32` `Tensor`, determined at runtime.

object tensor_rank_tensor_dyn(ImplicitContainer<T> name)

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`.
Parameters
ImplicitContainer<T> name
A name for this `Op`.
Returns
object
`int32` `Tensor`, determined at runtime.

Public properties

object batch_shape get;

`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.shape[:-2]`

object batch_shape_dyn get;

`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.shape[:-2]`

Dimension domain_dimension get;

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`.

object domain_dimension_dyn get;

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`.

object dtype get;

The `DType` of `Tensor`s handled by this `LinearOperator`.

object dtype_dyn get;

The `DType` of `Tensor`s handled by this `LinearOperator`.

IList<object> graph_parents get;

List of graph dependencies of this `LinearOperator`.

object graph_parents_dyn get;

List of graph dependencies of this `LinearOperator`.

PropertyInfo H get; set;

Returns the adjoint of the current `LinearOperator`.

Given `A` representing this `LinearOperator`, return `A*`. Note that calling `self.adjoint()` and `self.H` are equivalent.

object H_dyn get; set;

Returns the adjoint of the current `LinearOperator`.

Given `A` representing this `LinearOperator`, return `A*`. Note that calling `self.adjoint()` and `self.H` are equivalent.

Nullable<bool> is_non_singular get;

object is_non_singular_dyn get;

object is_positive_definite get;

object is_positive_definite_dyn get;

object is_self_adjoint get;

object is_self_adjoint_dyn get;

Nullable<bool> is_square get;

Return `True/False` depending on if this operator is square.

object is_square_dyn get;

Return `True/False` depending on if this operator is square.

object name get;

Name prepended to all ops created by this `LinearOperator`.

object name_dyn get;

Name prepended to all ops created by this `LinearOperator`.

object name_scope get;

object name_scope_dyn get;

object PythonObject get;

Dimension range_dimension get;

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`.

object range_dimension_dyn get;

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`.

TensorShape shape get;

`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.shape`.

object shape_dyn get;

`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.shape`.

ValueTuple<object> submodules get;

object submodules_dyn get;

Nullable<int> tensor_rank get;

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`.

object tensor_rank_dyn get;

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`.

object trainable_variables get;

object trainable_variables_dyn get;

object variables get;

object variables_dyn get;