vc_newton_system: Newton iteration for a square nonlinear system

View source: R/newton_system.R

vc_newton_systemR Documentation

Newton iteration for a square nonlinear system

Description

Newton iteration for a square nonlinear system

Usage

vc_newton_system(
  f,
  x0,
  jacobian = NULL,
  h = NULL,
  method = "central",
  max_iter = 50L,
  f_tol = 1e-08,
  x_tol = 1e-08,
  jacobian_tol = 1e-12,
  backtrack = TRUE,
  max_backtrack = 20L,
  atol = 1e-08,
  rtol = 1e-04
)

Arguments

f

Deterministic function accepting one coordinate vector and returning a finite real vector of the same length (at least two). Output dimension and optional unique/nonempty names must remain fixed. Wrap f(x,y) explicitly as function(v)f(v[1],v[2]); no signature guessing is performed.

x0

Finite initial coordinate vector of length at least two. Optional unique/nonempty names are passed to f and jacobian.

jacobian

Optional function accepting the same vector and returning a finite real square matrix in output-row/input-column order. Entries are checked, but not certified to be derivatives; matrix names never reorder entries. NULL reuses vc_jacobian with complete sensitivity diagnostics.

h

NULL or positive scalar/per-coordinate first-difference steps.

method

One difference method or one per coordinate: central, forward or backward. Used only for the numerical Jacobian.

max_iter

Nonnegative integer maximum accepted updates.

f_tol

Nonnegative absolute infinity-norm residual tolerance.

x_tol

Nonnegative relative step tolerance, using maximum coordinate change divided by max(1,max(abs(next_point))). A small step alone is not convergence.

jacobian_tol

Nonnegative minimum reciprocal one-norm condition estimate. Matrices at or below this threshold are rejected before solving.

backtrack

Logical; TRUE halves a Newton step until its finite residual satisfies residual_next <= (1-1e-4*damping)*residual_current, or residual_next <= f_tol. This safeguard does not guarantee convergence. FALSE accepts any finite trial, recovering undamped Newton iteration.

max_backtrack

Nonnegative integer maximum step halvings per update. The full step is always attempted first.

atol, rtol

Nonnegative absolute/relative sensitivity tolerances passed to vc_jacobian; failed numerical entry flags terminate conservatively.

Details

Solves J*s=-f by a linear solve, never by an explicit inverse. The initial residual is checked before asking for a Jacobian. Later numerical convergence requires residual <= f_tol and a small relative step, or an exactly zero computed residual. A small step with excessive residual is stagnation. Repeated accepted points within x_tol trigger a cycle diagnostic. Rejected trials never replace the last valid iterate.

This recovers original newton_raphson2d's square-system recurrence and iterate records, separates graphics, generalizes dimension and retains conditioning, stencil and domain failures. Exact-Newton local theory requires appropriate differentiability, a nonsingular true Jacobian and a sufficiently close initial point. Arbitrary starts, damping, numerical derivatives, multiple roots and singular systems have no promised global convergence or quadratic rate. Finite residual tests do not prove a root, regularity, uniqueness or that a supplied Jacobian is correct. Fixed tolerances are scale-dependent; rescale poorly conditioned systems.

Value

Plain list with type, x0, estimate (last accepted point), value, converged, status, points and values (rows aligned with iterations), iterations (n, residual, step_norm, relative_step, damping, jacobian_rcond), jacobian_diagnostics, trials (all accepted/rejected attempted steps with point, value, residual, error and damping), control and note. A zero-update or failed search retains the initial row. Status is converged, max_iter, jacobian_unavailable, jacobian_unreliable, jacobian_singular, linear_solve_failed, nonfinite_step, invalid_trial, line_search_failed, stagnation or cycle_detected. Input/initial-field errors raise errors; failures after initialization return diagnostics without erasing history.

Examples

f <- function(v)c(v[1]^2+v[2]^2-1,v[1]-v[2])
f |> vc_newton_system(c(.8,.2))
vc_newton_system(function(v)v,c(0,0))$status

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