vc_directional: Approximate a directional derivative on its actual line...

View source: R/multivariable.R

vc_directionalR Documentation

Approximate a directional derivative on its actual line restriction

Description

Approximate a directional derivative on its actual line restriction

Usage

vc_directional(
  f,
  point,
  direction,
  method = c("central", "forward", "backward"),
  h = NULL,
  atol = 1e-08,
  rtol = 1e-04,
  warn = TRUE,
  gradient = NULL
)

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.

direction

Nonzero finite real vector matching point. It is normalized by scaled arithmetic to avoid squared-norm overflow/underflow. No change in direction magnitude changes the mathematical unit-direction derivative.

method

One of "central", "forward", or "backward".

h

Initial step in the line parameter, or NULL for max(1,abs(point)) times the one-variable epsilon heuristic. Every active coordinate must move representably at each nonzero stencil parameter; otherwise an error asks for rescaling or a larger step, rather than returning a false zero.

atol

Nonnegative finite absolute tolerance for sensitivity comparisons.

rtol

Nonnegative finite relative tolerance for sensitivity comparisons.

warn

Logical scalar; warn when sensitivity diagnostics fail.

gradient

Optional vc_gradient result at this same point/value for a diagnostic dot-product comparison. NULL does not compute any gradient.

Details

Differentiates t -> f(point+t*direction) at zero with vc_derivative(), rather than assuming the gradient formula. With a supplied gradient, agreement is checked against atol+rtol times the larger magnitude, and both diagnostic flags must pass for compatible/mismatch labels. The identity with the dot product requires appropriate differentiability; agreement of finitely many probes is not a proof. Discontinuous or nonsmooth fields can have misleading symmetric quotients. One-sided methods yield only one-sided evidence. Normalized components lost to underflow are errors. For mathematically axis-aligned directions, use exact zeros rather than roundoff-sized components from trigonometric evaluations at cardinal angles.

Value

Plain list with type, point, value, direction (unit vector), method, estimate, derivative (full one-variable diagnostics), reliable, optional gradient_dot and difference (NA without gradient), gradient_comparison (not_requested, compatible, mismatch or inconclusive), and note.

Examples

f <- function(v)v[1]^2+2*v[2]^2
g <- f |> vc_gradient(c(1,2))
f |> vc_directional(c(1,2),direction=c(3,4),gradient=g)

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