API Reference

abstract type AbstractBlockMatrix{T} <: LinearMap{T}

Abstract type representing a block matrix with element type T. The block matrix is composed of a small number of smaller matrix blocks, allowing for efficient storage and computation.

Notes

• The AbstractBlockMatrix type serves as a base for concrete block matrix implementations, providing a common interface for linear algebra operations.

struct BlockSparseMatrix{T,M,P,S} <: AbstractBlockMatrix{T}

A concrete implementation of a block sparse matrix, which is a sparse matrix composed of smaller dense matrix blocks.

Type Parameters

• T: The element type of the matrix.
• M: The type of the matrix blocks.
• P: The integer type used for indexing.
• S: The type of the scheduler.

Fields

• blocks: A vector of matrix blocks that comprise the block sparse matrix.
• rowindices: A vector where each element is a vector of row indices for the corresponding block.
• colindices: A vector where each element is a vector of column indices for the corresponding block.
• size: A tuple representing the size of the block sparse matrix.
• colors: A vector of colors, where each color is a vector of block indices that can be processed in parallel without race conditions.
• transposecolors: A vector of colors for the transpose matrix, where each color is a vector of block indices that can be processed in parallel without race conditions.
• scheduler: A scheduler that manages the parallel computation of matrix-vector products.

BlockSparseMatrix(
    blocks,
    rowindices,
    colindices,
    size::Tuple{Int,Int};
    coloringalgorithm=coloringalgorithm,
    scheduler=SerialScheduler(),
)

Constructs a new BlockSparseMatrix instance from the given blocks, their indices, and size.

Arguments

• blocks: A vector of matrices representing the blocks.
• rowindices: A vector where each element is a vector of row indices for the corresponding block.
• colindices: A vector where each element is a vector of column indices for the corresponding block.
• size: A tuple representing the size of the block sparse matrix.
• coloringalgorithm: The algorithm from GraphsColoring.jl used to color the blocks for parallel computation. Defaults to coloringalgorithm.
• scheduler: The scheduler used to manage parallel computation. Defaults to SerialScheduler().

Returns

• A new BlockSparseMatrix instance constructed from the given blocks and size.

struct ColorInfo{R}

A wrapper struct that holds conflict indices information used for graph coloring.

Type Parameters

• R: The type of the conflict indices container.

Fields

• conflictindices: A collection of indices that represent potential conflicts between blocks. Used to determine which blocks can be processed in parallel without race conditions.

struct SymmetricBlockMatrix{T,D,P,M,S} <: AbstractBlockMatrix{T}

A concrete implementation of a symmetric block matrix, which is a block matrix where the off-diagonal blocks are shared between the upper and lower triangular parts. The diagonal blocks are symmetric as well.

Type Parameters

• T: The element type of the matrix.
• D: The type of the diagonal matrix blocks.
• P: The integer type used for indexing.
• M: The type of the off-diagonal matrix blocks.
• S: The type of the scheduler.

Fields

• diagonals: A vector of diagonal matrix blocks.
• diagonalindices: A vector where each element is a vector of indices for the corresponding diagonal block.
• offdiagonals: A vector of off-diagonal matrix blocks.
• rowindices: A vector where each element is a vector of row indices for the corresponding off-diagonal block.
• colindices: A vector where each element is a vector of column indices for the corresponding off-diagonal block.
• size: A tuple representing the size of the symmetric block matrix.
• diagonalcolors: A vector of colors for the diagonal blocks, where each color is a vector of block indices that can be processed in parallel without race conditions.
• offdiagonalcolors: A vector of colors for the off-diagonal blocks, where each color is a vector of block indices that can be processed in parallel without race conditions.
• transposeoffdiagonalcolors: A vector of colors for the transposed off-diagonal blocks, where each color is a vector of block indices that can be processed in parallel without race conditions.
• scheduler: A scheduler that manages the parallel computation of matrix-vector products.

SymmetricBlockMatrix(
    diagonals,
    diagonalindices,
    offdiagonals,
    rowindices,
    colindices,
    size::Tuple{Int,Int};
    scheduler=DynamicScheduler(),
)

Constructs a new SymmetricBlockMatrix instance from the given diagonal and off-diagonal blocks with their indices.

Arguments

• diagonals: A vector of diagonal matrix blocks.
• diagonalindices: A vector where each element is a vector of indices for the corresponding diagonal block.
• offdiagonals: A vector of off-diagonal matrix blocks.
• rowindices: A vector where each element is a vector of row indices for the corresponding off-diagonal block.
• colindices: A vector where each element is a vector of column indices for the corresponding off-diagonal block.
• size: A tuple representing the size of the symmetric block matrix.
• scheduler: The scheduler used to manage parallel computation. Defaults to DynamicScheduler().

