vc_derivative: Approximate a derivative with finite differences

View source: R/vc_derivative.R

vc_derivativeR Documentation

Approximate a derivative with finite differences

Description

Evaluate finite difference quotients at three decreasing step sizes. These are numerical approximations, never a proof of differentiability.

Usage

vc_derivative(
  f,
  x,
  method = c("central", "forward", "backward"),
  h = NULL,
  atol = 1e-08,
  rtol = 1e-04,
  warn = TRUE
)

Arguments

f

Function accepting a real scalar and returning one finite real scalar. It should be deterministic. Vectorization is not required.

x

Finite real scalar at which to approximate the derivative.

method

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

h

Positive finite real initial step. NULL uses max(1, abs(x)) times machine epsilon to the power 1/3 for central differences or 1/2 for one-sided differences. This heuristic is not optimal for every function or physical scale.

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

For positive s the forward quotient is (f(x+s)-f(x))/s, the backward quotient is (f(x)-f(x-s))/s, and the central quotient is (f(x+s)-f(x-s))/(2*s). The actual representable displacements are used as denominators to account for floating-point rounding of x+s and x-s. For sufficiently smooth functions these have nominal truncation orders one, one, and two, respectively, on an equally spaced stencil.

Steps h, h/2 and h/4 are evaluated. The last approximation is returned. Stability requires both successive changes to be at most atol + rtol * max(abs(the two estimates)). For central differences, the finest left and right quotients must also agree by this criterion. Failure produces a diagnostic and, by default, a warning. Reported changes are sensitivity measures, not rigorous error bounds.

Central differences require finite values on both sides, and one-sided methods require only their selected side and x. Out-of-domain values, collapsed or overflowing stencils, and nonfinite quotients are errors. One-sided results need not equal a two-sided derivative, especially at domain boundaries. Stable results can occur at discontinuities, cusps, or unresolved oscillations; even agreement of all checks is not proof. Cancellation, underflow, and large additive offsets can also conceal error.

Value

A plain list with estimate, x, method, h, a diagnostics data frame (step, forward, backward, estimate; unused sides are NA), changes (absolute successive changes), stable, side_agreement (NA for one-sided methods), reliable (the conjunction of applicable checks, not a mathematical guarantee), and a character note explaining that limitation.

Examples

vc_derivative(function(x) x^3, 2)$estimate
sin |> vc_derivative(x = 0, method = "central")
vc_derivative(abs, 0, warn = FALSE)$reliable
vc_derivative(sqrt, 1, method = "forward")$estimate

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