tfmri.linalg.LinearOperator

class LinearOperator(dtype, graph_parents=None, is_non_singular=None, is_self_adjoint=None, is_positive_definite=None, is_square=None, name=None, parameters=None)[source]

Bases: tensorflow_mri.python.util.linalg_imaging.LinalgImagingMixin, tensorflow.python.ops.linalg.linear_operator.LinearOperator

Base class defining a [batch of] linear operator[s].

Provides access to common matrix operations without the need to materialize the matrix.

This operator is similar to tf.linalg.LinearOperator, but has additional methods to simplify operations on images, while maintaining compatibility with the TensorFlow linear algebra framework.

Inputs and outputs to this linear operator or its subclasses may have meaningful non-vectorized N-D shapes. Thus this class defines the additional properties domain_shape and range_shape and the methods domain_shape_tensor and range_shape_tensor. These enrich the information provided by the built-in properties shape, domain_dimension, range_dimension and methods domain_dimension_tensor and range_dimension_tensor, which only have information about the vectorized 1D shapes.

Subclasses of this operator must define the methods _domain_shape and _range_shape, which return the static domain and range shapes of the operator. Optionally, subclasses may also define the methods _domain_shape_tensor and _range_shape_tensor, which return the dynamic domain and range shapes of the operator. These two methods will only be called if _domain_shape and _range_shape do not return fully defined static shapes.

Subclasses must define the abstract method _transform, which applies the operator (or its adjoint) to a [batch of] images. This internal method is called by transform. In general, subclasses of this operator should not define the methods _matvec or _matmul. These have default implementations which call _transform.

Operators derived from this class may be used in any of the following ways:

  1. Using method transform, which expects a full-shaped input and returns a full-shaped output, i.e. a tensor with shape [...] + shape, where shape is either the domain_shape or the range_shape. This method is unique to operators derived from this class.

  2. Using method matvec, which expects a vectorized input and returns a vectorized output, i.e. a tensor with shape [..., n] where n is either the domain_dimension or the range_dimension. This method is part of the TensorFlow linear algebra framework.

  3. Using method matmul, which expects matrix inputs and returns matrix outputs. Note that a matrix is just a column vector in this context, i.e. a tensor with shape [..., n, 1], where n is either the domain_dimension or the range_dimension. Matrices which are not column vectors (i.e. whose last dimension is not 1) are not supported. This method is part of the TensorFlow linear algebra framework.

Operators derived from this class may also be used with the functions tf.linalg.matvec and tf.linalg.matmul, which will call the corresponding methods.

This class also provides the convenience functions flatten_domain_shape and flatten_range_shape to flatten full-shaped inputs/outputs to their vectorized form. Conversely, expand_domain_dimension and expand_range_dimension may be used to expand vectorized inputs/outputs to their full-shaped form.

Subclassing

Subclasses must always define _transform, which implements this operator’s functionality (and its adjoint). In general, subclasses should not define the methods _matvec or _matmul. These have default implementations which call _transform.

Subclasses must always define _domain_shape and _range_shape, which return the static domain/range shapes of the operator. If the subclassed operator needs to provide dynamic domain/range shapes and the static shapes are not always fully-defined, it must also define _domain_shape_tensor and _range_shape_tensor, which return the dynamic domain/range shapes of the operator. In general, subclasses should not define the methods _shape or _shape_tensor. These have default implementations.

If the subclassed operator has a non-scalar batch shape, it must also define _batch_shape which returns the static batch shape. If the static batch shape is not always fully-defined, the subclass must also define _batch_shape_tensor, which returns the dynamic batch shape.

Parameters

  • dtype – The tf.dtypes.DType of the matrix that this operator represents.

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

  • is_square – Expect that this operator acts like square [batch] matrices.

  • name – A name for this LinearOperator.

Initialize the LinearOperator. (deprecated arguments)

Deprecated: SOME ARGUMENTS ARE DEPRECATED: (graph_parents). They will be removed in a future version. Instructions for updating: Do not pass graph_parents. They will no longer be used.

This is a private method for subclass use. Subclasses should copy-paste this ``__init__`` documentation.

Parameters

  • dtype – The type of the this LinearOperator. Arguments to matmul and solve will have to be this type.

  • graph_parents – (Deprecated) 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.

  • parameters – Python dict of parameters used to instantiate this LinearOperator.

Raises

  • ValueError – If any member of graph_parents is None or not a Tensor.

  • ValueError – If hints are set incorrectly.