specular.optimization.LineSearchError

Bases: RuntimeError

Exception raised when a line search cannot accept a finite, positive step. It is a subclass of RuntimeError.

Notes

Searches created with make_step_size raise this exception for failures such as a non-descent initial slope, an exhausted budget, a search bound reached without acceptable curvature, or stagnation at floating-point precision. A failed search does not return an unchecked fallback step.

minimize and specular_gradient catch this exception from a step rule and return an OptimizationResult with success=False and a stop_reason beginning with "line search failed:". The last accepted point remains intact. Invalid arguments or callback shape errors use their own exceptions and are not treated as a failed line search.

Examples

Copy

from specular.optimization import LineSearchError, make_step_size

search = make_step_size(
    "armijo",
    f=lambda x: x * x,
    gradient=lambda x: 2.0 * x,
)

try:
    search(1, x=1.0, d=1.0)
except LineSearchError as error:
    print(error)
# Line search requires a descent direction (negative raw slope)

Source code in specular/optimization/step_size.py

Copy

class LineSearchError(RuntimeError):
    """A line search could not accept a finite, positive step."""