Module executor 

Iteration driver. The high-level entry point is Executor; Stepper exposes one-iteration-at-a-time control, and run_loop_with_control is the borrowed-problem variant used by composed solvers.

Canonical iteration ordering

Executor::run (and the equivalent Stepper/run_loop_with_control paths) drive the solver through this exact sequence, and every contract elsewhere in the framework cross-links here:

1. Convergence history resets, then Solver::init is called once. The returned state is what iter-0 sees.
2. Then, repeatedly, before each Solver::next_iter call (including the first):
   1. An executor-attached CancellationToken is checked, when configured. Cancellation stops the run with Termination::Cancelled. The borrowed run_loop_with_control path has no attached token and skips this step.
   2. Execution controls check iteration, legacy cost and gradient budgets, raw evaluation budgets, elapsed time, target cost, improvement stall, and acceptance stall, followed by application hooks in insertion order. See RunControl.
   3. Solver::check_convergence evaluates solver-owned convergence. Its default delegates to the legacy Solver::terminate hook. The first stop ends the run.
3. If nothing fired, Solver::next_iter returns a SolverStep. The executor publishes counts and coherent progress, increments the iteration counter when completed is true, and updates the incumbent.
4. A step with termination stops with a report tagged TerminationStage::Step. Otherwise execution returns to step 2.

Because checks happen before iter 0, an already-optimal initial point exits immediately with the corresponding reason rather than taking one redundant step.

With Executor::require_evaluated_state, each successful init or next_iter return is checked for a complete record before bookkeeping or observation, including clean mid-step stops. Restored checkpoints are also validated before observation. Missing records panic as solver contract violations; hard problem errors bypass publication and validation.

Executor::resume restores state-carried evolution data and evaluation counters, while Executor::resume_from_checkpoint restores the solver, state, and counters from an ExactCheckpoint and skips init. Consume a paused stepper with Stepper::into_checkpoint, or retain the final solver and raw counters with Executor::run_with_solver.

Structs

CancellationToken

Shared, one-shot signal for stopping an Executor between iterations.

Executor

User-facing driver. Owns the problem, solver, initial state, and the execution controls; run drives the iteration loop to completion. See the module docs for the canonical ordering and into_stepper for one-step-at-a- time control.

OptimizationResult

Outcome of an optimization run.

OptimizationResultWithSolver

Outcome of an optimization run that retains the final solver by ownership.

Stepper

Drive a solver one iteration at a time.

Enums

StepOutcome

Outcome of a single Stepper::step call.

Functions

run_loop_with_control

Drive a borrowed solver using execution budgets and application stops.