Skip to content

dsdbsparse#

Includes the abstract base class for distributed block-accessible sparse matrices.

Classes:

  • BlockConfig –

    Configuration of block-sizes and block-slices for a DSDBSparse matrix.

  • DSDBSparse –

    Base class for Distributed Stack of Distributed Block-accessible

BlockConfig #

BlockConfig(block_sizes: NDArray, block_offsets: NDArray, index_type: int32 | int64, rowptr_map: dict | None = None, block_slice_cache: dict | None = None)

Configuration of block-sizes and block-slices for a DSDBSparse matrix.

Parameters:

  • block_sizes (NDArray) –

    The size of each block in the sparse matrix.

  • block_offsets (NDArray) –

    The block offsets of the block-sparse matrix.

  • index_type (int32 | int64) –

    The index type to use for the sparse matrix. This is relevant for the low level kernels to avoid unnecessary type conversions.

  • rowptr_map (dict, default: None ) –

    A mapping from block-coordinates to row-pointers. Default is None.

  • block_slice_cache (dict, default: None ) –

    A cache for the block slices. Default is None.

DSDBSparse #

DSDBSparse(dtype: dtype[generic], block_sizes: NDArray, nnz: int, local_stack_shape: tuple | int, global_stack_shape: tuple | int, index_type: int32 | int64, symmetry: str | None = None)

Bases: ABC

Base class for Distributed Stack of Distributed Block-accessible Sparse matrices.

Parameters:

  • dtype (dtype[generic]) –

    The data type of the matrix.

  • block_sizes (NDArray) –

    The size of each block in the sparse matrix.

  • nnz (int) –

    The number of non-zero elements in the sparse matrix.

  • local_stack_shape (tuple or int) –

    The local shape of the stack. If this is an integer, it is interpreted as a one-dimensional stack.

  • global_stack_shape (tuple or int) –

    The global shape of the stack. If this is an integer, it is interpreted as a one-dimensional stack.

  • index_type (int32 | int64) –

    The index type to use for the sparse matrix. This is relevant for the low level kernels to avoid unnecessary type conversions.

  • symmetry (str | None, default: None ) –

    The symmetry of the matrix. This can be "symmetric", "hermitian", "skew-symmetric", "skew-hermitian", or None. Default is None.

Methods:

  • __repr__ –

    Returns a string representation of the object.

  • diagonal –

    Returns or sets the diagonal elements of the matrix.

  • fill_diagonal –

    Returns or sets the diagonal elements of the matrix.

  • dtranspose –

    Performs a distributed transposition of the datastructure.

  • spy –

    Returns the row and column indices of the non-zero elements.

  • symmetrize –

    Symmetrizes the matrix with a given symmetry.

  • to_dense –

    Converts the local data to a dense array.

  • free_data –

    Frees the local data.

  • allocate_data –

    Allocates the local data.

  • from_sparray –

    Creates a new DSDBSparse matrix from a scipy.sparse array.

  • empty_like –

    Creates a new DSDBSparse matrix with the same shape and

Attributes:

  • block_sizes (ArrayLike) –

    Returns the global block sizes.

  • block_offsets (ArrayLike) –

    Returns the block sizes.

  • blocks (_DSDBlockIndexer) –

    Returns a block indexer.

  • stack (_DStackView) –

    Returns a stack indexer.

  • data (NDArray) –

    Returns the local slice of the data, masking the padding.

block_sizes property writable #

block_sizes: ArrayLike

Returns the global block sizes.

block_offsets property #

block_offsets: ArrayLike

Returns the block sizes.

blocks property #

blocks: _DSDBlockIndexer

Returns a block indexer.

stack property #

stack: _DStackView

Returns a stack indexer.

data property writable #

data: NDArray

Returns the local slice of the data, masking the padding.

__repr__ #

__repr__() -> str

Returns a string representation of the object.

diagonal #

diagonal(stack_index: tuple = (Ellipsis,)) -> NDArray

Returns or sets the diagonal elements of the matrix.

Note

In the block distributed case, this returns the local diagonal elements.

Parameters:

  • stack_index (tuple, default: (Ellipsis,) ) –

    The index in the stack. Default is (Ellipsis,).

