brahmap.base.BaseBlockDiagNoiseCovLinearOperator

Bases: BlockDiagonalLinearOperator

Base class for block-diagonal noise covariance operator.

Parameters:

Name	Type	Description	Default
block_list	list[NoiseCovLinearOperator]	A list of linear operators representing the individual diagonal blocks	required
**kwargs	Any	Extra keyword arguments	{}

Attributes:

Name	Type	Description
size	int	An array containing the number of rows/columns for each block
diag	NDArray[number]	An array containing the diagonal of the operator

Methods:

Name	Description
reset_counters	Resets matrix-vector product counter to zero.
dot	Numpy-like dot() method.
matvec	Matrix-vector multiplication method.
to_array	Returns the dense form of the linear operator as a 2D NumPy array.
get_inverse	Returns the inverse block-diagonal covariance operator.

Source code in brahmap/base/noise_ops.py

class BaseBlockDiagNoiseCovLinearOperator(BlockDiagonalLinearOperator):
    """Base class for block-diagonal noise covariance operator.

    Parameters
    ----------
    block_list : List[NoiseCovLinearOperator]
        A list of linear operators representing the individual diagonal blocks
    **kwargs : Any
        Extra keyword arguments

    Attributes
    ----------
    size : int
        An array containing the number of rows/columns for each block
    diag : npt.NDArray[np.number]
        An array containing the diagonal of the operator
    """

    def __init__(
        self,
        block_list: List[NoiseCovLinearOperator],
        **kwargs: Any,
    ):
        super(BaseBlockDiagNoiseCovLinearOperator, self).__init__(
            cast(List[LinearOperator], block_list), **kwargs
        )

        if not self.symmetric:
            raise ValueError("The noise (inv-)covariance operators must be symmetric")

    @property
    def size(self) -> int:
        """Array containing the number of rows/columns for each block

        Returns
        -------
        int
            Array containing the number of rows/columns for each block
        """
        return sum(self.col_size)

    @property
    def diag(self) -> npt.NDArray[np.number]:
        """Array containing the diagonal of the operator

        Returns
        -------
        npt.NDArray[np.number]
            Array containing the diagonal of the operator
        """
        diag = np.concatenate(
            [cast(NoiseCovLinearOperator, block).diag for block in self.block_list],
            axis=None,
        )
        return diag

    def get_inverse(self) -> "BaseBlockDiagInvNoiseCovLinearOperator":
        """Returns the inverse block-diagonal covariance operator.

        Returns
        -------
        BaseBlockDiagInvNoiseCovLinearOperator
            The inverse block-diagonal covariance operator
        """
        inverse_list = [
            cast(NoiseCovLinearOperator, block).get_inverse()
            for block in self.block_list
        ]
        return BaseBlockDiagInvNoiseCovLinearOperator(
            block_list=inverse_list,
        )

Attributes

dtype: npt.DTypeLike property writable

The data type of the operator.

Returns:

Type	Description
DTypeLike	The NumPy data type of the operator

nargin: int property

Size of the input vector \(x\), i.e. the number of columns of the operator

Returns:

Type	Description
int	The number of input columns

nargout: int property

Size of the output vector \(A(x)\), i.e. the number of rows of the operator

Returns:

Type	Description
int	The number of output rows

symmetric: bool property

Indicates whether the operator is symmetric or not

Returns:

Type	Description
bool	True if symmetric, False otherwise

shape: Tuple[int, int] property

A tuple (nargout, nargin) representing the shape of the operator

Returns:

Type	Description
tuple[int, int]	A tuple (nrows, ncols)

nMatvec: int property

The number of matrix-vector multiplications computed so far

Returns:

Type	Description
int	The number of matrix-vector multiplications performed

T: LinearOperator property

The transpose operator

Returns:

Type	Description
LinearOperator	The transpose of this linear operator

H: LinearOperator property

The adjoint operator

Returns:

Type	Description
LinearOperator	The Hermitian adjoint of this linear operator

block_list: List[LinearOperator] property

A list of linear operators representing the individual diagonal blocks.

Returns:

Type	Description
list[LinearOperator]	A list of linear operators representing the individual diagonal blocks

num_blocks: int property

The total number of diagonal blocks in the operator.

Returns:

Type	Description
int	The total number of diagonal blocks in the operator

row_size: npt.NDArray[np.integer] property

Array containing the number of rows for each block.

Returns:

Type	Description
NDArray[integer]	Array containing the number of rows for each block

col_size: npt.NDArray[np.integer] property

Array containing the number of columns for each block.

Returns:

Type	Description
NDArray[integer]	Array containing the number of columns for each block

size: int property

Array containing the number of rows/columns for each block

Returns:

Type	Description
int	Array containing the number of rows/columns for each block

diag: npt.NDArray[np.number] property

Array containing the diagonal of the operator

