Euclidean Sheaves

 EuclideanSheaf{T}

A Euclidean sheaf is a network sheaf where each vertex stalk is a Euclidean space R^n for some n, each edge stalk is a Euclidean space R^m for some m, and each restriction map is a linear map R^n -> R^m represented by a matrix of type T.

constant_sheaf(g::Graph, d::Int=1) -> EuclideanSheaf{Float64}

Construct the constant sheaf $\underline{\mathbb{R}^d}$ on graph g: each vertex and edge stalk is $\mathbb{R}^d$ and every restriction map is the $d\times d$ identity.

cycle_sheaf(n::Int, stalk_dim::Int, rm_pair_fn::Function) -> EuclideanSheaf{Float64}

Construct an EuclideanSheaf on the n-vertex cycle graph where each vertex stalk has dimension stalk_dim. For edge k (in graph iteration order) the pair of restriction maps (rm_src, rm_dst) is produced by calling rm_pair_fn(n, stalk_dim, k).

harmonic_extension(s::EuclideanSheaf, boundary::Dict{Int,<:AbstractVector})
    -> (BlockVector, Matrix)

Compute the harmonic extension of boundary over the interior vertices of s.

boundary maps each boundary vertex index to a vector of length s.vertex_stalks[v].

Returns (x_p, null_basis) where:

• x_p is the minimum-norm particular solution as a BlockArray over s.vertex_stalks
• null_basis is a matrix whose columns span the solution's indeterminate directions, embedded in the full cochain space (zero at boundary dofs). Has 0 columns when the boundary conditions uniquely determine the harmonic extension.

The complete solution set is { x_p + null_basis * c : c ∈ Rᵏ } where k = size(null_basis, 2).

Throws ArgumentError if any boundary vector has the wrong length for its stalk.

harmonic_extension_ldl_diagnostics(s::EuclideanSheaf,
                                   boundary::Dict{Int,<:AbstractVector};
                                   tol=nothing)
    -> HarmonicExtensionLDLDiagnostics

Compute LDL-based diagnostics for the restricted Laplacian L_II used by harmonic_extension for the boundary data boundary.

The boundary and interior vertex sets are exactly those induced by the harmonic extension problem: boundary fixes the boundary vertices and the remaining vertices are treated as interior. The diagnostics are computed from the sparse ChordalLDLt factorization of L_II with RowMaximum pivoting, matching the solver path used internally by harmonic_extension.

Returns a HarmonicExtensionLDLDiagnostics struct. Its fields expose the same partition metadata and pivot summary used internally, and its text/plain show method prints a structured diagnostic table.

When L_II is empty (no interior degrees of freedom), the returned arrays are empty and the rank/nullity estimates are both zero.

harmonic_extension_svd_diagnostics(s::EuclideanSheaf,
                                   boundary::Dict{Int,<:AbstractVector};
                                   tol=nothing)
    -> HarmonicExtensionSVDDiagnostics

Compute SVD-based diagnostics for the restricted Laplacian L_II used by harmonic_extension for the boundary data boundary.

The interface matches harmonic_extension_ldl_diagnostics. The return value is a HarmonicExtensionSVDDiagnostics struct with the same partition metadata, plus singular-value-specific diagnostics and a formatted show method for interactive inspection.

When L_II is empty (no interior degrees of freedom), the singular-value arrays are empty and the condition numbers are reported as Inf.

ldlt_pinv_solve(F, B::AbstractMatrix; tol=nothing) -> Matrix

Apply the pseudoinverse of the factorized matrix to every column of B, i.e. return a dense matrix whose j-th column is ldlt_pinv_solve(F, B[:, j]). The out/w scratch buffers are shared across columns.

nearestglobalsection

