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, 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`.
85pub trait IpoptNlp: Nlp {
86 fn x_l(&self) -> &dyn Vector;
87 fn x_u(&self) -> &dyn Vector;
88 fn d_l(&self) -> &dyn Vector;
89 fn d_u(&self) -> &dyn Vector;
90
91 /// Bound expansion matrices: `Px_L` extracts the
92 /// `x` components that have a finite lower bound, etc.
93 fn px_l(&self) -> Rc<dyn Matrix>;
94 fn px_u(&self) -> Rc<dyn Matrix>;
95 fn pd_l(&self) -> Rc<dyn Matrix>;
96 fn pd_u(&self) -> Rc<dyn Matrix>;
97
98 /// Replace the `x_L / x_U / d_L / d_U` bounds in place. Invoked by the
99 /// algorithm's accept step when the safe-slack mechanism moved one or
100 /// more bounds (port of `IpoptNLP::AdjustVariableBounds`,
101 /// `IpOrigIpoptNLP.cpp:990-1001`). Default is a no-op for NLP
102 /// implementations that do not own mutable bound storage.
103 fn adjust_variable_bounds(
104 &mut self,
105 _new_x_l: &dyn Vector,
106 _new_x_u: &dyn Vector,
107 _new_d_l: &dyn Vector,
108 _new_d_u: &dyn Vector,
109 ) {
110 }
111
112 /// Fill `x` with the initial primal values (mirrors upstream
113 /// `IpoptNLP::GetStartingPoint`'s `init_x` flag). Default impl
114 /// leaves `x` at its current contents (typically the zero vector
115 /// produced by `make_new`).
116 fn get_starting_x(&mut self, _x: &mut dyn Vector) -> bool {
117 true
118 }
119
120 /// Fill `y_c` / `y_d` with initial multiplier guesses (mirrors
121 /// `IpoptNLP::GetStartingPoint`'s `init_lambda` flag). Default
122 /// impl leaves them at their current contents (zeros).
123 fn get_starting_y(&mut self, _y_c: &mut dyn Vector, _y_d: &mut dyn Vector) -> bool {
124 true
125 }
126
127 /// Fill `z_l` / `z_u` / `v_l` / `v_u` with initial bound-multiplier
128 /// guesses (mirrors `init_z`). Default impl leaves them at zeros.
129 #[allow(clippy::too_many_arguments)]
130 fn get_starting_z(
131 &mut self,
132 _z_l: &mut dyn Vector,
133 _z_u: &mut dyn Vector,
134 _v_l: &mut dyn Vector,
135 _v_u: &mut dyn Vector,
136 ) -> bool {
137 true
138 }
139
140 /// Lift a compressed `x_var` (length `n_x_var`) to the full-x
141 /// length (`n_full_x` = user TNLP's `n`), splicing fixed-variable
142 /// values back in. Used at finalize-solution time to hand the user
143 /// a full-length x. Default impl returns x as-is, valid when the
144 /// problem has no fixed variables.
145 fn lift_x_to_full(&self, x: &dyn Vector) -> Vec<Number> {
146 let dx = x
147 .as_any()
148 .downcast_ref::<DenseVector>()
149 .expect("IpoptNlp::lift_x_to_full expects DenseVector");
150 dx.expanded_values().to_vec()
151 }
152
153 /// Pack the algorithm-side `(y_c, y_d)` constraint multipliers into
154 /// the user TNLP's `lambda` array (length `n_full_g`, ordered by
155 /// the original `g` index). Used by `GetIpoptCurrentIterate` and
156 /// `finalize_solution`. Default impl returns an empty vector — the
157 /// canonical `OrigIpoptNlp` implementation overrides it to perform
158 /// the c/d-split inverse and scaling unwind.
159 fn pack_lambda_for_user(&self, _y_c: &dyn Vector, _y_d: &dyn Vector) -> Vec<Number> {
160 Vec::new()
161 }
162
163 /// Pack the algorithm-side `(c, d)` constraint values into the user
164 /// TNLP's `g` array (length `n_full_g`, ordered by the original `g`
165 /// index, in user-unscaled space). Default impl returns an empty
166 /// vector; `OrigIpoptNlp` overrides.
167 fn pack_g_for_user(&self, _c: &dyn Vector, _d: &dyn Vector) -> Vec<Number> {
168 Vec::new()
169 }
170
171 /// Expand a compressed lower-bound-multiplier vector
172 /// (length = number of finite-lower-bound free variables) into the
173 /// user TNLP's full-`n` length `z_L` array. Default impl returns an
174 /// empty vector; `OrigIpoptNlp` overrides.
175 fn pack_z_l_for_user(&self, _z_l: &dyn Vector) -> Vec<Number> {
176 Vec::new()
177 }
178
179 /// Expand a compressed upper-bound-multiplier vector into the user
180 /// TNLP's full-`n` length `z_U` array. Default impl returns an
181 /// empty vector; `OrigIpoptNlp` overrides.
182 fn pack_z_u_for_user(&self, _z_u: &dyn Vector) -> Vec<Number> {
183 Vec::new()
184 }
185
186 /// Number of variables `n` as the user TNLP declared it (= `n_full_x`,
187 /// before fixed-variable elimination). Used by inspector entry
188 /// points that need to size full-`n` buffers. Default impl returns
189 /// 0; `OrigIpoptNlp` overrides.
190 fn n_full_x(&self) -> Index {
191 0
192 }
193
194 /// Number of constraints `m` as the user TNLP declared it (= `n_full_g`).
195 /// Default impl returns 0; `OrigIpoptNlp` overrides.
196 fn n_full_g(&self) -> Index {
197 0
198 }
199
200 /// Lift the algorithm-side `(y_c, y_d)` multipliers back to the
201 /// user TNLP's `lambda` array (length `m_full = n_c + n_d`),
202 /// matching upstream `IpOrigIpoptNLP::FinalizeSolution`. Sibling
203 /// to `pack_lambda_for_user`; added by pounce#11 for the
204 /// `finalize_solution` path. Default returns empty; `OrigIpoptNlp`
205 /// overrides.
206 fn finalize_solution_lambda(&self, _y_c: &dyn Vector, _y_d: &dyn Vector) -> Vec<Number> {
207 Vec::new()
208 }
209
210 /// Lift compressed `z_l` back to full-x. Sibling to
211 /// `pack_z_l_for_user`; added by pounce#11. Default returns empty.
212 fn finalize_solution_z_l(&self, _z_l: &dyn Vector) -> Vec<Number> {
213 Vec::new()
214 }
215
216 /// Lift compressed `z_u` back to full-x. Sibling to
217 /// `pack_z_u_for_user`; added by pounce#11. Default returns empty.
218 fn finalize_solution_z_u(&self, _z_u: &dyn Vector) -> Vec<Number> {
219 Vec::new()
220 }
221
222 /// Map a 0-based **full-x** index (user-TNLP space, length
223 /// `n_full_x()`) to a 0-based **var-x** index (algorithm-side,
224 /// length `n()`). Returns `None` when the variable was eliminated
225 /// because `x_l[i] == x_u[i]` under
226 /// `fixed_variable_treatment = make_parameter`.
227 ///
228 /// Default impl assumes no fixed variables (identity mapping). The
229 /// `OrigIpoptNlp` implementation consults
230 /// `BoundClassification::full_to_var`.
231 fn full_x_to_var_x(&self, full_idx: Index) -> Option<Index> {
232 Some(full_idx)
233 }
234
235 /// Map a 0-based **full-g** index (user-TNLP space, length
236 /// `n_full_g()`) to a 0-based position in the c-block (algorithm-side
237 /// equality multiplier vector `y_c`, length `m_eq()`). Returns
238 /// `None` when the constraint is an inequality (lives in `d`, not
239 /// `c`).
240 ///
241 /// Default impl assumes the c-block matches the user's g order
242 /// (no c/d split); `OrigIpoptNlp` overrides via
243 /// `BoundClassification::c_map`.
244 fn full_g_to_c_block(&self, full_idx: Index) -> Option<Index> {
245 Some(full_idx)
246 }
247
248 /// Inverse of [`Self::full_x_to_var_x`]: map a 0-based var-x index
249 /// (length `n()`) to the corresponding full-x index (length
250 /// `n_full_x()`). Used when scattering a compressed step or
251 /// iterate back into the user's full-x array.
252 ///
253 /// Default impl assumes no fixed variables (identity); `OrigIpoptNlp`
254 /// returns `classification.x_not_fixed_map[var_idx]`.
255 fn var_x_to_full_x(&self, var_idx: Index) -> Index {
256 var_idx
257 }
258
259 /// Effective objective scaling factor (`df_` upstream): the value
260 /// `f` is multiplied by inside [`Self::eval_f`]. Used to recover the
261 /// unscaled objective for display. Default `1.0` (no scaling);
262 /// `OrigIpoptNlp` overrides.
263 fn obj_scaling_factor(&self) -> Number {
264 1.0
265 }
266
267 /// Human-readable variable / constraint names projected into the
268 /// algorithm's split space (free variables, equalities, inequalities),
269 /// or `None` when the model carries no names. The debugger uses this to
270 /// label residuals by model name (`mass_balance`) rather than index
271 /// (`c[3]`) — see [`SplitNames`] and Lee et al. (2024,
272 /// <https://doi.org/10.69997/sct.147875>).
273 ///
274 /// Default returns `None`; `OrigIpoptNlp` overrides by pulling
275 /// `idx_names` metadata from the underlying TNLP and composing it with
276 /// the bound / c-d-split permutations.
277 fn split_space_names(&self) -> Option<SplitNames> {
278 None
279 }
280}