Public Documentation

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

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

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

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

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

nblocks(A, [dim...])

Returns a tuple containing the number of blocks in a block array. Optionally you can specify the dimension(s) you want the number of blocks for.

julia> A =  BlockArray(rand(5,4,6), [1,4], [1,2,1], [1,2,2,1]);

julia> nblocks(A)
(2, 3, 4)

julia> nblocks(A, 2)
3

julia> nblocks(A, 3, 2)
(4, 3)

blocksize(A, inds)

Returns a tuple containing the size of the block at block index inds.

julia> A = BlockArray(rand(5, 4, 6), [1, 4], [1, 2, 1], [1, 2, 2, 1]);

julia> blocksize(A, (1, 3, 2))
(1, 1, 2)

julia> blocksize(A, (2, 1, 3))
(4, 1, 2)

blocksizes(A)

returns a subtype of AbstractBlockSizes that contains information about the block sizes of A. Any subtype of AbstractBlockArrays must override this.

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

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

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

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

BlockArray{T, N, R<:AbstractArray{<:AbstractArray{T,N},N}, BS<:AbstractBlockSizes{N}} <: 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}}.

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

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

mortar(blocks::AbstractArray)
mortar(blocks::AbstractArray{R, N}, sizes_1, sizes_2, ..., sizes_N)
mortar(blocks::AbstractArray{R, N}, block_sizes::BlockSizes{N})

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.

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},BlockArrays.BlockSizes{1,Tuple{Array{Int64,1}}}}:
 0.0                
 0.5865981007905481
 0.0                
 ───────────────────
 0.05016684053503706
 0.0
 ───────────────────
 0.0