vc_newton: Newton-Raphson iteration with explicit termination...

View source: R/newton.R

vc_newtonR Documentation

Newton-Raphson iteration with explicit termination diagnostics

Description

Newton-Raphson iteration with explicit termination diagnostics

Usage

vc_newton(
  f,
  x0,
  df = NULL,
  h = NULL,
  max_iter = 50L,
  f_tol = 1e-08,
  x_tol = 1e-08,
  derivative_tol = 1e-12,
  method = c("central", "forward", "backward")
)

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.

df

Optional function returning a finite real derivative scalar. NULL uses vc_derivative(), retaining its diagnostics.

h

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

max_iter

Nonnegative integer maximum number of accepted updates.

f_tol

Nonnegative absolute numerical residual tolerance.

x_tol

Nonnegative relative step tolerance, scaled by max(1,abs(x_next)).

derivative_tol

Nonnegative absolute safety threshold for slope size.

method

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

Details

Uses x_next=x-f(x)/df(x), without damping or fallback. The initial residual is checked before evaluating the slope. Later acceptance as converged requires residual <=f_tol and a relative step <=x_tol, or an exactly zero computed residual. A small step with a large residual is stagnation. Repeated iterates within x_tol flag a cycle, not convergence. These finite numerical tests are not a proof of a mathematical root. Near a simple root, sufficient smoothness and a sufficiently close start give the usual local Newton theory; arbitrary starts and multiple roots have no such general guarantee. Finite-difference derivatives also do not promise the quadratic rate of exact-derivative Newton theory. Small slopes, scale, rounding, restricted domains and poor derivative estimates can prevent convergence. Numerical derivative diagnostics that fail terminate the iteration conservatively. A supplied df is checked for finite scalar output, not independently certified to be the derivative of f. Warnings during numerical derivative probes and trial evaluations are suppressed; invalid results are retained as failure diagnostics rather than treated as usable values.

Value

Plain list with type, x0, estimate (last accepted iterate), converged, status, iterations (n, x, fx, dfx, step, residual, derivative_status), derivative_diagnostics, rejected_trial (or NULL), control (input numerical settings), and note. status is converged, max_iter, derivative_too_small, derivative_unreliable, nonfinite_derivative, nonfinite_evaluation, nonfinite_step, stagnation or cycle_detected. Unaccepted trials never replace the last valid iterate.

Examples

f <- function(x) x^2-2
f |> vc_newton(x0=1)
vc_newton(function(x) x^2, 0)$status
vc_newton(function(x) x^3-2*x+2, 0)$status

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