Banded tensors

BandedTensor3D{T,b}

Three-dimensional banded tensor with element type T.

Extended help

Band structure

The band structure is assumed to be symmetric, and is defined in terms of the band width $b$. For a cubic banded tensor of dimensions $N × N × N$, the element $A_{ijk}$ may be non-zero only if $|i - j| ≤ b$, $|i - k| ≤ b$ and $|j - k| ≤ b$.

Storage

The data is stored as a Vector of small matrices, each with size $r × r$, where $r = 2b + 1$ is the total number of bands. Each submatrix holds the non-zero values of a slice of the form A[:, :, k].

For $b = 2$, one of these matrices looks like the following, where dots indicate out-of-bands values (equal to zero):

| x  x  x  ⋅  ⋅ |
| x  x  x  x  ⋅ |
| x  x  x  x  x |
| ⋅  x  x  x  x |
| ⋅  ⋅  x  x  x |

These submatrices are stored as static matrices (SMatrix).

Setting elements

To define the elements of the tensor, each slice A[:, :, k] must be set at once. For instance:

A = BandedTensor3D(undef, 20, Val(2))  # tensor of size 20×20×20 and band width b = 2
for k in axes(A, 3)
    A[:, :, k] = rand(5, 5)
end

See setindex! for more details.

Non-cubic tensors

A slight departure from cubic tensors is currently supported, with dimensions of the form $N × N × M$. Moreover, bands may be shifted along the third dimension by an offset $δ$. In this case, the bands are given by $|i - j| ≤ b$, $|i - (k + δ)| ≤ b$ and $|j - (k + δ)| ≤ b$.

BandedTensor3D{T}(undef, (Ni, Nj, Nk), Val(b); [bandshift = (0, 0, 0)])
BandedTensor3D{T}(undef, N, Val(b); ...)

Construct 3D banded tensor with band widths b.

Right now, the first two dimension sizes Ni and Nj of the tensor must be equal. In the second variant, the tensor dimensions are N × N × N.

The tensor is constructed uninitialised. Each submatrix A[:, :, k] of size (2b + 1, 2b + 1), for k ∈ 1:Nk, should be initialised as in the following example:

A[:, :, k] = rand(2b + 1, 2b + 1)

The optional bandshift argument should be a tuple of the form (δi, δj, δk) describing a band shift. Right now, band shifts are limited to δi = δj = 0, so this argument should actually look like (0, 0, δk).

bandshift(A::BandedTensor3D) -> (δi, δj, δk)

Return tuple with band shifts along each dimension.

bandwidth(A::BandedTensor3D)

Get band width b of BandedTensor3D.

The band width is defined here such that the element A[i, j, k] may be non-zero only if $|i - j| ≤ b$, $|i - k| ≤ b$ and $|j - k| ≤ b$. This definition is consistent with the specification of the upper and lower band widths in BandedMatrices.

band_indices(A::BandedTensor3D, k)

Return the range of indices a:b for subarray A[:, :, k] where values may be non-zero.

SubMatrix{T} <: AbstractMatrix{T}

Represents the submatrix A[:, :, k] of a BandedTensor3D A.

Wraps the SMatrix holding the submatrix.

setindex!(A::BandedTensor3D, Ak::AbstractMatrix, :, :, k)

Set submatrix A[:, :, k] to the matrix Ak.

The Ak matrix must have dimensions (r, r), where r = 2b + 1 is the total number of bands of A.

dot(x, Asub::SubMatrix, y)

Efficient implementation of the generalised dot product dot(x, Asub * y).

To be used with a submatrix Asub = A[:, :, k] of a BandedTensor3D A.

muladd!(Y::AbstractMatrix, A::BandedTensor3D, b::AbstractVector)

Perform contraction Y[i, j] += ∑ₖ A[i, j, k] * b[k].

Note that the result is added to previously existent values of Y.

As an (allocating) alternative, one can use Y = A * b, which returns Y as a BandedMatrix.