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.

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

Abstract type representing a matrix block with element type T. This type inherits from LinearMap{T}, indicating that matrix-vector products can be performed with instances of this type, even when considering a single block in isolation. The dimensions of the vectors involved in the matrix-vector product are the same as the dimensions of the block.

Additionally, transpose and adjoint operations are also supported.

Notes

• The matrix-vector product operation is well-defined for a single block.
• Both transpose and adjoint operations are available.

struct BlockSparseMatrix{T,M,D,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.
• D: The type of the row and column index dictionaries.
• S: The type of the scheduler.

Fields

• blocks: A vector of matrix blocks that comprise the block sparse matrix.
• size: A tuple representing the size of the block sparse matrix.
• forwardbuffer: A buffer used for forward matrix-vector product computations.
• adjointbuffer: A buffer used for adjoint matrix-vector product computations.
• buffer: The underlying buffer that is reused for both forward and adjoint products.
• rowindexdict: A dictionary that maps row indices to block indices.
• colindexdict: A dictionary that maps column indices to block indices.
• 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::Vector{M},
    size::Tuple{Int,Int};
    coloringalgorithm=coloringalgorithm,
    scheduler=SerialScheduler(),
) where {M<:AbstractMatrixBlock}

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

Arguments

• blocks: A vector of AbstractMatrixBlock instances.
• 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.

BlockSparseMatrix(
    blocks::Vector{M},
    rowindices::V,
    colindices::V,
    size::Tuple{Int,Int};
    coloringalgorithm=coloringalgorithm,
    scheduler=DynamicScheduler(),
) where {M,V}

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

Arguments

• blocks: A vector of dense matrices.
• rowindices: A vector of row indices corresponding to each block.
• colindices: A vector of column indices corresponding to each 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, row indices, column indices, and size.

struct DenseMatrixBlock{T,M,RC} <: AbstractMatrixBlock{T}

A concrete implementation of an AbstractMatrixBlock representing a dense matrix block. This struct stores the actual matrix data, as well as the global row and column indices of the block in the sparse block matrix.

Type Parameters

• T: The element type of the matrix block.
• M: The type of the matrix storage.
• RC: The type of the row and column index collections.

Fields

• matrix: The dense matrix stored in the block.
• rowindices: The global row indices of the block in the sparse block matrix.
• colindices: The global column indices of the block in the sparse block matrix.

DenseMatrixBlock(matrix::M, rowindices::RC, colindices::RC) where {M,RC<:Vector{Int}}

Constructs a new DenseMatrixBlock instance from the given matrix, row indices, and column indices.

Arguments

• matrix: The dense matrix to be stored in the block.
• rowindices: The global row indices of the block in the sparse block matrix.
• colindices: The global column indices of the block in the sparse block matrix.

Type Parameters

• M: The type of the matrix storage.
• RC: The type of the row and column index collections, which must be a Vector{Int}.

Returns

• A new DenseMatrixBlock instance with the specified matrix, row indices, and column indices.

Notes

• The element type of the DenseMatrixBlock instance is inferred from the element type of the input matrix.

struct SymmetricBlockMatrix{T,DM,M,D,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.
• DM: The type of the diagonal matrix blocks.
• M: The type of the off-diagonal matrix blocks.
• D: The type of the row and column index dictionaries.
• S: The type of the scheduler.

Fields

• diagonals: A vector of diagonal matrix blocks.
• offdiagonals: A vector of off-diagonal matrix blocks.
• size: A tuple representing the size of the symmetric block matrix.
• forwardbuffer: A buffer used for forward matrix-vector product computations.
• adjointbuffer: A buffer used for adjoint matrix-vector product computations.
• buffer: The underlying buffer that is reused for both forward and adjoint products.
• diagonalsrowindexdict: A dictionary that maps row indices to diagonal block indices.
• diagonalscolindexdict: A dictionary that maps column indices to diagonal block indices.
• offdiagonalsrowindexdict: A dictionary that maps row indices to off-diagonal block indices.
• offdiagonalscolindexdict: A dictionary that maps column indices to off-diagonal block indices.
• 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::Vector{DM},
    offdiagonals::Vector{M},
    size::Tuple{Int,Int};
    scheduler=DynamicScheduler(),
) where {DM<:AbstractMatrixBlock,M<:AbstractMatrixBlock}

Constructs a new SymmetricBlockMatrix instance from the given diagonal and off-diagonal blocks, and size.

Arguments

• diagonals: A vector of AbstractMatrixBlock instances.
• offdiagonals: A vector of AbstractMatrixBlock instances.
• 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 size.

SymmetricBlockMatrix(
    diagonals::Vector{DM},
    diagonalindices::V,
    offdiagonals::Vector{M},
    rowindices::V,
    columnindices::V,
    size::Tuple{Int,Int};
    scheduler=DynamicScheduler(),
) where {DM,M,V}

Constructs a new SymmetricBlockMatrix instance from the given diagonal and off-diagonal blocks, indices, and size.

Arguments

• diagonals: A vector of symmetric dense matrices.
• diagonalindices: A vector of indices corresponding to the diagonal blocks.
• offdiagonals: A vector of dense matrices.
• rowindices: A vector of row indices corresponding to the off-diagonal blocks.
• columnindices: A vector of column indices corresponding to the off-diagonal blocks.
• 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, indices, and size.

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.

buffer(A::AbstractBlockMatrix)

Returns the buffer associated with the given AbstractBlockMatrix instance for the matrix-vector product.

buffers(::Type{T}, rows, cols) where {T}