Returns:

Type	Description
NDArray[number]	Array containing the diagonal of the operator

Functions

reset_counters() -> None

Resets matrix-vector product counter to zero.

Source code in brahmap/base/linop.py

def reset_counters(self) -> None:
    """Resets matrix-vector product counter to zero."""
    self._nMatvec = 0

dot(x) -> npt.NDArray[np.number]

Numpy-like dot() method.

Parameters:

Name	Type	Description	Default
x	Any	The input vector or object to multiply with.	required

Returns:

Type	Description
NDArray[number]	The result of the dot product.

Source code in brahmap/base/linop.py

def dot(self, x) -> npt.NDArray[np.number]:
    """Numpy-like dot() method.

    Parameters
    ----------
    x : Any
        The input vector or object to multiply with.
    Returns
    -------
    npt.NDArray[np.number]
        The result of the dot product.
    """
    return self.__mul__(x)

matvec(x) -> npt.NDArray[np.number]

Matrix-vector multiplication method.

The matvec method encapsulates the matvec routine specified at construct time, to ensure the consistency of the input and output arrays with the operator's shape.

Parameters:

Name	Type	Description	Default
x	NDArray[number]	The input vector \(x\) to be multiplied by the operator	required

Returns:

Type	Description
NDArray[number]	The result of the matrix-vector multiplication \(A(x)\)

Source code in brahmap/base/linop.py

def matvec(self, x) -> npt.NDArray[np.number]:
    """
    Matrix-vector multiplication method.

    The `matvec` method encapsulates the `matvec`
    routine specified at construct time, to ensure the
    consistency of the input and output arrays with the
    operator's shape.

    Parameters
    ----------
    x : npt.NDArray[np.number]
        The input vector $x$ to be multiplied by the operator

    Returns
    -------
    npt.NDArray[np.number]
        The result of the matrix-vector multiplication $A(x)$
    """
    x = np.asanyarray(x, dtype=self.dtype)
    M, N = self.shape

    # check input data consistency
    N = int(N)
    try:
        x = x.reshape(N)
    except ValueError:
        msg = (
            f"The size of the input array is incompatible with the "
            f"dimensions required by the operator\n"
            f"size of the input array: {x.size}\n"
            f"shape of the operator: {self.shape}"
        )
        msg = f"{self.__class__.__name__}: " + msg
        raise ValueError(msg)

    y = self.__matvec(x)

    # check output data consistency
    M = int(M)
    try:
        y = y.reshape(M)
    except ValueError:
        msg = (
            f"The size of the output array is incompatible with the "
            f"dimensions required by the operator\n"
            f"size of the output array: {y.size}\n"
            f"shape of the operator: {self.shape}"
        )
        msg = f"{self.__class__.__name__}: " + msg
        raise ValueError(msg)

    return y

to_array() -> npt.NDArray[np.number]

Returns the dense form of the linear operator as a 2D NumPy array.

Warning

This method first allocates a NumPy array of shape self.shape and data-type self.dtype, and then fills them with numbers. As such, for a large linear operator, it can occupy an enormous amount of memory and crash your system. Don't use it unless you understand the risk!

Returns:

Type	Description
NDArray[number]	The dense 2D array representation of the linear operator

Source code in brahmap/base/linop.py

def to_array(self) -> npt.NDArray[np.number]:
    """Returns the dense form of the linear operator as a 2D NumPy array.

    !!! Warning

        This method first allocates a NumPy array of shape `self.shape`
        and data-type `self.dtype`, and then fills them with numbers. As
        such, for a large linear operator, it can occupy an enormous
        amount of memory and crash your system. Don't use it unless you
        understand the risk!

    Returns
    -------
    npt.NDArray[np.number]
        The dense 2D array representation of the linear operator
    """
    n, m = self.shape
    H = np.empty((n, m), dtype=self.dtype)
    ej = np.zeros(m, dtype=self.dtype)
    for j in range(m):
        ej[j] = 1.0
        H[:, j] = self * ej
        ej[j] = 0.0
    return H

get_inverse() -> BaseBlockDiagInvNoiseCovLinearOperator

Returns the inverse block-diagonal covariance operator.

Returns:

Type	Description
BaseBlockDiagInvNoiseCovLinearOperator	The inverse block-diagonal covariance operator

Source code in brahmap/base/noise_ops.py

def get_inverse(self) -> "BaseBlockDiagInvNoiseCovLinearOperator":
    """Returns the inverse block-diagonal covariance operator.

    Returns
    -------
    BaseBlockDiagInvNoiseCovLinearOperator
        The inverse block-diagonal covariance operator
    """
    inverse_list = [
        cast(NoiseCovLinearOperator, block).get_inverse()
        for block in self.block_list
    ]
    return BaseBlockDiagInvNoiseCovLinearOperator(
        block_list=inverse_list,
    )