vectorialcalculus (version 1.0.5)

critical_points_2d: Critical points of a two-variable function using gradient and Hessian

Description

Identifies stationary points of a function of two variables over a given rectangular domain. A set of initial points is generated on a regular grid together with additional random starting points. Each start is refined using numerical optimization applied to the squared gradient norm. Points with a sufficiently small gradient norm are kept and then merged if they are too close to each other.

Usage

critical_points_2d(
  f,
  xlim,
  ylim,
  start_n = c(7L, 7L),
  n_rand = 40L,
  h = NULL,
  tol_grad = 1e-06,
  tol_merge = 0.001,
  tol_eig = 1e-06,
  maxit = 200,
  optim_method = c("BFGS", "Nelder-Mead"),
  plot = TRUE,
  grid_plot = c(60L, 60L),
  surface_colorscale = "YlGnBu",
  surface_opacity = 0.85,
  cp_colors = list(minimum = "#2ca02c", maximum = "#d62728", saddle = "#1f77b4", flat =
    "#ff7f0e"),
  cp_size = 6,
  scene = list(aspectmode = "data", xaxis = list(title = "x"), yaxis = list(title = "y"),
    zaxis = list(title = "f(x,y)"))
)

Value

A list with:

critical_points

A data frame with columns x, y, z, the gradient norm, and the classification label.

fig

A plotly object if plot = TRUE, or NULL otherwise.

Arguments

f

Function of two variables f(x, y) returning a numeric scalar.

xlim

Numeric vector c(xmin, xmax) defining the domain in the x-direction.

ylim

Numeric vector c(ymin, ymax) defining the domain in the y-direction.

start_n

Integer vector of length two. Number of regular starting points per axis for the grid.

n_rand

Integer. Number of additional random starting points inside the domain.

h

Numeric step size for finite-difference gradients and Hessians. If NULL, an automatic step size is used.

tol_grad

Numeric tolerance. Points with gradient norm below this threshold are treated as stationary.

tol_merge

Numeric tolerance for merging nearby solutions.

tol_eig

Numeric tolerance used when classifying eigenvalues of the Hessian.

maxit

Maximum number of iterations permitted for numerical optimization.

optim_method

Character string naming an optimization method supported by stats::optim, such as "BFGS" or "Nelder-Mead".

plot

Logical. If TRUE, a plotly surface with critical points is drawn.

grid_plot

Integer vector of length two. Resolution of the grid used when drawing the surface.

surface_colorscale

Character. Name of the Plotly colorscale for the surface.

surface_opacity

Numeric between 0 and 1 giving the opacity of the surface.

cp_colors

Named list mapping each critical point type to a color. Expected names: "minimum", "maximum", "saddle", "flat".

cp_size

Numeric. Size of the point markers.

scene

List of Plotly scene options (axis titles, aspect mode, and so on).

Details

Each surviving point is classified based on the eigenvalues of the numerical Hessian matrix. The Hessian classification uses four categories:

• "minimum" - both eigenvalues positive,

• "maximum" - both eigenvalues negative,

• "saddle" - mixed signs,

• "flat" - small eigenvalues, inconclusive classification.

Optionally, a 3D surface with the detected critical points can be displayed using plotly.

Examples

# \donttest{
f <- function(x, y) x^2 + y^2
critical_points_2d(f, xlim = c(-2, 2), ylim = c(-2, 2), plot = FALSE)
# }