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    /// Constraint linearity tags. Used by adaptive-mu's
228    /// `nlp_scaling_method=equilibration-based`.
229    fn get_constraints_linearity(&mut self, _types: &mut [Linearity]) -> bool {
230        false
231    }
232
233    /// Number of variables that appear nonlinearly. Returning -1
234    /// means "treat all as nonlinear" (the Ipopt default).
235    fn get_number_of_nonlinear_variables(&mut self) -> Index {
236        -1
237    }
238
239    /// List of nonlinear variable indices, in the index style
240    /// returned from [`Self::get_nlp_info`].
241    fn get_list_of_nonlinear_variables(&mut self, _pos_nonlin_vars: &mut [Index]) -> bool {
242        false
243    }
244
245    /// Per-iteration intermediate callback. Returning false requests
246    /// early termination with `User_Requested_Stop`.
247    fn intermediate_callback(
248        &mut self,
249        _stats: IterStats,
250        _ip_data: &IpoptData,
251        _ip_cq: &IpoptCq,
252    ) -> bool {
253        true
254    }
255
256    /// Final metadata pass — called just before
257    /// [`Self::finalize_solution`]. Default does nothing.
258    fn finalize_metadata(&mut self, _var: &MetaData, _con: &MetaData) {}
259}
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264
265    /// Tiny `min x[0]^2 + x[1]^2  s.t. x[0] + x[1] = 1` problem.
266    /// Used as a smoke test that the trait is object-safe and the
267    /// defaults compile.
268    struct Mini;
269    impl TNLP for Mini {
270        fn get_nlp_info(&mut self) -> Option<NlpInfo> {
271            Some(NlpInfo {
272                n: 2,
273                m: 1,
274                nnz_jac_g: 2,
275                nnz_h_lag: 2,
276                index_style: IndexStyle::C,
277            })
278        }
279        fn get_bounds_info(&mut self, b: BoundsInfo<'_>) -> bool {
280            b.x_l.iter_mut().for_each(|v| *v = -1e19);
281            b.x_u.iter_mut().for_each(|v| *v = 1e19);
282            b.g_l[0] = 1.0;
283            b.g_u[0] = 1.0;
284            true
285        }
286        fn get_starting_point(&mut self, sp: StartingPoint<'_>) -> bool {
287            assert!(sp.init_x);
288            sp.x[0] = 0.5;
289            sp.x[1] = 0.5;
290            true
291        }
292        fn eval_f(&mut self, x: &[Number], _new_x: bool) -> Option<Number> {
293            Some(x[0] * x[0] + x[1] * x[1])
294        }
295        fn eval_grad_f(&mut self, x: &[Number], _new_x: bool, grad_f: &mut [Number]) -> bool {
296            grad_f[0] = 2.0 * x[0];
297            grad_f[1] = 2.0 * x[1];
298            true
299        }
300        fn eval_g(&mut self, x: &[Number], _new_x: bool, g: &mut [Number]) -> bool {
301            g[0] = x[0] + x[1];
302            true
303        }
304        fn eval_jac_g(
305            &mut self,
306            _x: Option<&[Number]>,
307            _new_x: bool,
308            mode: SparsityRequest<'_>,
309        ) -> bool {
310            match mode {
311                SparsityRequest::Structure { irow, jcol } => {
312                    irow.copy_from_slice(&[0, 0]);
313                    jcol.copy_from_slice(&[0, 1]);
314                }
315                SparsityRequest::Values { values } => {
316                    values.copy_from_slice(&[1.0, 1.0]);
317                }
318            }
319            true
320        }
321        fn finalize_solution(&mut self, _sol: Solution<'_>, _d: &IpoptData, _q: &IpoptCq) {}
322    }
323
324    #[test]
325    fn tnlp_is_object_safe() {
326        // The trait must be usable behind `dyn`; this also exercises
327        // every default-impl method to make sure they compile.
328        let mut t: Box<dyn TNLP> = Box::new(Mini);
329        let info = t.get_nlp_info().expect("get_nlp_info");
330        assert_eq!(info.n, 2);
331        assert_eq!(info.m, 1);
332        assert_eq!(info.index_style, IndexStyle::C);
333
334        let mut x_l = [0.0; 2];
335        let mut x_u = [0.0; 2];
336        let mut g_l = [0.0; 1];
337        let mut g_u = [0.0; 1];
338        assert!(t.get_bounds_info(BoundsInfo {
339            x_l: &mut x_l,
340            x_u: &mut x_u,
341            g_l: &mut g_l,
342            g_u: &mut g_u
343        }));
344        assert_eq!(g_l[0], 1.0);
345
346        let mut grad = [0.0; 2];
347        assert!(t.eval_grad_f(&[3.0, 4.0], true, &mut grad));
348        assert_eq!(grad, [6.0, 8.0]);
349
350        // exact-Hessian default returns false
351        let mut tmp_v = [0.0; 0];
352        assert!(!t.eval_h(
353            None,
354            false,
355            1.0,
356            None,
357            false,
358            SparsityRequest::Values { values: &mut tmp_v }
359        ));
360
361        // Quasi-Newton info default
362        assert_eq!(t.get_number_of_nonlinear_variables(), -1);
363    }
364
365    #[test]
366    fn sparsity_request_round_trip() {
367        let mut t = Mini;
368        let mut irow = [0; 2];
369        let mut jcol = [0; 2];
370        assert!(t.eval_jac_g(
371            None,
372            false,
373            SparsityRequest::Structure {
374                irow: &mut irow,
375                jcol: &mut jcol
376            }
377        ));
378        assert_eq!(irow, [0, 0]);
379        assert_eq!(jcol, [0, 1]);
380
381        let mut vals = [0.0; 2];
382        assert!(t.eval_jac_g(
383            Some(&[1.0, 2.0]),
384            true,
385            SparsityRequest::Values { values: &mut vals }
386        ));
387        assert_eq!(vals, [1.0, 1.0]);
388    }
389}
pounce_nlp/tnlp.rs

pounce_nlp/
tnlp.rs
