cubic_spline() [1/2]

template<typename Scalar >

Scalar stan::math::internal::cubic_spline ( Scalar  x_left, Scalar  f_left, Scalar  df_left, Scalar  x_right, Scalar  f_right, Scalar  df_right  )

inlinenoexcept

Selects a safeguarded trial point for maximizing a scalar function on a line.

The routine assumes a 1-D bracket [x_left, x_right], together with function values and directional derivatives at both endpoints. Internally it:

1. Normalizes the interval to $s \in [0, 1]$ via x(s) = x_left + s * (x_right - x_left), and builds a cubic Hermite model F(s) that matches {f_left, df_left} at s = 0 and {f_right, df_right} at s = 1.
2. Initializes the best candidate at the bisection point s = 0.5.
3. Adds a secant candidate for the derivative root, using the derivative values at s = 0 and s = 1: F'(0) = width * df_left, F'(1) = width * df_right.
4. Finds stationary points of the cubic model by solving F'(s) = 0. This reduces to a quadratic equation, handled with a numerically stable q-formula and tolerances for degeneracies (nearly linear derivative, small discriminant, etc.).
5. Evaluates all admissible model-based candidates and keeps the one with the largest F(s). All such candidates are restricted to a trimmed interior $s \in [edge_guard, 1 - edge_guard]$, i.e. $x \in [x_left + edge_guard * width, x_right - edge_guard * width]$.
6. If the bracket is invalid (x_right <= x_left), any input is non-finite, or the interval is too tiny to be useful, it falls back to pure bisection and returns (x_left + x_right) / 2.

The intended use is in line searches for MAXIMIZATION with a "well-formed" bracket satisfying x_left < x_right, df_left > 0, df_right < 0. These sign conditions are not required for safety; they only improve the model.

Template Parameters

Scalar

Floating-point scalar type (float, double, long double).

Parameters

x_left	Left endpoint of the current bracket.
f_left	Function value at x_left, i.e. f(x_left).
df_left	Directional derivative at x_left with respect to increasing x, i.e. f'(x_left) in the search direction.
x_right	Right endpoint of the current bracket.
f_right	Function value at x_right, i.e. f(x_right).
df_right	Directional derivative at x_right with respect to increasing x, i.e. f'(x_right) in the search direction.

Returns

A trial point in the trimmed interior of (x_left, x_right) chosen by the cubic/derivative model. If inputs are degenerate, the midpoint (x_left + x_right) / 2 is returned instead.

Definition at line 159 of file wolfe_line_search.hpp.