Allocates and returns a set of buffers for efficient matrix-vector product computations. The buffers are designed to minimize memory allocation and copying, reducing computational overhead.

Arguments

• T: The element type of the buffers.
• rows: The number of rows in the matrix.
• cols: The number of columns in the matrix.

Returns

• A tuple containing:

  • forwardbuffer: A view of the buffer for forward matrix-vector products, with length rows.
  • adjointbuffer: A view of the buffer for adjoint matrix-vector products, with length cols.
  • buffer: The underlying buffer, which is reused for both forward and adjoint products.

Notes

• The buffer is allocated with a length equal to the maximum of rows and cols, ensuring sufficient storage for both forward and adjoint products.
• The forwardbuffer and adjointbuffer views are created using unsafe_wrap, which means that they overlap and share the same memory.

colblockids(A::AbstractBlockMatrix, j::Integer)

Returns the indices of the blocks in the AbstractBlockMatrix instance that contain the given column index j.

Arguments

• A: The AbstractBlockMatrix instance to query.
• j: The column index to search for.

Returns

• A collection of block indices that contain the column index j.

colindices(block::AbstractMatrixBlock)

Returns the global column indices of the matrix block in the sparse block matrix.

Notes

• The returned indices are global indices in the sparse block matrix, not local indices inside the block.

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.

conflictindices(block::AbstractMatrixBlock; transpose=false)

Returns the conflict indices for a given AbstractMatrixBlock object. These indices represent the memory locations that are accessed by the block during a matrix-vector product.

Arguments

• block: The AbstractMatrixBlock object for which to compute the conflict indices.
• transpose: A boolean flag indicating whether to consider the transpose of the block. Defaults to false.

Returns

• A collection of indices representing the memory locations that are accessed by the block.

Notes

• If transpose is false, the function returns the row indices of the block, as these correspond to the memory locations accessed during a standard matrix-vector product.
• If transpose is true, the function returns the column indices of the block, as these correspond to the memory locations accessed during a transposed (and adjoint) matrix-vector product.

denseblocks(blocks::Vector{M}, rowindices::V, colindices::V) where {M,V}

Constructs a vector of DenseMatrixBlock instances from the given blocks, row indices, and column indices.

Arguments

• blocks: A vector of matrix blocks.
• rowindices: A vector of global row indices corresponding to each block.
• colindices: A vector of global column indices corresponding to each block.

Type Parameters

• M: The type of the matrix blocks.
• V: The type of the row and column index vectors.

Returns

• A vector of DenseMatrixBlock instances, where each instance corresponds to a block in the input blocks vector.

Notes

• The element type of the DenseMatrixBlock instances is inferred from the element type of the input blocks.
• The rowindices and colindices vectors are assumed to have the same length as the blocks vector.

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.

diagonalcolindices(A::SymmetricBlockMatrix, j::Integer)

Returns the indices of the diagonal blocks in the given SymmetricBlockMatrix instance that contain the column index j.

Arguments

• A: The SymmetricBlockMatrix instance to query.
• j: The column index to search for.

Returns

• A vector of indices of the diagonal blocks that contain the column index j. If no such blocks exist, an empty vector is returned.

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.

diagonalrowindices(A::SymmetricBlockMatrix, i::Integer)

Returns the indices of the diagonal blocks in the given SymmetricBlockMatrix instance that contain the row index i.

Arguments

• A: The SymmetricBlockMatrix instance to query.
• i: The row index to search for.

Returns

• A vector of indices of the diagonal blocks that contain the row index i. If no such blocks exist, an empty vector is returned.

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.

islessinordering(blocka::AbstractMatrixBlock, blockb::AbstractMatrixBlock)

Defines a sorting rule for AbstractMatrixBlock objects. This function determines the order of two blocks based on their row and column indices.

Returns

• true if blocka is considered less than blockb according to the sorting rule, false otherwise.

Sorting Rule

• Blocks are first compared based on the maximum row index. If the maximum row index of blocka is less than that of blockb, blocka is considered less than blockb.
• If the maximum row indices are equal, the blocks are compared based on the maximum column index. If the maximum column index of blocka is less than that of blockb, blocka is considered less than blockb.

matrix(block::AbstractMatrixBlock)

Returns the content of the matrix block.

Returns

• matrix: The actual matrix stored in the block.

Notes

• This function provides direct access to the matrix data, allowing for further manipulation.

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.

offdiagonalrowindices(A::SymmetricBlockMatrix, i::Integer)

Returns the indices of the off-diagonal blocks in the given SymmetricBlockMatrix instance that contain the row index i.

Arguments

• A: The SymmetricBlockMatrix instance to query.
• i: The row index to search for.

Returns

• A vector of indices of the off-diagonal blocks that contain the row index i. If no such blocks exist, an empty vector is returned.

rowblockids(A::AbstractBlockMatrix, i::Integer)

Returns the indices of the blocks in the AbstractBlockMatrix instance that contain the given row index i.

Arguments

• A: The AbstractBlockMatrix instance to query.
• i: The row index to search for.

Returns

• A collection of block indices that contain the row index i.

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.

rowindices(block::AbstractMatrixBlock)

Returns the global row indices of the matrix block in the sparse block matrix.

Notes

• The returned indices are global indices in the sparse block matrix, not local indices inside the block.

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.

colors(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::Vector{A}; kwargs...) where {A<:AbstractMatrixBlock}

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 vector of AbstractMatrixBlock objects.
• kwargs...: Additional keyword arguments passed to the conflictindices function.

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.