Construct a Transported Graph Hessian Operator — transported.graph.hessian.operator • geosmooth

Builds an experimental transported-Hessian graph operator without fitting a response. This diagnostic layer constructs directed edge differences, matches directions across a base dart, assembles a second- or third-difference diagnostic operator, and returns diagnostics that make the transport rule auditable.

Usage

transported.graph.hessian.operator(
  adj.list,
  weight.list = NULL,
  transport.order = 2L,
  transport.rule = c("exact.coordinate", "local.embedding.soft", "edge.angle.hard",
    "edge.angle.soft", "regression.gradient"),
  coordinates = NULL,
  direction.labels = NULL,
  polynomial.probes = NULL,
  local.embedding.method = c("auto", "coordinates", "grip.edge.kk", "mds.edge.kk",
    "cmdscale"),
  local.embedding.dim = 2L,
  local.disk.hops = 1L,
  local.max.vertices = 50L,
  return.sparse = TRUE,
  tol = 1e-08,
  soft.angle.scale = NULL,
  soft.length.scale = NULL,
  soft.bandwidth = 0.25,
  max.match.angle = NULL,
  max.length.relative.error = NULL,
  min.match.margin = NULL,
  max.effective.matches = NULL,
  match.threshold.rule = c("none", "fixed", "local.quantile", "local.robust.z"),
  match.score.quantile = 0.25,
  match.margin.quantile = 0.5,
  min.best.score.z = 1,
  min.margin.z = 0,
  max.effective.match.fraction = NULL,
  edge.angle.scale = NULL,
  edge.length.scale = NULL,
  edge.angle.bandwidth = 0.35,
  edge.angle.max.angle.difference = NULL,
  edge.angle.max.length.relative.error = NULL,
  gradient.coordinate.method = c("coordinates", "local.embedding"),
  gradient.embedding.method = c("grip.edge.kk", "mds.edge.kk", "cmdscale"),
  gradient.embedding.dim = NULL,
  gradient.disk.hops = local.disk.hops,
  gradient.max.vertices = local.max.vertices,
  gradient.disk.rule = c("hops", "metric.diameter.fraction", "metric.local.scale"),
  gradient.disk.radius.fraction = 0.1,
  gradient.disk.local.scale.method = c("knn.distance", "median.incident.length",
    "quantile.incident.length"),
  gradient.disk.local.scale.k = 8L,
  gradient.disk.local.scale.quantile = 0.75,
  gradient.disk.local.scale.multiplier = 2,
  gradient.disk.min.vertices = 0L,
  gradient.chart.selection = c("fixed", "adaptive"),
  gradient.embedding.candidates = c("cmdscale", "mds.edge.kk"),
  gradient.disk.rule.candidates = c("hops", "metric.diameter.fraction",
    "metric.local.scale"),
  gradient.disk.hops.candidates = 1:5,
  gradient.disk.radius.fraction.candidates = c(0.05, 0.075, 0.1, 0.15, 0.2),
  gradient.disk.local.scale.multiplier.candidates = c(1, 1.5, 2, 3, 4),
  gradient.ridge = 1e-08,
  gradient.quadratic.disk.hops = 2L,
  gradient.quadratic.max.vertices = gradient.max.vertices
)

Arguments

