pounce_nlp/ipopt_nlp.rs
1//! NLP traits consumed by the algorithm core — port of `IpNLP.hpp` /
2//! `IpIpoptNLP.hpp`.
3//!
4//! These traits live in `pounce-nlp` (rather than `pounce-algorithm`)
5//! so that the concrete [`crate::orig_ipopt_nlp::OrigIpoptNlp`], which
6//! wraps a `TNLPAdapter` from this same crate, can implement them
7//! without forcing `pounce-nlp` to depend on `pounce-algorithm` (the
8//! reverse dependency already exists). `pounce-algorithm` re-exports
9//! both traits from its own `ipopt_nlp` module so the rest of the
10//! algorithm-side code continues to use the canonical
11//! `crate::ipopt_nlp::IpoptNlp` path.
12
13use pounce_common::types::{Index, Number};
14use pounce_linalg::{DenseVector, Matrix, SymMatrix, SymTMatrix, SymTMatrixSpace, Vector};
15use std::rc::Rc;
16
17/// Human-readable names projected into the algorithm's *split* space —
18/// the index space the debugger reports residuals in, where equality and
19/// inequality constraints are separated and fixed variables are removed.
20///
21/// Each vector is indexed by the split-space position (`x_var[j]` is the
22/// `j`-th free variable, `eq[k]` the `k`-th equality constraint, `ineq[k]`
23/// the `k`-th inequality), and each entry is `Some(name)` when the model
24/// carried one or `None` to fall back to an index label. Producing this
25/// requires composing the TNLP's original-order names with the
26/// fixed-variable and c/d-split permutations, which is why it lives on
27/// the NLP rather than being read directly off the TNLP.
28///
29/// Names are what turn "variables 1, 132, 439 in equations 3, 15" into a
30/// model-level diagnosis — the gap Lee et al. (2024,
31/// <https://doi.org/10.69997/sct.147875>) call out for equation-oriented
32/// model debugging.
33#[derive(Debug, Clone, Default)]
34pub struct SplitNames {
35 /// Names of the free variables, in algorithm-side `x` order (`n()`).
36 pub x_var: Vec<Option<String>>,
37 /// Names of the equality constraints, in `c` order (`m_eq()`).
38 pub eq: Vec<Option<String>>,
39 /// Names of the inequality constraints, in `d` order (`m_ineq()`).
40 pub ineq: Vec<Option<String>>,
41}
42
43impl SplitNames {
44 /// Whether any entry carries a name. An all-`None` projection (e.g.
45 /// the model shipped no `.col`/`.row` files, or presolve declined to
46 /// forward names) is reported as "no names available" so the debugger
47 /// falls back to index labels rather than printing blanks.
48 pub fn any_present(&self) -> bool {
49 self.x_var
50 .iter()
51 .chain(self.eq.iter())
52 .chain(self.ineq.iter())
53 .any(Option::is_some)
54 }
55}
56
57/// Lower-level NLP interface (post-`TNLPAdapter`). Equality and
58/// inequality constraints are already separated; bounds are already
59/// classified into `x_l_map` / `x_u_map` / etc.
60///
61/// This is the equivalent of upstream `Ipopt::NLP`.
62pub trait Nlp {
63 fn n(&self) -> Index;
64 fn m_eq(&self) -> Index;
65 fn m_ineq(&self) -> Index;
66
67 fn eval_f(&mut self, x: &dyn Vector) -> Number;
68 fn eval_grad_f(&mut self, x: &dyn Vector, g: &mut dyn Vector);
69 fn eval_c(&mut self, x: &dyn Vector, c: &mut dyn Vector);
70 fn eval_d(&mut self, x: &dyn Vector, d: &mut dyn Vector);
71 fn eval_jac_c(&mut self, x: &dyn Vector) -> Rc<dyn Matrix>;
72 fn eval_jac_d(&mut self, x: &dyn Vector) -> Rc<dyn Matrix>;
73 fn eval_h(
74 &mut self,
75 x: &dyn Vector,
76 obj_factor: Number,
77 y_c: &dyn Vector,
78 y_d: &dyn Vector,
79 ) -> Rc<dyn SymMatrix>;
80}
81
82/// Algorithm-side NLP (adds scaling-aware variants and provides the
83/// bound expansion matrices `Px_L`, `Px_U`, `Pd_L`, `Pd_U`). Mirrors
84/// upstream `Ipopt::IpoptNLP`.
85/// A `SymTMatrix` over `space` with all values explicitly set to zero.
86///
87/// `SymTMatrix::new` leaves a non-empty matrix flagged uninitialized, and
88/// `values()` asserts on that — so a zero-W block built for its sparsity
89/// alone has to be zeroed before anything walks it.
90pub fn zeroed_sym_t(space: Rc<SymTMatrixSpace>) -> SymTMatrix {
91 let nz = space.nonzeros() as usize;
92 let mut m = SymTMatrix::new(space);
93 m.set_values(&vec![0.0; nz]);
94 m
95}
96
97pub trait IpoptNlp: Nlp {
98 /// Per-evaluation call counts accumulated over the solve, ordered
99 /// `[f, grad_f, c, d, jac_c, jac_d, h]`. Populates the end-of-run
100 /// summary's evaluation tallies (#206). Default is all zeros for
101 /// implementors that do not count; [`OrigIpoptNlp`] reports its live
102 /// counters.
103 fn eval_counts(&self) -> [Index; 7] {
104 [0; 7]
105 }
106
107 /// A zero-valued `SymMatrix` carrying the Lagrangian Hessian's
108 /// *sparsity* and nothing else — upstream's `IpNLP::uninitialized_h`
109 /// (`IpIpoptNLP.hpp`), which `IpLeastSquareMults.cpp:38` uses to
110 /// build its `zeroW` block.
111 ///
112 /// The multiplier least-squares system and the default initializer
113 /// need a W block only so `StdAugSystemSolver` pins its triplet
114 /// structure with the W slots present; they pass `w_factor = 0.0`, so
115 /// the values are never read. Reaching for `curr_exact_hessian()`
116 /// there — an unmemoized `eval_h` — asks the user for a Hessian they
117 /// may have declared they cannot supply, which is exactly the case
118 /// under `hessian_approximation = limited-memory` (gh#698).
119 ///
120 /// Unlike upstream, the values are explicitly **zeroed** rather than
121 /// left uninitialized. Upstream can hand over uninitialized storage
122 /// because `w_factor = 0.0` means nothing reads it; pounce's
123 /// `StdAugSystemSolver::refill_values` still walks the W slots to
124 /// scale them, so the matrix has to be readable.
125 ///
126 /// The default implementation returns an empty (zero-nonzero) block
127 /// of the right dimension, which is correct for any NLP whose W is
128 /// structurally empty and safe for the rest: a caller that passes
129 /// `w_factor = 0.0` only ever needed the slots.
130 fn uninitialized_h(&self) -> Rc<dyn SymMatrix> {
131 Rc::new(zeroed_sym_t(SymTMatrixSpace::new(
132 self.x_l().dim(),
133 Vec::new(),
134 Vec::new(),
135 )))
136 }
137
138 fn x_l(&self) -> &dyn Vector;
139 fn x_u(&self) -> &dyn Vector;
140 fn d_l(&self) -> &dyn Vector;
141 fn d_u(&self) -> &dyn Vector;
142
143 /// The *declared* compressed inequality bounds `(d_L, d_U)`, in the same
144 /// (internally scaled) space as [`Self::d_l`] / [`Self::d_u`] but without
145 /// the `bound_relax_factor` widening or safe-slack adjustments the live
146 /// vectors carry. The scale-relative feasibility measure keys row
147 /// magnitudes off these: on the live vector a relaxed zero bound reads as
148 /// `~1e-8`, fabricating a magnitude for a row that has none. `None` (the
149 /// default) means "not tracked" — callers should fall back to the live
150 /// bounds.
151 fn declared_d_bounds(&self) -> Option<(Vec<Number>, Vec<Number>)> {
152 None
153 }
154
155 /// The *declared* compressed variable bounds `(x_L, x_U)` — the box the
156 /// user wrote, before `bound_relax_factor` widened it, in the same
157 /// compressed spaces as [`Self::x_l`] / [`Self::x_u`].
158 ///
159 /// Same "declared, not live" contract as [`Self::declared_d_bounds`].
160 /// Anything that reports *where the solution sits relative to the model*
161 /// — active-set identification above all — has to ask this rather than
162 /// the live vector: an iterate exactly on a declared bound is `1e-8`
163 /// inside the relaxed one, so a tolerance test against the live bounds
164 /// calls it inactive. `None` (the default) means "not tracked" — callers
165 /// should fall back to the live bounds.
166 fn declared_x_bounds(&self) -> Option<(Vec<Number>, Vec<Number>)> {
167 None
168 }
169
170 /// How far `x` sits outside the **declared** variable box — the box the
171 /// user wrote, before `bound_relax_factor` widened it.
172 ///
173 /// [`Self::declared_x_bounds`] returns those bounds in the *compressed*
174 /// spaces, which a caller holding an algorithm-space iterate cannot line
175 /// up on its own: the map from a bound slot to a full-x index runs through
176 /// the fixed-variable classification, and the iterate may be a compound
177 /// vector with no flat values to index. This does the lift and the
178 /// comparison where both are known.
179 ///
180 /// `None` means "not tracked" — no widening was recorded, so the declared
181 /// box and the live one are the same and there is nothing to add.
182 fn declared_box_violation(&self, _x: &dyn Vector) -> Option<Number> {
183 None
184 }
185
186 /// The *declared* equality right-hand sides `b` — the pre-fold constants
187 /// subtracted to turn `g_i(x) == b_i` into the algorithm's residual
188 /// `c_i(x) = 0` — reported in the same (internally scaled) space as
189 /// [`Nlp::eval_c`]'s output, so `|c_i| / |b_i|` is a pure ratio.
190 ///
191 /// The fold is exactly what erases the row's magnitude: `|c_i|` *is* the
192 /// violation and carries no independent scale, so a scale-relative
193 /// feasibility measure has nothing to divide by unless the RHS is plumbed
194 /// back. Same "declared, not live" contract as [`Self::declared_d_bounds`]:
195 /// the value is the one the user wrote (times any row scaling the solver
196 /// itself applied), never a relaxed or otherwise adjusted stand-in.
197 ///
198 /// `None` (the default) means "not tracked" — callers must then abstain
199 /// from any relative verdict on the `c` block rather than substitute a
200 /// magnitude of their own.
201 fn declared_c_rhs(&self) -> Option<Vec<Number>> {
202 None
203 }
204
205 /// Bound expansion matrices: `Px_L` extracts the
206 /// `x` components that have a finite lower bound, etc.
207 fn px_l(&self) -> Rc<dyn Matrix>;
208 fn px_u(&self) -> Rc<dyn Matrix>;
209 fn pd_l(&self) -> Rc<dyn Matrix>;
210 fn pd_u(&self) -> Rc<dyn Matrix>;
211
212 /// Replace the `x_L / x_U / d_L / d_U` bounds in place. Invoked by the
213 /// algorithm's accept step when the safe-slack mechanism moved one or
214 /// more bounds (port of `IpoptNLP::AdjustVariableBounds`,
215 /// `IpOrigIpoptNLP.cpp:990-1001`). Default is a no-op for NLP
216 /// implementations that do not own mutable bound storage.
217 fn adjust_variable_bounds(
218 &mut self,
219 _new_x_l: &dyn Vector,
220 _new_x_u: &dyn Vector,
221 _new_d_l: &dyn Vector,
222 _new_d_u: &dyn Vector,
223 ) {
224 }
225
226 /// Fill `x` with the initial primal values (mirrors upstream
227 /// `IpoptNLP::GetStartingPoint`'s `init_x` flag). Default impl
228 /// leaves `x` at its current contents (typically the zero vector
229 /// produced by `make_new`).
230 fn get_starting_x(&mut self, _x: &mut dyn Vector) -> bool {
231 true
232 }
233
234 /// Prepare a complete primal-dual starting-point snapshot for a warm
235 /// start. The default is a no-op for NLP implementations that do not
236 /// route through a TNLP callback.
237 ///
238 /// The warm-start initializer calls this once before its separate
239 /// `get_starting_x` / `get_starting_y` / `get_starting_z` projections.
240 /// Implementations can therefore fetch all requested data in one callback,
241 /// matching Ipopt's single `GetStartingPoint` call.
242 fn prepare_warm_start(&mut self) -> bool {
243 true
244 }
245
246 /// Release any temporary state prepared for the warm-start projections.
247 ///
248 /// Called once the initializer has obtained its `x`, `y`, and `z` blocks.
249 /// The default is a no-op; adapters that cache a TNLP callback payload use
250 /// this to keep that snapshot scoped to one initialization only.
251 fn finish_warm_start(&mut self) {}
252
253 /// Fill `y_c` / `y_d` with initial multiplier guesses (mirrors
254 /// `IpoptNLP::GetStartingPoint`'s `init_lambda` flag). Default
255 /// impl leaves them at their current contents (zeros).
256 fn get_starting_y(&mut self, _y_c: &mut dyn Vector, _y_d: &mut dyn Vector) -> bool {
257 true
258 }
259
260 /// Fill `z_l` / `z_u` / `v_l` / `v_u` with initial bound-multiplier
261 /// guesses (mirrors `init_z`). Default impl leaves them at zeros.
262 #[allow(clippy::too_many_arguments)]
263 fn get_starting_z(
264 &mut self,
265 _z_l: &mut dyn Vector,
266 _z_u: &mut dyn Vector,
267 _v_l: &mut dyn Vector,
268 _v_u: &mut dyn Vector,
269 ) -> bool {
270 true
271 }
272
273 /// Lift a compressed `x_var` (length `n_x_var`) to the full-x
274 /// length (`n_full_x` = user TNLP's `n`), splicing fixed-variable
275 /// values back in. Used at finalize-solution time to hand the user
276 /// a full-length x. Default impl returns x as-is, valid when the
277 /// problem has no fixed variables.
278 fn lift_x_to_full(&self, x: &dyn Vector) -> Vec<Number> {
279 let dx = x
280 .as_any()
281 .downcast_ref::<DenseVector>()
282 .expect("IpoptNlp::lift_x_to_full expects DenseVector");
283 dx.expanded_values().to_vec()
284 }
285
286 /// The full-x to hand `TNLP::finalize_solution`: [`Self::lift_x_to_full`],
287 /// plus whatever the reported point owes the user that the working
288 /// iterate does not — today, the `honor_original_bounds` projection
289 /// back into the declared box (the `bound_relax_factor` widening
290 /// otherwise reports a bound-pinned solution just outside its own
291 /// bounds). Default impl is `lift_x_to_full`; `OrigIpoptNlp`
292 /// overrides.
293 fn finalize_solution_x(&self, x: &dyn Vector) -> Vec<Number> {
294 self.lift_x_to_full(x)
295 }
296
297 /// Pack the algorithm-side `(y_c, y_d)` constraint multipliers into
298 /// the user TNLP's `lambda` array (length `n_full_g`, ordered by
299 /// the original `g` index). Used by `GetIpoptCurrentIterate` and
300 /// `finalize_solution`. Default impl returns an empty vector — the
301 /// canonical `OrigIpoptNlp` implementation overrides it to perform
302 /// the c/d-split inverse and scaling unwind.
303 fn pack_lambda_for_user(&self, _y_c: &dyn Vector, _y_d: &dyn Vector) -> Vec<Number> {
304 Vec::new()
305 }
306
307 /// Pack the algorithm-side `(c, d)` constraint values into the user
308 /// TNLP's `g` array (length `n_full_g`, ordered by the original `g`
309 /// index, in user-unscaled space). Default impl returns an empty
310 /// vector; `OrigIpoptNlp` overrides.
311 fn pack_g_for_user(&self, _c: &dyn Vector, _d: &dyn Vector) -> Vec<Number> {
312 Vec::new()
313 }
314
315 /// Expand a compressed lower-bound-multiplier vector
316 /// (length = number of finite-lower-bound free variables) into the
317 /// user TNLP's full-`n` length `z_L` array. Default impl returns an
318 /// empty vector; `OrigIpoptNlp` overrides.
319 fn pack_z_l_for_user(&self, _z_l: &dyn Vector) -> Vec<Number> {
320 Vec::new()
321 }
322
323 /// Expand a compressed upper-bound-multiplier vector into the user
324 /// TNLP's full-`n` length `z_U` array. Default impl returns an
325 /// empty vector; `OrigIpoptNlp` overrides.
326 fn pack_z_u_for_user(&self, _z_u: &dyn Vector) -> Vec<Number> {
327 Vec::new()
328 }
329
330 /// Number of variables `n` as the user TNLP declared it (= `n_full_x`,
331 /// before fixed-variable elimination). Used by inspector entry
332 /// points that need to size full-`n` buffers. Default impl returns
333 /// 0; `OrigIpoptNlp` overrides.
334 fn n_full_x(&self) -> Index {
335 0
336 }
337
338 /// Number of constraints `m` as the user TNLP declared it (= `n_full_g`).
339 /// Default impl returns 0; `OrigIpoptNlp` overrides.
340 fn n_full_g(&self) -> Index {
341 0
342 }
343
344 /// Lift the algorithm-side `(y_c, y_d)` multipliers back to the
345 /// user TNLP's `lambda` array (length `m_full = n_c + n_d`),
346 /// matching upstream `IpOrigIpoptNLP::FinalizeSolution`. Sibling
347 /// to `pack_lambda_for_user`; added by pounce#11 for the
348 /// `finalize_solution` path. Default returns empty; `OrigIpoptNlp`
349 /// overrides.
350 fn finalize_solution_lambda(&self, _y_c: &dyn Vector, _y_d: &dyn Vector) -> Vec<Number> {
351 Vec::new()
352 }
353
354 /// Lift compressed `z_l` back to full-x. Sibling to
355 /// `pack_z_l_for_user`; added by pounce#11. Default returns empty.
356 fn finalize_solution_z_l(&self, _z_l: &dyn Vector) -> Vec<Number> {
357 Vec::new()
358 }
359
360 /// Lift compressed `z_u` back to full-x. Sibling to
361 /// `pack_z_u_for_user`; added by pounce#11. Default returns empty.
362 fn finalize_solution_z_u(&self, _z_u: &dyn Vector) -> Vec<Number> {
363 Vec::new()
364 }
365
366 /// Map a 0-based **full-x** index (user-TNLP space, length
367 /// `n_full_x()`) to a 0-based **var-x** index (algorithm-side,
368 /// length `n()`). Returns `None` when the variable was eliminated
369 /// because `x_l[i] == x_u[i]` under
370 /// `fixed_variable_treatment = make_parameter`.
371 ///
372 /// Default impl assumes no fixed variables (identity mapping). The
373 /// `OrigIpoptNlp` implementation consults
374 /// `BoundClassification::full_to_var`.
375 fn full_x_to_var_x(&self, full_idx: Index) -> Option<Index> {
376 Some(full_idx)
377 }
378
379 /// Map a 0-based **full-g** index (user-TNLP space, length
380 /// `n_full_g()`) to a 0-based position in the c-block (algorithm-side
381 /// equality multiplier vector `y_c`, length `m_eq()`). Returns
382 /// `None` when the constraint is an inequality (lives in `d`, not
383 /// `c`).
384 ///
385 /// Default impl assumes the c-block matches the user's g order
386 /// (no c/d split); `OrigIpoptNlp` overrides via
387 /// `BoundClassification::c_map`.
388 fn full_g_to_c_block(&self, full_idx: Index) -> Option<Index> {
389 Some(full_idx)
390 }
391
392 /// Inverse of [`Self::full_x_to_var_x`]: map a 0-based var-x index
393 /// (length `n()`) to the corresponding full-x index (length
394 /// `n_full_x()`). Used when scattering a compressed step or
395 /// iterate back into the user's full-x array.
396 ///
397 /// Default impl assumes no fixed variables (identity); `OrigIpoptNlp`
398 /// returns `classification.x_not_fixed_map[var_idx]`.
399 fn var_x_to_full_x(&self, var_idx: Index) -> Index {
400 var_idx
401 }
402
403 /// Effective objective scaling factor (`df_` upstream): the value
404 /// `f` is multiplied by inside [`Self::eval_f`]. Used to recover the
405 /// unscaled objective for display. Default `1.0` (no scaling);
406 /// `OrigIpoptNlp` overrides.
407 fn obj_scaling_factor(&self) -> Number {
408 1.0
409 }
410
411 /// The **solver-computed** part of the objective scale, before the user's
412 /// constant `obj_scaling_factor` is multiplied in.
413 ///
414 /// [`Self::obj_scaling_factor`] returns the product `df * user_factor`,
415 /// which is the right thing for unscaling a residual but the wrong thing
416 /// for asking *why* the scale is small. `df` is what gradient-based scaling
417 /// computed and clamped at `nlp_scaling_min_value`; the user factor is a
418 /// deliberate choice. Only the former can mask a certificate (gh #200), so
419 /// the termination logic keys on this rather than on the product.
420 /// Default `1.0`; `OrigIpoptNlp` overrides.
421 fn computed_obj_scaling_factor(&self) -> Number {
422 1.0
423 }
424
425 /// Per-row scaling vector for the equality block (`dc_` upstream):
426 /// the factor each `c` row is multiplied by inside [`Self::eval_c`]
427 /// / [`Self::eval_jac_c`]. `None` ⇔ no row scaling (all 1.0);
428 /// length `m_eq()` when present. Together with
429 /// [`Self::obj_scaling_factor`] and [`Self::d_scale_vec`] this is
430 /// what lets `pounce-sensitivity` undo the NLP scaling baked into
431 /// the converged KKT factor (pounce#128). Default `None`;
432 /// `OrigIpoptNlp` overrides.
433 fn c_scale_vec(&self) -> Option<Vec<Number>> {
434 None
435 }
436
437 /// Per-row scaling vector for the inequality block (`dd_`
438 /// upstream), same convention as [`Self::c_scale_vec`]. Length
439 /// `m_ineq()` when present. Default `None`; `OrigIpoptNlp`
440 /// overrides.
441 fn d_scale_vec(&self) -> Option<Vec<Number>> {
442 None
443 }
444
445 /// The per-variable factors `d` a scaling wrapper below this NLP
446 /// applied as a change of variables `x̃ = d ⊙ x` (gh#486). `None`
447 /// ⇔ no variable scaling; length [`Self::n_full_x`] when present,
448 /// i.e. the **full-x** space of the TNLP that was submitted, before
449 /// fixed variables were dropped.
450 ///
451 /// This is the x-axis counterpart of [`Self::obj_scaling_factor`] /
452 /// [`Self::c_scale_vec`] / [`Self::d_scale_vec`], and it exists for
453 /// the same reason: a consumer reading the converged KKT system
454 /// rather than the `finalize_solution` payload is looking at `x̃`,
455 /// not `x`, and needs the factors to say so. Unlike the other
456 /// three, the substitution happens *below* the NLP — in
457 /// `ScalingTnlp` — so this only forwards what the TNLP reports.
458 /// Default `None`; `OrigIpoptNlp` overrides.
459 fn variable_scaling(&self) -> Option<Vec<Number>> {
460 None
461 }
462
463 /// Human-readable variable / constraint names projected into the
464 /// algorithm's split space (free variables, equalities, inequalities),
465 /// or `None` when the model carries no names. The debugger uses this to
466 /// label residuals by model name (`mass_balance`) rather than index
467 /// (`c[3]`) — see [`SplitNames`] and Lee et al. (2024,
468 /// <https://doi.org/10.69997/sct.147875>).
469 ///
470 /// Default returns `None`; `OrigIpoptNlp` overrides by pulling
471 /// `idx_names` metadata from the underlying TNLP and composing it with
472 /// the bound / c-d-split permutations.
473 fn split_space_names(&self) -> Option<SplitNames> {
474 None
475 }
476}