Perform Harmonic Smoothing with Topology Tracking

Relaxes graph values while recording changes in local extrema. Boundary vertices have neighbors outside the region and retain their original values.

Usage

harmonic.smoother(
  adj.list,
  weight.list,
  values,
  region.vertices,
  max.iterations = 100,
  tolerance = 1e-06,
  record.frequency = 1,
  stability.window = 3,
  stability.threshold = 0.05
)

Arguments

adj.list

A list of integer vectors, where each vector contains indices of vertices adjacent to the corresponding vertex. Indices must be 1-based.

weight.list

A list of numeric vectors containing weights of edges corresponding to adjacencies in adj.list.

values

A numeric vector of function values defined at each vertex.

region.vertices

An integer vector of vertex indices (1-based) defining the region to be smoothed. Boundary vertices will have fixed values.

max.iterations

Integer scalar, the maximum number of relaxation iterations to perform. Default is 100.

tolerance

Numeric scalar, the convergence threshold for value changes. Default is 1e-6.

record.frequency

Integer scalar, how often to record states (every N iterations). Default is 1 (record every iteration).

stability.window

Integer scalar, number of consecutive recorded differences to check for extrema stability. Default is 3.

stability.threshold

Numeric scalar in \([0,1]\), maximum allowed difference in topology to consider stable. Default is 0.05.

Value

A list of class "harmonic_smoother" containing:

harmonic_predictions

Numeric vector of smoothed function values

i_harmonic_predictions

Matrix of function values at each recorded iteration (columns are iterations)

i_basins

List of matrices representing extrema at each iteration

stable_iteration

First iteration with a detected extrema-stability window, or NA_integer_ if none was detected

stability_detected

Whether an extrema-stability window was detected

num_iterations, recorded_iterations

Number of relaxation updates and their actual indices for the recorded columns, starting at zero

max_change, max_residual

Per-update maximum change and harmonic residual. Both must fall below tolerance for convergence

status

converged, iteration_limit, or no_interior

topology_differences

Numeric vector of differences between consecutive recorded iterations

basin_cx_differences

Alias of topology_differences

converged

Logical indicator of whether the relaxation converged

num_region, num_boundary, num_interior

Vertex counts for the requested region and its boundary/interior split

Details

Uses the same inverse-length neighbor averages and boundary definition as perform.harmonic.smoothing. Unlike the basic function, it also relaxes regions with no boundary. Such a problem is not uniquely anchored; synchronous updates can oscillate on bipartite graphs, including paths.

The recorded diagnostic compares sets of (vertex, minimum/maximum) pairs. Its value is one minus twice the number of shared pairs divided by the sum of the two set sizes (zero for two empty sets). A detection means that the last stability.window recorded differences are at most stability.threshold. It does not establish numerical convergence, optimal smoothing, noise removal, or stability of full attraction basins. In particular, recording every two iterations can conceal an alternating oscillation. Always inspect converged and max_residual separately. Stability detection does not stop relaxation or select the returned fit. The initial and final states are always recorded, including a final partial recording interval. Disconnected components without fixed boundary values have the same lack of anchoring as a region without a boundary.

See also

perform.harmonic.smoothing for basic smoothing, plot.harmonic_smoother for visualization methods, summary.harmonic_smoother for summary statistics

Examples

adj.list <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
weight.list <- list(1, c(1, 1), c(1, 1), 1)
values <- c(0, 2, -1, 1)
result <- harmonic.smoother(
  adj.list, weight.list, values, region.vertices = seq_along(values),
  max.iterations = 20, record.frequency = 2
)
smoothed.values <- result$harmonic_predictions
smoothed.values
#> [1] -0.666666  1.666667 -0.666667  1.666666