API Reference

assemble(op, testspace, trialspace; tree=..., quadstrat=..., kwargs...)

Assemble a hierarchical matrix with automatic tree-based blocking.

High-level convenience function that automatically constructs a hierarchical clustering tree and assembles the complete HMatrix with near and far-field blocks. This is the recommended entry point for most applications.

Arguments

• op: Operator/kernel for matrix entry evaluation

• testspace: Test space (row basis/points)

• trialspace: Trial space (column basis/points)

• tree: Hierarchical tree structure. Auto-generated from AdaptiveCrossApproximation.defaulttreebackend() if not provided: a H2Trees.TwoNTree when only H2Trees.jl is loaded, or a k-means clustered tree when ParallelKMeans.jl is loaded alongside it.

• treekwargs: Keyword arguments forwarded to the automatic tree construction (e.g. minvalues, numberofclusters for the k-means backend); ignored if tree is given explicitly.

• quadstrat: Quadrature strategy, matching BEAST.assemble's keyword of the same name. Defaults like BEAST.defaultquadstrat(op, testspace, trialspace) for BEAST operators (via the ACABEAST extension).

• nearquadstrat: Quadrature strategy for near-field (dense) blocks. Defaults to quadstrat.

• farquadstrat: Quadrature strategy for far-field (compressed, admissible) blocks. Defaults to tofarquadstrat(quadstrat), which strips singular-quadrature handling since far blocks are always well-separated.

• kwargs...: Additional parameters passed to HMatrix:

  • tol: Convergence tolerance (default 1e-4)
  • maxrank: Maximum rank for compression (default 40)
  • compressor: ACA or IACA instance (default ACA(tol=tol))
  • isnear: Admissibility predicate (default isnear())
  • spaceordering: Space ordering strategy (default PreserveSpaceOrder())
  • verbose: Enable progress output (default true)

Returns

• HMatrix: Assembled hierarchical matrix ready for matrix-vector products

Notes

