pounce_nlp/tnlp.rs
1//! User-facing `TNLP` trait — port of `Interfaces/IpTNLP.{hpp,cpp}`.
2//!
3//! The Rust shape replaces upstream's two-call `(iRow,jCol,values)`
4//! convention with [`SparsityRequest`], a request enum carrying the
5//! caller-supplied buffers. This is more typesafe (no NULL pointers,
6//! buffer length is type-checked) and matches the eight-method API
7//! upstream documents.
8//!
9//! The `IpoptData` / `IpoptCalculatedQuantities` / `IteratesVector`
10//! parameters of `intermediate_callback` and `finalize_solution` are
11//! introduced as opaque [`IpoptData`] / [`IpoptCq`] types; their full
12//! field set lands in Phase 5.
13//!
14//! Trait objects: `dyn TNLP` is supported. Concrete callers store the
15//! TNLP behind an `Rc<RefCell<dyn TNLP>>` (so eval methods can mutate
16//! internal caches) — `pounce_algorithm::IpoptApplication` handles
17//! wrapping.
18
19use crate::alg_types::SolverReturn;
20use crate::return_codes::AlgorithmMode;
21use pounce_common::types::{Index, Number};
22use std::collections::BTreeMap;
23
24/// Linearity tags. Mirrors `TNLP::LinearityType` upstream.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum Linearity {
27 Linear,
28 NonLinear,
29}
30
31/// Index style for triplet I/O. Mirrors `TNLP::IndexStyleEnum`.
32/// `Fortran` (1-based) is what MUMPS / HSL want directly; `C`
33/// (0-based) is more natural for Rust user code.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub enum IndexStyle {
36 C = 0,
37 Fortran = 1,
38}
39
40/// Problem dimensions returned by [`TNLP::get_nlp_info`].
41#[derive(Debug, Clone, Copy)]
42pub struct NlpInfo {
43 pub n: Index,
44 pub m: Index,
45 pub nnz_jac_g: Index,
46 pub nnz_h_lag: Index,
47 pub index_style: IndexStyle,
48}
49
50/// Variable / constraint metadata buckets, mirroring upstream's
51/// `(StringMetaDataMapType, IntegerMetaDataMapType, NumericMetaDataMapType)`.
52#[derive(Debug, Default, Clone)]
53pub struct MetaData {
54 pub strings: BTreeMap<String, Vec<String>>,
55 pub integers: BTreeMap<String, Vec<Index>>,
56 pub numerics: BTreeMap<String, Vec<Number>>,
57}
58
59/// Conventional [`MetaData::strings`] key for per-index human-readable
60/// names (one entry per variable, or per constraint, in original
61/// problem order). Mirrors upstream Ipopt's `"idx_names"` metadata
62/// key. Carrying names this far lets the debugger report a near-singular
63/// Jacobian row as the `mass_balance` equation instead of "row 3" —
64/// the model-vs-index gap Lee et al. (2024,
65/// <https://doi.org/10.69997/sct.147875>) flag as a key roadblock for
66/// debugging equation-oriented models.
67pub const IDX_NAMES: &str = "idx_names";
68
69/// Bound-data target buffers passed into [`TNLP::get_bounds_info`].
70#[derive(Debug)]
71pub struct BoundsInfo<'a> {
72 pub x_l: &'a mut [Number],
73 pub x_u: &'a mut [Number],
74 pub g_l: &'a mut [Number],
75 pub g_u: &'a mut [Number],
76}
77
78/// Starting-point target buffers passed into [`TNLP::get_starting_point`].
79/// Each `init_*` flag matches upstream — mostly false unless warm-starting.
80#[derive(Debug)]
81pub struct StartingPoint<'a> {
82 pub init_x: bool,
83 pub x: &'a mut [Number],
84 pub init_z: bool,
85 pub z_l: &'a mut [Number],
86 pub z_u: &'a mut [Number],
87 pub init_lambda: bool,
88 pub lambda: &'a mut [Number],
89}
90
91/// Scaling-factor target buffers passed into [`TNLP::get_scaling_parameters`].
92#[derive(Debug)]
93pub struct ScalingRequest<'a> {
94 pub obj_scaling: &'a mut Number,
95 pub use_x_scaling: &'a mut bool,
96 pub x_scaling: &'a mut [Number],
97 pub use_g_scaling: &'a mut bool,
98 pub g_scaling: &'a mut [Number],
99}
100
101/// Mode discriminator for the structure / values calls of
102/// [`TNLP::eval_jac_g`] and [`TNLP::eval_h`]. Replaces upstream's
103/// `iRow != NULL` heuristic.
104#[derive(Debug)]
105pub enum SparsityRequest<'a> {
106 /// First call: fill `irow` and `jcol` with the structure (the
107 /// numbering style is whatever was returned in
108 /// [`NlpInfo::index_style`]). The values array is absent.
109 Structure {
110 irow: &'a mut [Index],
111 jcol: &'a mut [Index],
112 },
113 /// Subsequent calls: fill `values` with the entries of the matrix
114 /// at the current `x` (and, for the Hessian, `lambda`,
115 /// `obj_factor`).
116 Values { values: &'a mut [Number] },
117}
118
119/// Solution as passed to [`TNLP::finalize_solution`].
120#[derive(Debug)]
121pub struct Solution<'a> {
122 pub status: SolverReturn,
123 pub x: &'a [Number],
124 pub z_l: &'a [Number],
125 pub z_u: &'a [Number],
126 pub g: &'a [Number],
127 pub lambda: &'a [Number],
128 pub obj_value: Number,
129}
130
131/// Per-iteration callback payload for [`TNLP::intermediate_callback`].
132#[derive(Debug, Clone, Copy)]
133pub struct IterStats {
134 pub mode: AlgorithmMode,
135 pub iter: Index,
136 pub obj_value: Number,
137 pub inf_pr: Number,
138 pub inf_du: Number,
139 pub mu: Number,
140 pub d_norm: Number,
141 pub regularization_size: Number,
142 pub alpha_du: Number,
143 pub alpha_pr: Number,
144 pub ls_trials: Index,
145}
146
147/// Forward-declared placeholder for `IpoptData`. Phase 5 fills this
148/// in with the full mutable iterate-state structure; for Phase 3 it
149/// is opaque.
150#[derive(Debug, Default)]
151pub struct IpoptData {
152 _private: (),
153}
154
155/// Forward-declared placeholder for `IpoptCalculatedQuantities`.
156/// Phase 5 fills this in.
157#[derive(Debug, Default)]
158pub struct IpoptCq {
159 _private: (),
160}
161
162/// User-facing NLP interface — port of `class TNLP`. Object-safe.
163///
164/// Defaults provided for every method that upstream documents as
165/// "default returns false / does nothing", so simple problems only
166/// override the eight pure-virtual methods.
167pub trait TNLP {
168 /// **Required.** Problem dimensions and triplet index style.
169 fn get_nlp_info(&mut self) -> Option<NlpInfo>;
170
171 /// **Required.** Variable / constraint bounds.
172 fn get_bounds_info(&mut self, b: BoundsInfo<'_>) -> bool;
173
174 /// **Required.** Initial primal (and optionally dual) point.
175 fn get_starting_point(&mut self, sp: StartingPoint<'_>) -> bool;
176
177 /// **Required.** Objective value at `x`.
178 fn eval_f(&mut self, x: &[Number], new_x: bool) -> Option<Number>;
179
180 /// **Required.** Objective gradient at `x` into `grad_f`.
181 fn eval_grad_f(&mut self, x: &[Number], new_x: bool, grad_f: &mut [Number]) -> bool;
182
183 /// **Required.** Constraint values `g(x)`.
184 fn eval_g(&mut self, x: &[Number], new_x: bool, g: &mut [Number]) -> bool;
185
186 /// **Required.** Jacobian of `g`. Sparsity vs. values selected by
187 /// `mode`. `x` and `new_x` are unused on the structure call.
188 fn eval_jac_g(&mut self, x: Option<&[Number]>, new_x: bool, mode: SparsityRequest<'_>) -> bool;
189
190 /// **Required for exact Hessian, optional for L-BFGS.** Hessian
191 /// of the Lagrangian. Default returns false (signals to %Ipopt
192 /// that quasi-Newton must be used).
193 fn eval_h(
194 &mut self,
195 _x: Option<&[Number]>,
196 _new_x: bool,
197 _obj_factor: Number,
198 _lambda: Option<&[Number]>,
199 _new_lambda: bool,
200 _mode: SparsityRequest<'_>,
201 ) -> bool {
202 false
203 }
204
205 /// **Required.** Receives the final iterate after solve.
206 fn finalize_solution(&mut self, sol: Solution<'_>, ip_data: &IpoptData, ip_cq: &IpoptCq);
207
208 // ---- Optional methods (defaults match upstream's "do nothing") ----
209
210 /// Provide variable/constraint metadata (e.g. `idx_names`).
211 /// Default: no metadata.
212 fn get_var_con_metadata(&mut self, _var: &mut MetaData, _con: &mut MetaData) -> bool {
213 false
214 }
215
216 /// User-supplied scaling, used only when
217 /// `nlp_scaling_method=user-scaling`. Default: declines.
218 fn get_scaling_parameters(&mut self, _req: ScalingRequest<'_>) -> bool {
219 false
220 }
221
222 /// Variable linearity tags (used by Bonmin, not by Ipopt).
223 fn get_variables_linearity(&mut self, _types: &mut [Linearity]) -> bool {
224 false
225 }
226
227 /// Per-variable linearity with respect to the **objective only** (a
228 /// pounce extension; upstream has no objective-scoped query).
229 /// `NonLinear` iff the objective's nonlinear part depends on the
230 /// variable; a variable that enters the objective only linearly (or
231 /// not at all) is `Linear` even when it is nonlinear in a
232 /// constraint. Consumed by presolve's Phase-0 objective-coupling
233 /// guard, which must not mistake constraint-only nonlinearity for
234 /// objective coupling. Default: declines (slice untouched).
235 fn get_objective_variables_linearity(&mut self, _types: &mut [Linearity]) -> bool {
236 false
237 }
238
239 /// Constraint linearity tags. Used by adaptive-mu's
240 /// `nlp_scaling_method=equilibration-based`.
241 fn get_constraints_linearity(&mut self, _types: &mut [Linearity]) -> bool {
242 false
243 }
244
245 /// Number of variables that appear nonlinearly. Returning -1
246 /// means "treat all as nonlinear" (the Ipopt default).
247 fn get_number_of_nonlinear_variables(&mut self) -> Index {
248 -1
249 }
250
251 /// List of nonlinear variable indices, in the index style
252 /// returned from [`Self::get_nlp_info`].
253 fn get_list_of_nonlinear_variables(&mut self, _pos_nonlin_vars: &mut [Index]) -> bool {
254 false
255 }
256
257 /// Per-iteration intermediate callback. Returning false requests
258 /// early termination with `User_Requested_Stop`.
259 fn intermediate_callback(
260 &mut self,
261 _stats: IterStats,
262 _ip_data: &IpoptData,
263 _ip_cq: &IpoptCq,
264 ) -> bool {
265 true
266 }
267
268 /// Final metadata pass — called just before
269 /// [`Self::finalize_solution`]. Default does nothing.
270 fn finalize_metadata(&mut self, _var: &MetaData, _con: &MetaData) {}
271}
272
273#[cfg(test)]
274mod tests {
275 use super::*;
276
277 /// Tiny `min x[0]^2 + x[1]^2 s.t. x[0] + x[1] = 1` problem.
278 /// Used as a smoke test that the trait is object-safe and the
279 /// defaults compile.
280 struct Mini;
281 impl TNLP for Mini {
282 fn get_nlp_info(&mut self) -> Option<NlpInfo> {
283 Some(NlpInfo {
284 n: 2,
285 m: 1,
286 nnz_jac_g: 2,
287 nnz_h_lag: 2,
288 index_style: IndexStyle::C,
289 })
290 }
291 fn get_bounds_info(&mut self, b: BoundsInfo<'_>) -> bool {
292 b.x_l.iter_mut().for_each(|v| *v = -1e19);
293 b.x_u.iter_mut().for_each(|v| *v = 1e19);
294 b.g_l[0] = 1.0;
295 b.g_u[0] = 1.0;
296 true
297 }
298 fn get_starting_point(&mut self, sp: StartingPoint<'_>) -> bool {
299 assert!(sp.init_x);
300 sp.x[0] = 0.5;
301 sp.x[1] = 0.5;
302 true
303 }
304 fn eval_f(&mut self, x: &[Number], _new_x: bool) -> Option<Number> {
305 Some(x[0] * x[0] + x[1] * x[1])
306 }
307 fn eval_grad_f(&mut self, x: &[Number], _new_x: bool, grad_f: &mut [Number]) -> bool {
308 grad_f[0] = 2.0 * x[0];
309 grad_f[1] = 2.0 * x[1];
310 true
311 }
312 fn eval_g(&mut self, x: &[Number], _new_x: bool, g: &mut [Number]) -> bool {
313 g[0] = x[0] + x[1];
314 true
315 }
316 fn eval_jac_g(
317 &mut self,
318 _x: Option<&[Number]>,
319 _new_x: bool,
320 mode: SparsityRequest<'_>,
321 ) -> bool {
322 match mode {
323 SparsityRequest::Structure { irow, jcol } => {
324 irow.copy_from_slice(&[0, 0]);
325 jcol.copy_from_slice(&[0, 1]);
326 }
327 SparsityRequest::Values { values } => {
328 values.copy_from_slice(&[1.0, 1.0]);
329 }
330 }
331 true
332 }
333 fn finalize_solution(&mut self, _sol: Solution<'_>, _d: &IpoptData, _q: &IpoptCq) {}
334 }
335
336 #[test]
337 fn tnlp_is_object_safe() {
338 // The trait must be usable behind `dyn`; this also exercises
339 // every default-impl method to make sure they compile.
340 let mut t: Box<dyn TNLP> = Box::new(Mini);
341 let info = t.get_nlp_info().expect("get_nlp_info");
342 assert_eq!(info.n, 2);
343 assert_eq!(info.m, 1);
344 assert_eq!(info.index_style, IndexStyle::C);
345
346 let mut x_l = [0.0; 2];
347 let mut x_u = [0.0; 2];
348 let mut g_l = [0.0; 1];
349 let mut g_u = [0.0; 1];
350 assert!(t.get_bounds_info(BoundsInfo {
351 x_l: &mut x_l,
352 x_u: &mut x_u,
353 g_l: &mut g_l,
354 g_u: &mut g_u
355 }));
356 assert_eq!(g_l[0], 1.0);
357
358 let mut grad = [0.0; 2];
359 assert!(t.eval_grad_f(&[3.0, 4.0], true, &mut grad));
360 assert_eq!(grad, [6.0, 8.0]);
361
362 // exact-Hessian default returns false
363 let mut tmp_v = [0.0; 0];
364 assert!(!t.eval_h(
365 None,
366 false,
367 1.0,
368 None,
369 false,
370 SparsityRequest::Values { values: &mut tmp_v }
371 ));
372
373 // Quasi-Newton info default
374 assert_eq!(t.get_number_of_nonlinear_variables(), -1);
375 }
376
377 #[test]
378 fn sparsity_request_round_trip() {
379 let mut t = Mini;
380 let mut irow = [0; 2];
381 let mut jcol = [0; 2];
382 assert!(t.eval_jac_g(
383 None,
384 false,
385 SparsityRequest::Structure {
386 irow: &mut irow,
387 jcol: &mut jcol
388 }
389 ));
390 assert_eq!(irow, [0, 0]);
391 assert_eq!(jcol, [0, 1]);
392
393 let mut vals = [0.0; 2];
394 assert!(t.eval_jac_g(
395 Some(&[1.0, 2.0]),
396 true,
397 SparsityRequest::Values { values: &mut vals }
398 ));
399 assert_eq!(vals, [1.0, 1.0]);
400 }
401}