Public Documentation

Documentation for BlockArrays.jl's public interface.

See Internal Documentation for internal package docs covering all submodules.

Contents

Index

AbstractBlockArray interface

This sections defines the functions a subtype of AbstractBlockArray should define to be a part of the AbstractBlockArray interface. An AbstractBlockArray{T, N} is a subtype of AbstractArray{T,N} and should therefore also fulfill the AbstractArray interface.

BlockArrays.AbstractBlockArrayType
abstract AbstractBlockArray{T, N} <: AbstractArray{T, N}

The abstract type that represents a blocked array. Types that implement the AbstractBlockArray interface should subtype from this type.

** Typealiases **

  • AbstractBlockMatrix{T} -> AbstractBlockArray{T, 2}

  • AbstractBlockVector{T} -> AbstractBlockArray{T, 1}

  • AbstractBlockVecOrMat{T} -> Union{AbstractBlockMatrix{T}, AbstractBlockVector{T}}

BlockArrays.BlockBoundsErrorType
BlockBoundsError([A], [inds...])

Thrown when a block indexing operation into a block array, A, tried to access an out-of-bounds block, inds.

BlockArrays.BlockType
Block(inds...)

A Block is simply a wrapper around a set of indices or enums so that it can be used to dispatch on. By indexing a AbstractBlockArray with a Block the a block at that block index will be returned instead of a single element.

julia> A = BlockArray(ones(2,3), [1, 1], [2, 1])
2×2-blocked 2×3 BlockMatrix{Float64}:
 1.0  1.0  │  1.0
 ──────────┼─────
 1.0  1.0  │  1.0

julia> A[Block(1, 1)]
1×2 Matrix{Float64}:
 1.0  1.0
BlockArrays.BlockIndexType
BlockIndex{N}

A BlockIndex is an index which stores a global index in two parts: the block and the offset index into the block.

It can be used to index into BlockArrays in the following manner:

julia> arr = Array(reshape(1:25, (5,5)));

julia> a = PseudoBlockArray(arr, [3,2], [1,4])
2×2-blocked 5×5 PseudoBlockMatrix{Int64}:
 1  │   6  11  16  21
 2  │   7  12  17  22
 3  │   8  13  18  23
 ───┼────────────────
 4  │   9  14  19  24
 5  │  10  15  20  25

julia> a[BlockIndex((1,2), (1,2))]
11

julia> a[BlockIndex((2,2), (2,3))]
20
BlockArrays.blockaxesFunction
blockaxes(A)

Return the tuple of valid block indices for array A.

Examples

julia> A = BlockArray([1,2,3],[2,1])
2-blocked 3-element BlockVector{Int64}:
 1
 2
 ─
 3

julia> blockaxes(A)
(BlockRange(Base.OneTo(2)),)

julia> B = BlockArray(zeros(3,4), [1,2], [1,2,1])
2×3-blocked 3×4 BlockMatrix{Float64}:
 0.0  │  0.0  0.0  │  0.0
 ─────┼────────────┼─────
 0.0  │  0.0  0.0  │  0.0
 0.0  │  0.0  0.0  │  0.0

julia> blockaxes(B)
(BlockRange(Base.OneTo(2)), BlockRange(Base.OneTo(3)))
blockaxes(A, d)

Return the valid range of block indices for array A along dimension d.

Examples

julia> A = BlockArray([1,2,3],[2,1])
2-blocked 3-element BlockVector{Int64}:
 1
 2
 ─
 3

julia> blockaxes(A,1)
BlockRange(Base.OneTo(2))

julia> blockaxes(A,1) |> collect
2-element Vector{Block{1, Int64}}:
 Block(1)
 Block(2)
BlockArrays.blockisequalFunction
blockisequal(a::AbstractUnitRange{Int}, b::AbstractUnitRange{Int})

Check if a and b have the same block structure.

Examples

julia> b1 = blockedrange(1:2)
2-blocked 3-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
 1
 ─
 2
 3

julia> b2 = blockedrange([1,1,1])
3-blocked 3-element BlockedUnitRange{Vector{Int64}}:
 1
 ─
 2
 ─
 3

julia> blockisequal(b1, b1)
true

julia> blockisequal(b1, b2)
false
blockisequal(a::Tuple, b::Tuple)