Requires H2Trees.jl to be loaded for automatic tree generation. If providing a custom tree, ensure it implements the tree interface expected by HMatrix assembly. For operators whose matrix is cheap to build directly and never benefits from low-rank compression (e.g. BEAST's local operators Identity/NCross), the ACABEAST extension adds a more specific assemble method that bypasses tree construction and ACA entirely, calling BEAST.assemble directly.

Examples

# With BEAST boundary integral operators
hmat = AdaptiveCrossApproximation.assemble(op, testspace, trialspace; tol=1e-5, maxrank=100)
y = hmat * x  # Efficient matrix-vector product

See also

HMatrix

AdaptiveCrossApproximation

Adaptive Cross Approximation (ACA) algorithms for hierarchical low-rank matrix compression.

Provides full-rank and incomplete adaptive cross approximation algorithms optimized for boundary integral operators and other kernel-based matrices. Key features:

• ACA: Standard adaptive cross approximation selecting pivots by alternating rows/columns
• IACA: Incomplete variant for geometric pivoting in hierarchical matrix construction
• HMatrix: Hierarchical matrix representation combining dense near-field and low-rank far-field blocks
• Pivoting strategies: Maximum value, geometric (Leja, Fill Distance, Mimicry), random sampling
• Convergence criteria: Frobenius norm estimation, random sampling, extrapolation, combined criteria
• Kernel matrices: Support for BEAST boundary integral operators and point-based kernels

Main API

Compressors:

• ACA: Standard row-first variant
• ACAᵀ: Column-first variant (dual of ACA)
• IACA: Incomplete variant for geometric pivoting and hierarchical matrices
• aca: Convenience function for matrix compression

Hierarchical matrices:

• HMatrix: Hierarchical matrix type
• AdaptiveCrossApproximation.assemble: Automatic assembly with tree-based blocking
• nearmatrix, farmatrix: Extract system components

Pivoting strategies:

• MaximumValue: Partial pivoting (largest absolute value)
• Leja2: Modified Leja point selection
• FillDistance: Geometric fill distance minimization
• MimicryPivoting: Distributional mimicry without full matrix access
• TreeMimicryPivoting: Tree-aware variant for H²-matrices

Convergence criteria:

• FNormEstimator: Frobenius norm-based stopping (ACA and IACA paths)
• FNormExtrapolator: Extrapolation-enhanced convergence detection
• PhaseExtrapolator: Multi-phase extrapolation for geometric pivoting
• RandomSampling: Random sampling-based convergence

Kernel matrices:

• AbstractKernelMatrix: Interface for lazy matrix entry evaluation
• PointMatrix: Point cloud kernel matrices
• BEASTKernelMatrix: BEAST boundary integral operator matrices

Example

using AdaptiveCrossApproximation

# Compress a matrix with default settings
U, V = aca(M; tol=1e-4, maxrank=50)
approx = U * V

# Or build an HMatrix with automatic tree-based blocking
hmat = AdaptiveCrossApproximation.assemble(operator, testspace, trialspace)
y = hmat * x  # Matrix-vector product

See also

• BEAST.jl for boundary integral operators
• H2Trees.jl for hierarchical clustering
• BlockSparseMatrices.jl for sparse block storage

ACA{RowPivType,ColPivType,ConvCritType}

Adaptive Cross Approximation (ACA) compressor for low-rank matrix approximation.

Computes M ≈ U * V by iteratively selecting rows and columns (pivots) until a convergence criterion is met. The algorithm starts with row, samples it to select a column pivot, then alternates between row and column selection.

Fields

• rowpivoting::RowPivType: Strategy for selecting row pivots
• columnpivoting::ColPivType: Strategy for selecting column pivots
• convergence::ConvCritType: Convergence criterion to stop iterations

ACA(; tol=1e-4, rowpivoting=MaximumValue(), columnpivoting=MaximumValue(),
    convergence=FNormEstimator(tol))

Build an ACA compressor from keyword arguments.

This is the constructor most users call directly (e.g. ACA(tol=1e-4) or ACA(rowpivoting=Leja2(pos))); convergence defaults to FNormEstimator(tol) so passing tol alone is usually enough.

Keyword Arguments

• tol::Real = 1e-4: Tolerance used to build the default convergence criterion. Ignored if convergence is passed explicitly.
• rowpivoting = MaximumValue(): Row pivot selection strategy.
• columnpivoting = MaximumValue(): Column pivot selection strategy.
• convergence = FNormEstimator(tol): Convergence criterion to stop iterations.

(aca::ACA)(A, colbuffer, rowbuffer, rows, cols, rowidcs, colidcs, maxrank)

Compute ACA approximation with preallocated buffers (main computational routine).

Fills colbuffer and rowbuffer with low-rank factors U and V such that A[rowidcs, colidcs] ≈ U * V. Uses deflation to ensure orthogonality of pivots.

Arguments

• A: Matrix or matrix-like object (must support nextrc! interface)
• colbuffer::AbstractArray{K}: Buffer for U factors, size (length(rowidcs), maxrank)
• rowbuffer::AbstractArray{K}: Buffer for V factors, size (maxrank, length(colidcs))
• rows::Vector{Int}: Storage for selected row indices
• cols::Vector{Int}: Storage for selected column indices
• rowidcs::Vector{Int}: Global row indices of the block to compress
• colidcs::Vector{Int}: Global column indices of the block to compress
• maxrank::Int: Maximum number of pivots (hard limit on rank)

Returns

• npivot::Int: Number of pivots computed (≤ maxrank). The approximation is A[rowidcs, colidcs] ≈ colbuffer[:, 1:npivot] * rowbuffer[1:npivot, :]

ACAᵀ{RowPivType,ColPivType,ConvCritType}

Column-first variant of adaptive cross approximation. Starts by selecting columns first, then rows. Dual of standard ACA.

Fields

• rowpivoting::RowPivType: Strategy for selecting row pivots
• columnpivoting::ColPivType: Strategy for selecting column pivots
• convergence::ConvCritType: Convergence criterion

ACAᵀ(; tol=1e-4, rowpivoting=MaximumValue(), columnpivoting=MaximumValue(),
    convergence=FNormEstimator(tol))

Build an ACAᵀ compressor from keyword arguments.

This is the constructor most users call directly, mirroring ACA's keyword constructor; convergence defaults to FNormEstimator(tol) so passing tol alone is usually enough.

Keyword Arguments

• tol::Real = 1e-4: Tolerance used to build the default convergence criterion. Ignored if convergence is passed explicitly.
• rowpivoting = MaximumValue(): Row pivot selection strategy.
• columnpivoting = MaximumValue(): Column pivot selection strategy.
• convergence = FNormEstimator(tol): Convergence criterion to stop iterations.

(aca::ACAᵀ)(A, colbuffer, rowbuffer, rows, cols, rowidcs, colidcs, maxrank)

Compute column-first ACA approximation with preallocated buffers (main computational routine).

Fills colbuffer and rowbuffer with low-rank factors U and V such that A[rowidcs, colidcs] ≈ U * V. Uses deflation to ensure orthogonality of pivots.

Arguments

• A: Matrix or matrix-like object (must support nextrc! interface)
• colbuffer::AbstractArray{K}: Buffer for U factors, size (length(rowidcs), maxrank)
• rowbuffer::AbstractArray{K}: Buffer for V factors, size (maxrank, length(colidcs))
• rows::Vector{Int}: Storage for selected row indices
• cols::Vector{Int}: Storage for selected column indices
• rowidcs::Vector{Int}: Global row indices of the block to compress
• colidcs::Vector{Int}: Global column indices of the block to compress
• maxrank::Int: Maximum number of pivots (hard limit on rank)

Returns

• npivot::Int: Number of pivots computed (≤ maxrank). The approximation is A[rowidcs, colidcs] ≈ colbuffer[:, 1:npivot] * rowbuffer[1:npivot, :]

AbstractKernelMatrix{T}

Abstract matrix-like interface for kernel-based entry evaluation used by ACA-style compressors.

Arguments

• T: scalar element type returned by kernel evaluations

Returns

A subtype that supports lazy matrix entry access through the kernel matrix interface.

Notes

Implement this type when matrix entries are computed on demand from geometric/operator data.

See also

AbstractKernelMatrix(operator, testspace, trialspace; args...)

AbstractKernelMatrix(operator, testspace::AbstractVector, trialspace::AbstractVector; args...)

Create a PointMatrix kernel wrapper from vector point data and operator.

Constructs a PointMatrix when given vector collections of test and trial points. Matches the exported AbstractKernelMatrix factory interface to provide point-based kernel evaluation.

Arguments

• operator: kernel function or operator
• testspace::AbstractVector: test point locations (indexed collection)
• trialspace::AbstractVector: trial point locations (indexed collection)
• args...: additional keyword arguments (unused for point-based evaluation)

Returns

• PointMatrix with element type inferred from operator

AbstractKernelMatrix(operator, testspace, trialspace; args...)

Construct a concrete kernel matrix wrapper from operator and space data.

Arguments

• operator: operator or kernel definition
• testspace: space for row evaluation points or basis data
• trialspace: space for column evaluation points or basis data
• args...: backend-specific keyword arguments

Returns

A concrete subtype of AbstractKernelMatrix provided by method dispatch.

Notes

This declaration defines the interface entry point. Concrete backends provide specialized methods for specific operator/space types.

See also

AbstractKernelMatrix, nextrc!

AbstractKernelMatrix(operator::Function, testspace::AbstractVector, trialspace::AbstractVector; args...)

Create a PointMatrix from a plain Julia function kernel (with warning).

Provides fallback support for plain function kernels. Issues a warning as operators with structure (kernels, boundary integral operators) are typically preferred for better performance and correctness.

Arguments

• operator::Function: plain Julia function with signature operator(testpoint, trialpoint)
• testspace::AbstractVector: test point locations (indexed collection)
• trialspace::AbstractVector: trial point locations (indexed collection)
• args...: additional keyword arguments (unused)

Returns

• PointMatrix with element type inferred from function evaluation

BEASTKernelMatrix{T,NearBlockAssemblerType} <: AbstractKernelMatrix{T}

Kernel matrix wrapper for BEAST operator assembly.

Provides lazy matrix entry evaluation through a BEAST near-field block assembler, which computes matrix entries on demand from operator and basis function data.

Fields

• nearassembler::NearBlockAssemblerType: BEAST assembler providing matrix entries

Type parameters

• T: scalar element type returned by kernel evaluations
• NearBlockAssemblerType: type of the underlying BEAST assembler

CombinedConvCrit

Composite convergence criterion combining multiple criteria. Stops only when ALL constituent criteria have signaled convergence (AND logic).

Fields

• crits::Vector{ConvCrit}: Vector of convergence criteria to combine

CombinedPivStrat

Composite pivoting strategy that switches between multiple strategies based on convergence.

Combines multiple pivoting strategies with a combined convergence criterion, allowing the pivot selection method to change as different convergence criteria are satisfied. For example, can start with geometric pivoting and switch to value-based pivoting once a certain accuracy is reached.

Fields

• strats::Vector{PivStrat}: Ordered list of pivoting strategies to use

ConvCrit

Abstract base type for convergence criteria used by ACA and IACA compressors.

Notes

Concrete subtypes define how stopping decisions are made and are converted into stateful ConvCritFunctor objects during block compression.

See also

ConvCritFunctor, FNormEstimator, FNormExtrapolator, PhaseExtrapolator, RandomSampling

ConvCritFunctor

Abstract base type for stateful convergence criterion functors.

Notes

Instances are called during ACA iterations and return (npivot, continue::Bool). Subtypes should implement reset! to reinitialize internal state for a new block.

See also

ConvCrit, reset!, normF!

ConvPivStrat <: PivStrat

Abstract type for convergence-driven pivoting strategies.

These strategies adapt their behavior based on convergence information or use randomization to improve robustness.

Concrete Types

• RandomSampling: Random pivot selection for convergence estimation

ConvPivStratFunctor <: PivStratFunctor

Abstract type for stateful convergence-driven pivoting functors.

DirectionFilter

Direction/orientation filter for TreeMimicryPivoting. Restricts descent and pivot selection to basis functions of the currently active direction, cycling through directions in phases. Built through TreeMimicryPivoting2.

Fields

• edgedirections::Vector{Int32}: per-index edge-direction group id
• basisdirections::Vector{Int32}: per-index normal-direction group id
• nodedirectionids::Vector{Vector{Int32}}: dominant direction ids per tree node

DirectionFilterState{CC}

Per-factorization state of a DirectionFilter: the shared convergence criterion plus the set of directions whose phase has finished.

FNormEstimator{F} <: ConvCrit

Frobenius norm-based convergence criterion for ACA and IACA.

Dispatches on input type: matrix arguments follow the ACA path (accumulated Frobenius norm), vector arguments follow the IACA path (moving-average norm).

Fields

• tol::F: Relative tolerance threshold

FNormExtrapolator{F} <: ConvCrit

Convergence criterion using polynomial extrapolation of pivot norms. Combines norm estimation with quadratic extrapolation to predict convergence.

Fields

• estimator::FNormEstimator{F}: Underlying norm estimator

FNormExtrapolator(tol::F)

Construct extrapolator with Frobenius norm estimator.

Arguments

• tol::F: Convergence tolerance

FillDistance{D,F<:Real} <: GeoPivStrat

Geometric pivoting strategy based on fill distance minimization.

Selects pivots to minimize the fill distance, promoting well-distributed sampling in geometric space.

Fields

• pos::Vector{SVector{D,F}}: Geometric positions of all points (D-dimensional)

Type Parameters

• D: Spatial dimension
• F: Floating point type for coordinates

GPUBEASTKernelMatrix{T,NearBlockAssemblerType} <: AbstractKernelMatrix{T}

Kernel matrix backed by a GPU-resident BEAST near-field assembler.

Built by the ACABEASTCUDA extension from a BEAST operator and space pair; entries are evaluated by delegating to nearassembler, which handles device transfer and batched GPU quadrature internally.

GPUMatrixData{QuadStratType}

Matrix-data marker requesting GPU-accelerated near-field assembly.

Wraps a quadstrat together with ndevices, the number of GPU devices to distribute near-field work across; recognized by the ACABEASTCUDA extension when building a GPUBEASTKernelMatrix.

GeoPivStrat <: PivStrat

Abstract type for geometric/spatial pivoting strategies.

These strategies select pivots based on spatial/geometric properties rather than matrix values. Useful when geometric information about rows/columns is available.

Concrete Types

• FillDistance: Maximizes minimum distance to already selected points
• Leja2: Maximizes product of distances to selected points

GeoPivStratFunctor <: PivStratFunctor

Abstract type for stateful geometric pivoting functors.

H2Tree <: AbstractTree

Tree backend marker selecting H2Trees.jl's TwoNTree clustering, built by the ACAH2Trees extension.

HMatrix{K,NearInteractionType,FarInteractionType}

Hierarchical matrix that stores near-field interactions explicitly and far-field interactions as low-rank block data.

Arguments

• nearinteractions: block-sparse near-field contribution
• farinteractions: collection of compressed far-field interaction blocks
• dim::Tuple{Int,Int}: matrix dimensions (m, n)

Returns

An HMatrix linear map that supports matrix-vector products and conversion to a dense matrix via Matrix.

Notes

HMatrix is typically created through the high-level constructor HMatrix(operator, testspace, trialspace, tree; kwargs...) or assemble(...).

See also

HMatrix, assemble, farmatrix, nearmatrix

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

Assemble a hierarchical matrix approximation of an operator on test and trial spaces.

Arguments

• operator: bilinear form or kernel operator used for matrix entry evaluation
• testspace: test space used for row indexing
• trialspace: trial space used for column indexing
• tree: hierarchical clustering/tree structure controlling block partitioning
• tol: compression tolerance (default 1e-4)
• compressor: ACA-style compressor, e.g. ACA(; tol=tol)
• isnear: near-field predicate controlling admissibility
• maxrank: maximum rank for far-field block compression
• spaceordering: strategy for applying tree permutations to spaces
• nearmatrixdata: optional data passed to near-field assembly
• farmatrixdata: optional data passed to far-field assembly
• scheduler: thread scheduler used for assembly
• verbose: enable progress output for near- and far-field assembly (default true)

Returns

An HMatrix containing assembled near and far interactions.

Notes

Use this constructor as the main entry point when you already have a tree. For a convenience entry point, use assemble.

See also

assemble, ACA, IACA, farmatrix, nearmatrix

IACA{RowPivType,ColPivType,ConvCritType}

Incomplete Adaptive Cross Approximation (IACA) compressor.

Unlike standard ACA, IACA computes only one side per iteration and relies on geometric pivoting strategies (for example mimicry or tree mimicry) to select pivots from spatial information. This reduces matrix entry evaluations in hierarchical matrix construction, where only selected row or column samples are required.

Fields

• rowpivoting::RowPivType: Strategy for selecting row pivots (geometric)
• columnpivoting::ColPivType: Strategy for selecting column pivots
• convergence::ConvCritType: Convergence criterion

IACA(tpos, spos)

Create a default incomplete ACA compressor for geometrically indexed row/column sets.

Arguments

• tpos::Vector{SVector{D,F}}: geometric positions for test indices
• spos::Vector{SVector{D,F}}: geometric positions for trial indices

Returns

An IACA instance using MaximumValue/MimicryPivoting with FNormExtrapolator.

See also

IACA, MimicryPivoting, FNormExtrapolator

(iaca::IACA{ValuePivStratFunctor,GeoPivStratFunctor,ConvCritFunctor})(A, colbuffer, rowbuffer, maxrank, rows, cols, rowidcs)

Main computational routine for column matrix IACA (value-based row pivoting, geometric column pivoting). Performs incomplete ACA compression where columns are selected geometrically and rows by maximum value.

Arguments

• A: Matrix to compress
• colbuffer::AbstractArray{K}: Buffer for column data
• rowbuffer::AbstractArray{K}: Buffer for row data
• maxrank::Int: Maximum rank
• rows::Vector{Int}: Row indices storage
• cols::Vector{Int}: Column indices storage
• rowidcs::Vector{Int}: Row index range

Returns

• npivot::Int: Number of pivots computed
• rows::Vector{Int}: Selected row indices (global)
• cols::Vector{Int}: Selected column indices

(iaca::IACA{GeoPivStratFunctor,ValuePivStratFunctor,ConvCritFunctor})(A, colbuffer, rowbuffer, maxrank, rows, cols, colidcs)

Main computational routine for row matrix IACA (geometric row pivoting, value-based column pivoting). Performs incomplete ACA compression where rows are selected geometrically and columns by maximum value.

Arguments

• A: Matrix to compress
• colbuffer::AbstractMatrix{K}: Buffer for column data
• rowbuffer::AbstractMatrix{K}: Buffer for row data
• maxrank::Int: Maximum rank
• rows::Vector{Int}: Row indices storage
• cols::Vector{Int}: Column indices storage
• colidcs::Vector{Int}: Column index range

Returns

• npivot::Int: Number of pivots computed
• rows::Vector{Int}: Selected row indices
• cols::Vector{Int}: Selected column indices (global)

KMeansTreeBackend <: AbstractTree

Tree backend marker selecting k-means clustering (via ParallelKMeans.jl), built by the ACAParallelKMeansTrees extension.

Leja2{D,F<:Real} <: GeoPivStrat

Geometric pivoting strategy based on Leja points (product of distances).

A modified more efficient version of the fill distance approach. This leads to well-separated point sequences. These points have been introduced as modified leja points and will, therefore, be referred to as Leja2 points within this package.

Fields

• pos::Vector{SVector{D,F}}: Geometric positions of all points (D-dimensional)

Type Parameters

• D: Spatial dimension
• F: Floating point type for coordinates

LowRankMatrix{K} <: LinearMaps.LinearMap{K}

Efficient storage and evaluation of low-rank matrix blocks as U*V.

Stores left and right factors separately, performing matrix-vector products as (U*V)*x = U*(V*x) to avoid forming the dense U*V product. Critical for efficient hierarchical matrix computations where blocks are stored in low-rank form.

Fields

• U::Matrix{K}: Left factor, size (m, r) where r is the rank
• V::Matrix{K}: Right factor, size (r, n)
• z::Vector{K}: Temporary buffer for intermediate products V*x

Type parameters

• K: scalar element type

Notes

Create via LowRankMatrix(U, V) which allocates the temporary buffer automatically. Block dimensions are (m, n) = (size(U, 1), size(V, 2)).

MaximumValue <: ValuePivStrat

Pivoting strategy that selects the index with maximum absolute value.

This is the standard pivoting strategy used in classical ACA algorithms also referred to as partial pivoting. At each iteration, it chooses the row or column with the largest absolute value among the unused indices, ensuring numerical stability and good approximation quality.

MimicryPivoting{D,F<:Real} <: GeoPivStrat

Geometric pivoting strategy that mimics point distribution of a fully pivoted ACA geometrically.

Selects pivots to reproduce the spatial distribution of a fully pivoted ACA. The strategy balances three objectives: geometric separation (Leja-like behavior), proximity to the reference distribution, and fill distance maximization. Particularly useful for H²–matrix compression where incomplete factorizations are sufficient.

Fields

• refpos::Vector{SVector{D,F}}: Positions of test or expansion domain
• pos::Vector{SVector{D,F}}: Positions from which to select pivots

Type Parameters

• D: Spatial dimension
• F: Floating point type for coordinates

(pivstrat::MimicryPivotingFunctor)(npivot::Int)

Select the next pivot by index count rather than residual data, as used by IACA.

Note that unlike TreeMimicryPivoting, MimicryPivoting resolves pivots to positions in the idcs array it was built with, not to global indices; it is therefore only valid within IACA when the corresponding row/column index range is the identity range 1:n (i.e. MimicryPivoting is not usable for nested/sub-block compression).

NoFilter

Identity pivot filter: accepts every node and index, assigns unit weight and runs a single (directionless) phase. Recovers the plain tree-mimicry pivoting behaviour.

NoFilterState

Per-factorization state of NoFilter; stateless.

PermuteSpaceInPlace <: SpaceOrderingStyle

spaceordering style that permutes testspace/trialspace in place to match the tree's internal point ordering, rather than leaving them untouched.

Pass as HMatrix(...; spaceordering=PermuteSpaceInPlace()). Useful when downstream code expects a space physically reordered to tree order; compare with the default PreserveSpaceOrder.

PhaseExtrapolator{F} <: ConvCrit

Convergence criterion using polynomial extrapolation of pivot norms across multiple phases.

Extends FNormExtrapolator with per-phase direction tracking: convergence requires that all active phases individually show extrapolated convergence, and that two consecutive pivots both satisfy the criterion.

Fields

• estimator::FNormEstimator{F}: Underlying norm estimator

See also

FNormExtrapolator, PhaseExtrapolatorFunctor, reset_phase!

PhaseExtrapolator(tol::F)

Construct a phase extrapolator with the given tolerance.

PhaseExtrapolatorFunctor{F} <: ConvCritFunctor

Stateful functor for PhaseExtrapolator.

Tracks per-pivot norms and their associated phases, fitting a quadratic polynomial to predict convergence. Requires two consecutive converging pivots before stopping.

Fields

• estimator::FNormEstimatorFunctor{F}: Moving-average norm state
• lastnorms::Vector{F}: Per-pivot norms, indexed by pivot number
• normdirections::Vector{Int32}: Phase label for each pivot
• lastconverged::Bool: Whether the previous pivot also converged
• currentdirection::Int32: Phase label currently active (set via reset_phase!)

PivStrat

Abstract base type for pivoting strategies in cross approximation algorithms.

Pivoting strategies determine which row or column to select at each iteration of the ACA algorithm. Concrete subtypes are typically stateless and callable, creating stateful PivStratFunctor instances when invoked with index information.

Subtypes by Category

• GeoPivStrat: Geometric strategies (e.g., fill distance, Leja points)
• ValuePivStrat: Value-based strategies (e.g., maximum absolute value)
• ConvPivStrat: Convergence-driven strategies (e.g., random sampling)

Interface

Concrete subtypes should implement:

• (strategy::MyPivStrat)(len::Int): Create functor for len indices
• (strategy::MyPivStrat)(idcs::AbstractArray{Int}): Create functor for index array

PivStratFunctor

Abstract base type for stateful pivoting functors.

Functors maintain state during the pivot selection process (e.g., tracking which indices have been used). Created by calling a PivStrat instance with index information.

Interface

Concrete subtypes should implement:

• (functor::MyPivStratFunctor)(): Select initial pivot (no data available)
• (functor::MyPivStratFunctor)(rc::AbstractArray): Select next pivot based on row/column data

PointMatrix{T,FunctorType,PointCollectionType} <: AbstractKernelMatrix{T}

Kernel matrix evaluating entries from a kernel functor and point collections.

Stores point sample locations and a kernel function, computing matrix entries on demand by evaluating the kernel at test and trial point pairs. Useful for point cloud interactions or problems with explicit coordinate data.

Fields

• functor::FunctorType: Kernel function or operator to evaluate
• testpoints::PointCollectionType: Test space point locations
• trialpoints::PointCollectionType: Trial space point locations

Type parameters

• T: scalar element type returned by kernel evaluations
• FunctorType: type of the kernel functor
• PointCollectionType: type of point collections (e.g., Vector, AbstractArray)

PreserveSpaceOrder <: SpaceOrderingStyle

spaceordering style that leaves testspace/trialspace untouched; block assembly indexes through the tree's permutation instead. This is the default for HMatrix(...; spaceordering=PreserveSpaceOrder()). Compare with PermuteSpaceInPlace.

RandomSampling{F<:Real} <: ConvCrit

Convergence criterion based on random matrix entry sampling. Monitors approximation error at randomly sampled positions.

Fields

• nsamples::Int: Number of random samples to take
• factor::F: Factor for automatic sample count (nsamples = factor * (nrows + ncols))
• tol::F: Convergence tolerance

RandomSampling(; factor=1.0, nsamples=0, tol=1e-4)

Construct random sampling convergence criterion.

Arguments

• factor::F: Multiplier for automatic sample count (default: 1.0)
• nsamples::Int: Fixed sample count (default: 0, use factor instead)
• tol::F: Convergence tolerance (default: 1e-4)

RandomSamplingPivoting <: ConvPivStrat

Pivoting strategy that uses the error of random sampling from the convergence estimation.

Instead of selecting pivots based on maximum values or geometric properties, this strategy chooses pivots from randomly sampled indices used by a random sampling convergence criterion. Works in conjunction with the random-sampling convergence functor to provide statistically based pivot selection.

Fields

• rc::Int: Index indicating which coordinate (row=1 or column=2) to select from

SpaceOrderingStyle

Abstract type selecting how test/trial spaces are reconciled with a tree's internal point ordering during HMatrix assembly.

Concrete Types

• PreserveSpaceOrder: Leave spaces untouched, index through the tree's permutation instead (the default).
• PermuteSpaceInPlace: Physically permute spaces to match tree order.

TreeMimicryPivoting{D,T,TreeType,Filter} <: GeoPivStrat

Tree-aware mimicry pivoting strategy.

This strategy adapts the MimicryPivoting idea to a hierarchical tree of clusters. Instead of selecting individual points directly, it navigates the tree to pick clusters and then nodes within those clusters so that the selected pivots mimic a reference distribution at multiple scales.

A pluggable Filter restricts the tree descent and the pivot selection. The default NoFilter accepts every node and index, recovering the plain geometric strategy. TreeMimicryPivoting2 plugs in a direction filter that groups basis functions by orientation and rotates through them in phases.

Fields

• refpos::Vector{SVector{D,T}}: Reference positions to mimic (e.g., parent pivots)
• pos::Vector{SVector{D,T}}: Candidate point positions
• tree::TreeType: Tree providing cluster centers, children and values
• filter::Filter: Restriction on descent and pivot selection

Type parameters

• D: spatial dimension
• T: numeric type for coordinates
• TreeType: tree adapter (must implement center, values, children, firstchild)
• Filter: filter type, statically dispatched in the per-pivot hot loops

TreeMimicryPivoting(refpos, pos, tree)

Build a TreeMimicryPivoting strategy with the default NoFilter, i.e. plain tree-aware mimicry pivoting with no directional restriction.

Arguments

• refpos::Vector{SVector{D,T}}: Reference positions to mimic (e.g., parent pivots).
• pos::Vector{SVector{D,T}}: Candidate point positions.
• tree: Tree adapter providing center, values, children and firstchild (the ACAH2Trees extension supplies a ready-made adapter for H2Trees.TwoNTree).

ValuePivStrat <: PivStrat

Abstract type for value-based pivoting strategies.

These strategies select pivots based on matrix element values sampled during the ACA algorithm. Most common approach for general matrices.

Concrete Types

• MaximumValue: Selects index with maximum absolute value (standard ACA)
• RandomSampling: Random selection (for statistical approaches)

ValuePivStratFunctor <: PivStratFunctor

Abstract type for stateful value-based pivoting functors.

LevelIterator(tree, level)

Return an iterator over the nodes of tree at level.

Part of the tree backend interface required by HMatrix assembly; used together with levels to drive near/far-field block assembly level by level.

TreeMimicryPivoting2(refpos, pos, edgedirections, basisdirections, nodedirectionids, tree)

Tree-mimicry pivoting with a DirectionFilter: pivots mimic the reference distribution while cycling through orientation groups in phases.

aca(M; tol=1e-4, rowpivoting=MaximumValue(), columnpivoting=MaximumValue(),
    convergence=FNormEstimator(tol), maxrank=40, svdrecompress=false)

Compute adaptive cross approximation of matrix M returning low-rank factors.

High-level convenience function that automatically allocates buffers and returns U, V such that M ≈ U * V.

Arguments

• M::AbstractMatrix{K}: Matrix to approximate

Keyword Arguments

• tol::Real = 1e-4: Approximation tolerance
• rowpivoting = MaximumValue(): Row pivot selection strategy
• columnpivoting = MaximumValue(): Column pivot selection strategy
• convergence = FNormEstimator(tol): Convergence criterion
• maxrank::Int = 40: Maximum rank (hard limit)
• svdrecompress::Bool = false: Apply SVD-based recompression to reduce rank further

Returns

• U::Matrix{K}: Left factor, size (size(M,1), r) where r ≤ maxrank
• V::Matrix{K}: Right factor, size (r, size(M,2))

Satisfies M ≈ U * V with norm(M - U*V) / norm(M) ≲ tol (if maxrank sufficient).

SVD Recompression

When svdrecompress=true, performs QR-SVD recompression: computes M ≈ U*V, then U = Q*R, R*V = Û*Σ*V̂ᵀ, truncates small singular values, and returns optimal rank factors at the cost of additional computation.

acaᵀ(M; tol=1e-4, rowpivoting=MaximumValue(), columnpivoting=MaximumValue(),
    convergence=FNormEstimator(tol), maxrank=40, svdrecompress=false)

Compute column-first adaptive cross approximation of matrix M returning low-rank factors.

High-level convenience function that automatically allocates buffers and returns U, V such that M ≈ U * V.

Arguments

• M::AbstractMatrix{K}: Matrix to approximate

Keyword Arguments

• tol::Real = 1e-4: Approximation tolerance
• rowpivoting = MaximumValue(): Row pivot selection strategy
• columnpivoting = MaximumValue(): Column pivot selection strategy
• convergence = FNormEstimator(tol): Convergence criterion
• maxrank::Int = 40: Maximum rank (hard limit)
• svdrecompress::Bool = false: Apply SVD-based recompression to reduce rank further

Returns

• U::Matrix{K}: Left factor, size (size(M,1), r) where r ≤ maxrank
• V::Matrix{K}: Right factor, size (r, size(M,2))

Satisfies M ≈ U * V with norm(M - U*V) / norm(M) ≲ tol (if maxrank sufficient).

SVD Recompression

When svdrecompress=true, performs QR-SVD recompression: computes M ≈ U*V, then U = Q*R, R*V = Û*Σ*V̂ᵀ, truncates small singular values, and returns optimal rank factors at the cost of additional computation.

assemble(op, testspace, trialspace; tree=..., quadstrat=..., kwargs...)

Assemble a hierarchical matrix with automatic tree-based blocking.

High-level convenience function that automatically constructs a hierarchical clustering tree and assembles the complete HMatrix with near and far-field blocks. This is the recommended entry point for most applications.

Arguments

• op: Operator/kernel for matrix entry evaluation

• testspace: Test space (row basis/points)

• trialspace: Trial space (column basis/points)

• tree: Hierarchical tree structure. Auto-generated from AdaptiveCrossApproximation.defaulttreebackend() if not provided: a H2Trees.TwoNTree when only H2Trees.jl is loaded, or a k-means clustered tree when ParallelKMeans.jl is loaded alongside it.

• treekwargs: Keyword arguments forwarded to the automatic tree construction (e.g. minvalues, numberofclusters for the k-means backend); ignored if tree is given explicitly.

• quadstrat: Quadrature strategy, matching BEAST.assemble's keyword of the same name. Defaults like BEAST.defaultquadstrat(op, testspace, trialspace) for BEAST operators (via the ACABEAST extension).

• nearquadstrat: Quadrature strategy for near-field (dense) blocks. Defaults to quadstrat.

• farquadstrat: Quadrature strategy for far-field (compressed, admissible) blocks. Defaults to tofarquadstrat(quadstrat), which strips singular-quadrature handling since far blocks are always well-separated.

• kwargs...: Additional parameters passed to HMatrix:

  • tol: Convergence tolerance (default 1e-4)
  • maxrank: Maximum rank for compression (default 40)
  • compressor: ACA or IACA instance (default ACA(tol=tol))
  • isnear: Admissibility predicate (default isnear())
  • spaceordering: Space ordering strategy (default PreserveSpaceOrder())
  • verbose: Enable progress output (default true)

Returns

• HMatrix: Assembled hierarchical matrix ready for matrix-vector products

Notes

Requires H2Trees.jl to be loaded for automatic tree generation. If providing a custom tree, ensure it implements the tree interface expected by HMatrix assembly. For operators whose matrix is cheap to build directly and never benefits from low-rank compression (e.g. BEAST's local operators Identity/NCross), the ACABEAST extension adds a more specific assemble method that bypasses tree construction and ACA entirely, calling BEAST.assemble directly.

Examples

# With BEAST boundary integral operators
hmat = AdaptiveCrossApproximation.assemble(op, testspace, trialspace; tol=1e-5, maxrank=100)
y = hmat * x  # Efficient matrix-vector product

See also

HMatrix

assemblefars(operator, testspace, trialspace, tree, ::PermuteSpaceInPlace; kwargs...)

Assemble far-field blocks with tree-aligned space reordering.

Compresses inadmissible cluster pairs using ACA-style algorithms, with both spaces permuted to align with the hierarchical tree structure. Produces a specialized storage format optimized for the reordered layout.

Arguments

• operator: Operator/kernel for matrix entry evaluation
• testspace: Test space (row basis) — will be reordered
• trialspace: Trial space (column basis) — will be reordered
• tree: Hierarchical tree structure
• ::PermuteSpaceInPlace: Space ordering strategy marker
• compressor = ACA(): Low-rank compressor algorithm
• isnear: Admissibility predicate (default: isnear())
• matrixdata: Assembly data passed to kernel matrix (optional)
• maxrank = 50: Maximum rank for compressed blocks
• scheduler: Thread scheduler (default: SerialScheduler())
• verbose: enable progress output (default true)

Returns

• Vector{VariableBlockCompressedRowStorage}: Level-wise compressed blocks in permuted layout

Notes

Called by HMatrix constructor when spaceordering=PermuteSpaceInPlace(). The spaces are reordered to match tree leaf ordering before compression, improving cache locality and reducing fragmentation. Returns specialized block storage optimized for permuted layout.

assemblefars(operator, testspace, trialspace, tree, ::PreserveSpaceOrder; kwargs...)

Assemble far-field blocks without reordering test and trial spaces.

Compresses inadmissible cluster pairs using ACA-style algorithms, maintaining the original space ordering. Produces a collection of level-by-level block-sparse matrices.

Arguments

• operator: Operator/kernel for matrix entry evaluation
• testspace: Test space (row basis/evaluation points)
• trialspace: Trial space (column basis/evaluation points)
• tree: Hierarchical tree structure controlling block layout
• ::PreserveSpaceOrder: Space ordering strategy marker
• compressor = ACA(): Low-rank compressor algorithm
• isnear: Admissibility predicate (default: isnear())
• matrixdata: Assembly data passed to kernel matrix (optional)
• maxrank = 50: Maximum rank for compressed blocks
• scheduler: Thread scheduler (default: SerialScheduler())
• verbose: enable progress output (default true)

Returns

• Vector{BlockSparseMatrix}: Collection of level-wise compressed blocks

Notes

Called by HMatrix constructor when spaceordering=PreserveSpaceOrder(). Iterates over tree levels, compressing each level's far-field interactions independently. Returns one sparse matrix per level, indexed by tree depth.

assemblenears(operator, testspace, trialspace, tree, ::PermuteSpaceInPlace; kwargs...)

Assemble near-field blocks with tree-aligned space reordering.

Computes dense matrix blocks for admissible cluster pairs, with both spaces permuted to align with the hierarchical tree structure. Produces a specialized block storage format optimized for the reordered layout.

Arguments

• operator: Operator/kernel for matrix entry evaluation
• testspace: Test space (row basis) — will be reordered
• trialspace: Trial space (column basis) — will be reordered
• tree: Hierarchical tree structure
• ::PermuteSpaceInPlace: Space ordering strategy marker
• isnear: Admissibility predicate (default: isnear())
• scheduler: Thread scheduler (default: SerialScheduler())
• matrixdata: Assembly data passed to kernel matrix (optional)
• verbose: enable progress output (default true)

Returns

• VariableBlockCompressedRowStorage: Permuted block-sparse near-field storage

Notes

Called by HMatrix constructor when spaceordering=PermuteSpaceInPlace(). The spaces are reordered to match tree leaf ordering before block assembly, improving cache locality and reducing block fragmentation.

assemblenears(operator, testspace, trialspace, tree, ::PreserveSpaceOrder; kwargs...)

Assemble near-field blocks without reordering test and trial spaces.

Computes dense (non-low-rank) matrix blocks for all admissible cluster pairs, retaining the original ordering of test and trial spaces. The resulting block-sparse matrix stores these near-field interactions.

Arguments

• operator: Operator/kernel for matrix entry evaluation
• testspace: Test space (row basis/evaluation points)
• trialspace: Trial space (column basis/evaluation points)
• tree: Hierarchical tree structure
• ::PreserveSpaceOrder: Space ordering strategy marker
• isnear: Admissibility predicate (default: isnear())
• scheduler: Thread scheduler (default: SerialScheduler())
• matrixdata: Assembly data passed to kernel matrix (optional)
• verbose: enable progress output (default true)

Returns

• BlockSparseMatrix: Block-sparse storage of near-field blocks

Notes

Called by HMatrix constructor when spaceordering=PreserveSpaceOrder(). Each near-field block is evaluated directly via the kernel matrix, avoiding compression.

basisfunction_orientation_ids(edges, normals; edge_digits=1, normal_digits=1)

Assign integer orientation-group ids to a set of basis functions from their edge directions and face normals.

Arguments

• edges: one direction vector per basis function (e.g. RWG edge directions)
• normals: one normal vector per basis function; zero vectors are treated as "no normal" and get id 0

Returns

• (edgeids, normalids, nedgeids, nnormalids): per-basis-function group ids for edges and normals (both Vector{Int32}), plus the number of distinct groups found for each. Directions that are antiparallel (up to rounding at digits decimal places) are assigned the same id, since only the underlying line matters for orientation grouping.

See also

node_normal_orientation_sets, orientation_ids, normal_orientation_ids

beastkernelmatrix(operator, testspace, trialspace, matrixdata)

Build a BEAST-backed kernel matrix (e.g. BEASTKernelMatrix or GPUBEASTKernelMatrix) from a BEAST operator, spaces, and matrixdata (a quadrature strategy, or a GPUMatrixData for GPU assembly).

No default method is provided here; it is implemented by the ACABEAST and ACABEASTCUDA package extensions and dispatched to from AbstractKernelMatrix(operator, testspace, trialspace; matrixdata=...) when BEAST types are detected.

center(tree, node::Int)

Return the spatial centroid of node in tree.

Part of the tree adapter interface required by TreeMimicryPivoting; implement this for a custom tree type.

children(tree, node::Int)

Return the child node indices of node in tree.

Part of the tree adapter interface required by TreeMimicryPivoting; implement this for a custom tree type.

defaulttreebackend()

Return the tree backend assemble uses when no tree is given explicitly.

Resolved at call time from which packages are loaded: KMeansTreeBackend if ParallelKMeans.jl is loaded alongside H2Trees.jl (via the ACAParallelKMeansTrees extension), otherwise H2Tree if H2Trees.jl alone is loaded (via ACAH2Trees). Errors if neither is loaded, since assemble then has no way to build a tree.

farinteractions(tree; args...)

Extract far-field (inadmissible) block pairs requiring low-rank compression.

Should be implemented by tree backends (e.g., H2Trees) to return index ranges for pairs of clusters that do NOT satisfy the admissibility criterion. These blocks are compressed via ACA or similar algorithms.

Arguments

• tree: Hierarchical tree object implementing the tree interface
• args...: Additional keyword arguments passed by the assembly routine (e.g., isnear)

Returns

• (values, farptr, farvalues): Triple of row indices, far-field pointers, and column ranges

Notes

Implemented by tree backend extensions. The pointer array farptr enables efficient lookup of far-field couples for each node, reducing access overhead during level-by-level assembly.

farinteractions_consecutive(tree; args...)

Extract far-field blocks with consecutive storage layout.

Variant used when spaces are permuted to align with tree ordering. Returns far-field block structure compatible with permuted space layout.

Arguments

• tree: Hierarchical tree object
• args...: Additional keyword arguments (e.g., isnear)

Returns

• (values, farptr, farvalues): Index structure for consecutive far-field layout

Notes

Implemented by tree backend extensions. Must account for space permutation applied by PermuteSpaceInPlace() ordering strategy.

farmatrix(hmat::HMatrix)

Extract the far-field (low-rank compressed) contributions from a hierarchical matrix.

Returns a new HMatrix containing only the low-rank far-field blocks, with all near-field blocks removed. Useful for analyzing the rank structure or applying operations that exploit low-rank properties.

Arguments

• hmat::HMatrix: Source hierarchical matrix

Returns

• HMatrix: New matrix with identical far-field interactions but empty near-field

firstchild(tree, node::Int)

Return the index of the first child of node in tree.

Part of the tree adapter interface required by TreeMimicryPivoting; implement this for a custom tree type.

isnear(η::Real=Float64(1.0))

Create an admissibility predicate for near-field block detection.

Clusters with scaled geometric distance less than η are considered admissible for near-field assembly (direct evaluation). The scaling factor η controls the geometric separation required for far-field low-rank approximation.

Arguments

• η::Real = 1.0: Admissibility parameter (dimensionless geometric distance threshold)

Returns

• IsNearFunctor: Admissibility predicate functor

Notes

For well-separated clusters (distance > η × cluster diameter), the interaction is computed via ACA compression; otherwise, via direct near-field assembly. Typical values: η ≈ 1.0 to 3.0 depending on required accuracy.

levels(tree)

Return an iterable of the levels of tree, coarsest first.

Part of the tree backend interface required by HMatrix assembly; each level is iterated with LevelIterator to visit its nodes.

nearinteractions(tree; args...)

Extract near-field (admissible) block pairs from a hierarchical tree structure.

Should be implemented by tree backends (e.g., H2Trees) to return index ranges for pairs of clusters that satisfy the admissibility criterion. This is the primary method when space ordering is not modified.

Arguments

• tree: Hierarchical tree object implementing the tree interface
• args...: Additional keyword arguments passed by the assembly routine (e.g., isnear)

Returns

• (values, nearvalues): Tuple of index vectors for row/column near-field blocks

Notes

Implemented by tree backend extensions (e.g., ACAH2Trees for H2Trees). Should return rows and corresponding near-field column indices that are admissible for direct (non-low-rank) assembly.

nearinteractions_consecutive(tree; args...)

Extract near-field blocks with consecutive storage layout.

Variant used when spaces are permuted to align with tree ordering. Returns near-field block structure compatible with permuted space layout.

Arguments

• tree: Hierarchical tree object
• args...: Additional keyword arguments (e.g., isnear)

Returns

• (values, nearvalues): Index vectors for consecutive near-field layout

Notes

Implemented by tree backend extensions. Must account for space permutation applied by PermuteSpaceInPlace() ordering strategy.

nearmatrix(hmat::HMatrix)

Extract the near-field (dense block) contributions from a hierarchical matrix.

Returns only the block-sparse near-field interactions, removing all low-rank far-field blocks. Useful for analyzing near-field structure or applying operations specific to dense blocks.

Arguments

• hmat::HMatrix: Source hierarchical matrix

Returns

• BlockSparseMatrix: Near-field interactions as block-sparse matrix

nextrc!(buf, A, i, j)

Fill buf in place with the entries A[i, j] (a sampled row/column block).

Interface method used by ACA, ACAᵀ and IACA to pull the row/column samples they pivot on, so A need not materialize as a dense matrix. The fallback here covers any AbstractArray; kernel-matrix backends (AbstractKernelMatrix subtypes such as BEASTKernelMatrix or PointMatrix) provide their own methods that evaluate entries on demand.

nnz(A::HMatrix)

Count the number of stored scalars in a hierarchical matrix.

Sums the near-field block-sparse storage with the far-field low-rank factor storage (length(U) + length(V) per block), i.e. the actual memory footprint in matrix entries rather than the dense size(A,1) * size(A,2). See also storage for a GB-scale report including compression ratio.

node_normal_orientation_sets(normals, tree; normal_digits=1, max_orientations=3,
    primary_probability=0.2, secondary_probability=0.1, active_probability=0.7,
    orth_tol=0.25)

Determine, per tree node, which basis-function normal directions dominate its subtree.

Walks tree top-down (a node must implement values, children, parent; see TreeMimicryPivoting). At each node it counts how often each normal-direction group occurs among its basis functions and selects up to max_orientations mutually (near-)orthogonal directions (via orth_tol on abs(dot(·,·))) that together explain at least active_probability of the node's basis functions, requiring the dominant direction to cover at least primary_probability and secondary ones at least secondary_probability. If no direction set is dominant enough, the node inherits its parent's set. Used to drive TreeMimicryPivoting2's DirectionFilter, which restricts descent/pivoting to one orientation group at a time.

Returns

• (nodesets, normalids, nnormalids): nodesets[node]::Vector{Int32} is the set of dominant direction ids for node; normalids/nnormalids are as returned by normal_orientation_ids on normals.

See also

basisfunction_orientation_ids, TreeMimicryPivoting2

normal_orientation_ids(q)

Like orientation_ids, but zero-valued keys (i.e. "no normal") are left at id 0 instead of starting a new group.

Returns

• (ids, nids): per-entry group ids (0 for zero keys) and the number of distinct non-zero groups found.

orientation_ids(q)

Assign a sequential Int32 id to each distinct value in q, in order of first occurrence. Every entry gets an id (starting at 1); use normal_orientation_ids instead if zero-valued keys should be exempt (id 0).

Returns

• (ids, nids): per-entry group ids and the number of distinct groups found.

parent(tree, node::Int)

Return the parent node index of node in tree.

Part of the tree adapter interface required by TreeMimicryPivoting; implement this for a custom tree type.

permutation(tree)

Return the index permutation tree applies to its underlying space.

Part of the tree backend interface required by HMatrix assembly; used by PermuteSpaceInPlace to reorder test/trial spaces to match tree clustering.

reset!(convcrit::ConvCritFunctor)

Reset a convergence functor before starting compression of a new block.

Notes

Concrete subtypes should overload this method. The default fallback throws ArgumentError.

See also

ConvCritFunctor

reset_phase!(convcrit::PhaseExtrapolatorFunctor, direction::Integer)

Set the current phase label. Call before each new pivot to associate it with a direction.

rwgorientations(space)

Compute per-basis-function edge directions and face normals for space.

Returns (edges, normals), one unit vector each per basis function, suitable as input to basisfunction_orientation_ids and node_normal_orientation_sets.

Implemented in the ACABEAST extension for BEAST Raviart–Thomas spaces.

scalartype(operator)

Return the scalar element type produced by evaluating operator.

Interface point for custom operators used with AbstractKernelMatrix backends; e.g. the ACABEAST extension implements this for BEAST integral operators. No default is provided — implement a method for your operator type.

storage(hmat::HMatrix)

Analyze and report memory storage requirements of a hierarchical matrix.

Prints detailed statistics (to stdout) comparing the actual storage needed for the hierarchical representation versus dense storage, including compression ratio. Also reports total memory footprint via Julia's summarysize.

Arguments

• hmat::HMatrix: Hierarchical matrix to analyze

Returns

• Float64: Total storage in GB used by hierarchical blocks

Output

Prints to stdout:

• storage: Total block storage in GB
• summary size: Total memory footprint including Julia object overhead (GB)
• compression ratio: Ratio of hierarchical storage to dense storage

testtree(tree)

Return the sub-tree used for row (test space) clustering.

Part of the tree backend interface required by HMatrix assembly and TreeMimicryPivoting; implement this for a custom tree type (the ACAH2Trees extension implements it for H2Trees.TwoNTree). For a single shared tree, this may return tree itself.

tofarquadstrat(quadstrat)

Convert a near-field quadrature strategy into the strategy used for admissible (far-field, well-separated) blocks.

Falls back to returning quadstrat unchanged. The ACABEAST extension specializes this for BEAST.DoubleNumWiltonSauterQStrat to extract its non-singular outer_rule_far/inner_rule_far orders into a plain BEAST.DoubleNumQStrat, since far blocks are by construction well-separated and never need singular quadrature.

trialtree(tree)

Return the sub-tree used for column (trial space) clustering.

Counterpart to testtree in the tree backend interface; see its docstring for details.

update_refcentroid!(functor::PivStratFunctor, refidcs)

Update the stored reference-domain centroid in pivoting functors that track it. The default implementation is a no-op; concrete subtypes override as needed.

values(tree, node)

Return the point indices contained in node (or each node in a vector of nodes) of tree.

Part of the tree adapter interface required by TreeMimicryPivoting; implement this for a custom tree type.