vc_taylor: Numerical Taylor approximations of order one or two

View source: R/vc_taylor.R

vc_taylorR Documentation

Numerical Taylor approximations of order one or two

Description

Construct P(x) = f(x0) + d1*(x-x0) + d2*(x-x0)^2/2 (order two), or omit the quadratic term for order one. Derivatives are numerical.

Usage

vc_taylor(
  f,
  x0,
  order = 2L,
  x = NULL,
  method = c("central", "forward", "backward"),
  h = NULL,
  h2 = NULL,
  atol = 1e-08,
  rtol = 1e-04,
  warn = TRUE
)

Arguments

f

Deterministic function accepting a real scalar and returning one finite real scalar. Vectorization is not required.

x0

Finite real scalar evaluation point of the local model.

order

Integer 1 or 2. Higher orders are not implemented.

x

Optional nonempty finite real vector at which to compare f and P. NULL leaves comparison empty; the returned polynomial is still evaluable.

method

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

h

Positive finite real initial derivative step, or NULL for the heuristic used by vc_derivative(), evaluated with x = x0.

h2

Positive finite initial step for the second derivative. NULL uses max(1, abs(x0)) * .Machine$double.eps^(1/4). Ignored for order one, but a supplied value must still be valid. h controls only the first derivative.

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

The first derivative reuses vc_derivative() with its selected method and diagnostics. Order two uses a direct three-point stencil, never repeated numerical differentiation. With actual representable displacements a = x0-left and b = right-x0, the second derivative is 2 * ((f(right)-f(x0))/b - (f(x0)-f(left))/a) / (a+b). Equal spacing gives the usual centered second difference, with nominal second-order truncation for sufficiently smooth functions. Asymmetric rounded stencils can reduce that order.

Second-derivative steps h2, h2/2, h2/4 are compared using the same absolute/relative tolerance rule as vc_derivative(). An additional roundoff indicator is 4epsilonmax(abs(stencil values))/min(a,b)^2. The finest indicator must not exceed atol + rtol*abs(d2). This is a conservative floating-point scale heuristic, not a rigorous error bound. The finest estimate is retained even if checks fail. Order two always requires finite values on both sides, even with a one-sided first derivative.

A genuine Taylor interpretation assumes the required derivatives exist near x0. Numerical checks do not establish this assumption. Comparison errors are sampled differences f(x)-P(x), not certified remainder bounds. Optional comparison points with failed/nonfinite function evaluations have value and error NA, with explicit status; evaluation warnings are suppressed. Nonfinite polynomial values are likewise NA in the comparison table. Large offsets, cancellation and unresolved oscillations can evade checks. Checks are conservative: the existing first-derivative side comparison can flag smooth stationary points, and the second-derivative roundoff indicator can flag a nonzero constant with exactly zero curvature. Such results are retained with failed diagnostics, not declared invalid.

Value

Plain list with type, x0, y0, order, coefficients (in powers of x-x0, including the constant), polynomial (a vectorized function), derivative (full vc_derivative result), second_derivative (diagnostics list or NULL), comparison (data frame or NULL), reliable and note. The comparison columns are x, distance, value, approximation, error, abs_error and status. reliable means only that applicable numerical checks passed. The polynomial rejects invalid inputs and overflowing evaluations. second_derivative contains estimate, h, diagnostics (step, left_step, right_step, estimate, roundoff_indicator), changes, stable, resolved, and reliable. stable compares successive estimates; resolved checks the finest roundoff indicator; reliable is their conjunction.

Examples

a <- vc_taylor(exp, 0, order = 2, x = c(-0.2, 0, 0.2))
a$comparison
a$polynomial(c(0, 0.1))
sin |> vc_taylor(x0 = 0, order = 1, x = c(0, 0.2))

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