vc_linearization: Construct a numerical total differential and affine local...

View source: R/multivariable_models.R

vc_linearizationR Documentation

Construct a numerical total differential and affine local model

Description

Construct a numerical total differential and affine local model

Usage

vc_linearization(
  f,
  point,
  dx = NULL,
  scales = c(1, 0.5, 0.25),
  gradient = NULL,
  method = "central",
  h = NULL,
  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.

dx

Optional increment vector, or matrix with one increment per row. Coordinates are positional; when both point and increments are named, names must agree in order. NULL constructs evaluators without probes.

scales

Strictly decreasing positive finite probe multipliers; default compares each increment at full, half and quarter scale.

gradient

Optional vc_gradient result at the same point and field value. When supplied, its diagnostics are retained and method, h, atol, rtol and warn are ignored; the gradient is not recomputed.

method

One difference method, or one per coordinate. Explicit one-sided methods can be used at known coordinate-domain boundaries.

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.

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

Reuses vc_gradient without modifying the accepted derivative engine. The candidate differential is sum(gradient*dx); the model is f(point)+sum(gradient*(new_point-point)). It is the mathematical total differential/tangent model only under appropriate total differentiability. Coordinate sensitivity checks do not establish this hypothesis. Probes compare the model with actual finite changes at point+scaled_dx. Comparison differential uses the representable displacement; the requested functional value is also retained. Absolute remainder divided by actual displacement norm is reported, not promoted to a differentiability test. Even decreasing ratios on finitely many directions are not a proof. Gradient approximation error and roundoff can produce a residual floor. Zero increments have no normalized remainder. Domain errors, collapsed active coordinates, scaling underflow/overflow and nonfinite diagnostics remain explicit probe statuses; they do not become apparently valid zeros. Callable evaluators reject invalid dimensions/nonfinite results. Probing may evaluate outside the coordinate stencils, so it can fail even when gradient diagnostics pass. A supplied gradient is checked at the point, not proven to belong to the same field everywhere.

Value

Plain list with type, point, value, gradient (full result), gradient_reliable, differential (function of an increment), model (function of an absolute point), comparison (table or NULL), probes (requested/actual increments, endpoints), scales, normal, unit_normal, normal_status, plane_coefficients, coefficient_status and note. For the candidate graph hyperplane, normal is (-gradient,1); plane_coefficients appends the offset to that vector. An unrepresentable offset is NA and failed unit normalization returns NULL, with explicit geometry statuses; the centered model remains usable. Table columns are probe, scale, distance, requested_differential, differential, approximation, value, change, remainder, normalized_remainder, displacement_error, status and message. Unavailable diagnostics are NA.

Examples

f <- function(v)v[1]^2+2*v[2]^2
a <- f |> vc_linearization(c(1,1),dx=c(.1,.2))
a$differential(c(.1,.2))
a$model(c(1.1,1.2))
a$comparison

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