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 julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2]) 2×2-blocked 3×5 BlockArray{Float32,2}: #undef #undef #undef │ #undef #undef ------------------------┼---------------- #undef #undef #undef │ #undef #undef #undef #undef #undef │ #undef #undef

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}}

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 BlockArray{Float64,2}:
 1.0  1.0  │  1.0
 ──────────┼─────
 1.0  1.0  │  1.0

julia> A[Block(1, 1)]
1×2 Array{Float64,2}:
 1.0  1.0

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}}.

Constructs a BlockArray with uninitialized blocks from a block type R with sizes defind by block_sizes.

julia> BlockArray(undef_blocks, Matrix{Float64}, [1,3], [2,2])
2×2-blocked 4×4 BlockArray{Float64,2}:
 #undef  │  #undef  #undef  #undef  │
 --------┼--------------------------┼
 #undef  │  #undef  #undef  #undef  │
 #undef  │  #undef  #undef  #undef  │
 --------┼--------------------------┼
 #undef  │  #undef  #undef  #undef  │

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

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

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 PseudoBlockArray{Int64,2}:
 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

BlockRange(startblock, stopblock)

represents a cartesian range of blocks.

The relationship between Block and BlockRange mimicks the relationship between CartesianIndex and CartesianRange.

BlockedUnitRange

is an AbstractUnitRange{Int} that has been divided into blocks, and is used to represent axes of block arrays. Construction is typically via blockrange which converts a vector of block lengths to a BlockedUnitRange.

julia> blockedrange([2,2,3])
3-blocked 7-element BlockedUnitRange{Array{Int64,1}}:
 1
 2
 ─
 3
 4
 ─
 5
 6
 7

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 Array 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 Array.

julia> using BlockArrays, Random, SparseArrays

julia> Random.seed!(12345);

julia> A = PseudoBlockArray(rand(2,3), [1,1], [2,1])
2×2-blocked 2×3 PseudoBlockArray{Float64,2}:
 0.562714  0.371605  │  0.381128
 ────────────────────┼──────────
 0.849939  0.283365  │  0.365801

julia> A = PseudoBlockArray(sprand(6, 0.5), [3,2,1])
3-blocked 6-element PseudoBlockArray{Float64,1,SparseVector{Float64,Int64},Tuple{BlockedUnitRange{Array{Int64,1}}}}:
 0.0
 0.5865981007905481
 0.0
 ───────────────────
 0.05016684053503706
 0.0
 ───────────────────
 0.0

blockaxes(A)

Return the tuple of valid block indices for array A.

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

julia> blockaxes(A)[1]
2-element BlockRange{1,Tuple{UnitRange{Int64}}}:
 Block(1)
 Block(2)

blockaxes(A, d)

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

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

julia> blockaxes(A,1)
2-element BlockRange{1,Tuple{UnitRange{Int64}}}:
 Block(1)
 Block(2)

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 BlockArray{Float64,2,Array{Array{Float64,2},2},Tuple{BlockedUnitRange{Array{Int64,1}},BlockedUnitRange{Array{Int64,1}}}} at block index [3,2]
[...]

blockfirsts(a::AbstractUnitRange{Int})

returns the first index of each block of a.

blockisequal(a::AbstractUnitRange{Int}, b::AbstractUnitRange{Int})

returns true if a and b have the same block structure.

blockisequal(a::Tuple, b::Tuple)

returns true if all(blockisequal.(a,b))` is true.

blocklasts(a::AbstractUnitRange{Int})

returns the last index of each block of a.

blocklengths(a::AbstractUnitRange{Int})

returns the length of each block of a.

blocksize(A)

Return the tuple of the number of blocks along each dimension.

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

julia> blocksize(A)
(2, 3)

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 Array{Int64,2}:
 1  3  5
 2  4  6

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

julia> Matrix.(collect(eachblock(A)))
2×2 Array{Array{Int64,2},2}:
 [1 3]  [5]
 [2 4]  [6]

julia> sum.(eachblock(A))
2×2 Array{Int64,2}:
 4  5
 6  6

getblock!(X, A, inds...)

Stores the block at blockindex inds in X and returns it. Throws a BlockBoundsError if the attempted assigned block is out of bounds.

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

julia> x = zeros(1, 2);

julia> getblock!(x, A, 2, 1);

julia> x
1×2 Array{Float64,2}:
 1.0  1.0

getblock(A, inds...)

Returns the block at blockindex inds.... An alternative syntax is A[Block(inds...)]. Throws aBlockBoundsError` if this block is out of bounds.

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

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