Returns

• A new SymmetricBlockMatrix instance constructed from the given blocks and indices.

struct VariableBlockCompressedRowStorage{T,M,P,S} <: AbstractBlockMatrix{T}

A compressed row storage format for block sparse matrices with variable-sized blocks. This format stores blocks in row-major order, enabling efficient matrix-vector products and parallel computation.

Type Parameters

• T: The element type of the matrix.
• M: The type of the matrix blocks.
• P: The integer type used for indexing.
• S: The type of the scheduler.

Fields

• blocks: A vector of matrix blocks stored in row-major order.
• rowptr: A vector of pointers indicating the start of each block row in the blocks vector. Similar to CSR format, rowptr[i] points to the first block of the i-th block row.
• colindices: A vector where each element is the starting column index of the corresponding block. The indices for each block must be contiguous (e.g., if a block starts at column 5 and has 3 columns, it occupies columns 5, 6, and 7).
• rowindices: A vector where each element is the starting row index of the corresponding block. The indices for each block must be contiguous (e.g., if a block starts at row 10 and has 4 rows, it occupies rows 10, 11, 12, and 13).
• size: A tuple representing the total size of the matrix.
• scheduler: A scheduler that manages the parallel computation of matrix-vector products.

Notes

• Blocks are sorted by row index first, then by column index within each row.
• The compressed row storage format allows efficient parallel computation across block rows.
• This format is particularly efficient for matrix-vector products and can handle variable-sized blocks.
• Each block must occupy a contiguous range of row and column indices.

VariableBlockCompressedRowStorage(
    matrices,
    rowindices,
    colindices,
    matrixsize::Tuple{Int,Int};
    scheduler = SerialScheduler()
)

Constructs a VariableBlockCompressedRowStorage from vectors of matrices and their corresponding row and column indices. The blocks are automatically sorted by row index first, then by column index, and stored in compressed row storage format.

Arguments

• matrices: A vector of matrices representing the blocks.
• rowindices: A vector where each element is the starting row index of the corresponding block. Each block must occupy contiguous row indices starting from this value.
• colindices: A vector where each element is the starting column index of the corresponding block. Each block must occupy contiguous column indices starting from this value.
• matrixsize: The total size of the matrix as a tuple (nrows, ncols).
• scheduler: A scheduler for parallel computation. Defaults to SerialScheduler().

Returns

• A VariableBlockCompressedRowStorage instance with compressed row storage format.

Notes

• Blocks do not need to be provided in sorted order; they will be sorted internally.
• The row and column indices for each block must be contiguous.
• Blocks with the same row index are grouped together in the compressed format.

VariableBlockCompressedRowStorage(
    bsm::BlockSparseMatrix;
    scheduler=bsm.scheduler
)

Converts a BlockSparseMatrix to VariableBlockCompressedRowStorage format.

Arguments

• bsm: A BlockSparseMatrix to convert.
• scheduler: A scheduler for parallel computation. Defaults to the scheduler from bsm.

Returns

• A VariableBlockCompressedRowStorage instance in compressed row storage format.

Notes

• No sanity checks are performed on the input matrix. It is assumed that the blocks in the BlockSparseMatrix have contiguous row and column indices.
• The conversion uses lazy functors to avoid unnecessary memory allocations during construction.

VariableBlockCompressedRowStorage(
    sbm::SymmetricBlockMatrix;
    scheduler=sbm.scheduler
)

Converts a SymmetricBlockMatrix to VariableBlockCompressedRowStorage format. The symmetric structure is expanded by including both the diagonal blocks, off-diagonal blocks, and their transposes explicitly.

Arguments

• sbm: A SymmetricBlockMatrix to convert.
• scheduler: A scheduler for parallel computation. Defaults to the scheduler from sbm.

Returns

• A VariableBlockCompressedRowStorage instance in compressed row storage format.

Notes

• No sanity checks are performed on the input matrix. It is assumed that the blocks in the SymmetricBlockMatrix have contiguous row and column indices.
• The conversion expands the symmetric structure: diagonal blocks are included once, while off-diagonal blocks are included twice (once as-is and once transposed).
• The conversion uses lazy functors to avoid unnecessary memory allocations during construction.

block(A::BlockSparseMatrix, i)

Returns the i-th block of the given BlockSparseMatrix instance.

Arguments

• A: The BlockSparseMatrix instance to query.
• i: The index of the block to retrieve.

Returns

• The i-th block of the BlockSparseMatrix.

colors(A::BlockSparseMatrix)

Returns the colors used for multithreading in matrix-vector for the given BlockSparseMatrix. These colors are created using GraphsColoring.jl and represent a partitioning of the blocks into sets that can be processed in parallel without race conditions.

Arguments

