Struct InnerExecutor 

pub struct InnerExecutor<S, So> { /* private fields */ }

Pre-configured inner solver an outer solver drives once per outer iteration.

Owns the configured inner solver, execution controls, and its max_iter budget. The problem is supplied (borrowed) at run time, so the outer solver can pass the &P it receives in next_iter without taking ownership.

Mirrors Executor’s builder API: max_iter and stop_when_factory are chainable. The differences are (a) the problem isn’t owned, and (b) run is reusable: the same InnerExecutor is expected to be invoked many times across the outer’s lifetime.

run_loop_with_control provides the lower-level interface for custom outer solvers.

Serialization

With serde, the solver and iteration/evaluation/time budgets serialize. Application hooks, deprecated criteria, capability controls (raw budgets and publication validation), and erased target/stall checks cannot be reconstructed and cause a serialization error. They are never silently dropped from an exact checkpoint.

Composition contracts

Three rules outer solvers must follow when consuming the result of run; see also CONTRIBUTING.md “Solver composition”:

1. Eval aggregation. The Problem wrapper bumps EvalCounts on every cost/gradient/residual/Jacobian/Hessian call, and the executor mirrors the per-run delta onto the inner state via CountsMirror. What the outer must do depends on which problem the inner sees:

   • Same-problem inner (the outer passes its own &mut Problem<P> to run): the inner’s calls bump the same wrapper as the outer’s, so aggregation happens transparently. No explicit roll-up; the outer state’s CountsMirror impl decides how the counts surface on its State::cost_evals/ GradientState::gradient_evals.
   • Adapter-problem inner (the outer builds a fresh Problem::new(adapter) per outer iter, e.g. the barrier and augmented-Lagrangian methods): after run returns, fold the inner wrapper’s counts back into the outer’s wrapper via EvalCounts::add on Problem::counts_mut. Skipping this fold silently corrupts MaxCostEvals budgets and the public result.cost_evals().

   See the Solver::next_iter contract for the canonical wording.

2. History resets per run. Each fresh run resets solver convergence, built-in clocks and stall checks, and deprecated criterion history. stop_when_factory creates a fresh custom closure per run. A direct stop_when closure retains its captures across calls.

3. Failure routing. run returns a full OptimizationResult; classify the reason. Use TerminationReason::is_failure to decide whether to bubble: SolverFailed should bubble via the outer’s mid-iter Option<TerminationReason> return; everything else (MaxIter, *Tolerance, SolverConverged, NumericalNoProgress) is a “clean stop” the outer can consume and continue past. A clean stop does not itself establish convergence or solution accuracy.

Implementations

impl<S: State + CountsMirror, So> InnerExecutor<S, So>

pub fn new(solver: So) -> Self

Build an inner executor around solver. Default max_iter is 1000, mirroring Executor::new.

pub fn max_iter(self, n: u64) -> Self

Set the inner-loop iteration budget. Each call to run drives the inner solver up to this many iterations.

pub fn require_evaluated_state(self) -> Self

where S: EvaluatedState,

Validate complete records at publication boundaries.

See RunControl::require_evaluated_state for validation ordering and solver-contract panics. This control cannot be serialized as part of an inner executor.

pub fn max_evaluations(self, kind: EvaluationKind, limit: u64) -> Self

where S: RawEvaluationState,

Set a raw category or total-work budget at iteration boundaries.

See RunControl::max_evaluations for accounting, precedence, and serialization limits.

pub fn target_objective<F: Scalar + 'static>(self, target: F) -> Self

where S: ObjectiveIncumbentState<Float = F>,

Stop when an eligible objective-ordered incumbent reaches a finite target.

Replaces target_cost, and vice versa. See RunControl::target_objective.

pub fn no_objective_improvement<F: Scalar + 'static>( self, patience: u64, min_delta: F, ) -> Self

where S: ObjectiveIncumbentState<Float = F>,

Stop after completed iterations without a sufficient objective decrease.

Replaces no_improvement, and vice versa. See RunControl::no_objective_improvement for threshold validation, publication age, and resume behavior.

pub fn max_cost_evals(self, limit: u64) -> Self

Set a cost-evaluation budget, checked after initialization and between iterations.

pub fn max_gradient_evals(self, limit: u64) -> Self

where S: GradientState,

Set a gradient-evaluation budget, checked between iterations.

pub fn max_time(self, limit: Duration) -> Self

Set a time budget starting at the first post-initialization check.

pub fn target_cost<F: Scalar + 'static>(self, target: F) -> Self

where S: State<Float = F>,

Stop when the state’s best cost reaches the finite target.

pub fn no_improvement<F: Scalar + 'static>( self, patience: u64, min_delta: F, ) -> Self

where S: State<Float = F>,

Stop after patience checks without improvement greater than min_delta.

pub fn no_acceptance(self, patience: u64) -> Self

where S: AcceptanceState,

Stop after a positive number of iterations without an accepted move.

pub fn stop_when_factory<M, C>(self, make: M) -> Self

where M: FnMut() -> C + 'static, C: FnMut(&S) -> Option<TerminationReason> + 'static,

Append a factory creating fresh application-stop history for each run.

pub fn terminate_on<C>(self, criterion: C) -> Self

where C: TerminationCriterion<S> + 'static,

👎Deprecated:

configure inner solver convergence or use stop_when_factory; removal scheduled for Basin 2.0

Add a termination criterion to the inner loop. Criteria are checked in insertion order before each inner iteration. See the type-level “Composition contracts” for the statelessness requirement that applies because criteria are reused across run calls.

pub fn stop_when<C>(self, check: C) -> Self

where C: FnMut(&S) -> Option<TerminationReason> + 'static,

Append an application stop whose captures persist across inner runs. Use stop_when_factory for fresh per-run history.

pub fn solver(&self) -> &So

Read-only access to the inner solver. Lets composed outer solvers dispatch on the inner before run, e.g. to build an inner state via InitialState::seed or MemeticInner::seed_scaled. Mutable access goes through run, which already takes &mut self.

pub fn run<P>( &mut self, problem: &mut Problem<P>, state: S, ) -> Result<OptimizationResult<S>, So::Error>

where So: Solver<P, S>,

Drive the inner solver against problem from state, returning the final inner state and termination reason. Reusable: call once per outer iter.

The inner state’s State::cost_evals reflects only per-run work (snapshot-relative against the wrapper count at entry), not cumulative across calls. The wrapper itself accumulates monotonically: for same-problem composition the outer reads its own Problem::counts after run to see total work; for adapter-problem composition the outer builds a fresh inner Problem and folds counts via EvalCounts::add on Problem::counts_mut after run returns.

Internally exactly run_loop_with_control: init is called on every invocation, so the inner solver sees a fresh setup pass each time (e.g. seeding cost/gradient at the new starting point).

Trait Implementations

impl<'de, S, So> Deserialize<'de> for InnerExecutor<S, So>

where So: Deserialize<'de>,

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<S, So> Serialize for InnerExecutor<S, So>

where So: Serialize,

Available on crate feature serde only.

fn serialize<Ser>(&self, serializer: Ser) -> Result<Ser::Ok, Ser::Error>

where Ser: Serializer,

Serialize this value into the given Serde serializer.