View source: R/vc_derivative.R
| vc_derivative | R Documentation |
Evaluate finite difference quotients at three decreasing step sizes. These are numerical approximations, never a proof of differentiability.
vc_derivative(
f,
x,
method = c("central", "forward", "backward"),
h = NULL,
atol = 1e-08,
rtol = 1e-04,
warn = TRUE
)
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. |
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.
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.
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
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.