pounce_algorithm/
restoration.rs

1//! `RestorationPhase` trait — port of `IpRestoPhase.hpp`.
2//!
3//! Defined here in `pounce-algorithm` (rather than `pounce-restoration`)
4//! so that [`crate::ipopt_alg::IpoptAlgorithm`] can call into it without
5//! creating a circular crate dependency. Concrete impls (the default
6//! `MinC1NormRestoration`, the rare `RestoRestorationPhase`) live in
7//! `pounce-restoration` and `impl RestorationPhase for ...`.
8//!
9//! Called by the main loop when the line search exhausts its alpha
10//! reductions without acceptance (or by the iterate initializer when
11//! `start_with_resto = true`). On success the impl writes a recovered
12//! iterate to `data.trial` and the main loop accepts it; on failure the
13//! main loop surfaces `SolverReturn::RestorationFailure`.
14
15use crate::ipopt_cq::IpoptCqHandle;
16use crate::ipopt_data::IpoptDataHandle;
17use crate::ipopt_nlp::IpoptNlp;
18use crate::kkt::aug_system_solver::AugSystemSolver;
19use pounce_common::types::Number;
20use std::cell::RefCell;
21use std::rc::Rc;
22
23/// Callback that the inner restoration IPM consults at every iteration
24/// to decide whether the recovered iterate is acceptable to the *outer*
25/// algorithm's filter and reference iterate. Mirrors upstream
26/// `IpRestoFilterConvCheck::TestOrigProgress`
27/// (`IpRestoFilterConvCheck.cpp:53-80`): given `(orig_trial_barr,
28/// orig_trial_theta)` evaluated at the inner iterate's `(x_orig, s)`
29/// slice, returns `true` iff
30///
31/// 1. the pair is acceptable to the outer filter, AND
32/// 2. the pair is acceptable to the outer reference iterate (with the
33///    rapid-barrier-increase guard disabled — `force_armijo=true` /
34///    `called_from_restoration=true`).
35///
36/// Constructed by [`crate::line_search::ls_acceptor::BacktrackingLsAcceptor::make_orig_progress_check`]
37/// at restoration entry, with the outer filter cloned and the outer
38/// reference `(theta, barr)` snapshotted in the closure.
39pub type OrigProgressCallback = Box<dyn Fn(Number, Number) -> bool>;
40
41/// Outcome of a restoration attempt. Mirrors upstream's `bool` return
42/// from `RestorationPhase::PerformRestoration` plus the in-band
43/// `info_skip_output` / `iter_count` side-effects that the impl writes
44/// to `data` directly.
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub enum RestorationOutcome {
47    /// Resto succeeded; outer loop should `accept_trial_point` and
48    /// continue. The impl has written the recovered iterate into
49    /// `data.trial`, set `info_skip_output = true`, and updated the
50    /// info counters.
51    Recovered,
52    /// Resto failed. Outer loop maps this to
53    /// `SolverReturn::RestorationFailure`.
54    Failed,
55    /// The inner sub-IPM converged its KKT system but the orig-NLP
56    /// constraint violation at the converged point is still well above
57    /// `tol`. Mirrors the `LOCALLY_INFEASIBLE` exception thrown from
58    /// `IpRestoConvCheck.cpp:240`. Outer loop maps this to
59    /// `SolverReturn::LocalInfeasibility`.
60    LocallyInfeasible,
61}
62
63pub trait RestorationPhase {
64    /// Inner-IPM iteration count from the most recent
65    /// `perform_restoration` call. Read by `IpoptAlgorithm` for the
66    /// pounce#12 audit counters in `SolveStatistics`. Default 0; the
67    /// concrete `MinC1NormRestoration` impl stashes
68    /// `RestoSolveResult::iter_count` and returns it here.
69    fn last_inner_iter_count(&self) -> pounce_common::types::Index {
70        0
71    }
72
73    /// Drive a feasibility-restoration sub-solve. The impl reads the
74    /// outer iterate from `data.curr`, the original NLP from `nlp`,
75    /// uses `aug_solver` for any post-success multiplier-recomputation
76    /// least-square solve, and on success writes the recovered iterate
77    /// into `data.trial`. Default returns
78    /// [`RestorationOutcome::Failed`] — the trait surface is uniform
79    /// for `AlgBuilder` even when no concrete restoration is wired.
80    fn perform_restoration(
81        &mut self,
82        _data: &IpoptDataHandle,
83        _cq: &IpoptCqHandle,
84        _nlp: &Rc<RefCell<dyn IpoptNlp>>,
85        _aug_solver: &mut dyn AugSystemSolver,
86    ) -> RestorationOutcome {
87        RestorationOutcome::Failed
88    }
89
90    /// Forward the outer interactive debugger onto the restoration inner
91    /// IPM so the same debugger can step the sub-solve. Default no-op.
92    fn set_debug_hook(
93        &mut self,
94        _hook: Option<std::rc::Rc<std::cell::RefCell<dyn crate::debug::DebugHook>>>,
95    ) {
96    }
97
98    /// Inject the orig-progress callback the inner IPM should consult at
99    /// every iteration. Mirrors upstream
100    /// `IpRestoFilterConvCheck::SetOrigLSAcceptor` (the outer line
101    /// search hands its acceptor to the resto conv check at restoration
102    /// entry). Default no-op so non-filter-aware drivers compose.
103    fn set_orig_progress_check(&mut self, _cb: Option<OrigProgressCallback>) {}
104
105    /// Propagate the outer algorithm's per-iteration print gate to the
106    /// restoration driver so the nested restoration IPM honors
107    /// `print_level == 0` instead of leaking its `r`-suffixed iteration
108    /// table to stdout. Default no-op for drivers without a nested IPM.
109    fn set_print_iter_output(&mut self, _enabled: bool) {}
110}
pounce_algorithm/restoration.rs

pounce_algorithm/
restoration.rs
