vc_classify_stationary: Assess a multivariable stationary candidate by the second...

View source: R/stationary_multivariable.R

vc_classify_stationaryR Documentation

Assess a multivariable stationary candidate by the second derivative test

Description

Assess a multivariable stationary candidate by the second derivative test

Usage

vc_classify_stationary(
  f,
  point,
  assume_c2 = FALSE,
  h = NULL,
  hessian_h = NULL,
  tol_grad = 1e-05,
  tol_eigen = 1e-06,
  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.

point

Nonempty finite real coordinate vector. Optional names must be unique and nonempty and are passed to f.

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.

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

Central coordinate quotients must be stable and small on BOTH finest sides. This additional stationarity check can pass at a smooth quadratic minimum when vc_gradient's stricter relative side-agreement flag fails; that original flag is retained, never rewritten. A cusp such as abs(x)+y^2 is not accepted just because central cancellation gives zero. Finite checks can still miss nonsmoothness or discontinuity.

With declared C2 regularity, a stationary candidate and reliable Hessian, positive/negative definite estimates suggest a strict minimum/maximum; eigenvalues of both signs suggest a saddle. Semidefinite, degenerate, unresolved or unavailable Hessians are inconclusive, never flat extrema. The margin is tol_eigen plus dimension times the maximum entry change over consecutive refinements plus dimension times the maximum finest roundoff indicator. It is a conservative diagnostic, NOT a certified perturbation bound. Near-stationary numerical points need not be exact critical points; all labels remain conditional. No boundary or constrained extremum test, higher-order test or global classification is performed.

Value

Plain list with type, point, value, classification, reason, stationary_evidence, gradient (unchanged complete engine result), side_max, hessian (complete result or NULL), eigenvalues, eigen_margin, matrix_allowance, assume_c2 and note. Labels are minimum, maximum, saddle, inconclusive or not_stationary; all are numerical assessments.

Examples

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

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