brahmap.base.NoiseCovLinearOperator

Bases: LinearOperator

Base class for noise covariance operators

Parameters:

Name	Type	Description	Default
nargin	int	The number of rows/columns of the operator	required
matvec	Callable	A function that defines the matrix-vector product \(x \mapsto N(x)=Nx\)	required
input_type	Literal['covariance', 'power_spectrum']	Specifies whether the input is a covariance array or a power spectrum array, by default "covariance"	'covariance'
dtype	DTypeFloat	The data type of the operator, by default np.float64	float64
**kwargs	Any	Extra keyword arguments	{}

Attributes:

Name	Type	Description
size	int	The dimension i.e. the number of rows/columns of the operator
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 of the operator.

Source code in brahmap/base/noise_ops.py

class NoiseCovLinearOperator(LinearOperator):
    """Base class for noise covariance operators

    Parameters
    ----------
    nargin : int
        The number of rows/columns of the operator
    matvec : Callable
        A function that defines the matrix-vector product $x \\mapsto N(x)=Nx$
    input_type : Literal['covariance', 'power_spectrum'], optional
        Specifies whether the input is a covariance array or a power spectrum array,
         by default `"covariance"`
    dtype : DTypeFloat, optional
        The data type of the operator, by default `np.float64`
    **kwargs : Any
        Extra keyword arguments

    Attributes
    ----------
    size : int
        The dimension i.e. the number of rows/columns of the operator
    diag : npt.NDArray[np.number]
        An array containing the diagonal of the operator
    """

    def __init__(
        self,
        nargin: int,
        matvec: Callable,
        input_type: Literal["covariance", "power_spectrum"] = "covariance",
        dtype: DTypeFloat = np.float64,
        **kwargs: Any,
    ) -> None:
        if input_type not in ["covariance", "power_spectrum"]:
            raise ValueError(
                "Please provide only one of `covariance` or `power_spectrum`"
            )

        self.__size = nargin

        super(NoiseCovLinearOperator, self).__init__(
            nargin=nargin,
            nargout=nargin,
            matvec=matvec,
            symmetric=True,
            dtype=dtype,
            **kwargs,
        )

    @property
    def size(self) -> int:
        """The dimension i.e. the number of rows/columns of the operator

        Returns
        -------
        int
            The size of the operator
        """
        return self.__size

    @property
    def diag(self) -> npt.NDArray[np.number]:  # type: ignore
        """The diagonal of the operator.

        Returns
        -------
        npt.NDArray[np.number]
            An array containing the diagonal of the operator
        """
        raise NotImplementedError("Please subclass to implement `diag`")

    def get_inverse(self) -> "InvNoiseCovLinearOperator":  # type: ignore
        """Returns the inverse of the operator.

        Returns
        -------
        InvNoiseCovLinearOperator
            The inverse noise covariance operator
        """
        raise NotImplementedError("Please subclass to implement `get_inverse()`")

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

size: int property

The dimension i.e. the number of rows/columns of the operator

Returns:

Type	Description
int	The size of the operator

diag: npt.NDArray[np.number] property

The diagonal of the operator.

Returns:

Type	Description
NDArray[number]	An 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() -> InvNoiseCovLinearOperator

Returns the inverse of the operator.

Returns:

Type	Description
InvNoiseCovLinearOperator	The inverse noise covariance operator

Source code in brahmap/base/noise_ops.py

def get_inverse(self) -> "InvNoiseCovLinearOperator":  # type: ignore
    """Returns the inverse of the operator.

    Returns
    -------
    InvNoiseCovLinearOperator
        The inverse noise covariance operator
    """
    raise NotImplementedError("Please subclass to implement `get_inverse()`")