Entrypoint solver. Keyword method selects backend: :ldl (direct LDL, default), :cg (iterative CG — requires d*d' to be strictly PD), or :pinv (SVD pseudoinverse). The :ldl backend handles rank-deficient cases via a pinv fallback.

nearestglobalsection_cg

Iterative Krylov (CG) backend. Returns a BlockArray global section.

nearestglobalsection_ldl

Deterministic direct backend using LDL factorization on the symmetric edge-space operator E = d*d'. This handles symmetric indefinite matrices without Tikhonov regularization. Falls back to pinv if LDL fails.

nearestglobalsection_pinv

Robust pseudoinverse backend (SVD). Deterministic but potentially expensive.

nullspace_ldlt(X::AbstractMatrix; tol=nothing) -> Matrix

Compute a basis for the nullspace of the symmetric positive-semidefinite matrix X using a sparse LDLt factorisation from CliqueTrees.Multifrontal (ChordalLDLt with RowMaximum pivoting).

The factorisation is $X = P^\mathsf{T} L D L^\mathsf{T} P$. Columns of D whose absolute diagonal value is at or below tol (default: $\sqrt{\varepsilon_\text{Float64}} \times \max(1, \|D\|_\infty)$) identify null directions; the corresponding columns of P^{-1} (L^\mathsf{T})^{-1} form the returned basis matrix.

nullspace_ldlt(s::EuclideanSheaf; tol=nothing) -> Matrix

Convenience overload: computes the sheaf Laplacian $L = d^\mathsf{T} d$ (where $d$ is the coboundary map of s) and delegates to nullspace_ldlt(L).

The returned columns form a basis for the space of global sections of s.

restricted_laplacian_blocks(s::EuclideanSheaf,
                            interior::AbstractVector{Int},
                            boundary::AbstractVector{Int})
    -> (L_II::SparseMatrixCSC, L_IB::SparseMatrixCSC)

Compute the interior-interior and interior-boundary blocks of the sheaf Laplacian without assembling the full Laplacian.

interior and boundary are disjoint vectors of vertex indices (any order). Only edges with at least one interior endpoint contribute.

• L_II is the $(\sum_{v \in I} d_v) \times (\sum_{v \in I} d_v)$ symmetric positive-semidefinite block.
• L_IB is the $(\sum_{v \in I} d_v) \times (\sum_{v \in B} d_v)$ interior-boundary coupling block.

The DOF ordering within each block follows the order of interior / boundary. Edges entirely within the boundary subgraph are skipped, so assembly cost is $O(|E_I| \cdot d_{\max}^2)$ where $E_I$ is the set of edges with at least one interior endpoint.

sheaf_laplacian_matrix(s::EuclideanSheaf) -> AbstractMatrix

Compute the sheaf Laplacian L = dᵀd as a sparse matrix, where d is the coboundary map.

The result is symmetric positive semidefinite. Use nullspace_ldlt to find the space of global sections (kernel of L), or nearest_global_section to project a cochain to the nearest global section.

sheaf_laplacian_matrix_direct(s::EuclideanSheaf) -> SparseMatrixCSC

Assemble the sheaf Laplacian $L = d^\mathsf{T} d$ directly from the restriction maps of s, without forming the coboundary matrix $d$.

For each edge $e = (u, v)$ the following block contributions are accumulated:

L_{u,u} += ρ_{u→e}^T ρ_{u→e}
L_{v,v} += ρ_{v→e}^T ρ_{v→e}
L_{u,v} += -ρ_{u→e}^T ρ_{v→e}
L_{v,u} += -ρ_{v→e}^T ρ_{u→e}

This avoids constructing the $(\sum d_e) \times (\sum d_v)$ coboundary matrix and the subsequent matrix multiply, saving both time and memory for large sheaves. The result is numerically identical to sheaf_laplacian_matrix.

zero_sheaf(g::Graph) -> EuclideanSheaf{Float64}

Construct the zero sheaf on graph g: all vertex and edge stalks are 0-dimensional (i.e. the trivial bundle).

addsheafedge!(s::EuclideanSheaf, v1::Int, v2::Int, rm1, rm2)

Add an edge between vertices v1 and v2 with restriction maps rm1 and rm2. rm1 is the restriction map from vertex v1 to the edge and rm2 is the restriction map from vertex v2 to the edge.

Both rm1 and rm2 may be any AbstractMatrix (e.g. Matrix, Diagonal, SparseMatrixCSC); they are converted to Matrix{T} when stored.

edge_stalk_dimensions(s::EuclideanSheaf)

Return a vector of edge stalk dimensions ordered by edges in the underlying graph.

edge_stalks(
    s::EuclideanSheaf
) -> Dict{UnorderedPair{Int64}, Int64}

Get the edge stalks of a Euclidean sheaf.

Arguments

• s: The Euclidean sheaf

Returns

• Dict{UnorderedPair{Int}, Int}: Mapping from edge (as unordered vertex pair) to stalk dimension

See also

• vertex_stalks
• AbstractNetworkSheaf

get_restriction_map(s::EuclideanSheaf, v1::Int, v2::Int)

Get the restriction map from vertex v1 to the edge (v1, v2).

underlying_graph(
    s::EuclideanSheaf
) -> Graphs.SimpleGraphs.SimpleGraph

Get the underlying graph of a Euclidean sheaf.

Arguments

• s: The Euclidean sheaf

Returns

• Graphs.SimpleGraph: The graph on which the sheaf is defined

See also

• AbstractNetworkSheaf

vertex_stalks(s::EuclideanSheaf) -> Vector{Int64}

Get the vertex stalks of a Euclidean sheaf.

Arguments

• s: The Euclidean sheaf

Returns

• Vector{Int}: Dimensions of each vertex stalk

See also

• edge_stalks
• AbstractNetworkSheaf