vc_concavity: Sample concavity and search for smooth inflection candidates

View source: R/concavity.R

vc_concavityR Documentation

Sample concavity and search for smooth inflection candidates

Description

Sample concavity and search for smooth inflection candidates

Usage

vc_concavity(
  f,
  interval,
  n = 201L,
  h = NULL,
  h2 = NULL,
  x_tol = 1e-08,
  atol = 1e-08,
  rtol = 1e-04,
  max_iter = 100L
)

Arguments

f

Deterministic function accepting a real scalar and returning one finite real scalar. Vectorization is not required.

interval

Increasing pair of finite real search bounds.

n

Integer number of grid samples, at least 5.

h

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

h2

Optional positive second-difference step, as in vc_taylor().

x_tol

Positive root refinement tolerance; candidates within 10*x_tol are merged, keeping the smallest sampled derivative residual.

atol

Nonnegative finite absolute tolerance for sensitivity comparisons.

rtol

Nonnegative finite relative tolerance for sensitivity comparisons.

max_iter

Positive integer limit for bracketed root refinement. Bounded local minimization uses stats::optimize() with its own stopping rule.

Details

Reuses the direct three-point second-difference engine from Taylor, with three-scale sensitivity and roundoff diagnostics. Only reliable nonzero signs label concavity; region bounds cover sample spans, not proved continuous intervals. Inflection candidates require opposite consistent reliable curvature signs at three radii, contracting function-value neighborhood evidence and a stable numerical first derivative. A zero second difference alone is not an inflection. Singular and unresolved candidates remain separate. Continuous curvature sign changes with unresolved first-derivative evidence are reported in singular_candidates, not asserted to be smooth inflections. Default neighborhood curvature steps are capped at one percent of distance from the candidate to avoid straddling its possible singularity. This finite search is incomplete; it need not detect inflections with nonexistent or singular derivatives. Positive/negative f” on an interval gives the usual concavity criterion; this function labels only sampled evidence. Second-difference O(h^2) truncation presumes sufficient fourth-order local smoothness and spacing. Numerical evidence does not prove continuity or a change of concavity. Invalid/warning-producing numerical probes are recorded as unavailable when their values fail validation; probing warnings are suppressed.

Value

Plain list with type, interval, scan (x, value, second_derivative, reliable, classification), regions (sample spans), inflections (x, value, left_sign, right_sign, status), singular_candidates (same columns), rejected_candidates, complete=FALSE, status (sampled or no_evaluable_curvature), refinements (attempted root refinements with residual/status/messages), note. Scan labels are concave_up, concave_down, near_zero or unresolved.

Examples

vc_concavity(function(x) x^3, c(-1,1))$inflections
f <- function(x) x^4
(f |> vc_concavity(interval=c(-1,1)))$inflections

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