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

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

source
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
source
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
source
BlockArrays.blockaxesFunction
blockaxes(A)

Return the tuple of valid block indices for array A.

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

julia> blockaxes(A)[1]
2-element BlockRange{1, Tuple{Base.OneTo{Int64}}}:
 Block(1)
 Block(2)
source
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 BlockVector{Int64}:
 1
 2
 ─
 3

julia> blockaxes(A,1)
2-element BlockRange{1, Tuple{Base.OneTo{Int64}}}:
 Block(1)
 Block(2)
source
BlockArrays.blockisequalFunction

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

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

source

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

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

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

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

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
source
BlockArrays.blocksizesFunction
blocksizes(A)
blocksizes(A,i)

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

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
source
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
source
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> Matrix.(collect(eachblock(A)))
2×2 Matrix{Matrix{Int64}}:
 [1 3]  [5;;]
 [2 4]  [6;;]

julia> sum.(eachblock(A))
2×2 Matrix{Int64}:
 4  5
 6  6
source
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, Matrix{Matrix{Float64}}, Tuple{BlockedUnitRange{Vector{Int64}}, BlockedUnitRange{Vector{Int64}}}} at block index [3,2]
[...]
source

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

source
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
source
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
source
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([
                  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> 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> ans == mortar(
                  (1ones(1, 3), 2ones(1, 2)),
                  (3ones(2, 3), 4ones(2, 2)),
              )
true
source
mortar((block_11, ..., block_1m), ... (block_n1, ..., block_nm))

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

source
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
source
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
source
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
source
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
source
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
source
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
source
Base.push!Function
push!(dest::BlockVector, items...)

Push items to the end of the last block.

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

Push items to the beginning of the first block.

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

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

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

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

source

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 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 PseudoBlockMatrix{Float64}:
 0.944791  0.339612  │  0.322501
 ────────────────────┼──────────
 0.866895  0.136117  │  0.252549

julia> A = PseudoBlockArray(sprand(6, 0.5), [3,2,1])
3-blocked 6-element PseudoBlockVector{Float64, SparseVector{Float64, Int64}, Tuple{BlockedUnitRange{Vector{Int64}}}}:
 0.0
 0.0
 0.26755021483368013
 ───────────────────
 0.0
 0.11848853125656122
 ───────────────────
 0.0
source
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.

source

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.

source

Kronecker products

BlockArrays.blockkronFunction

" blockkron(A...)

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

source
BlockArrays.BlockKronType

" BlockKron(A...)

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

source
BlockArrays.blockvecFunction
blockvec(A::AbstractMatrix)

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

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