adj.list: List of integer neighbor vectors using 1-based vertex indices. The graph must be undirected.
weight.list: Optional list of positive edge lengths parallel to adj.list. If NULL, all edge lengths are one.
transport.order: Integer scalar, either 2L or 3L. 2L constructs the transported Hessian-like second-difference operator. 3L currently constructs a supplied-coordinate regression-quadratic third-difference operator and is supported only for transport.rule = "regression.gradient" with gradient.coordinate.method = "coordinates".
transport.rule: Character scalar. "exact.coordinate" uses exact direction labels. "local.embedding.soft" uses coordinate direction vectors and softmax transport weights. "edge.angle.hard" and "edge.angle.soft" use coordinate-derived edge angles relative to the base dart. "regression.gradient" compares locally estimated gradient components.
coordinates: Optional numeric matrix with one row per vertex. For transport.rule = "exact.coordinate", coordinates must define axis-aligned graph edges so direction labels can be inferred. Coordinates are required by "edge.angle.hard" and "edge.angle.soft".
direction.labels: Optional list parallel to adj.list; each entry gives the exact direction label for the corresponding outgoing dart. When supplied, these labels override labels inferred from coordinates.
polynomial.probes: Optional numeric vector or matrix with one row per vertex. If supplied, residual diagnostics $\|AP\|_F/\|P\|_F$ are reported for the transported Hessian matrix $A$.
local.embedding.method: Character scalar controlling the coordinates used by transport.rule = "local.embedding.soft". "auto" uses supplied coordinates when available and otherwise tries "grip.edge.kk". "coordinates" uses supplied coordinates directly. "grip.edge.kk" builds a local graph disk and prefers weighted GRIP followed by true edge-KK optimization when the installed grip exposes weighted.grip() and edge.kk(). Older compatibility names are used only as fallbacks. "mds.edge.kk" uses classical MDS followed by the same edge-KK optimizer when available. "cmdscale" uses classical MDS only.
local.embedding.dim: Positive integer embedding dimension for local graph-disk embeddings.
local.disk.hops: Non-negative integer hop radius around each base dart used by graph-derived local embedding methods.
local.max.vertices: Positive integer cap on local disk size. If a disk is larger, the nearest vertices by hop distance are retained.
return.sparse: Logical. If TRUE, attach Matrix sparse matrices to the returned payloads.
tol: Positive numeric tolerance for coordinate-axis direction inference.
soft.angle.scale, soft.length.scale: Optional positive numeric scales for the soft transport angular and length score components. If NULL, robust global defaults are estimated from candidate dart comparisons.
soft.bandwidth: Positive numeric softmax bandwidth $\tau$. Smaller values make the soft rule closer to hard nearest-direction matching.
max.match.angle: Optional non-negative numeric angle threshold in radians. For soft transport, candidate Hessian rows whose best match has angle larger than this threshold are dropped.
max.length.relative.error: Optional non-negative numeric threshold for the best match's relative edge-length error, $|\ell_{\mathrm{matched}}-\ell_{\mathrm{direction}}|/ \ell_{\mathrm{direction}}$. Candidate rows above the threshold are dropped.
min.match.margin: Optional non-negative numeric threshold for the difference between the second-best and best soft-match scores. Candidate rows with smaller margins are dropped.
max.effective.matches: Optional positive numeric threshold for $\exp(H)$, where $H$ is the softmax transport entropy. Candidate rows with more diffuse matches are dropped.
match.threshold.rule: Character scalar. "none" and "fixed" apply only the explicit fixed gates above. "local.quantile" also gates rows by local candidate-score and margin quantiles. "local.robust.z" also gates rows by robust local z-scores for best-match score and margin.
match.score.quantile, match.margin.quantile: Quantile thresholds used by match.threshold.rule = "local.quantile". The best score must lie at or below match.score.quantile; the best-vs-second margin must lie at or above match.margin.quantile.
min.best.score.z, min.margin.z: Non-negative robust-z thresholds used by match.threshold.rule = "local.robust.z". A larger best-score z-score means the best candidate is unusually low-scoring relative to local alternatives. A larger margin z-score means the best-vs-second separation is unusually large.
max.effective.match.fraction: Optional positive numeric threshold for $\exp(H) / n_{\mathrm{candidate}}$. Candidate rows whose softmax mass is too diffuse across the local target directions are dropped.
edge.angle.scale, edge.length.scale: Optional positive numeric scales for edge-angle matching. If NULL, robust global medians are estimated from candidate angle differences and length differences.
edge.angle.bandwidth: Positive numeric softmax bandwidth used only by transport.rule = "edge.angle.soft".
edge.angle.max.angle.difference: Optional non-negative threshold, in radians, for accepting an edge-angle match.
edge.angle.max.length.relative.error: Optional non-negative threshold for accepting an edge-angle match based on relative edge-length error.
gradient.coordinate.method: Character scalar used only by transport.rule = "regression.gradient". "coordinates" uses the supplied global coordinates. "local.embedding" estimates the two endpoint gradients of each base dart in one shared graph-derived local chart.
gradient.embedding.method: Character scalar used by gradient.coordinate.method = "local.embedding". The choices match the graph-derived local embedding backends used by local.embedding.soft.
gradient.embedding.dim: Optional positive integer dimension for graph-derived regression-gradient local charts. If NULL, the supplied coordinate dimension is used when available, otherwise local.embedding.dim.
gradient.disk.hops: Non-negative integer hop radius for graph-derived regression-gradient local charts.
gradient.max.vertices: Positive integer cap on graph-derived regression-gradient local chart size.
gradient.disk.rule: Character scalar controlling graph-derived regression-gradient disk construction. "hops" uses gradient.disk.hops. "metric.diameter.fraction" uses a two-center graph-geodesic disk whose metric radius is gradient.disk.radius.fraction times the graph diameter. "metric.local.scale" uses a two-center graph-geodesic disk whose metric radius is gradient.disk.local.scale.multiplier times the larger endpoint local scale.
gradient.disk.radius.fraction: Positive numeric scalar used by gradient.disk.rule = "metric.diameter.fraction".
gradient.disk.local.scale.method: Character scalar controlling the per-vertex metric scale used by gradient.disk.rule = "metric.local.scale". "knn.distance" uses the weighted graph distance to the gradient.disk.local.scale.k-th nearest vertex. "median.incident.length" and "quantile.incident.length" use incident edge-length summaries.
gradient.disk.local.scale.k: Positive integer neighborhood index used by gradient.disk.local.scale.method = "knn.distance".
gradient.disk.local.scale.quantile: Numeric probability in [0, 1] used by gradient.disk.local.scale.method = "quantile.incident.length".
gradient.disk.local.scale.multiplier: Positive numeric scalar multiplier for gradient.disk.rule = "metric.local.scale".
gradient.disk.min.vertices: Non-negative integer lower target for metric disk coverage. Metric disks whose radius selects too few vertices are expanded to include at least this many nearest vertices, subject to gradient.max.vertices.
gradient.chart.selection: Character scalar used only by graph-derived regression-gradient transport. "fixed" uses gradient.embedding.method and gradient.disk.hops. "adaptive" tries gradient.embedding.candidates crossed with gradient.disk.hops.candidates for each base dart and chooses the chart with the lowest graph-only diagnostic score.
gradient.embedding.candidates: Character vector of graph-derived local embedding backends considered by gradient.chart.selection = "adaptive".
gradient.disk.rule.candidates: Character vector of disk construction rules considered by gradient.chart.selection = "adaptive".
gradient.disk.hops.candidates: Non-negative integer vector of hop radii considered by gradient.chart.selection = "adaptive".
gradient.disk.radius.fraction.candidates: Positive numeric vector of graph-diameter fractions considered by gradient.chart.selection = "adaptive".
gradient.disk.local.scale.multiplier.candidates: Positive numeric vector of local-scale multipliers considered by gradient.chart.selection = "adaptive".
gradient.ridge: Non-negative ridge parameter used by transport.rule = "regression.gradient" when inverting local weighted least-squares normal equations.
gradient.quadratic.disk.hops: Non-negative integer hop radius for the supplied-coordinate local quadratic regressions used by transport.order = 3L.
gradient.quadratic.max.vertices: Positive integer cap on local quadratic-regression disk size for transport.order = 3L.

