vectorialcalculus (version 1.0.5)

critical_points_nd: Critical points of a scalar field in n dimensions (no plot)

Description

Searches for approximate critical points of a scalar field f(x) in dimension n >= 3 over a rectangular domain. The algorithm looks for points where the gradient is close to zero by minimizing the squared gradient norm g(x) = ||grad f(x)||^2 from multiple starting points.

Usage

critical_points_nd(
  f,
  bounds,
  start_grid = NULL,
  n_random = 50L,
  max_grid_starts = 2000L,
  h = NULL,
  tol_grad = 1e-06,
  tol_merge = 0.001,
  tol_eig = 1e-06,
  maxit = 200,
  optim_method = c("BFGS", "Nelder-Mead"),
  seed = NULL,
  store_hessian = FALSE
)

Value

A list with components:

critical_points

A data frame with columns x1, ..., xn, the function value f, the gradient norm grad_norm, and the classification label class.

eigvals

A list of numeric vectors containing the Hessian eigenvalues for each critical point.

hessians

If store_hessian = TRUE, a list of Hessian matrices (one per critical point). Otherwise NULL.

starts_info

A list with information about the number of grid and random starting points actually used.

Arguments

f

Scalar field as function(x), where x is a numeric vector of length n, returning a numeric scalar.

bounds

Domain bounds. Either:

• an n x 2 numeric matrix or data frame with columns lower and upper, or

• a list of length n, each element a numeric vector c(lower, upper).

start_grid

Integer vector of length n with the number of regular grid points per dimension used as deterministic starting points. If NULL, a default rep(5, n) is used. The total number of grid points is limited by max_grid_starts.

n_random

Integer. Number of additional random starting points sampled uniformly inside the domain defined by bounds.

max_grid_starts

Maximum number of deterministic grid starting points that are actually used. If the full grid would exceed this value, a random subset of that size is taken.

h

Step size for finite differences. Can be:

• NULL: automatic componentwise step size 1e-4 * (1 + abs(x_i)),

• a numeric scalar: same step for all coordinates,

• a numeric vector of length n: one step per coordinate.

tol_grad

Numeric threshold on the gradient norm used to accept a point as critical. Smaller values make the criterion more strict.

tol_merge

Numeric radius used to merge nearby critical point candidates (Euclidean distance).

tol_eig

Numeric tolerance used to decide whether Hessian eigenvalues are treated as positive, negative or close to zero for classification.

maxit

Maximum number of iterations allowed for each call to stats::optim().

optim_method

Primary optimization method passed to stats::optim(), for example "BFGS" or "Nelder-Mead". If the primary method fails with an error, the function falls back to "Nelder-Mead".

seed

Optional integer seed for reproducibility of the random starting points.

store_hessian

Logical. If TRUE, the Hessian matrix at each critical point is stored and returned.

Details

Candidate points that are closer than tol_merge (in Euclidean distance) are merged into a single representative. Each accepted point is classified by the eigenvalues of the numerical Hessian as "minimum", "maximum", "saddle" or "flat".

Gradients and Hessians are computed with second-order central finite differences.

Examples

# \donttest{
# Example 1: unique minimum at (1, 1, 1)
f1 <- function(x) sum((x - 1)^2)
B  <- rbind(c(-2, 3), c(-2, 3), c(-2, 3))  # 3D bounds
res1 <- critical_points_nd(
  f1,
  bounds      = B,
  start_grid  = c(5, 5, 5),
  n_random    = 50,
  seed        = 1
)
res1$critical_points

# Example 2: saddle at the origin in 3D
f2 <- function(x) x[1]^2 + x[2]^2 - x[3]^2
B2 <- rbind(c(-1, 1), c(-1, 1), c(-1, 1))
res2 <- critical_points_nd(
  f2,
  bounds      = B2,
  start_grid  = c(5, 5, 5),
  n_random    = 30,
  seed        = 123
)
res2$critical_points

# Example 3 (4D): multiple critical points
f3 <- function(x) sum(x^4 - 2 * x^2)
B3 <- do.call(rbind, replicate(4, c(-2, 2), simplify = FALSE))
res3 <- critical_points_nd(
  f3,
  bounds      = B3,
  start_grid  = rep(4, 4),
  n_random    = 200,
  seed        = 42
)
head(res3$critical_points)
# }