step.DV: Dumontet-Vignes automatic step selection

In pnd: Parallel Numerical Derivatives, Gradients, Jacobians, and Hessians of Arbitrary Accuracy Order

Dumontet–Vignes automatic step selection

Description

Dumontet–Vignes automatic step selection

Usage

step.DV(
  FUN,
  x,
  h0 = 1e-05 * max(abs(x), sqrt(.Machine$double.eps)),
  range = h0/c(1e+06, 1e-06),
  max.rel.error = .Machine$double.eps^(7/8),
  ratio.limits = c(2, 15),
  maxit = 40L,
  cores = 1,
  preschedule = getOption("pnd.preschedule", TRUE),
  cl = NULL,
  ...
)

Arguments

FUN	Function for which the optimal numerical derivative step size is needed.
x	Numeric scalar: the point at which the derivative is computed and the optimal step size is estimated.
h0	Numeric scalar: initial step size, defaulting to a relative step of slightly greater than .Machine$double.eps^(1/3) (or absolute step if x == 0). This step size for first derivarives is internallt translated into the initial step size for third derivatives by multiplying it by the machine epsilon raised to the power -2/15.
range	Numeric vector of length 2 defining the valid search range for the step size.
max.rel.error	Positive numeric scalar > 0 indicating the maximum relative error of function evaluation. For highly accurate functions with all accurate bits is equal to .Machine$double.eps/2. For noisy functions (derivatives, integrals, output of optimisation routines etc.), it is higher, typically sqrt(.Machine$double.eps). Dumontet and Vignes recommend .Machine$double.eps^(3/4) = 2e-12 for common functions.
ratio.limits	Numeric vector of length 2 defining the acceptable ranges for step size: the algorithm stops if the relative perturbation of the third derivative by amplified rounding errors falls within this range.
maxit	Maximum number of algorithm iterations to avoid infinite loops in cases the desired relative perturbation factor cannot be achieved within the given range. Consider extending the range if this limit is reached.
cores	Integer specifying the number of CPU cores used for parallel computation. Recommended to be set to the number of physical cores on the machine minus one.
preschedule	Logical: if TRUE, disables pre-scheduling for mclapply() or enables load balancing with parLapplyLB(). Recommended for functions that take less than 0.1 s per evaluation.
cl	An optional user-supplied cluster object (created by makeCluster or similar functions). If not NULL, the code uses parLapply() (if preschedule is TRUE) or parLapplyLB() on that cluster on Windows, and mclapply (fork cluster) on everything else.
...	Passed to FUN.

Details

This function computes the optimal step size for central differences using the \insertCitedumontet1977determinationpnd algorithm. If the estimated third derivative is exactly zero, the function assumes a third derivative of 1 to prevent division-by-zero errors.

Note: the iteration history tracks the third derivative, not the first.

Value

A list similar to the one returned by optim():

• par – the optimal step size found.

• value – the estimated numerical first derivative (using central differences).

• counts – the number of iterations (each iteration includes four function evaluations).

• abs.error – an estimate of the truncation and rounding errors.

• exitcode – an integer code indicating the termination status:

  • 0 – Optimal termination within tolerance.

  • 1 – Third derivative is zero; large step size preferred.

  • 3 – Solution lies at the boundary of the allowed value range.

  • 4 – Step trimmed to 0.1|x| when |x| is not tiny and within range.

  • 5 – Maximum number of iterations reached; optimal step size is within the allowed range.

  • 6 – Maximum number of iterations reached; optimal step size was outside allowed range and had to be snapped to a boundary or to 0.1|x|.

  • 7 – No search was performed (used when maxit = 1).

• message – A summary message of the exit status.

• iterations – A list including the full step size search path (note: for the third derivative), argument grids, function values on those grids, and estimated third derivative values.

References

\insertAllCited

Examples

f <- function(x) x^4
step.DV(x = 2, f)
step.DV(x = 2, f, h0 = 1e-3)

# Alternative plug-in estimator with only one evaluation of f'''
step.DV(x = 2, f, maxit = 1)
step.plugin(x = 2, f)

pnd documentation built on Feb. 13, 2026, 1:06 a.m.