Return all(blockisequal.(a,b))`

BlockArrays.blocksizeFunction
blocksize(A)
blocksize(A,i)

Return the tuple of the number of blocks along each dimension. See also size and blocksizes.

Examples

julia> A = BlockArray(ones(3,3),[2,1],[1,1,1])
2×3-blocked 3×3 BlockMatrix{Float64}:
 1.0  │  1.0  │  1.0
 1.0  │  1.0  │  1.0
 ─────┼───────┼─────
 1.0  │  1.0  │  1.0

julia> blocksize(A)
(2, 3)

julia> blocksize(A,2)
3
BlockArrays.blockfirstsFunction
blockfirsts(a::AbstractUnitRange{Int})

Return the first index of each block of a.

Examples

julia> b = blockedrange(1:3)
3-blocked 6-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
 1
 ─
 2
 3
 ─
 4
 5
 6

julia> blockfirsts(b)
3-element Vector{Int64}:
 1
 2
 4
BlockArrays.blocklastsFunction
blocklasts(a::AbstractUnitRange{Int})

Return the last index of each block of a.

Examples

julia> b = blockedrange(1:3)
3-blocked 6-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
 1
 ─
 2
 3
 ─
 4
 5
 6

julia> blocklasts(b)
3-element ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}:
 1
 3
 6
BlockArrays.blocklengthsFunction
blocklengths(a::AbstractUnitRange{Int})

Return the length of each block of a.

Examples

julia> b = blockedrange(1:3)
3-blocked 6-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
 1
 ─
 2
 3
 ─
 4
 5
 6

julia> blocklengths(b)
3-element Vector{Int64}:
 1
 2
 3
BlockArrays.blocksizesFunction
blocksizes(A)
blocksizes(A,i)

Return the tuple of the sizes of blocks along each dimension. See also size and blocksize.

Examples

julia> A = BlockArray(ones(3,3),[2,1],[1,1,1])
2×3-blocked 3×3 BlockMatrix{Float64}:
 1.0  │  1.0  │  1.0
 1.0  │  1.0  │  1.0
 ─────┼───────┼─────
 1.0  │  1.0  │  1.0

julia> blocksizes(A)
([2, 1], [1, 1, 1])

julia> blocksizes(A,2)
3-element Vector{Int64}:
 1
 1
 1
BlockArrays.blocksFunction
blocks(a::AbstractArray{T,N}) :: AbstractArray{<:AbstractArray{T,N},N}

Return the array-of-arrays view to a such that

blocks(a)[i₁, i₂, ..., iₙ] == a[Block(i₁), Block(i₂), ..., Block(iₙ)]

This function does not copy the blocks and give a mutable viwe to the original array. This is an "inverse" of mortar.

Examples

julia> bs1 = permutedims(reshape([
               1ones(1, 3), 2ones(1, 2),
               3ones(2, 3), 4ones(2, 2),
           ], (2, 2)))
2×2 Matrix{Matrix{Float64}}:
 [1.0 1.0 1.0]               [2.0 2.0]
 [3.0 3.0 3.0; 3.0 3.0 3.0]  [4.0 4.0; 4.0 4.0]

julia> a = mortar(bs1)
2×2-blocked 3×5 BlockMatrix{Float64}:
 1.0  1.0  1.0  │  2.0  2.0
 ───────────────┼──────────
 3.0  3.0  3.0  │  4.0  4.0
 3.0  3.0  3.0  │  4.0  4.0

julia> bs2 = blocks(a)
2×2 Matrix{Matrix{Float64}}:
 [1.0 1.0 1.0]               [2.0 2.0]
 [3.0 3.0 3.0; 3.0 3.0 3.0]  [4.0 4.0; 4.0 4.0]

julia> bs1 == bs2
true

julia> bs2[1, 1] .*= 100;

julia> a  # in-place mutation is reflected to the block array
2×2-blocked 3×5 BlockMatrix{Float64}:
 100.0  100.0  100.0  │  2.0  2.0
 ─────────────────────┼──────────
   3.0    3.0    3.0  │  4.0  4.0
   3.0    3.0    3.0  │  4.0  4.0
BlockArrays.eachblockFunction
eachblock(A::AbstractBlockArray)

Create a generator that iterates over each block of an AbstractBlockArray returning views.

julia> v = Array(reshape(1:6, (2, 3)))
2×3 Matrix{Int64}:
 1  3  5
 2  4  6

julia> A = BlockArray(v, [1,1], [2,1])
2×2-blocked 2×3 BlockMatrix{Int64}:
 1  3  │  5
 ──────┼───
 2  4  │  6

julia> sum.(eachblock(A))
2×2 Matrix{Int64}:
 4  5
 6  6
BlockArrays.blockcheckboundsFunction
blockcheckbounds(A, inds...)

Throw a BlockBoundsError if the specified block indexes are not in bounds for the given block array. Subtypes of AbstractBlockArray should specialize this method if they need to provide custom block bounds checking behaviors.

julia> A = BlockArray(rand(2,3), [1,1], [2,1]);

julia> blockcheckbounds(A, 3, 2)
ERROR: BlockBoundsError: attempt to access 2×2-blocked 2×3 BlockMatrix{Float64} at block index [3,2]
[...]

BlockArray

BlockArrays.BlockArrayType
BlockArray{T, N, R<:AbstractArray{<:AbstractArray{T,N},N}, BS<:NTuple{N,AbstractUnitRange{Int}}} <: AbstractBlockArray{T, N}

A BlockArray is an array where each block is stored contiguously. This means that insertions and retrieval of blocks can be very fast and non allocating since no copying of data is needed.

In the type definition, R defines the array type that holds the blocks, for example Matrix{Matrix{Float64}}.

BlockArrays.undef_blocksConstant
undef_blocks

Alias for UndefBlocksInitializer(), which constructs an instance of the singleton type UndefBlocksInitializer (@ref), used in block array initialization to indicate the array-constructor-caller would like an uninitialized block array.

Examples

julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2])
2×2-blocked 3×5 BlockMatrix{Float32}:
 #undef  #undef  #undef  │  #undef  #undef
 ────────────────────────┼────────────────
 #undef  #undef  #undef  │  #undef  #undef
 #undef  #undef  #undef  │  #undef  #undef
BlockArrays.UndefBlocksInitializerType
UndefBlocksInitializer

Singleton type used in block array initialization, indicating the array-constructor-caller would like an uninitialized block array. See also undef_blocks (@ref), an alias for UndefBlocksInitializer().

Examples

julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2])
2×2-blocked 3×5 BlockMatrix{Float32}:
 #undef  #undef  #undef  │  #undef  #undef
 ────────────────────────┼────────────────
 #undef  #undef  #undef  │  #undef  #undef
 #undef  #undef  #undef  │  #undef  #undef
BlockArrays.mortarFunction
mortar(blocks::AbstractArray)
mortar(blocks::AbstractArray{R, N}, sizes_1, sizes_2, ..., sizes_N)
mortar(blocks::AbstractArray{R, N}, block_sizes::NTuple{N,AbstractUnitRange{Int}})

Construct a BlockArray from blocks. block_sizes is computed from blocks if it is not given.

This is an "inverse" of blocks.

Examples

julia> arrays = permutedims(reshape([
                  fill(1.0, 1, 3), fill(2.0, 1, 2),
                  fill(3.0, 2, 3), fill(4.0, 2, 2),
              ], (2, 2)))
2×2 Matrix{Matrix{Float64}}:
 [1.0 1.0 1.0]               [2.0 2.0]
 [3.0 3.0 3.0; 3.0 3.0 3.0]  [4.0 4.0; 4.0 4.0]

julia> M = mortar(arrays)
2×2-blocked 3×5 BlockMatrix{Float64}:
 1.0  1.0  1.0  │  2.0  2.0
 ───────────────┼──────────
 3.0  3.0  3.0  │  4.0  4.0
 3.0  3.0  3.0  │  4.0  4.0

julia> M == mortar(
                  (fill(1.0, 1, 3), fill(2.0, 1, 2)),
                  (fill(3.0, 2, 3), fill(4.0, 2, 2)),
              )
true
mortar((block_11, ..., block_1m), ... (block_n1, ..., block_nm))

Construct a BlockMatrix with n * m blocks. Each block_ij must be an AbstractMatrix.

BlockArrays.blockappend!Function
blockappend!(dest::BlockVector, sources...) -> dest

Append blocks from sources to dest. The number of blocks in dest are increased by sum(blocklength, sources).

This function avoids copying the elements of the blocks in sources when these blocks are compatible with dest. Importantly, this means that mutating sources afterwards alters the items in dest and it may even break the invariance of dest if the length of sources are changed.

The blocks in dest must not alias with sources or components of them. For example, the result of blockappend!(x, x) is undefined.

Examples

julia> using BlockArrays

julia> blockappend!(mortar([[1], [2, 3]]), mortar([[4, 5]]))
3-blocked 5-element BlockVector{Int64}:
 1
 ─
 2
 3
 ─
 4
 5
BlockArrays.blockpush!Function
blockpush!(dest::BlockVector, blocks...) -> dest

Push blocks to the end of dest.

This function avoids copying the elements of the blocks when these blocks are compatible with dest. Importantly, this means that mutating blocks afterwards alters the items in dest and it may even break the invariance of dest if the length of blocks are changed.

Examples

julia> using BlockArrays

julia> blockpush!(mortar([[1], [2, 3]]), [4, 5], [6])
4-blocked 6-element BlockVector{Int64}:
 1
 ─
 2
 3
 ─
 4
 5
 ─
 6
BlockArrays.blockpushfirst!Function
blockpushfirst!(dest::BlockVector, blocks...) -> dest

Push blocks to the beginning of dest. See also blockpush!.

This function avoids copying the elements of the blocks when these blocks are compatible with dest. Importantly, this means that mutating blocks afterwards alters the items in dest and it may even break the invariance of dest if the length of blocks are changed.

Examples

julia> using BlockArrays

julia> blockpushfirst!(mortar([[1], [2, 3]]), [4, 5], [6])
4-blocked 6-element BlockVector{Int64}:
 4
 5
 ─
 6
 ─
 1
 ─
 2
 3
BlockArrays.blockpop!Function
blockpop!(A::BlockVector) -> block

Pop a block from the end of dest.

Examples

julia> using BlockArrays

julia> A = mortar([[1], [2, 3]]);

julia> blockpop!(A)
2-element Vector{Int64}:
 2
 3

julia> A
1-blocked 1-element BlockVector{Int64}:
 1
BlockArrays.blockpopfirst!Function
blockpopfirst!(dest::BlockVector) -> block

Pop a block from the beginning of dest.

Examples

julia> using BlockArrays

julia> A = mortar([[1], [2, 3]]);

julia> blockpopfirst!(A)
1-element Vector{Int64}:
 1

julia> A
1-blocked 2-element BlockVector{Int64}:
 2
 3
Base.append!Function
append!(dest::BlockVector, sources...)

Append items from sources to the last block of dest.

The blocks in dest must not alias with sources or components of them. For example, the result of append!(x, x) is undefined.

Examples

julia> using BlockArrays

julia> append!(mortar([[1], [2, 3]]), mortar([[4], [5]]))
2-blocked 5-element BlockVector{Int64}:
 1
 ─
 2
 3
 4
 5
Base.push!Function
push!(dest::BlockVector, items...)

Push items to the end of the last block.

Base.pushfirst!Function
pushfirst!(A::BlockVector, items...)

Push items to the beginning of the first block.

Base.pop!Function
pop!(A::BlockVector)

Pop the last element from the last non-empty block. Remove all empty blocks at the end.

Base.popfirst!Function
popfirst!(A::BlockVector)

Pop the first element from the first non-empty block. Remove all empty blocks at the beginning.

PseudoBlockArray

BlockArrays.PseudoBlockArrayType
PseudoBlockArray{T, N, R} <: AbstractBlockArray{T, N}

A PseudoBlockArray is similar to a BlockArray except the full array is stored contiguously instead of block by block. This means that is not possible to insert and retrieve blocks without copying data. On the other hand parent on a PseudoBlockArray is instead instant since it just returns the wrapped array.

When iteratively solving a set of equations with a gradient method the Jacobian typically has a block structure. It can be convenient to use a PseudoBlockArray to build up the Jacobian block by block and then pass the resulting matrix to a direct solver using parent.

Examples

julia> A = zeros(Int, 2, 3);

julia> B = PseudoBlockArray(A, [1,1], [2,1])
2×2-blocked 2×3 PseudoBlockMatrix{Int64}:
 0  0  │  0
 ──────┼───
 0  0  │  0

julia> parent(B) === A
true

julia> B[Block(1,1)] .= 4
1×2 view(::Matrix{Int64}, 1:1, 1:2) with eltype Int64:
 4  4

julia> A
2×3 Matrix{Int64}:
 4  4  0
 0  0  0
BlockArrays.PseudoBlockVectorType
PseudoBlockVector{T}

Alias for PseudoBlockArray{T, 1}

julia> A = [1:6;]
6-element Vector{Int64}:
 1
 2
 3
 4
 5
 6

julia> PseudoBlockVector(A, [3,2,1])
3-blocked 6-element PseudoBlockVector{Int64}:
 1
 2
 3
 ─
 4
 5
 ─
 6
BlockArrays.PseudoBlockMatrixType
PseudoBlockMatrix{T}

Alias for PseudoBlockArray{T, 2}

julia> A = reshape([1:6;], 2, 3)
2×3 Matrix{Int64}:
 1  3  5
 2  4  6

julia> PseudoBlockMatrix(A, [1,1], [1,2])
2×2-blocked 2×3 PseudoBlockMatrix{Int64}:
 1  │  3  5
 ───┼──────
 2  │  4  6
Base.resize!Function
resize!(a::BlockVector, N::Block) -> PseudoBlockVector

Resize a to contain the first N blocks, returning a new BlockVector sharing memory with a. If N is smaller than the current collection block length, the first N blocks will be retained. N is not allowed to be larger.

resize!(a::PseudoBlockVector, N::Block) -> PseudoBlockVector

Resize a to contain the first N blocks, returning a new PseudoBlockVector sharing memory with a. If N is smaller than the current collection block length, the first N blocks will be retained. N is not allowed to be larger.

Kronecker products

BlockArrays.blockkronFunction
blockkron(A...)

Return a blocked version of kron(A...) with the natural block-structure imposed.

Examples

julia> A = reshape(1:9, 3, 3)
3×3 reshape(::UnitRange{Int64}, 3, 3) with eltype Int64:
 1  4  7
 2  5  8
 3  6  9

julia> BlockArrays.blockkron(A, A)
3×3-blocked 9×9 BlockMatrix{Int64}:
 1   4   7  │   4  16  28  │   7  28  49
 2   5   8  │   8  20  32  │  14  35  56
 3   6   9  │  12  24  36  │  21  42  63
 ───────────┼──────────────┼────────────
 2   8  14  │   5  20  35  │   8  32  56
 4  10  16  │  10  25  40  │  16  40  64
 6  12  18  │  15  30  45  │  24  48  72
 ───────────┼──────────────┼────────────
 3  12  21  │   6  24  42  │   9  36  63
 6  15  24  │  12  30  48  │  18  45  72
 9  18  27  │  18  36  54  │  27  54  81
BlockArrays.BlockKronType
BlockKron(A...)

Create a lazy representation of kron(A...) with the natural block-structure imposed. This is a component in blockkron(A...).

BlockArrays.blockvecFunction
blockvec(A::AbstractMatrix)

creates a blocked version of vec(A), with the block structure used to represent the columns.

Examples

julia> A = reshape(1:9, 3, 3)
3×3 reshape(::UnitRange{Int64}, 3, 3) with eltype Int64:
 1  4  7
 2  5  8
 3  6  9

julia> BlockArrays.blockvec(A)
3-blocked 9-element PseudoBlockVector{Int64, UnitRange{Int64}, Tuple{BlockedUnitRange{StepRangeLen{Int64, Int64, Int64, Int64}}}}:
 1
 2
 3
 ─
 4
 5
 6
 ─
 7
 8
 9
BlockArrays.khatri_raoFunction
khatri_rao(A, B)

References

  • Liu, Shuangzhe, and Gõtz Trenkler (2008) Hadamard, Khatri-Rao, Kronecker and Other Matrix Products. International J. Information and Systems Sciences 4, 160–177.
  • Khatri, C. G., and Rao, C. Radhakrishna (1968) Solutions to Some Functional Equations and Their Applications to Characterization of Probability Distributions. Sankhya: Indian J. Statistics, Series A 30, 167–180.