vc_lagrange: Assess an equality-constrained candidate using Lagrange...

View source: R/lagrange.R

vc_lagrangeR Documentation

Assess an equality-constrained candidate using Lagrange multipliers

Description

Assess an equality-constrained candidate using Lagrange multipliers

Usage

vc_lagrange(
  f,
  g,
  point,
  assume_c2 = FALSE,
  h = NULL,
  hessian_h = NULL,
  tol_feasible = 1e-08,
  tol_stationary = 1e-05,
  rank_tol = 1e-08,
  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.

g

Equality constraints g=0, either a deterministic vector-valued function accepting one coordinate vector, or a nonempty list of scalar functions. Optional constraint names must be fixed, unique and nonempty.

point

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

assume_c2

Caller declaration that BOTH f and all constraints are C2 in a neighborhood. FALSE prevents extremum labels. Numerical evidence cannot establish regularity, exact feasibility or exact stationarity.

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_feasible

Positive absolute infinity-norm constraint tolerance.

tol_stationary

Positive absolute infinity-norm tolerance for the Lagrange residual and its finest forward/backward coordinate quotients.

rank_tol

Positive relative/absolute SVD rank threshold factor. Singular values must exceed rank_tol*max(1,largest singular value) plus an empirical Jacobian refinement allowance. Rank depends on scaling.

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; warn when the assessment is inconclusive.

Details

Evaluates a supplied candidate; it does not search for candidates. Uses L=f-sum(lambda_i*g_i), so grad f=transpose(J)lambda. vc_gradient, vc_jacobian and direct vc_hessian engines are reused unchanged. The SVD of J solves for multipliers without forming the normal equations JJ^T. Stored raw sensitivity flags remain unchanged. First-order evidence uses stable central estimates and BOTH small finest coordinate-side Lagrange residuals; individual zero partials can fail stricter relative side flags even for smooth fields. This criterion is finite evidence, not proof.

A full-row-rank Jacobian identifies an estimated tangent basis Z. With feasible/stationary evidence, declared C2 and reliable Hessian stencils, eigenvalues of transpose(Z)H_LZ suggest strict constrained minimum or maximum (definite), or saddle (both signs). Semidefinite, singular-rank, unresolved and zero-dimensional tangent cases remain inconclusive. The original bordered matrix is retained for teaching, but its arbitrary leading-minor sign pattern is not used as a universal classifier.

Eigenvalue margin is tol_eigen plus dimension times the maximum entry refinement change of H_L and weighted roundoff indicators. Jacobian rank allowance uses sqrt(m*n) times its maximum consecutive refinement change. These are heuristic sensitivity diagnostics, not certified matrix or tangent-space error bounds. Individual Hessian flags are required (zero multiplier constraint Hessians do not affect H_L reliability). Scaling, offsets and near-zero curvature may require informed h/hessian_h choices. No inequalities, boundary/global optimization, singular-constraint theory, higher-order classification or existence/completeness proof is supplied.

Value

Plain list with type, point, value, constraints, classification, reason, feasible, stationary_evidence, regular, rank, rank_threshold, singular_values, lambda, stationarity_residual, side_max, gradient, jacobian, hessians (objective/constraints), lagrangian_hessian, bordered_hessian, tangent_basis, reduced_hessian, eigenvalues, eigen_margin, control and note. Unavailable quantities are NULL/NA and engine failures remain in the corresponding diagnostics. Labels are minimum, maximum, saddle, inconclusive, infeasible or not_stationary. Multipliers at deficient rank are minimum-norm diagnostics, not unique.

Examples

f <- function(v)sum(v^2)
g <- function(v)sum(v)-1
f |> vc_lagrange(g=g,point=c(.5,.5),assume_c2=TRUE,hessian_h=.01)

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