pounce_sens_core/
lib.rs

1//! Engine-agnostic core of POUNCE's sensitivity layer.
2//!
3//! This crate holds the parts of the sIPOPT port that do not know which
4//! solver produced the KKT system they are reading. Everything here is
5//! written against one trait — [`backsolver::SensBacksolver`], whose whole
6//! required surface is `dim()` and `solve(rhs, lhs)` — so any engine that can
7//! back-solve against its converged factor gets the parametric machinery for
8//! free:
9//!
10//! * [`boundcheck`] — fix-relax refinement, path following through
11//!   active-set breakpoints, and the directional derivative at a kink.
12//! * [`sens_app`] — the sIPOPT `SensApplication` driver, the reduced-Hessian
13//!   entry point, and the option registrations.
14//! * [`p_calculator`], [`schur_data`], [`schur_driver`], [`step_calc`],
15//!   [`reduced_hessian`] — the `P = K⁻¹A` / Schur-complement stack.
16//!
17//! Two consumers exist in tree. `pounce-sensitivity` implements the trait over
18//! the NLP filter-IPM's KKT factor (`PdSensBacksolver`); `pounce-convex`
19//! implements it over the convex active-set KKT. Neither depends on the other,
20//! and this crate depends on neither — it needs only `pounce-common` and
21//! `pounce-linalg`.
22//!
23//! # What deliberately did not move here
24//!
25//! Two parts of the NLP arm's sensitivity layer are genuinely engine-coupled
26//! and stay in `pounce-sensitivity`, so this boundary is a decision rather
27//! than an oversight:
28//!
29//! * **The corrector.** Its entry points take the concrete `PdSensBacksolver`
30//!   and reach for `activity_handles()`, `offsets_public()`, `block_dims()`,
31//!   `pack_natural()` and `corrector_sigma()` — none of which are on the
32//!   trait, and several of which only mean anything for the filter-IPM's
33//!   eight-block compound iterate.
34//! * **Activity classification's plumbing.** It reads the filter-IPM's own
35//!   iterate (`z_l`, `z_u`, `v_l`, `v_u`) out of an `IpoptData` handle. Its
36//!   pure decision rule is portable and is expected to land here later; the
37//!   plumbing around it is not.
38//!
39//! Generalizing either would mean abstracting `IpoptData` / `CalculatedQuantities`
40//! access behind another trait, which is a larger project than this crate.
41//!
42//! # Provenance
43//!
44//! Port of upstream Ipopt's `contrib/sIPOPT/` (Pirnay, López-Negrete &
45//! Biegler 2012, DOI [10.1007/s12532-012-0043-2]). The module names mirror
46//! upstream's file names so the two can be read side by side.
47//!
48//! [10.1007/s12532-012-0043-2]: https://doi.org/10.1007/s12532-012-0043-2
49
50#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
51
52pub mod activity_kernel;
53pub mod backsolver;
54pub mod boundcheck;
55pub mod p_calculator;
56pub mod reduced_hessian;
57pub mod schur_data;
58pub mod schur_driver;
59pub mod sens_app;
60pub mod step_calc;
61
62// Root re-exports. These are not a convenience: several moved modules refer to
63// each other through the crate root (`&dyn crate::SchurData` appears in
64// `schur_driver`'s public trait signature), so removing one of these breaks
65// compilation rather than merely lengthening a path. `pounce-sensitivity`
66// re-exports the same names, which is what keeps its published API unchanged
67// across this extraction.
68pub use backsolver::{DenseLuBacksolver, SensBacksolver};
69pub use p_calculator::{IndexPCalculator, PCalculator};
70pub use reduced_hessian::compute_reduced_hessian;
71pub use schur_data::{IndexSchurData, SchurData};
72pub use schur_driver::{DenseGenSchurDriver, SchurDriver};
73pub use sens_app::{SensApplication, SensOptions, register_options};
74pub use step_calc::{SensStepCalc, StdStepCalc, WithBacksolver};
pounce_sens_core/lib.rs

pounce_sens_core/
lib.rs
