Select a path from six quadratic-surface refinement searches — quadform_geodesics_best_of

Run both refinement methods with all three neighborhood rules and return the shortest usable result. Each search starts afresh from the same seeded equal-surface-length initialization. This is a finite-budget heuristic, not a certificate of a globally shortest surface path.

Usage

quadform_geodesics_best_of_six(
  A,
  from,
  to,
  domain,
  seed = 1,
  length_scale = 1,
  initial_edges = 16L,
  candidates = 32L,
  max_epochs = 64L,
  max_vertices = 257L,
  max_edge_calls = Inf,
  max_seconds = Inf,
  cache_edges = 0L,
  rejection_cap = 1000L,
  random_orientation = TRUE,
  trace = FALSE,
  trace_limit = 1000L
)

Arguments

A: Finite symmetric 2 by 2 quadratic-form matrix.
from, to: Numeric vectors of two domain coordinates, inside domain.
domain: A list with kind = "ball", numeric center and positive radius, or kind = "box" and numeric lower and upper bounds.
seed: Whole-number seed between zero and $2^{32}-1$. Dedicated C++ streams do not create or modify R's random state.
length_scale: Positive surface-length reference for absolute tolerances.
initial_edges: Initial segment count, between 2 and 256.
candidates: Accepted disk draws per visit, between 1 and 256. Draws outside the domain are rejected; exact duplicates are removed afterwards.
max_epochs: Rounds per search, default 64. Plateau stopping is disabled.
max_vertices: Maximum path size, at most 257 and greater than initial_edges.
max_edge_calls, max_seconds: Safety allowances for each of the six searches, not combined allowances. Defaults are unlimited; rounds still bound the search. Interrupted searches retain their original statuses.
cache_edges: Cache capacity per search; default zero.
rejection_cap: Maximum attempts per accepted candidate or shuffle draw.
random_orientation: Randomize internal endpoint orientation once per call. Returned paths always follow the caller's endpoint order.
trace: Retain a bounded in-memory refinement trace. Default FALSE.
trace_limit: Maximum retained trace events, between zero and 10000.

Value

The selected solver result, with an additional ensemble list. ensemble$results retains all six solver results and ensemble$summary records methods, rules, seeds, lengths, error estimates, statuses, round completion and costs. selected_index identifies the minimum estimated length; exact length ties prefer the earlier row. tied_indices also includes usable results whose difference from the selected length is no larger than their combined estimated errors. These estimates are not rigorous intervals. Numerical ties never cause a longer estimated path to replace the minimum. status within ensemble is "complete" when all six round budgets complete (or endpoints coincide), "partial" when at least one usable path is available but some search is incomplete, and "no_path" when none is usable. In the latter case selected_index is missing and the top-level result is the first no-path solver result. Top-level counters describe the selected search only; total cost is in ensemble$total_edge_calls, total_solver_seconds, and total_call_seconds. Input errors and unexpected R errors propagate.

Details

Searches use the same seed to preserve their initialization, but may diverge in their candidate draws and visits as their paths change. They execute serially and do not change R's random state. Parallelize independent endpoint pairs in separate R processes rather than nesting workers inside this function. No state files are saved.