• A: The BlockSparseMatrix instance to query.

Returns

• A collection of colors, where each color is a vector of block indices that can be processed in parallel.

diagonal(A::SymmetricBlockMatrix, i)

Returns the i-th diagonal block of the given SymmetricBlockMatrix instance.

Arguments

• A: The SymmetricBlockMatrix instance to query.
• i: The index of the diagonal block to retrieve.

Returns

• The i-th diagonal block of the SymmetricBlockMatrix.

diagonalcolors(A::SymmetricBlockMatrix)

Returns the colors used for the diagonal blocks of the given SymmetricBlockMatrix instance. These colors are used to coordinate parallel computation and avoid race conditions.

Arguments

• A: The SymmetricBlockMatrix instance to query.

Returns

• A vector of colors, where each color is a vector of diagonal block indices that can be processed in parallel without race conditions.

eachblockindex(A::BlockSparseMatrix)

Returns an iterator over the indices of the blocks in the given BlockSparseMatrix instance.

Arguments

• A: The BlockSparseMatrix instance to query.

Returns

• An iterator that yields the indices of the blocks in the BlockSparseMatrix.

eachdiagonalindex(A::SymmetricBlockMatrix)

Returns an iterator over the indices of the diagonal blocks in the given SymmetricBlockMatrix instance.

Arguments

• A: The SymmetricBlockMatrix instance to query.

Returns

• An iterator that yields the indices of the diagonal blocks in the SymmetricBlockMatrix.

eachoffdiagonalindex(A::SymmetricBlockMatrix)

Returns an iterator over the indices of the off-diagonal blocks in the given SymmetricBlockMatrix instance.

Arguments

• A: The SymmetricBlockMatrix instance to query.

Returns

• An iterator that yields the indices of the off-diagonal blocks in the SymmetricBlockMatrix.

offdiagonal(A::SymmetricBlockMatrix, i)

Returns the i-th off-diagonal block of the given SymmetricBlockMatrix instance.

Arguments

• A: The SymmetricBlockMatrix instance to query.
• i: The index of the off-diagonal block to retrieve.

Returns

• The i-th off-diagonal block of the SymmetricBlockMatrix.

offdiagonalcolors(A::SymmetricBlockMatrix)

Returns the colors used for the off-diagonal blocks of the given SymmetricBlockMatrix instance. These colors are used to coordinate parallel computation and avoid race conditions.

Arguments

• A: The SymmetricBlockMatrix instance to query.

Returns

• A vector of colors, where each color is a vector of off-diagonal block indices that can be processed in parallel without race conditions.

rowcolvals(A)

Extracts the row, column, and value indices from a block-sparse matrix A such that a sparse matrix can be constructed.

Arguments

• A: A block-sparse matrix.

Returns

• rows: An array of row indices.
• cols: An array of column indices.
• vals: An array of values.

scheduler(A::AbstractBlockMatrix)

Returns the scheduler associated with the given AbstractBlockMatrix instance. This scheduler is responsible for managing the parallel computation of matrix-vector products.

Returns

• The scheduler associated with the matrix.

Notes

• The scheduler is used to coordinate the computation of matrix-vector product.

transposecolors(A::BlockSparseMatrix)

Returns the colors used for multithreading in the transposed matrix-vector product computations for the given BlockSparseMatrix. These colors are created using GraphsColoring.jl and represent a partitioning of the blocks into sets that can be processed in parallel without race conditions.

Arguments

• A: The BlockSparseMatrix instance to query.

Returns

• A collection of colors, where each color is a vector of block indices that can be processed in parallel.

transposeoffdiagonalcolors(A::SymmetricBlockMatrix)

Returns the colors used for the transposed off-diagonal blocks of the given SymmetricBlockMatrix instance. These colors are used to coordinate parallel computation and avoid race conditions when computing the transpose of the matrix.

Arguments

• A: The SymmetricBlockMatrix instance to query.

Returns

• A vector of colors, where each color is a vector of transposed off-diagonal block indices that can be processed in parallel without race conditions.

conflicts(blocks::ColorInfo)

Computes the conflicts between blocks for the purpose of graph coloring using GraphsColoring.jl. This function is used to determine the coloring of blocks for multithreading in the matrix-vector product, ensuring that blocks with no conflicts can be processed in parallel.

Arguments

• blocks: A ColorInfo object containing the conflict indices information.

Returns

• A tuple containing:

  • An iterator over block indices
  • A ConflictFunctor wrapping the computed conflict indices
  • A range representing the maximum conflict index

Notes

• Blocks with no conflicts (i.e., blocks that do not overlap in their conflict indices) can be processed in parallel.
• The colors are used to group blocks into sets that can be processed in parallel, avoiding race conditions and ensuring efficient multithreading in the matrix-vector product.