Returns:

  • diagonal ( NDArray ) –

    The diagonal elements of the matrix.

fill_diagonal #

fill_diagonal(val: NDArray, stack_index: tuple = (Ellipsis,)) -> NDArray

Returns or sets the diagonal elements of the matrix.

Parameters:

  • val (NDArray) –

    The value(s) to set along the diagonal.

  • stack_index (tuple, default: (Ellipsis,) ) –

    The index in the stack. Default is (Ellipsis,).

Returns:

  • diagonal ( NDArray ) –

    The diagonal elements of the matrix.

dtranspose #

dtranspose(discard: bool = False) -> None

Performs a distributed transposition of the datastructure.

This is done by reshaping the local data, then performing an in-place Alltoall communication, and finally reshaping the data back to the correct new shape.

The local reshaping of the data cannot be done entirely in-place. This can lead to pronounced memory peaks if all ranks start reshaping concurrently, which can be mitigated by using more ranks and by not forcing a synchronization barrier right before calling dtranspose.

Parameters:

  • discard (bool, default: False ) –

    Whether to perform a "fake" transposition. Default is False. This is useful if you want to get the correct data shape after a transposition, but do not want to perform the actual all-to-all communication.

spy abstractmethod #

spy() -> tuple[NDArray, NDArray]

Returns the row and column indices of the non-zero elements.

This is essentially the same as converting the sparsity pattern to coordinate format. The returned sparsity pattern is not sorted.

Note

In the block distributed case, this returns the local sparsity pattern including the offset.

Returns:

  • rows ( NDArray ) –

    Row indices of the non-zero elements.

  • cols ( NDArray ) –

    Column indices of the non-zero elements.

symmetrize abstractmethod #

symmetrize(symmetry: str) -> None

Symmetrizes the matrix with a given symmetry.

Note

This assumes that the matrix's sparsity pattern is symmetric.

Parameters:

  • symmetry (str) –

    The symmetry to enforce. This can be "symmetric", "hermitian", "skew-symmetric", or "skew-hermitian".

to_dense abstractmethod #

to_dense() -> NDArray

Converts the local data to a dense array.

This is dumb, unless used for testing and debugging.

Returns:

  • arr ( NDArray ) –

    The dense array of shape (*local_stack_shape, *shape).

free_data #

free_data() -> None

Frees the local data.

allocate_data #

allocate_data(stack_size: int | None = None) -> None

Allocates the local data.

Note

This should not be called with a non-None stack size if the data will be dtransposed. The data is not zeroed. It is the user responsibility to ensure that the data is initialized correctly.

Parameters:

  • stack_size (int, default: None ) –

    The size of the stack dimension to allocate. If None, the full stack size is used. Default is None.

from_sparray abstractmethod classmethod #

from_sparray(sparray: spmatrix, block_sizes: NDArray, global_stack_shape: tuple, symmetry: str | None = None, dtype: dtype[generic] = complex128, allocate: bool = True) -> DSDBSparse

Creates a new DSDBSparse matrix from a scipy.sparse array.

This essentially distributed the matrix across the stack and block communicators.

Parameters:

  • sparray (spmatrix) –

    The sparse matrix from which to use the sparsity pattern.

  • block_sizes (NDArray) –

    The block sizes of the block-sparse matrix.

  • global_stack_shape (tuple) –

    The global shape of the stack.

  • symmetry (str | None, default: None ) –

    The symmetry of the matrix. This can be "symmetric", "hermitian", "skew-symmetric", "skew-hermitian", or None. Default is None.

  • dtype (dtype, default: complex128 ) –

    The data type of the matrix. Default is xp.complex128.

  • allocate (bool, default: True ) –

    Whether to allocate the data of the resulting matrix. Default is True.

Returns:

empty_like abstractmethod classmethod #

empty_like(dsdbsparse: DSDBSparse) -> DSDBSparse

Creates a new DSDBSparse matrix with the same shape and dtype.

Note

There is no data allocated in the new matrix. The sparsity pattern is the same as the original matrix.

Parameters:

  • dsdbsparse (DSDBSparse) –

    The matrix to copy the shape and dtype from.

Returns: