API Reference

NestedCrossApproximation

Nested cross approximation (NCA) for the kernel-independent construction of H²-matrices.

The admissible blocks of a matrix are compressed into nested cluster bases, transfer matrices and coupling matrices, all of which are built from matrix entries only. Key features:

• H²-matrices: Dense near field and nested far field with a fast matrix-vector product
• Compressors: Top-down, bottom-up and batched bottom-up construction of the nested bases
• Factorizations: The ACA and the IACA of AdaptiveCrossApproximation.jl select the pivots
• Representors: Optional reduction of the far field before the pivot search
• Directional H²-matrices: Wideband admissibility with a directional subdivision of the far field for electrically large clusters

The package does not export any names.

Main API

H²-matrix:

• PetrovGalerkinNCA: H²-matrix type and its assembly
• farmatrix, nearmatrix: Extract the far and the near field
• storage: Report the memory footprint

Compressors:

• TopDown: Pivots are passed from the root to the leaves
• BottomUp: Pivots are passed from the leaves to the root
• BatchedBottomUp: Bottom-up variant that evaluates one batch of blocks per level

Representors:

• RandomRep: Random subset of the far field
• ChebyshevRep: Points close to a Chebyshev grid around the far field
• MimicryRep: Geometric selection by tree mimicry pivoting

Admissibility:

• AdaptiveCrossApproximation.isnear: Standard admissibility condition
• isnearwideband: Wideband condition, leads to a directional H²-matrix

Example

using NestedCrossApproximation: PetrovGalerkinNCA, TopDown
using AdaptiveCrossApproximation, H2Trees, ParallelKMeans

builder = KMeansTreeBuilder(; minvalues=100)
tree = BlockTree(
    KMeansTree(testpoints; builder=builder), KMeansTree(trialpoints; builder=builder)
)
h2mat = PetrovGalerkinNCA(
    operator,
    testspace,
    trialspace,
    tree;
    testcompressor=TopDown(; factorization=ACA(; tol=1e-4)),
    trialcompressor=TopDown(; factorization=ACA(; tol=1e-4)),
)
y = h2mat * x

See also

• AdaptiveCrossApproximation.jl for the low-rank factorizations, pivoting strategies and kernel matrices
• H2Trees.jl for the cluster trees
• BlockSparseMatrices.jl for the storage of the near field

BasisStore{T,P}

Leaf bases of one side of an H²-matrix.

blocks[i] is the basis of the cluster plan.nodes[i], of size (points, rank) on the test side and (rank, points) on the trial side. With a directional plan a cluster holds one basis per direction.

Fields

• plan::P: clusters (and directions) the blocks belong to
• blocks::Vector{Matrix{T}}: basis matrices

BatchedBottomUp{PivotSelectorType,CompressorType}

Compressor that constructs the nested bases from the leaves to the root and evaluates the matrix entries of a whole level in one batch.

The construction has three phases:

1. The far-field pivots of every cluster are selected from the geometry alone, without matrix entries.
2. For each cluster of a level one dense block against its far-field pivots is evaluated. Its other indices are all points of a leaf, or the pivots of the children.
3. The pivots of the cluster are selected in this block, and its basis or transfer matrices are computed from it.

Fields

• pivotselector::PivotSelectorType: geometric pivoting strategy for the first phase, e.g. AdaptiveCrossApproximation.TreeMimicryPivoting
• compressor::CompressorType: factorization of a dense block for the third phase, e.g. a fully pivoted ACA

Notes

The batched evaluation leaves the choice between CPU and GPU to the kernel matrix. Directional H²-matrices require BottomUp.

BatchedBottomUp(; pivotselector, compressor)

Build a BatchedBottomUp compressor from keyword arguments.

Keyword Arguments

• pivotselector: geometric pivoting strategy that selects the far-field pivots
• compressor: factorization of a dense block

BottomUp{LowRankFactorizationType,RepresentorType}

Compressor that constructs the nested bases from the leaves to the root.

For each cluster a block against its far field, the admissible clusters of the cluster and of all its ancestors, is factorized. In a leaf all points of the cluster are candidates for the pivots, in any other cluster the pivots of its children. The selected pivots of the cluster define its basis and transfer matrices.

Fields

• factorization::LowRankFactorizationType: low-rank factorization that selects the pivots, an ACA or an IACA of AdaptiveCrossApproximation.jl
• representor::RepresentorType: Representor that reduces the far field before the factorization, or nothing

Notes

BottomUp is the only compressor that supports directional H²-matrices (see isnearwideband), where a basis is built for each cluster and direction.

BottomUp(; factorization=ACA(), representor=nothing)

Build a BottomUp compressor from keyword arguments.

Keyword Arguments

• factorization = ACA(): low-rank factorization that selects the pivots
• representor = nothing: Representor that reduces the far field

ChebyshevRep{D,F} <: Representor

Representor that selects the points of the far field closest to a tensor Chebyshev grid.

The grid is aligned with the principal axes of the far field and scaled to its extent.

Fields

• pos::Vector{SVector{D,F}}: positions of the indices of the far field

Notes

Only three-dimensional positions are supported.

ConcurrentWorkspaceError

Thrown when a matrix-vector product starts on an H2Workspace that is in use by another product.

CouplingStore{T,P}

Coupling matrices of an H²-matrix.

blocks[i] holds the matrix entries at the pivots of the i-th admissible pair of a test and a trial cluster, A[testpivots, trialpivots].

Fields

• plan::P: test and trial cluster (or direction index) of each block
• blocks::Vector{Matrix{T}}: coupling matrices

DirectionTree{N,T}

Hierarchy of directions for the directional subdivision on a TwoNTree.

The roots are the 2N axis directions, the centres of the faces of a cube. Each level subdivides a face patch into 2^(N-1) patches, so that the directions of a level are nested in those of the previous one. The roots belong to the finest high-frequency level of the cluster tree, and every coarser level uses the next level of directions.

Fields

• level::Int: depth of the direction tree
• dirroot::Int: level of the cluster tree that uses the root directions
• rootcount::Int: number of root directions
• branching::Int: number of children of a direction
• nodes::Vector{DirectionNode{N,T}}: directions, level by level

DirectionalData{I<:Integer}

Far interactions of the clusters of one tree, subdivided into directions.

A cluster in the high-frequency regime holds a set of directions, and each of its far nodes belongs to one of them. A cluster in the low-frequency regime holds the single direction 0. The position of a (cluster, direction) pair in dirs is its direction index, by which the pivots, bases and transfer matrices of a directional H²-matrix are addressed.

Fields

• fardata::FarData{I}: far nodes of each node, grouped by direction
• nodetodirsptr::Vector{I}: position of the first direction of each node in dirs
• dirs::Vector{I}: directions of all nodes
• diridxtofarptr::Vector{I}: position of the first far node of each direction index
• nodetochdirptr::Vector{I}: position of the first entry of each node in partochddirmap
• partochddirmap::Vector{I}: for each direction of the parent the matching local direction of the node, 0 if there is none
• isnear: admissibility condition

FarData{I<:Integer}

Far interactions of the clusters of one tree in compressed sparse row layout.

The far nodes of node, i.e. the clusters of the other tree that form an admissible pair with it, are farnodes[nodetofarnodesptr[node]:(nodetofarnodesptr[node + 1] - 1)].

Fields

• nodetofarnodesptr::Vector{I}: position of the first far node of each node
• farnodes::Vector{I}: far nodes of all nodes

H2Workspace(core; scheduler=core.scheduler)
H2Workspace(core, T; scheduler=core.scheduler)

H²-matrix as a linear map: a read-only core and the buffers of the matrix-vector product for vectors of element type T (default eltype(core)).

Fields

• core: read-only part, e.g. a PetrovGalerkinNCACore
• trialcoeffs, testcoeffs: coefficients of the trial and the test clusters
• scheduler: OhMyThreads scheduler of the matrix-vector product
• busy: set during a matrix-vector product

Notes

A workspace supports *, mul!, transpose, and adjoint. The fields of the core are also available as properties of the workspace, e.g. h2mat.nearinteractions.

One workspace runs one matrix-vector product at a time: a second product on the same workspace throws a ConcurrentWorkspaceError. To multiply with the same matrix from several tasks, give each task its own workspace over the shared core:

workspaces = [H2Workspace(core; scheduler=OhMyThreads.SerialScheduler()) for _ in 1:4]

For vectors of an element type other than T the buffers are allocated in every product.

See also

core, PetrovGalerkinNCACore, PetrovGalerkinNCA

IsLowFrequencyFunctor{F}

Classifier deciding whether a tree node is in the low-frequency regime.

A node is low-frequency when k * d <= γ, where d is a characteristic diameter: a plain value when called as f(d), or one derived from a tree node when called as f(tree, node).

Construct with islf rather than calling the constructor directly.

Fields

• γ::F: admissibility threshold.
• k::F: wavenumber.

IsNearWidebandFunctor{F,LF}

Admissibility condition for wideband problems, in which clusters may be small or large compared to the wavelength.

Classifies a pair of clusters as near (assembled densely) or far (compressed). The condition switches per pair between a geometric one in the low-frequency regime and a wavenumber-dependent one in the high-frequency regime, as decided by islf.

Construct with isnearwideband rather than calling the constructor directly.

Fields

• k::F: wavenumber.
• ηlf::F: admissibility parameter used in the low-frequency branch.
• ηhf::F: admissibility parameter used in the high-frequency branch.
• islf::LF: low-frequency classifier, e.g. an IsLowFrequencyFunctor.

MimicryRep{D,T,TreeType} <: Representor

Representor that selects the representatives with the tree mimicry pivoting, i.e. from the geometry of the cluster and its far field.

Fields

• pivoting::TreeMimicryPivoting{D,T,TreeType}: pivoting strategy of AdaptiveCrossApproximation.jl, built from the positions of the cluster side, the positions of the far side, and the tree of the far side

Notes

Requires a far field given as clusters and is therefore only supported with BottomUp.

PetrovGalerkinNCA{T}

H2Workspace over a PetrovGalerkinNCACore: an H²-matrix constructed with the nested cross approximation, as a linear map.

PetrovGalerkinNCA(operator, testspace, trialspace, tree; kwargs...)

Assemble an H²-matrix of operator with the nested cross approximation and return it as a linear map: a PetrovGalerkinNCACore and one H2Workspace over it.

The keyword arguments are those of PetrovGalerkinNCACore.

Notes

The returned workspace runs one matrix-vector product at a time. For concurrent products build further workspaces over core(h2mat), see H2Workspace.

PetrovGalerkinNCACore{T}

Read-only part of an H²-matrix constructed with the nested cross approximation.

Near interactions are stored as dense blocks. Far interactions are stored in nested form: a basis for each leaf cluster, a transfer matrix for each cluster and child, and a coupling matrix for each admissible pair of clusters. Test and trial side have separate bases, so the test and the trial space may differ.

Fields

• tree: block tree of the test and the trial cluster tree
• nearinteractions: block-sparse matrix of the near field
• nestedtestbases, nestedtrialbases: leaf bases, see BasisStore
• testtransfermatrices, trialtransfermatrices: transfer matrices, see TransferStore
• couplingmatrices: coupling matrices, see CouplingStore
• aggregationplan, disaggregationplan: position of the coefficients of each trial and test cluster in the coefficient vectors of the matrix-vector product
• scheduler: default scheduler of a workspace, created from ntasks by the constructor
• dim::Tuple{Int,Int}: matrix dimensions (m, n)

Notes

A core is not a linear map. Wrap it in an H2Workspace, which owns the buffers of the matrix-vector product and is the LinearMap:

core = PetrovGalerkinNCACore(operator, testspace, trialspace, tree)
h2mat = H2Workspace(core)
mul!(y, h2mat, x)

A matrix-vector product does not write to the core, so several workspaces may share one core and run concurrently. PetrovGalerkinNCA builds a core and one workspace in a single call.

See also

H2Workspace, PetrovGalerkinNCA

PetrovGalerkinNCACore(operator, testspace, trialspace, tree; kwargs...)

Assemble the read-only part of an H²-matrix of operator with the nested cross approximation.

The near field is assembled densely. For the far field the test and the trial compressor select pivots for every cluster, from which the nested bases, the transfer matrices and the coupling matrices are computed.

Arguments

• operator: operator or kernel that defines the matrix entries
• testspace, trialspace: test and trial space, e.g. basis functions or point sets. Together with operator they have to be supported by AdaptiveCrossApproximation.AbstractKernelMatrix.
• tree: block tree (H2Trees.BlockTree) of the cluster trees of both spaces

Keyword Arguments

• testcompressor = TopDown(): compressor for the test bases, one of TopDown, BottomUp, and BatchedBottomUp
• trialcompressor = TopDown(): compressor for the trial bases
• isnear = isnear(): admissibility condition. With isnearwideband a directional H²-matrix is built, which requires BottomUp on both sides.
• maxrank::Int = 50: maximum number of pivots of a cluster
• matrixdata: data for the evaluation of the near field, e.g. a quadrature strategy
• farmatrixdata: data for the evaluation of the far field
• ntasks::Integer = Threads.nthreads(): number of parallel tasks for the assembly and the matrix-vector product; ntasks = 1 runs on the calling task
• verbose::Bool = false: show progress bars during the assembly

Returns

• PetrovGalerkinNCACore

RandomRep <: Representor

Representor that draws the representatives uniformly at random from the far field.

Representor

Abstract type for strategies that reduce the far field of a cluster to a few representative points before the low-rank factorization.

A compressor with a representor factorizes the cluster against the representatives only, which reduces the number of evaluated matrix entries at the cost of some accuracy.

Interface

A representor is called as representor(refidcs, idcs, npivots) and returns at most npivots of the candidates idcs; refidcs are the indices of the cluster.

Concrete Types

• RandomRep: Random subset
• ChebyshevRep: Points close to a Chebyshev grid
• MimicryRep: Geometric selection by tree mimicry pivoting

SingularCrossMatrixError(kind, npivots, rank)

Raised when the cross matrix A[pivots, cols] selected for a cluster is singular, so the nested basis or transfer matrix for that cluster cannot be formed.

TopDown{LowRankFactorizationType,RepresentorType}

Compressor that constructs the nested bases from the root to the leaves.

For each cluster the block of the cluster against its far field is factorized. The far field consists of the points of the admissible clusters and of the far-field pivots of the parent, through which the far field of all ancestors is taken into account. The selected pivots of the cluster define its basis and transfer matrices.

Fields

• factorization::LowRankFactorizationType: low-rank factorization that selects the pivots, an ACA or an IACA of AdaptiveCrossApproximation.jl
• representor::RepresentorType: Representor that reduces the far field before the factorization, or nothing

Notes

The far field is a set of points. Hence TreeMimicryPivoting in an IACA and MimicryRep are not supported; use MimicryPivoting instead. Directional H²-matrices require BottomUp.

TopDown(; factorization=ACA(), representor=nothing)

Build a TopDown compressor from keyword arguments.

Keyword Arguments

• factorization = ACA(): low-rank factorization that selects the pivots
• representor = nothing: Representor that reduces the far field

TransferStore{T,P}

Transfer matrices of one side of an H²-matrix, ordered level by level.

Each block connects a cluster and one of its children, and is of size (child rank, parent rank) on the test side and (parent rank, child rank) on the trial side. With a directional plan the blocks connect (cluster, direction) pairs.

Fields

• plan::P: levels, parents and children the blocks belong to
• blocks::Vector{Matrix{T}}: transfer matrices

_scheduler(ntasks)

Scheduler of the parallel loops on ntasks tasks: a DynamicScheduler with ntasks chunks, or serial execution on the calling task for ntasks = 1. The public functions take only ntasks.

assemble_couplingstore(farmatrix, testpivots, trialpivots, testfardata, trialfardata;
    ntasks, pbar)

Evaluate the coupling matrix A[testpivots, trialpivots] of every admissible cluster pair and return them as a CouplingStore.

With DirectionalData the pivots of the directions the two clusters lie in with respect to each other are used.

assemble_level(farmatrix, rowidcs, colidcs; maxrank, ntasks, transposed=false) -> storage

Phase 2: assemble one tree level's dense far blocks (block i is rowidcs[i] × colidcs[i]). The CPU method returns a plain Vector{Matrix}; the returned storage type is the backend seam consumed by compresslevel_*!. maxrank is unused here on CPU (blocks are exactly sized) but sets the padded buffer width for the GPU method. With transposed=true, evaluates transpose(farmatrix[colidcs[i], rowidcs[i]]) into the same layout, for trial-side compression without conjugation.

assemblefars(tree, isnear, testcompressor, trialcompressor, farmatrix;
    ntasks, maxrank, partition=interactions(tree, isnear), verbose=false)

Assemble the far field of an H²-matrix.

Determines the admissible cluster pairs of tree, builds the nested bases of both sides with testbases and trialbases, and evaluates the coupling matrices at the resulting pivots.

Returns

A named tuple with nestedtestbases, testtransfermats, testpivots, nestedtrialbases, trialtransfermats, trialpivots, and couplingmatrices.

assemblenears(operator, testspace, trialspace, tree; isnear, ntasks, matrixdata,
    partition=interactions(tree, isnear), verbose=false)

Assemble the near field of an H²-matrix.

Evaluates the near-field blocks of tree (see interactions) densely, one block row per test cluster with near blocks, in the original order of the spaces.

Returns

A BlockSparseMatrix of size (length(testspace), length(trialspace)).

compresslevel_test!(cfg, storage, subtree, activeclusters, tvalues,
                    childranges, nodechildren, tpivots, bases, transfer,
                    maxrank, pbar; scheduler)

Phase 3 (test side): for each active cluster select its own pivots via the ACA callable cfg, then build its leaf basis (nestedtestbasis) or child transfer matrices (testtransfer) from the assembled block. Writes tpivots, bases, transfer by global node id. Dispatched on storage (host Vector{Matrix} here); the GPU method batches the same steps over a device stack. Full-pivoted ACA rescales the squared sampled residual by s/(s-r) without counting the full far-field columns.

The per-cluster loop runs under scheduler (@tasks), since each iteration compresses an independent block and writes a distinct node id — the only shared mutable state is the ACA scratch buffer, which is task-local (@local). The GPU method ignores scheduler (a whole level is one batched launch).

compresslevel_trial!(cfg, storage, subtree, activeclusters, svalues,
                     childranges, nodechildren, spivots, bases, transfer,
                     maxrank, pbar)

Phase 3 (trial side): mirrors [compresslevel_test!], but nestedtrialbasis/trialtransfer expect a buffer shaped (far-pivot-rank × own-trial-dofs), the transpose of the block's own orientation, so the local slice is transposed before use. transpose, not adjoint: T is typically complex (BEM) and adjoint would wrongly conjugate.

compute_test_pivots!(factorization, representor, farmatrix, tree, tidcs, Ft,
    colbuffer, rowbuffer; maxrank=40)
compute_trial_pivots!(factorization, representor, farmatrix, tree, Fs, sidcs,
    colbuffer, rowbuffer; maxrank=40)

Select the pivots of a cluster by a low-rank factorization of the block of the cluster against its far field.

Arguments

• factorization: ACA or IACA prepared for the block
• representor: Representor that reduces the far field, or nothing
• farmatrix: kernel matrix for the evaluation of far-field entries
• tree: block tree
• tidcs, sidcs: candidates for the pivots of the cluster
• Ft, Fs: far field of the cluster as nodes of the other tree, or as points wrapped in PreResolvedIndices
• colbuffer, rowbuffer: buffers of the factorization

Returns

• rows, cols: row and column pivots. On the test side rows are the pivots of the cluster and cols those in the far field, on the trial side vice versa.

Notes

On return the buffer of the cluster side (colbuffer on the test side) holds the pivot columns (rows) of the cluster as required by nestedtestbasis and testtransfer; the other buffer is reset to zero.

compute_test_pivots!(factorization, representor, farmatrix, tree, tidcs, Ft,
    colbuffer, rowbuffer; maxrank=40)
compute_trial_pivots!(factorization, representor, farmatrix, tree, Fs, sidcs,
    colbuffer, rowbuffer; maxrank=40)

Select the pivots of a cluster by a low-rank factorization of the block of the cluster against its far field.

Arguments

• factorization: ACA or IACA prepared for the block
• representor: Representor that reduces the far field, or nothing
• farmatrix: kernel matrix for the evaluation of far-field entries
• tree: block tree
• tidcs, sidcs: candidates for the pivots of the cluster
• Ft, Fs: far field of the cluster as nodes of the other tree, or as points wrapped in PreResolvedIndices
• colbuffer, rowbuffer: buffers of the factorization

Returns

• rows, cols: row and column pivots. On the test side rows are the pivots of the cluster and cols those in the far field, on the trial side vice versa.

Notes

On return the buffer of the cluster side (colbuffer on the test side) holds the pivot columns (rows) of the cluster as required by nestedtestbasis and testtransfer; the other buffer is reset to zero.

core(h2mat::H2Workspace)

Return the read-only part of h2mat, which can be shared with further workspaces.

directionalfardata(fardata::FarData, tree, fartree, isnear)

Subdivide the far interactions of tree into directions and return a DirectionalData.

Each far node of a high-frequency cluster is assigned to the direction closest to the vector between the two cluster centres, and the far nodes in fardata are reordered by direction. A cluster also takes over the directions of its parent, which makes the directional bases nested.

For a TwoNTree the directions are the nodes of a DirectionTree. For a BoundingBallTree each cluster has its own set of directions, whose number follows from the wavenumber and the diameter of the cluster.

dirfarfield(tree, data::DirectionalData, node::Int, dir::Int)

Return the far field of node in direction dir: its own far nodes in this direction followed by those inherited from its ancestors.

For a high-frequency direction the matching directions of the ancestors are followed upwards. For the low-frequency direction 0 the far nodes of the ancestors are collected as long as these are in the low-frequency regime.

fardata(tree::BlockTree, isnear, partition=interactions(tree, isnear))

Determine the admissible cluster pairs of tree and return the far interactions of the test and of the trial tree.

An existing ACA interaction partition can be reused. The test-side far arrays are shared with it; directional subdivision may reorder its far nodes in place.

Returns

• Two FarData for the standard admissibility condition, two DirectionalData for isnearwideband.

farfield(tree, fardata::FarData, node::Int)

Return the far field of node: its own far nodes followed by those of all its ancestors.

A nested basis has to represent the cluster with respect to this set, since the interactions of the ancestors are passed down through the transfer matrices.

farmatrix(h2mat::PetrovGalerkinNCA)

Return the far field of h2mat as a PetrovGalerkinNCA with an empty near field.

The nested bases, transfer and coupling matrices are shared with h2mat, the buffers of the matrix-vector product are not.

islf(γ::Real, k::Real)

Create a low-frequency classifier for wavenumber k and threshold γ.

Returns

• IsLowFrequencyFunctor.

isnearwideband(k::Real; ηlf=1.0, ηhf=5.0, γ=1.0, islf=islf(γ, k))

Create the wideband admissibility condition for wavenumber k.

Passed as isnear to PetrovGalerkinNCA it leads to a directional H²-matrix. With the diameters d of two clusters and their distance dist, the pair is in the low-frequency regime if k * min(d) <= γ. It is far (admissible) if

• max(d) <= ηlf * dist in the low-frequency regime,
• k * max(d)^2 <= ηhf * dist in the high-frequency regime.

All parameters are stored as float(typeof(k)), so the wavenumber alone fixes the element type.

Arguments

• k::Real: wavenumber.

Keyword Arguments

• ηlf::Real = 1.0: admissibility parameter for the low-frequency branch.
• ηhf::Real = 5.0: admissibility parameter for the high-frequency branch.
• γ::Real = 1.0: threshold used by the default low-frequency classifier (see islf); ignored if islf is passed explicitly.
• islf = islf(γ, k): low-frequency classifier deciding, per node, which branch applies.

Returns

• IsNearWidebandFunctor.

nearmatrix(h2mat::PetrovGalerkinNCA)

Return the near field of h2mat as a block-sparse matrix.

nestedtestbasis(tvalues, pivots, buffer)
nestedtrialbasis(svalues, pivots, buffer)

Compute the basis of a leaf cluster from the pivot columns (rows) of the matrix stored in buffer.

With the row pivots τ and the column pivots σ of a test cluster t the basis is A[t, σ] * inv(A[τ, σ]), for a trial cluster s it is inv(A[τ, σ]) * A[τ, s].