julia> getblock(A, 2, 1)
1×2 Array{Int64,2}:
 2  4

julia> A[Block(1, 2)]
1×1 Array{Int64,2}:
 5

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.

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.

Examples

julia> blocks = permutedims(reshape([
                  1ones(1, 3), 2ones(1, 2),
                  3ones(2, 3), 4ones(2, 2),
              ], (2, 2)))
2×2 Array{Array{Float64,2},2}:
 [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> mortar(blocks)
2×2-blocked 3×5 BlockArray{Float64,2}:
 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> ans == mortar(
                  (1ones(1, 3), 2ones(1, 2)),
                  (3ones(2, 3), 4ones(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.

setblock!(A, v, inds...)

Stores the block v in the block at block index inds in A. An alternative syntax is A[Block(inds...)] = v. Throws a BlockBoundsError if this block is out of bounds.

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

julia> setblock!(A, [1 2], 1, 1);

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

julia> A
2×2-blocked 2×3 PseudoBlockArray{Float64,2}:
 1.0  2.0  │  0.0
 ──────────┼─────
 3.0  4.0  │  0.0

BlockIndexRange(block, startind:stopind)

represents a cartesian range inside a block.

BlockSlice(indices)

Represent an AbstractUnitRange of indices that attaches a block.

Upon calling to_indices(), Blocks are converted to BlockSlice objects to represent the indices over which the Block spans.

This mimics the relationship between Colon and Base.Slice.

SubBlockIterator(subblock_lasts::Vector{Int}, block_lasts::Vector{Int})
SubBlockIterator(A::AbstractArray, bs::NTuple{N,AbstractUnitRange{Int}} where N, dim::Integer)

An iterator for iterating BlockIndexRange of the blocks specified by subblock_lasts. The Block index part of BlockIndexRange is determined by subblock_lasts. That is to say, the Block index first specifies one of the block represented by subblock_lasts and then the inner-block index range specifies the region within the block. Each such block corresponds to a block specified by blocklasts.

Note that the invariance subblock_lasts ⊂ block_lasts must hold and must be ensured by the caller.

Examples

julia> using BlockArrays

julia> import BlockArrays: SubBlockIterator, BlockIndexRange

julia> A = BlockArray(1:6, 1:3);

julia> subblock_lasts = axes(A, 1).lasts;

julia> @assert subblock_lasts == [1, 3, 6];

julia> block_lasts = [1, 3, 4, 6];

julia> for idx in SubBlockIterator(subblock_lasts, block_lasts)
           B = @show view(A, idx)
           @assert !(parent(B) isa BlockArray)
           idx :: BlockIndexRange
           idx.block :: Block{1}
           idx.indices :: Tuple{UnitRange}
       end
view(A, idx) = [1]
view(A, idx) = [2, 3]
view(A, idx) = [4]
view(A, idx) = [5, 6]

julia> [idx.block.n[1] for idx in SubBlockIterator(subblock_lasts, block_lasts)]
4-element Array{Int64,1}:
 1
 2
 3
 3

julia> [idx.indices[1] for idx in SubBlockIterator(subblock_lasts, block_lasts)]
4-element Array{UnitRange{Int64},1}:
 1:1
 1:2
 1:1
 2:3

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 julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2]) 2×2-blocked 3×5 BlockArray{Float32,2}: #undef #undef #undef │ #undef #undef ────────────────────────┼──────────────── #undef #undef #undef │ #undef #undef #undef #undef #undef │ #undef #undef

" blockcolsupport(A, j)

gives an iterator containing the possible non-zero blocks in the j-th block-column of A.

" blockrowsupport(A, k)

gives an iterator containing the possible non-zero blocks in the k-th block-row of A.

unblock(block_sizes, inds, I)

Returns the indices associated with a block as a BlockSlice.