Crate pounce_sensitivity

Expand description

Sensitivity analysis for POUNCE — port of upstream Ipopt’s contrib/sIPOPT/.

§Status

Phases A–C complete. Wired today:

schur_data::IndexSchurData + p_calculator::IndexPCalculator: row-selector representation of the perturbation matrix B.
backsolver::DenseLuBacksolver + PdSensBacksolver: backsolves against the converged KKT factor (test / live IPM, respectively).
schur_driver::DenseGenSchurDriver: dense Schur-complement factor S = -B K⁻¹ Bᵀ with parallel right-hand-side solves.
step_calc::StdStepCalc + sens_app::SensApplication: high-level parametric_step(Δp, dx) and reduced_hessian::compute_reduced_hessian entry points.
SensSolve / SensResult: one-call builder (covers the on_converged plumbing typically required to wire the above into an IpoptApplication).

Verified against upstream sIPOPT 3.14.19’s parametric_cpp golden output to 1e-8 (see tests/parametric_cpp.rs); the standalone pounce_sens AMPL driver in pounce-cli matches sensitivity_amplsolver’s _sens_sol output on representative .nl problems.

Phase D progress (per pounce#7):

Fixed-variable lifting ✔ — pounce_sens handles n_x != n_full via the IpoptNlp::full_x_to_var_x / var_x_to_full_x / full_g_to_c_block / full_g_to_d_block trait methods (which delegate to BoundClassification.x_not_fixed_map / full_to_c / full_to_d).
Reduced-Hessian eigendecomposition ✔ — pure-Rust cyclic Jacobi in pounce_linalg::symmetric_eigen (shared with the convex QP sensitivity path); surfaced via SensApplication::compute_reduced_hessian_eigen, SensSolve::with_reduced_hessian_eigen, the pounce_sens --rh-eigendecomp flag, and the Python solve_with_sens(rh_eigendecomp=True) kwarg. Over parameter-pin rows the decomposed matrix is −H_R, so its ascending spectrum runs stiffest-first (gh#937); see Solver::compute_reduced_hessian.
sens_boundcheck bound refinement ✔ — boundcheck::refine_step_onto_bounds repairs the active set the step implies, both halves of upstream’s fix-relax: a coordinate the step carries past a bound is pinned AT that bound, and a bound multiplier the step drives negative is set to zero so the variable can leave. Either way the system is re-solved, so the other coordinates move with it. Surfaced via SensSolve::with_boundcheck, pounce_sens --sens-boundcheck, the Python solve_with_sens(sens_boundcheck=True) kwarg, and estimate(mode="fix_relax") in pyomo-pounce, all four running the same refinement.

§Algorithmic reference

Pirnay, H., López-Negrete, R., and Biegler, L.T. (2012). Optimal sensitivity based on IPOPT. Mathematical Programming Computation, 4(4), 307–331. DOI: 10.1007/s12532-012-0043-2.

Verified 2026-05-14 via Crossref: title, authors (Hans Pirnay; Rodrigo López-Negrete; Lorenz T. Biegler), MPC volume 4 issue 4 pp 307–331.

§Upstream source mirror

Port targets ref/Ipopt/contrib/sIPOPT/src/ in this repo (EPL-2.0, © Hans Pirnay 2009–2011 per the file headers). Each public item in this crate documents the upstream symbol it mirrors with file path and (where stable) line numbers.

Re-exports§

pub use algorithm_backsolver::PdSensBacksolver;
pub use convenience::SensResult;
pub use convenience::SensSolve;
pub use diff_handoff::DEFAULT_ACTIVE_TOL;
pub use diff_handoff::DiffHandoff;
pub use options::DEFAULT_SENS_BOUND_EPS;
pub use options::SensOptionOverrides;
pub use options::pdpert_verdict;
pub use options::release_floor_from_options;
pub use solver::ConvergedState;
pub use solver::Solver;
pub use solver::SolverError;
pub use pounce_sens_core;

Modules§

activity: Post-solve activity classification (the covariance/information roadmap’s item 0, gh #362).
algorithm_backsolver: PdSensBacksolver — SensBacksolver adapter over the converged PdFullSpaceSolver from pounce-algorithm.
backsolver: SensBacksolver trait — abstract backsolver against a converged KKT factor.
boundcheck: Holding the parametric sensitivity step inside the variable bounds.
convenience: High-level “solve, then run sensitivity” entry point for callers that don’t want to write the set_on_converged callback + PdSensBacksolver + IndexSchurData plumbing by hand.
corrector: Newton iterations on the barrier system, against the held factor.
diff_handoff: The solve → DiffHandoff contract — the solver-agnostic bundle that every differentiable solve hands to its backward pass.
index: Scoped index newtypes for the two variable spaces this crate mixes.
options: Resolving the registered sIPOPT option keys into the values this crate actually acts on (gh#551 / gh#677).
p_calculator: PCalculator trait surface.
reduced_hessian: ReducedHessianCalculator — port of upstream SensReducedHessianCalculator.{hpp,cpp}.
rowlimit: Watching a limit that is written as a constraint row, on an engine whose KKT has no slack block (gh#929).
schur_data: SchurData trait surface and the IndexSchurData flavor.
schur_driver: SchurDriver trait + DenseGenSchurDriver implementation.
sens_app: SensApplication — high-level entry point for sensitivity analysis.
solver: Solver — value-typed session API that holds an IpoptApplication, its TNLP, and the converged KKT factor between calls.
step_calc: SensStepCalc trait — orchestrates the sensitivity step computation.

Structs§

DenseGenSchurDriver: Dense general (non-symmetric) Schur driver.
DenseLuBacksolver: Synthetic dense-LU backsolver. Used in this crate’s tests to validate the sensitivity math against known-good linear-algebra answers without standing up the full pounce IPM. Phase B.2 ships a real pounce-algorithm-backed implementation; this stays for regression tests and as a reference for the trait contract.
IndexPCalculator: Concrete PCalculator for ±1-flagged parameter matrices.
IndexSchurData: Specialization for B matrices whose non-zero entries are ±1 (the parametric / reduced-Hessian common case). Storage is two parallel arrays mirroring upstream’s idx_ and val_ (SensIndexSchurData.hpp:127-128).
SensApplication: User-facing entry point for sensitivity analysis on a converged pounce solve.
SensOptions: Numeric / boolean knobs that drive a SensApplication. The fields’ names + defaults mirror the option keys registered in register_options.
StdStepCalc: Reference implementation that strings together SchurDriver::schur_solve and a final SensBacksolver::solve using the A data the driver was built with.

Enums§

PathOperator: Which operator a caller wants the walk’s Schur pin applied to.

Traits§

PCalculator: Algorithmic-strategy surface for computing the sensitivity matrix P = K⁻¹ A and the Schur complement S = B K⁻¹ A.
SchurData: Minimum surface for any matrix that lives in the augmented sIPOPT system’s A / B slots. The numerical drivers in this crate (PCalculator, SchurDriver, SensStepCalc) consume SchurData objects and never touch the storage shape directly.
SchurDriver: Factor the Schur complement once, then apply S⁻¹ to RHS vectors.
SensBacksolver: Solve K · lhs = rhs against the converged KKT factor. Returns false on failure (e.g. backend reports Singular).
SensStepCalc: Compute a sensitivity step Δu = S⁻¹ · rhs_u (Schur-space) and Δx_full = K⁻¹ · A · Δu (backsolved KKT-space), where the rhs_u vector encodes the parameter perturbation.
WithBacksolver: Bridge trait — exposes a SensBacksolver-shaped solve through whatever the driver wraps. Implementations of SchurDriver that want to be consumed by StdStepCalc opt in by also implementing WithBacksolver. This keeps SchurDriver’s own surface minimal — most drivers don’t need to expose the inner backsolver.

Functions§

compute_reduced_hessian
register_options: Register sIPOPT’s option keys against pounce’s RegisteredOptions. Mirrors upstream SensApplication::RegisterOptions (lines 54–117).
symmetric_eigen: In-place symmetric eigendecomposition.