Arguments

• tvalues, svalues: indices of the cluster
• pivots: pivots of the cluster, τ on the test and σ on the trial side
• buffer: the first length(pivots) columns (rows) hold A[:, σ] (A[τ, :])

nestedtestbasis(tvalues, pivots, buffer)
nestedtrialbasis(svalues, pivots, buffer)

Compute the basis of a leaf cluster from the pivot columns (rows) of the matrix stored in buffer.

With the row pivots τ and the column pivots σ of a test cluster t the basis is A[t, σ] * inv(A[τ, σ]), for a trial cluster s it is inv(A[τ, σ]) * A[τ, s].

Arguments

• tvalues, svalues: indices of the cluster
• pivots: pivots of the cluster, τ on the test and σ on the trial side
• buffer: the first length(pivots) columns (rows) hold A[:, σ] (A[τ, :])

storage(h2mat::PetrovGalerkinNCA)

Print the memory footprint of h2mat and its compression ratio with respect to the dense matrix.

Counts the entries of the near field, the coupling and transfer matrices, and the leaf bases.

Returns

• Storage of these entries in GB.

testbases(compressor, farmatrix, tree, fardata; ntasks, maxrank, pbar)
trialbases(compressor, farmatrix, tree, fardata; ntasks, maxrank, pbar)

Build the nested bases and transfer matrices of the test or the trial side.

Interface of the compressors: TopDown, BottomUp, and BatchedBottomUp implement both functions for FarData, BottomUp also for DirectionalData.

Arguments

• compressor: compressor that selects the pivots
• farmatrix: kernel matrix for the evaluation of far-field entries
• tree: block tree
• fardata: far interactions of the side that is compressed

Keyword Arguments

• ntasks::Integer: number of parallel tasks; ntasks = 1 runs on the calling task
• maxrank::Int: maximum number of pivots of a cluster
• pbar: progress bar

Returns

• basisstore: leaf bases, see BasisStore
• transferstore: transfer matrices, see TransferStore
• pivots: pivots of each cluster (or of each cluster and direction)

Notes

A new compressor additionally implements _basesworkload(compressor, tree, fardata), which sizes the progress bar.

testtransfer(rows, childrows, buf)
trialtransfer(cols, childcols, buf)

Compute the transfer matrix between a cluster and one of its children.

With the pivots τ, σ of the cluster and the pivots τc (σc) of the child, the transfer matrix is A[τc, σ] * inv(A[τ, σ]) on the test side and inv(A[τ, σ]) * A[τ, σc] on the trial side. As for the leaf bases, buf holds the pivot columns (rows) of the cluster.

testbases(compressor, farmatrix, tree, fardata; ntasks, maxrank, pbar)
trialbases(compressor, farmatrix, tree, fardata; ntasks, maxrank, pbar)

Build the nested bases and transfer matrices of the test or the trial side.

Interface of the compressors: TopDown, BottomUp, and BatchedBottomUp implement both functions for FarData, BottomUp also for DirectionalData.

Arguments

• compressor: compressor that selects the pivots
• farmatrix: kernel matrix for the evaluation of far-field entries
• tree: block tree
• fardata: far interactions of the side that is compressed

Keyword Arguments

• ntasks::Integer: number of parallel tasks; ntasks = 1 runs on the calling task
• maxrank::Int: maximum number of pivots of a cluster
• pbar: progress bar

Returns

• basisstore: leaf bases, see BasisStore
• transferstore: transfer matrices, see TransferStore
• pivots: pivots of each cluster (or of each cluster and direction)

Notes

A new compressor additionally implements _basesworkload(compressor, tree, fardata), which sizes the progress bar.

testtransfer(rows, childrows, buf)
trialtransfer(cols, childcols, buf)

Compute the transfer matrix between a cluster and one of its children.

With the pivots τ, σ of the cluster and the pivots τc (σc) of the child, the transfer matrix is A[τc, σ] * inv(A[τ, σ]) on the test side and inv(A[τ, σ]) * A[τ, σc] on the trial side. As for the leaf bases, buf holds the pivot columns (rows) of the cluster.