API

AlmostBandedMatrix(bands::BandedMatrix, fill)
AlmostBandedMatrix{T}(bands, fill)
AlmostBandedMatrix(::UndefInitializer, [::Type{T} = Float64], mn::NTuple{2, Integer},
    lu::NTuple{2, Integer}, rank::Integer)
AlmostBandedMatrix{T}(::UndefInitializer, mn::NTuple{2, Integer},
    lu::NTuple{2, Integer}, rank::Integer)

An AlmostBandedMatrix is a matrix with a bands part and a fill part. For efficient operations we store the matrix as a BandedMatrix and another AbstractMatrix with an overlapping bit.

Arguments

• bands::BandedMatrix: The banded component. Its lower bandwidth must be at least size(fill, 1) - 1 so it can store the overlap with the fill component.
• fill::AbstractMatrix: The dense or lazy low-rank component. It must have the same number of columns as bands and at least one row.
• mn::NTuple{2, Integer}: Matrix dimensions for an undef construction.
• lu::NTuple{2, Integer}: Lower and upper bandwidths for an undef construction.
• rank::Integer: Number of rows in the fill component for an undef construction. It must be positive and no greater than lu[2] + 1.

Fields

• bands: Banded storage, including the part that overlaps with fill.
• fill: Dense or lazy low-rank storage for the leading rows.

Notes

Construction synchronizes the overlapping entries by copying the fill component into the banded component. Mutating the fill component directly afterwards requires finish_part_setindex! before operations that read the overlap from the banded component.

Representation

[3 3 3 2 2 2 2 ... 2 2 2]\
[3 3 3 3 2 2 2 ... 2 2 2]\
[0 1 1 1 1 0 0 ... 0 0 0]\
[0 0 1 1 1 1 0 ... 0 0 0]\
[.......................]\
[.......................]\
[.......................]\
[0 0 0 0 0 0 0 ... 1 1 0]\
[0 0 0 0 0 0 0 ... 1 1 1]

where 2's are the fill part, and 1's are the bands part, and 3's are the overlapping part.

Example

bands = brand(Float64, 8, 8, 3, 2)
fill = rand(2, 8)
A = AlmostBandedMatrix(bands, fill)

Errors

Throws AssertionError if fill has no rows, if bands and fill have different numbers of columns, or if the lower bandwidth of bands is too small for the fill rank.

bandpart(A::AlmostBandedMatrix)

Return the banded part of the AlmostBandedMatrix. This is a BandedMatrix that stores the banded structure including the overlapping region with the fill part.

Arguments

• A::AlmostBandedMatrix: Matrix whose banded storage is requested.

Returns

Returns the mutable BandedMatrix stored by A; it is not a copy.

Example

A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
B = bandpart(A)  # Returns the BandedMatrix component

fillpart(A::AlmostBandedMatrix)

Return the fill part of the AlmostBandedMatrix. This is typically a low-rank matrix that represents additional structure beyond the banded part. The fill part overlaps with the first almostbandedrank(A) rows of the banded part.

Arguments

• A::AlmostBandedMatrix: Matrix whose fill storage is requested.

Returns

Returns the mutable fill matrix stored by A; it is not a copy. Call finish_part_setindex! after directly modifying entries in the overlap.

Example

A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
F = fillpart(A)  # Returns the fill matrix (2×10)

exclusive_bandpart(A::AlmostBandedMatrix)

Return the banded part of the AlmostBandedMatrix excluding the rows that overlap with the fill part. This is a view of the banded matrix starting from row almostbandedrank(A) + 1.

Arguments

• A::AlmostBandedMatrix: Matrix whose non-overlapping banded rows are requested.

Returns

Returns a view into bandpart(A), not a copy.

Example

A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
E = exclusive_bandpart(A)  # Returns a view of rows 3:10 of the banded part

almostbandwidths(A)

Return the bandwidths (l, u) of the banded part of the AlmostBandedMatrixA, where l is the number of sub-diagonals and u is the number of super-diagonals of bandpart(A).

Arguments

• A::AlmostBandedMatrix: Matrix to query.

Returns

Returns (l, u), where l is the lower bandwidth and u is the upper bandwidth.

Example

A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
almostbandwidths(A)  # Returns (3, 2)

almostbandedrank(A)

Return the rank of the fill part of the AlmostBandedMatrixA, i.e. the number of rows of fillpart(A). This is also the number of leading rows of the banded part that overlap with the fill part.

Arguments

• A::AlmostBandedMatrix: Matrix to query.

Returns

Returns the number of rows in fillpart(A).

Example

A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
almostbandedrank(A)  # Returns 2

finish_part_setindex!(A::AlmostBandedMatrix)
finish_part_setindex!(bands, fill)

Synchronize the overlapping region between the banded part and the fill part of an AlmostBandedMatrix. This function copies values from the fill part into the corresponding positions in the bands part where they overlap.

This is automatically called during construction but may need to be called manually if the fill part is modified directly after construction.

Arguments

• A::AlmostBandedMatrix: Matrix whose banded component is synchronized with its fill component.
• bands: Banded component to mutate when calling the two-argument form.
• fill: Fill component whose overlapping entries are copied into bands when calling the two-argument form.

Returns

Returns nothing. The bands argument, or equivalently bandpart(A), is mutated; fill is not mutated.

Example

A = AlmostBandedMatrix(brand(Float64, 8, 8, 3, 2), rand(2, 8))
fillpart(A)[1, 1] = 1
finish_part_setindex!(A)

Band(i)

Index selector for the diagonal at offset i of a banded matrix. Band(0) selects the main diagonal, positive offsets select superdiagonals, and negative offsets select subdiagonals.

Fields

• i::Int: Diagonal offset from the main diagonal.

Arguments

• i::Int: Diagonal offset to select.

Examples

julia> A = BandedMatrix(0 => 1:3, 1 => 4:5);

julia> A[Band(0)] == [1, 2, 3]
true

julia> A[Band(1)] == [4, 5]
true

BandError(A, i)
BandError(A, (k, j))
BandError(A)

Exception thrown when an operation accesses diagonal offset i outside the stored lower and upper bandwidths of A.

Fields

• A::AbstractMatrix: Matrix whose band structure rejects the access.
• i::Int: Requested diagonal offset, with positive offsets above and negative offsets below the main diagonal.

Arguments

• A::AbstractMatrix: Matrix whose band structure is being accessed.
• i::Int: Requested diagonal offset.
• (k, j)::Tuple{Int, Int}: Matrix coordinates from which the diagonal offset j - k is computed.

Examples

julia> A = BandedMatrix(0 => 1:3);

julia> BandError(A, 1) isa BandError
true