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    /// The user's intermediate callback returned `false` from a
62    /// restoration-phase fire (gh#645). Outer loop maps this to
63    /// `SolverReturn::UserRequestedStop` **without** promoting the
64    /// staged trial point, so the solve hands back the last iterate
65    /// accepted for the *original* NLP rather than a point of the
66    /// restoration subproblem — the same discipline the pounce#244
67    /// deadline exit already follows.
68    UserRequestedStop,
69    /// The original NLP is square and the restoration phase reached a
70    /// point feasible for it to `constr_viol_tol`. Port of the
71    /// `FEASIBILITY_PROBLEM_SOLVED` throw at `IpRestoMinC_1Nrm.cpp:269`;
72    /// the outer loop maps this to `SolverReturn::FeasiblePointFound`
73    /// (`IpIpoptAlg.cpp:542`) after recomputing the multipliers of the
74    /// feasibility problem. The impl has already promoted the recovered
75    /// point to `data.curr`.
76    FeasiblePointFound,
77}
78
79pub trait RestorationPhase {
80    /// Inner-IPM iteration count from the most recent
81    /// `perform_restoration` call. Read by `IpoptAlgorithm` for the
82    /// pounce#12 audit counters in `SolveStatistics`. Default 0; the
83    /// concrete `MinC1NormRestoration` impl stashes
84    /// `RestoSolveResult::iter_count` and returns it here.
85    fn last_inner_iter_count(&self) -> pounce_common::types::Index {
86        0
87    }
88
89    /// Drive a feasibility-restoration sub-solve. The impl reads the
90    /// outer iterate from `data.curr`, the original NLP from `nlp`,
91    /// uses `aug_solver` for any post-success multiplier-recomputation
92    /// least-square solve, and on success writes the recovered iterate
93    /// into `data.trial`. Default returns
94    /// [`RestorationOutcome::Failed`] — the trait surface is uniform
95    /// for `AlgBuilder` even when no concrete restoration is wired.
96    fn perform_restoration(
97        &mut self,
98        _data: &IpoptDataHandle,
99        _cq: &IpoptCqHandle,
100        _nlp: &Rc<RefCell<dyn IpoptNlp>>,
101        _aug_solver: &mut dyn AugSystemSolver,
102    ) -> RestorationOutcome {
103        RestorationOutcome::Failed
104    }
105
106    /// Forward the outer interactive debugger onto the restoration inner
107    /// IPM so the same debugger can step the sub-solve. Default no-op.
108    fn set_debug_hook(
109        &mut self,
110        _hook: Option<std::rc::Rc<std::cell::RefCell<dyn crate::debug::DebugHook>>>,
111    ) {
112    }
113
114    /// Forward the user's TNLP onto the restoration inner IPM so its
115    /// `intermediate_callback` fires from the sub-solve too (gh#645).
116    /// Default no-op, like [`Self::set_debug_hook`] above, which this
117    /// deliberately mirrors — the debugger took the same route first.
118    ///
119    /// Without this the callback fires only from the outer loop, so a
120    /// caller is blind for the whole of restoration. That is the phase
121    /// most likely to overrun a control period, which makes it the
122    /// phase a real-time caller most needs to be able to abort in.
123    ///
124    /// The inner IPM iterates on the min-C1-norm feasibility
125    /// subproblem, so the stats those fires carry describe *that*
126    /// problem, not the user's NLP. `AlgorithmMode::RestorationPhaseMode`
127    /// on each such fire is what makes them interpretable, and
128    /// [`crate::ipopt_alg::IpoptAlgorithm::fires_as_restoration`] is
129    /// what sets it — see the note there on why the live-inspector
130    /// context is deliberately *not* installed for these fires.
131    fn set_intermediate_tnlp(
132        &mut self,
133        _tnlp: Option<std::rc::Rc<std::cell::RefCell<dyn pounce_nlp::tnlp::TNLP>>>,
134    ) {
135    }
136
137    /// Inject the orig-progress callback the inner IPM should consult at
138    /// every iteration. Mirrors upstream
139    /// `IpRestoFilterConvCheck::SetOrigLSAcceptor` (the outer line
140    /// search hands its acceptor to the resto conv check at restoration
141    /// entry). Default no-op so non-filter-aware drivers compose.
142    fn set_orig_progress_check(&mut self, _cb: Option<OrigProgressCallback>) {}
143
144    /// Propagate the outer algorithm's per-iteration print gate to the
145    /// restoration driver so the nested restoration IPM honors
146    /// `print_level == 0` instead of leaking its `r`-suffixed iteration
147    /// table to stdout. Default no-op for drivers without a nested IPM.
148    fn set_print_iter_output(&mut self, _enabled: bool) {}
149}
pounce_algorithm/restoration.rs

pounce_algorithm/
restoration.rs