Value

A list of class "transported.graph.hessian.operator" with the canonical graph, directed-edge table, first-difference matrix, transported Hessian matrix, row metadata, dropped candidate rows, and diagnostics. For graph-derived regression-gradient transport with supplied coordinates, the embedding diagnostics also include synthetic chart-quality checks against those ambient coordinates.

Details

For a dart $u\to v$, the first difference is $$ \delta_{u\to v}f = \frac{f(v)-f(u)}{\ell_{uv}}. $$ For a base dart $u\to u'$ and a matched outgoing direction $u\to v \leftrightarrow u'\to v'$, the transported Hessian row is $$ \delta_{u'\to v'}f - \delta_{u\to v}. $$

The reference rule, transport.rule = "exact.coordinate", matches directions with identical coordinate labels. Labels may be supplied directly through direction.labels, or inferred from axis-aligned coordinates. The first general metric rule, transport.rule = "local.embedding.soft", uses supplied coordinates to softly match directions by angle and edge length. The edge-angle rules, "edge.angle.hard" and "edge.angle.soft", match directions by comparing their angle relative to the transported base edge. transport.rule = "regression.gradient" estimates local least-squares gradients and compares gradient components across graph darts. Those gradients can be computed either from supplied coordinates or from a graph-derived local embedding built in a shared disk around each base dart.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
weights <- list(1, c(1, 1), c(1, 1), 1)
x <- 0:3
transported.graph.hessian.operator(
  adj, weights, coordinates = matrix(x, ncol = 1),
  polynomial.probes = cbind(1, x, x^2)
)
#> 
#> Transported Graph Hessian Operator
#> ==================================
#> 
#> Vertices: 4; darts: 6
#> Transport rule: exact.coordinate
#> Derivative order: 2
#> Rows: 8; dropped candidates: 2
#> Nullity estimate: 2