vc_stationary_points: Search for multivariable stationary candidates from explicit...

View source: R/stationary_multivariable.R

vc_stationary_pointsR Documentation

Search for multivariable stationary candidates from explicit starts

Description

Search for multivariable stationary candidates from explicit starts

Usage

vc_stationary_points(
  f,
  starts,
  bounds = NULL,
  assume_c2 = FALSE,
  h = NULL,
  hessian_h = NULL,
  tol_grad = 1e-05,
  tol_eigen = 1e-06,
  tol_merge = 1e-04,
  max_iter = 500L,
  atol = 1e-08,
  rtol = 1e-04,
  warn = TRUE
)

Arguments

f

Deterministic scalar field accepting ONE numeric vector and returning one finite real scalar. For f(x,y), supply an explicit wrapper function(v)f(v[1],v[2]); no automatic signature guessing is performed.

starts

One finite coordinate vector or a finite numeric matrix with one starting point per row, at least two columns. Optional column names are passed to f and must be unique/nonempty. No random starts are added.

bounds

Optional finite increasing n-by-2 numeric search-window matrix. This limits optimization, not the domain of f: central stencils may extend outside the window and must still be evaluable. Boundary hits are rejected.

assume_c2

Logical declaration by the caller that f is twice continuously differentiable in a neighborhood. Default FALSE prevents an extremum label; numerical stencils cannot verify this hypothesis.

h

NULL for per-coordinate vc_derivative heuristics, one positive finite step for all coordinates, or a positive finite vector of that dimension. No recycling of shorter vectors is allowed.

hessian_h

Positive scalar/vector second-difference step, or NULL for vc_hessian defaults. h controls first differences independently.

tol_grad

Positive absolute tolerance for the gradient norm and the finest left/right coordinate quotients. This is not an error bound.

tol_eigen

Positive absolute eigenvalue margin, enlarged by an empirical matrix refinement/roundoff allowance before classification.

tol_merge

Positive Euclidean distance below which accepted candidates are merged. Every run, including duplicates, remains in runs.

max_iter

Positive integer optimization limit passed to stats::optim.

atol

Nonnegative finite absolute tolerance for sensitivity comparisons.

rtol

Nonnegative finite relative tolerance for sensitivity comparisons.

warn

Logical scalar; warn when sensitivity diagnostics fail.

Details

Recovers the original critical_points_2d/critical_points_nd strategy of minimizing squared numerical gradient norm and merging duplicates. Reuses vc_gradient and vc_classify_stationary. Unbounded searches use Nelder-Mead; finite windows use L-BFGS-B. Hessians are never obtained by repeated differentiation of gradients. No random state is read or changed. Failed function/stencil evaluations receive a finite penalty and remain visible in the objective history; errors in a run do not erase other runs. History rows are objective evaluations, NOT Newton iterations or a claimed descent trajectory. Residual convergence is assessed independently of the optimizer's stopping code. Local minimization can stop at a nonzero residual, miss roots, leave unbounded windows or fail on poor scales. There is no completeness, convergence or global-extremum guarantee. Nondifferentiable critical points and constrained/boundary extrema are outside this stationary-point search. Supply scientifically chosen starts.

Value

Plain list with type, starts, bounds, points (rows of merged candidates), table (id, value, residual, classification), assessments, runs (start, terminal point, optimizer code/message, accepted, candidate_id, status, assessment and every objective evaluation), and note. Empty searches return a zero-row matrix/table. No optimizer code alone accepts a candidate; final stationarity/side checks are mandatory.

Examples

f <- function(v)v[1]^2+2*v[2]^2
f |> vc_stationary_points(rbind(c(.1,.2),c(-.2,.1)),assume_c2=TRUE)

vectorialcalculus documentation built on Nov. 17, 2026, 1:09 a.m.