liblaf.peach.optim.base ¶

Methods:

• init –

  Create optimizer state from a model state and parameter vector.

• minimize –

  Run optimization until the configured termination rule stops.

• postprocess –

  Build the final solution object.

• step –

  Advance the optimizer by one step.

• terminate –

  Return whether optimization should stop and why.

init[X](
    problem: BaseProblem[X],
    model_state: X,
    params: Vector,
) -> S

26
27
28

def init[X](self, problem: BaseProblem[X], model_state: X, params: Vector) -> S:
    """Create optimizer state from a model state and parameter vector."""
    raise NotImplementedError

minimize[X](
    problem: BaseProblem[X],
    model_state: X,
    params: Vector,
) -> Solution[S, T]

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

def minimize[X](
    self, problem: BaseProblem[X], model_state: X, params: Vector
) -> Solution[S, T]:
    """Run optimization until the configured termination rule stops.

    After every step, [`Problem.callback`][liblaf.peach.optim.base.Problem.callback]
    is called when the concrete problem implements it. The callback receives
    the current model state and the same mutable optimizer state that will be
    stored on the returned [`Solution`][liblaf.peach.optim.base.Solution].

    Args:
        problem: Optimization problem that supplies objective hooks.
        model_state: Initial model state used by objective hooks.
        params: Initial optimizer parameter vector.

    Returns:
        The final solution.
    """
    problem: Problem[X] = cast("Problem[X]", problem)
    opt_state: S = self.init(problem, model_state, params)
    while True:
        self.step(problem, model_state, opt_state)
        if is_implemented(problem, Problem.callback):
            problem.callback(model_state, opt_state)
        ok, result = self.terminate(problem, model_state, opt_state)
        if ok:
            break
    solution: Solution[S, T] = self.postprocess(
        problem, model_state, opt_state, result
    )
    return solution

postprocess[X](
    problem: BaseProblem[X],
    model_state: X,
    opt_state: S,
    result: Result,
) -> Solution[S, T]

44
45
46
47
48
49
50

def postprocess[X](
    self, problem: BaseProblem[X], model_state: X, opt_state: S, result: Result
) -> Solution[S, T]:
    """Build the final solution object."""
    del problem, model_state
    stats: T = cast("T", {})
    return Optimizer.Solution(result=result, state=opt_state, stats=stats)

step[X](
    problem: BaseProblem[X], model_state: X, opt_state: S
) -> None

30
31
32
33
34
35
36

def step[X](self, problem: BaseProblem[X], model_state: X, opt_state: S) -> None:
    """Advance the optimizer by one step.

    Implementations should mutate `model_state` and `opt_state` with any
    accepted parameter, gradient, or diagnostic updates.
    """
    raise NotImplementedError

terminate[X](
    problem: BaseProblem[X], model_state: X, opt_state: S
) -> tuple[bool, Result]

38
39
40
41
42

def terminate[X](
    self, problem: BaseProblem[X], model_state: X, opt_state: S
) -> tuple[bool, Result]:
    """Return whether optimization should stop and why."""
    raise NotImplementedError

Methods:

• callback –

  Run an optional side-effect after an optimizer step.

• fun –

  Evaluate the scalar objective value.

• grad –

  Evaluate the objective gradient.

• hess_diag –

  Evaluate or approximate the Hessian diagonal.

• hess_prod –

  Evaluate the Hessian-vector product along p.

• hess_quad –

  Evaluate the quadratic form p.T @ H @ p.

• max_step_size –

  Return a safe fraction of proposed trial displacement p.

• update –

  Mutate model state for a line-search trial at x.

• value_and_grad –

  Evaluate the objective and gradient together.

callback(model_state: X, opt_state: State) -> None

61
62
63

@not_implemented
def callback(self, model_state: X, opt_state: State, /) -> None:
    """Run an optional side-effect after an optimizer step."""

fun(state: X) -> Scalar

37
38
39

@not_implemented
def fun(self, state: X, /) -> Scalar:
    """Evaluate the scalar objective value."""

grad(state: X) -> Vector

41
42
43

@not_implemented
def grad(self, state: X, /) -> Vector:
    """Evaluate the objective gradient."""

hess_diag(state: X) -> Vector

45
46
47

@not_implemented
def hess_diag(self, state: X, /) -> Vector:
    """Evaluate or approximate the Hessian diagonal."""

hess_prod(state: X, p: Vector) -> Vector

49
50
51

@not_implemented
def hess_prod(self, state: X, p: Vector, /) -> Vector:
    """Evaluate the Hessian-vector product along `p`."""

hess_quad(state: X, p: Vector) -> Scalar

53
54
55

@not_implemented
def hess_quad(self, state: X, p: Vector, /) -> Scalar:
    """Evaluate the quadratic form `p.T @ H @ p`."""

max_step_size(state: X, p: Vector) -> Scalar

65
66
67

@not_implemented
def max_step_size(self, state: X, p: Vector, /) -> Scalar:
    """Return a safe fraction of proposed trial displacement `p`."""

update(state: X, x: Vector) -> None

69
70
71

@not_implemented
def update(self, state: X, x: Vector, /) -> None:
    """Mutate model state for a line-search trial at `x`."""

value_and_grad(state: X) -> tuple[Scalar, Vector]

57
58
59

@not_implemented
def value_and_grad(self, state: X, /) -> tuple[Scalar, Vector]:
    """Evaluate the objective and gradient together."""

Attributes:

• INTERRUPT –
• MAX_STEPS_REACHED –
• NAN –
• PRIMARY_SUCCESS –
• SECONDARY_SUCCESS –
• STAGNATION –
• SUCCESS –
• UNKNOWN_ERROR –
• success (bool) –

  Whether the result represents an accepted optimization outcome.

INTERRUPT = auto()

MAX_STEPS_REACHED = auto()

NAN = auto()

PRIMARY_SUCCESS = auto()

SECONDARY_SUCCESS = auto()

STAGNATION = auto()

SUCCESS = auto()

UNKNOWN_ERROR = auto()

success: bool

Attributes:

• params (Vector) –

  Final optimizer parameters.

• result (Result) –
• state (S) –
• stats (T) –
• success (bool) –

  Whether result is successful.

params: Vector

result: Result

state: S

stats: T

success: bool

Attributes:

• params (Vector) –

  Current optimizer parameters.

params: Vector