pounce_cinterface/

solver.rs

//! Session-style C ABI built on [`pounce_sensitivity::Solver`].
//!
//! Adds an opaque [`IpoptSolver`] handle that captures the converged
//! KKT factor between calls, so C consumers can issue many cheap
//! operations (KKT back-solves, parametric steps, reduced Hessians)
//! against the same factorization without re-running the IPM.
//!
//! ```c
//! IpoptProblem prob = CreateIpoptProblem(...);
//! AddIpoptStrOption(prob, "linear_solver", "feral");
//! IpoptSolver sol = IpoptCreateSolver(&prob);   // consumes prob
//! IpoptSolverSolve(sol, x, NULL, NULL, NULL, NULL, NULL, user_data);
//! IpoptSolverParametricStep(sol, 2, pin_indices, deltas, dx_out);
//! IpoptSolverReducedHessian(sol, 2, pin_indices, 1.0, hr_out);
//! IpoptFreeSolver(sol);
//! ```
//!
//! Ownership: [`IpoptCreateSolver`] takes the IpoptProblem by **pointer
//! to the handle** and nulls it out on success — the IpoptSolver
//! becomes the sole owner. Calling [`crate::FreeIpoptProblem`] on the
//! now-null handle is safe (it null-checks).

use pounce_algorithm::application::{
    IpoptApplication, default_backend_factory_with_sink, feral_config_from_options,
    ma57_config_from_options,
};
use pounce_nlp::return_codes::ApplicationReturnStatus;
use pounce_nlp::tnlp::TNLP;
use pounce_restoration::resto_alg_builder::RestoAlgorithmBuilder;
use pounce_restoration::resto_inner_solver::{
    InnerBackendFactoryFactory, make_default_restoration_factory_provider,
};
use pounce_sensitivity::Solver as RustSolver;
use std::cell::RefCell;
use std::ffi::c_void;
use std::rc::Rc;

use crate::{
    Bool, CCallbackTnlp, FALSE, Index, IpoptProblem, IpoptProblemInfo, LastSolve, Number, TRUE,
};

/// Internal owned state for the session-style C handle.
pub struct IpoptSolverInfo {
    /// The session. `None` before the first solve or after a solve
    /// that didn't converge.
    session: Option<RustSolver>,
    /// All the problem state: callbacks, dims, bounds, options. On each
    /// solve the inner `IpoptApplication` is moved into a fresh
    /// `RustSolver` (held in `session`) and a blank app is left in its
    /// place; `IpoptSolverSolve` clones the OptionsList across that move
    /// so the user's options survive into the next solve.
    problem: IpoptProblemInfo,
    /// Number of constraints — cached for cheap shape checks.
    m: Index,
}

/// Opaque session-style handle. Construction via
/// [`IpoptCreateSolver`]; release via [`IpoptFreeSolver`].
pub type IpoptSolver = *mut IpoptSolverInfo;

/// Build an [`IpoptSolver`] session from a configured
/// [`IpoptProblem`]. **Consumes the IpoptProblem** on success: the
/// pointer at `*prob_handle` is set to NULL and ownership transfers
/// to the returned IpoptSolver. The user should not use the original
/// handle again, though calling [`crate::FreeIpoptProblem`] on the
/// now-null pointer is harmless (it null-checks).
///
/// Returns NULL if `prob_handle` is NULL, `*prob_handle` is NULL, or
/// the IpoptProblem hasn't been fully initialized.
///
/// Also returns NULL — **without** consuming the problem: the caller still
/// owns `*prob_handle` and frees it with [`crate::FreeIpoptProblem`] — when
/// the problem has declared complementarity pairs (gh#1147). A session
/// keeps the KKT factor of the model it solved, and with pairs that is the
/// lowered model (extra product rows, possibly lifted variables), so
/// [`IpoptSolverParametricStep`] and [`IpoptSolverReducedHessian`] over the
/// caller's rows would answer a different system. At `print_level >= 1` one
/// line on stderr says why. Python's `pounce.Solver` refuses pairs for the
/// same reason.
///
/// # Safety
///
/// `prob_handle` must be a valid pointer to an [`IpoptProblem`]
/// previously returned by [`crate::CreateIpoptProblem`] (or NULL).
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptCreateSolver(prob_handle: *mut IpoptProblem) -> IpoptSolver {
    unsafe {
        if prob_handle.is_null() {
            return std::ptr::null_mut();
        }
        let prob = *prob_handle;
        if prob.is_null() {
            return std::ptr::null_mut();
        }
        if !(&*prob).complementarity.is_empty() {
            if pounce_algorithm::second_opinion::narration_is_wanted((*prob).app.options()) {
                eprintln!(
                    "pounce: IpoptCreateSolver: a session cannot hold a problem with \
                     complementarity pairs ({} declared); solve it with IpoptSolve.",
                    (&*prob).complementarity.len()
                );
            }
            return std::ptr::null_mut();
        }
        // Take ownership of the Box and null out the caller's handle.
        let problem = *Box::from_raw(prob);
        *prob_handle = std::ptr::null_mut();
        let m = problem.m;
        let info = Box::new(IpoptSolverInfo {
            session: None,
            problem,
            m,
        });
        Box::into_raw(info)
    }
}

/// Release an [`IpoptSolver`] and all owned resources, including the
/// IpoptProblem state that was consumed by [`IpoptCreateSolver`].
///
/// # Safety
///
/// `solver` must be a pointer returned by [`IpoptCreateSolver`] and
/// not yet freed, or NULL.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptFreeSolver(solver: IpoptSolver) {
    unsafe {
        if solver.is_null() {
            return;
        }
        drop(Box::from_raw(solver));
    }
}

/// Run the IPM. Same output buffer contract as [`crate::IpoptSolve`]:
/// `x` is in/out (initial guess in, solution out); `g`, `obj_val` are
/// out-only; `mult_g`, `mult_x_L`, `mult_x_U` are out, and in as the
/// starting multipliers under `warm_start_init_point=yes`. All may be
/// NULL except `x` (when `n > 0`).
/// `user_data` is threaded into the C callbacks unchanged.
///
/// Returns the same `Index`-cast [`ApplicationReturnStatus`] code as
/// [`crate::IpoptSolve`]. On a converged status the session retains
/// the KKT factor for subsequent [`IpoptSolverKktSolve`],
/// [`IpoptSolverParametricStep`], and [`IpoptSolverReducedHessian`]
/// calls.
///
/// # Safety
///
/// All non-NULL output pointers must be valid for the appropriate
/// length; the C callbacks stored on the underlying IpoptProblem must
/// remain valid through the solve.
#[unsafe(no_mangle)]
#[allow(clippy::too_many_arguments)]
pub unsafe extern "C" fn IpoptSolverSolve(
    solver: IpoptSolver,
    x: *mut Number,
    g: *mut Number,
    obj_val: *mut Number,
    mult_g: *mut Number,
    mult_x_L: *mut Number,
    mult_x_U: *mut Number,
    user_data: *mut c_void,
) -> Index {
    unsafe {
        if solver.is_null() {
            return ApplicationReturnStatus::InternalError as Index;
        }
        // Invalidate any prior session state up front, before this solve is
        // attempted. The converged factor (`session`) and retained stats
        // (`problem.last_solve`) are only repopulated when the solve below runs to
        // completion; if the guarded body bails early or a panic is caught
        // (returning `Internal_Error`), neither the held KKT factor nor the
        // post-solve accessors must surface the *previous* solve's data. Clearing
        // here makes the failure-consistent state "no data" rather than a stale
        // factor / stale stats (F5).
        {
            let info = &mut *solver;
            info.session = None;
            info.problem.last_solve = None;
        }
        // Guard the whole solve: `RustSolver::solve` runs the entire pounce core
        // and the C-callback bridge, any of which could panic on an unexpected
        // internal state. A panic unwinding across `extern "C"` aborts the
        // embedding process; report `Internal_Error` instead, matching
        // `IpoptSolve` and upstream Ipopt's exception handling. (See `ffi_guard`.)
        crate::ffi_guard(ApplicationReturnStatus::InternalError as Index, || {
            let info = &mut *solver;
            let n = info.problem.n;
            let m = info.m;
            if n < 0 || m < 0 {
                return ApplicationReturnStatus::InvalidProblemDefinition as Index;
            }
            if n > 0 && x.is_null() {
                return ApplicationReturnStatus::InvalidProblemDefinition as Index;
            }
            // Unreachable: `IpoptCreateSolver` refuses a problem with pairs and
            // a session's problem is not reachable from C afterwards. Guarded
            // so a session can never run a solve that ignores declared pairs.
            if !info.problem.complementarity.is_empty() {
                return ApplicationReturnStatus::InvalidProblemDefinition as Index;
            }
            let n_us = n as usize;
            let m_us = m as usize;
            let initial_x = if n_us > 0 {
                std::slice::from_raw_parts(x, n_us).to_vec()
            } else {
                Vec::new()
            };

            let (lower_inf, upper_inf, zero_fixed_grad_lag) =
                crate::bridge_violation_options(info.problem.app.options());
            let bridge = Rc::new(RefCell::new(CCallbackTnlp {
                n,
                m,
                nele_jac: info.problem.nele_jac,
                nele_hess: info.problem.nele_hess,
                index_style: info.problem.index_style,
                x_l: info.problem.x_l.clone(),
                x_u: info.problem.x_u.clone(),
                g_l: info.problem.g_l.clone(),
                g_u: info.problem.g_u.clone(),
                initial_x,
                start_lambda: mult_g as *const Number,
                start_z_l: mult_x_L as *const Number,
                start_z_u: mult_x_U as *const Number,
                eval_f: info.problem.eval_f,
                eval_grad_f: info.problem.eval_grad_f,
                eval_g: info.problem.eval_g,
                eval_jac_g: info.problem.eval_jac_g,
                eval_h: info.problem.eval_h,
                user_data,
                intermediate_cb: info.problem.intermediate_cb,
                user_scaling: info.problem.user_scaling.clone(),
                nonlinear_vars: info.problem.nonlinear_vars.clone(),
                lower_inf,
                upper_inf,
                zero_fixed_grad_lag,
                final_status: None,
                final_x: vec![0.0; n_us],
                final_z_l: vec![0.0; n_us],
                final_z_u: vec![0.0; n_us],
                final_g: vec![0.0; m_us],
                final_lambda: vec![0.0; m_us],
                final_obj: 0.0,
            }));

            // Re-wire restoration fresh for this solve (same pattern as
            // IpoptSolve). Multi-pass provider so the ℓ₁ wrapper / auto-fallback
            // don't panic on the second inner solve (pounce#10 / pounce#24).
            let feral_cfg = feral_config_from_options(info.problem.app.options());
            // The `ma57_*` options under the `"resto."` prefix — dead until
            // gh#825, because nothing threaded any MA57 config into a factory.
            let ma57_cfg = ma57_config_from_options(info.problem.app.options(), "resto.");
            let resto_sink = info.problem.app.restoration_summary_sink();
            let bff_mint = move || -> InnerBackendFactoryFactory {
                let feral_cfg = feral_cfg.clone();
                let ma57_cfg = ma57_cfg.clone();
                let sink = std::sync::Arc::clone(&resto_sink);
                Box::new(move || {
                    default_backend_factory_with_sink(
                        feral_cfg.clone(),
                        ma57_cfg.clone(),
                        std::sync::Arc::clone(&sink),
                    )
                })
            };
            let resto_provider = make_default_restoration_factory_provider(
                RestoAlgorithmBuilder::new(),
                info.problem.app.algorithm_builder_from_options(),
                bff_mint,
            );
            info.problem
                .app
                .set_restoration_factory_provider(resto_provider);

            // Move the app out of the problem and into a fresh RustSolver. The
            // app carries the user's options (set via AddIpopt{Str,Num,Int}Option),
            // so we snapshot the OptionsList first and restore it into the fresh
            // blank app left behind. Without this, a second IpoptSolverSolve on the
            // same handle reads a default-initialised app — silently discarding the
            // linear solver, tolerances, scaling, etc. the caller configured (and
            // the `feral_config_from_options` snapshot above would, on that second
            // call, read the already-blanked options). The session API's design
            // center is repeated solves, so this must survive across them.
            let saved_options = info.problem.app.options().clone();
            let app = std::mem::replace(&mut info.problem.app, IpoptApplication::new());
            *info.problem.app.options_mut() = saved_options;
            let bridge_for_solver: Rc<RefCell<dyn TNLP>> = bridge.clone();
            let mut rust_solver = RustSolver::new(app, bridge_for_solver);
            let status = rust_solver.solve();
            let bridge_ref = bridge.borrow();
            info.problem.last_solve = Some(LastSolve {
                stats: rust_solver.app().statistics(),
                status,
                linear_solver: rust_solver.app().linear_solver_summary(),
                final_x: bridge_ref.final_x.clone(),
                final_lambda: bridge_ref.final_lambda.clone(),
                final_obj: bridge_ref.final_obj,
                mpcc: None,
                second_opinion: None,
            });
            if !x.is_null() && n_us > 0 {
                std::ptr::copy_nonoverlapping(bridge_ref.final_x.as_ptr(), x, n_us);
            }
            if !g.is_null() && m_us > 0 {
                std::ptr::copy_nonoverlapping(bridge_ref.final_g.as_ptr(), g, m_us);
            }
            if !obj_val.is_null() {
                *obj_val = bridge_ref.final_obj;
            }
            if !mult_g.is_null() && m_us > 0 {
                std::ptr::copy_nonoverlapping(bridge_ref.final_lambda.as_ptr(), mult_g, m_us);
            }
            if !mult_x_L.is_null() && n_us > 0 {
                std::ptr::copy_nonoverlapping(bridge_ref.final_z_l.as_ptr(), mult_x_L, n_us);
            }
            if !mult_x_U.is_null() && n_us > 0 {
                std::ptr::copy_nonoverlapping(bridge_ref.final_z_u.as_ptr(), mult_x_U, n_us);
            }

            info.session = Some(rust_solver);
            status as Index
        })
    }
}

/// Total compound-KKT vector dimension. Returns -1 if no converged
/// factor is held.
///
/// # Safety
///
/// `solver` must be a valid [`IpoptSolver`] or NULL.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptSolverGetKktDim(solver: IpoptSolver) -> Index {
    unsafe {
        if solver.is_null() {
            return -1;
        }
        let info = &*solver;
        match info.session.as_ref().and_then(|s| s.kkt_dim()) {
            Some(d) => d as Index,
            None => -1,
        }
    }
}

/// Solve `K · lhs = rhs` against the converged KKT factor. Both
/// `rhs` and `lhs` are flat buffers of length [`IpoptSolverGetKktDim`]
/// in the `x || s || y_c || y_d || z_l || z_u || v_l || v_u` packing.
///
/// `K` is the **natural-units** (unscaled) KKT matrix: any NLP
/// scaling the IPM applied (`nlp_scaling_method`) is undone in the
/// back-solve, so RHS and solution are in the user's own units
/// (pounce#128). Use [`IpoptSolverKktSolveScaled`] for the raw
/// back-solve against the factor exactly as the IPM holds it (the
/// pre-#128 behavior).
///
/// Returns `TRUE` on success, `FALSE` if no factor is held or the
/// back-solve fails.
///
/// # Safety
///
/// `rhs` and `lhs` must point to buffers at least
/// [`IpoptSolverGetKktDim`] doubles long.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptSolverKktSolve(
    solver: IpoptSolver,
    rhs: *const Number,
    lhs: *mut Number,
) -> Bool {
    unsafe { kkt_solve_impl(solver, rhs, lhs, false) }
}

/// [`IpoptSolverKktSolve`] without the natural-units correction: the
/// back-solve runs in the solver's internal scaled space. Identical
/// to `IpoptSolverKktSolve` when no NLP scaling is active.
///
/// # Safety
///
/// Same contract as [`IpoptSolverKktSolve`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptSolverKktSolveScaled(
    solver: IpoptSolver,
    rhs: *const Number,
    lhs: *mut Number,
) -> Bool {
    unsafe { kkt_solve_impl(solver, rhs, lhs, true) }
}

unsafe fn kkt_solve_impl(
    solver: IpoptSolver,
    rhs: *const Number,
    lhs: *mut Number,
    scaled: bool,
) -> Bool {
    // Guard the back-solve: it runs the linear-solver kernel against the
    // retained factor, which could panic on an unexpected state. A panic
    // unwinding across the `extern "C"` callers (`IpoptSolverKktSolve` /
    // `IpoptSolverKktSolveScaled`) aborts the embedding process; report
    // `FALSE` instead. (See `ffi_guard`.)
    crate::ffi_guard(FALSE, || unsafe {
        if solver.is_null() || rhs.is_null() || lhs.is_null() {
            return FALSE;
        }
        let info = &*solver;
        let Some(s) = info.session.as_ref() else {
            return FALSE;
        };
        let Some(dim) = s.kkt_dim() else {
            return FALSE;
        };
        let rhs_slice = std::slice::from_raw_parts(rhs, dim);
        let mut lhs_vec = vec![0.0; dim];
        let res = if scaled {
            s.kkt_solve_scaled(rhs_slice, &mut lhs_vec)
        } else {
            s.kkt_solve(rhs_slice, &mut lhs_vec)
        };
        if res.is_err() {
            return FALSE;
        }
        std::ptr::copy_nonoverlapping(lhs_vec.as_ptr(), lhs, dim);
        TRUE
    })
}

/// Like [`std::slice::from_raw_parts`], but yields an empty slice when
/// `len == 0` instead of dereferencing `ptr`. A legal zero-length call
/// (`n_pins == 0`) is allowed to pass a NULL/dangling pointer, yet
/// `from_raw_parts` requires its pointer be non-null and aligned *even
/// for empty slices* — `from_raw_parts(NULL, 0)` is undefined behaviour
/// and trips the `slice::from_raw_parts requires the pointer to be
/// aligned and non-null` debug-assertion on recent Rust. This mirrors
/// the `n_us > 0` gate already used in `IpoptSolverSolve`.
///
/// # Safety
///
/// When `len > 0`, `ptr` must point to `len` valid, initialized `T`.
unsafe fn slice_or_empty<'a, T>(ptr: *const T, len: usize) -> &'a [T] {
    unsafe {
        if len == 0 {
            &[]
        } else {
            std::slice::from_raw_parts(ptr, len)
        }
    }
}

/// First-order parametric step `Δx ≈ ∂x*/∂p · Δp`. `pin_indices` is
/// `n_pins` `Index` values (0-based indices into `g(x)`); `deltas` is
/// the parameter perturbation `Δp` of the same length; `dx_out` is the
/// `n`-long primal step output (length matches the problem's `n`).
///
/// Returns `TRUE` on success, `FALSE` if no converged factor, invalid
/// indices, or the sensitivity computation fails.
///
/// # Safety
///
/// `pin_indices` and `deltas` must point to `n_pins` valid elements;
/// `dx_out` must point to at least `n` `Number` slots (`n` from the
/// underlying IpoptProblem).
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptSolverParametricStep(
    solver: IpoptSolver,
    n_pins: Index,
    pin_indices: *const Index,
    deltas: *const Number,
    dx_out: *mut Number,
) -> Bool {
    // Guard the sensitivity solve: it runs the linear-solver kernel against
    // the retained factor, which could panic on an unexpected state. A panic
    // unwinding across `extern "C"` aborts the embedding process; report
    // `FALSE` instead. (See `ffi_guard`.)
    crate::ffi_guard(FALSE, || unsafe {
        if solver.is_null() || n_pins < 0 {
            return FALSE;
        }
        if n_pins > 0 && (pin_indices.is_null() || deltas.is_null()) {
            return FALSE;
        }
        if dx_out.is_null() {
            return FALSE;
        }
        let info = &*solver;
        let Some(s) = info.session.as_ref() else {
            return FALSE;
        };
        let m = info.m;
        let pins_raw = slice_or_empty(pin_indices, n_pins as usize);
        let mut pins = Vec::with_capacity(n_pins as usize);
        for &i in pins_raw {
            if i < 0 || i >= m {
                return FALSE;
            }
            pins.push(i as pounce_common::types::Index);
        }
        let deltas_slice = slice_or_empty(deltas, n_pins as usize);
        let Ok(dx) = s.parametric_step(&pins, deltas_slice) else {
            return FALSE;
        };
        std::ptr::copy_nonoverlapping(dx.as_ptr(), dx_out, dx.len());
        TRUE
    })
}

/// Reduced Hessian `obj_scal · B K⁻¹ Bᵀ` over the pinned rows.
/// `hr_out` receives an `n_pins²`-long column-major dense matrix.
///
/// The value is in **natural (unscaled) units**: any NLP scaling the
/// IPM applied (`nlp_scaling_method`) is undone before it is reported,
/// so `-inv(...)` of it is directly the parameter covariance of an
/// estimation problem (pounce#128). `obj_scal` is a plain extra
/// multiplier (pass 1.0); it is no longer needed to undo pounce's own
/// scaling.
///
/// **Sign convention: this writes `−H_R`, not `H_R`** (gh#937) — see
/// [`pounce_sensitivity::Solver::compute_reduced_hessian`], which it
/// forwards to. Negate `hr_out` to read curvature.
///
/// Returns `TRUE` on success, `FALSE` otherwise.
///
/// # Safety
///
/// `pin_indices` must point to `n_pins` valid elements; `hr_out` must
/// point to at least `n_pins²` `Number` slots.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn IpoptSolverReducedHessian(
    solver: IpoptSolver,
    n_pins: Index,
    pin_indices: *const Index,
    obj_scal: Number,
    hr_out: *mut Number,
) -> Bool {
    // Guard the reduced-Hessian assembly: it runs repeated back-solves against
    // the retained factor, which could panic on an unexpected state. A panic
    // unwinding across `extern "C"` aborts the embedding process; report
    // `FALSE` instead. (See `ffi_guard`.)
    crate::ffi_guard(FALSE, || unsafe {
        if solver.is_null() || n_pins < 0 || hr_out.is_null() {
            return FALSE;
        }
        if n_pins > 0 && pin_indices.is_null() {
            return FALSE;
        }
        let info = &*solver;
        let Some(s) = info.session.as_ref() else {
            return FALSE;
        };
        let m = info.m;
        let pins_raw = slice_or_empty(pin_indices, n_pins as usize);
        let mut pins = Vec::with_capacity(n_pins as usize);
        for &i in pins_raw {
            if i < 0 || i >= m {
                return FALSE;
            }
            pins.push(i as pounce_common::types::Index);
        }
        let Ok(hr) = s.compute_reduced_hessian(&pins, obj_scal) else {
            return FALSE;
        };
        std::ptr::copy_nonoverlapping(hr.as_ptr(), hr_out, hr.len());
        TRUE
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{AddIpoptIntOption, CreateIpoptProblem, FreeIpoptProblem};
    use std::ffi::CString;

    // f(x) = (x - 2)^2 — the same 1-D quadratic the bridge tests use;
    // converges in one Newton step.
    unsafe extern "C" fn quad_eval_f(
        _n: Index,
        x: *const Number,
        _new_x: Bool,
        obj_value: *mut Number,
        _user_data: *mut c_void,
    ) -> Bool {
        unsafe {
            let v = *x.offset(0);
            *obj_value = (v - 2.0) * (v - 2.0);
            TRUE
        }
    }
    unsafe extern "C" fn quad_eval_grad_f(
        _n: Index,
        x: *const Number,
        _new_x: Bool,
        grad: *mut Number,
        _user_data: *mut c_void,
    ) -> Bool {
        unsafe {
            let v = *x.offset(0);
            *grad.offset(0) = 2.0 * (v - 2.0);
            TRUE
        }
    }
    unsafe extern "C" fn quad_eval_h(
        _n: Index,
        _x: *const Number,
        _new_x: Bool,
        obj_factor: Number,
        _m: Index,
        _lambda: *const Number,
        _new_lambda: Bool,
        _nele_hess: Index,
        irow: *mut Index,
        jcol: *mut Index,
        values: *mut Number,
        _user_data: *mut c_void,
    ) -> Bool {
        unsafe {
            if !irow.is_null() && !jcol.is_null() && values.is_null() {
                *irow.offset(0) = 0;
                *jcol.offset(0) = 0;
            } else if irow.is_null() && jcol.is_null() && !values.is_null() {
                *values.offset(0) = 2.0 * obj_factor;
            } else {
                return FALSE;
            }
            TRUE
        }
    }

    fn create_quad() -> IpoptProblem {
        let xl = [-1.0e20];
        let xu = [1.0e20];
        unsafe {
            CreateIpoptProblem(
                1,
                xl.as_ptr(),
                xu.as_ptr(),
                0,
                std::ptr::null(),
                std::ptr::null(),
                0,
                1,
                0,
                Some(quad_eval_f),
                None,
                Some(quad_eval_grad_f),
                None,
                Some(quad_eval_h),
            )
        }
    }

    /// H13: a user option set before `IpoptCreateSolver` must survive every
    /// `IpoptSolverSolve` on the handle. Before the fix the app (and its
    /// OptionsList) was `mem::replace`d with a blank default on the first
    /// solve and never restored, so the second solve silently ran with
    /// default options. Here we set a clearly non-default `max_iter = 7`
    /// and assert it is still present after the first AND second solve.
    #[test]
    fn options_survive_repeated_session_solves() {
        let mut prob = create_quad();
        let key = CString::new("max_iter").unwrap();
        assert_eq!(unsafe { AddIpoptIntOption(prob, key.as_ptr(), 7) }, TRUE);

        // IpoptCreateSolver consumes the problem and nulls the handle.
        let solver = unsafe { IpoptCreateSolver(&mut prob) };
        assert!(!solver.is_null());
        assert!(prob.is_null(), "create must null the caller's handle");

        let read_max_iter = |solver: IpoptSolver| -> Option<i32> {
            let info = unsafe { &*solver };
            match info.problem.app.options().get_integer_value("max_iter", "") {
                Ok((v, true)) => Some(v),
                _ => None,
            }
        };

        // The option is present before any solve.
        assert_eq!(read_max_iter(solver), Some(7), "option set pre-solve");

        let mut x = [0.0_f64];
        let mut obj = 0.0_f64;
        let solve = |solver: IpoptSolver, x: &mut [f64], obj: &mut f64| unsafe {
            IpoptSolverSolve(
                solver,
                x.as_mut_ptr(),
                std::ptr::null_mut(),
                obj as *mut f64,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
            )
        };

        // First solve — the app is moved into the session; the OptionsList
        // must be restored into the blank app left behind.
        let _ = solve(solver, &mut x, &mut obj);
        assert_eq!(
            read_max_iter(solver),
            Some(7),
            "max_iter must survive the first session solve (H13)"
        );

        // Second solve — the design center of the session API. Pre-fix this
        // ran on a blanked app; the option must still be there.
        let _ = solve(solver, &mut x, &mut obj);
        assert_eq!(
            read_max_iter(solver),
            Some(7),
            "max_iter must survive a second session solve (H13)"
        );

        unsafe { IpoptFreeSolver(solver) };
        // The (now-null) problem handle is safe to free.
        unsafe { FreeIpoptProblem(prob) };
    }

    /// gh#1147: `IpoptSolverSolve`'s guard against declared pairs. Not
    /// reachable from C — `IpoptCreateSolver` refuses a problem with pairs
    /// (`tests/complementarity_solve.rs`) and a session's problem has no C
    /// handle — so the pair is planted on the session's problem directly.
    /// The guard refuses before any solve: no stats, no callback, `x`
    /// untouched.
    #[test]
    fn session_solve_refuses_pairs_planted_past_create() {
        let mut prob = create_quad();
        let solver = unsafe { IpoptCreateSolver(&mut prob) };
        assert!(!solver.is_null());
        unsafe { &mut *solver }
            .problem
            .complementarity
            .push(pounce_nlp::mpcc::ComplementarityPair { row: 0, var: 0 });
        let mut x = [0.5_f64];
        let rc = unsafe {
            IpoptSolverSolve(
                solver,
                x.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
            )
        };
        assert_eq!(
            rc,
            ApplicationReturnStatus::InvalidProblemDefinition as Index
        );
        assert_eq!(x, [0.5]);
        assert!(unsafe { &*solver }.problem.last_solve.is_none());
        // Without the planted pair the same session solves.
        unsafe { &mut *solver }.problem.complementarity.clear();
        let rc = unsafe {
            IpoptSolverSolve(
                solver,
                x.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
            )
        };
        assert_eq!(rc, ApplicationReturnStatus::SolveSucceeded as Index);
        assert!((x[0] - 2.0).abs() < 1e-8);
        unsafe { IpoptFreeSolver(solver) };
    }

    /// M37: a legal `n_pins == 0` call to the sensitivity entry points is
    /// allowed to pass NULL `pin_indices`/`deltas` (there is nothing to
    /// point at), but the implementation fed those straight into
    /// `slice::from_raw_parts(NULL, 0)` — undefined behaviour that aborts
    /// the process under the `-C debug-assertions` precondition checks
    /// recent rustc emits. The session check sits *before* the bad
    /// `from_raw_parts`, so a converged solver is required to reach it.
    /// Pre-fix this test aborts the binary; post-fix the calls return a
    /// well-defined `Bool` (an empty pin set is a no-op back-solve).
    #[test]
    fn zero_pins_with_null_pointers_is_not_ub() {
        let mut prob = create_quad();
        let solver = unsafe { IpoptCreateSolver(&mut prob) };
        assert!(!solver.is_null());

        // Solve so the handle holds a converged session (the null-pointer
        // path past the session guard is what trips the UB).
        let mut x = [0.0_f64];
        let mut obj = 0.0_f64;
        let status = unsafe {
            IpoptSolverSolve(
                solver,
                x.as_mut_ptr(),
                std::ptr::null_mut(),
                &mut obj as *mut f64,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
            )
        };
        assert_eq!(status, ApplicationReturnStatus::SolveSucceeded as Index);

        // n_pins == 0 with NULL pin/delta pointers — the legal empty call.
        // dx_out is a real n-long buffer (n == 1 here); n_pins² == 0 so the
        // reduced-Hessian output buffer is never written, but pass a valid
        // pointer anyway.
        let mut dx_out = [0.0_f64];
        let mut hr_out = [0.0_f64];

        // Reaching the assertions at all means no `from_raw_parts(NULL, 0)`
        // abort fired. An empty pin set is a well-defined no-op: a zero
        // perturbation yields Δx ≈ 0 and an empty (0×0) reduced Hessian, so
        // both calls succeed with TRUE — the defined, non-UB outcome.
        let step = unsafe {
            IpoptSolverParametricStep(
                solver,
                0,
                std::ptr::null(),
                std::ptr::null(),
                dx_out.as_mut_ptr(),
            )
        };
        assert_eq!(step, TRUE, "empty parametric step is a defined no-op");

        let rh = unsafe {
            IpoptSolverReducedHessian(solver, 0, std::ptr::null(), 1.0, hr_out.as_mut_ptr())
        };
        assert_eq!(rh, TRUE, "empty reduced Hessian is a defined no-op");

        unsafe { IpoptFreeSolver(solver) };
        unsafe { FreeIpoptProblem(prob) };
    }

    /// F5 (session arm): `IpoptSolverSolve` is now wrapped in `ffi_guard`, so
    /// a pounce-internal panic is converted to `Internal_Error` instead of
    /// aborting the embedding process. The secondary half of F5 is the state
    /// hygiene that wrapping demands: the call must invalidate the retained
    /// session factor (`session`) and stats (`problem.last_solve`) **up
    /// front**, so a solve that bails — or whose panic `ffi_guard` catches —
    /// does not leave the handle holding the *previous* solve's converged
    /// factorization (against which a later `IpoptSolverKktSolve` would
    /// silently back-solve) or stale stats.
    ///
    /// A caught panic can't be injected deterministically through the public
    /// C ABI (a panic in a user `extern "C"` callback aborts at its own
    /// boundary, before unwinding reaches `ffi_guard`; see that fn's note).
    /// So we drive the equivalent control-flow shape: after a successful
    /// solve we corrupt the cached constraint count to a negative value, so
    /// the next `IpoptSolverSolve` returns `InvalidProblemDefinition` from
    /// inside the guarded body **without** reaching the trailing
    /// `session = Some(..)` / `last_solve = Some(..)` writes — exactly where a
    /// caught panic also bails. The up-front clear is what makes the
    /// post-failure state "no data" in both cases.
    #[test]
    fn stale_session_state_cleared_when_resolve_bails() {
        let mut prob = create_quad();
        let solver = unsafe { IpoptCreateSolver(&mut prob) };
        assert!(!solver.is_null());

        let mut x = [0.0_f64];
        let mut obj = 0.0_f64;
        let solve = |solver: IpoptSolver, x: &mut [f64], obj: &mut f64| unsafe {
            IpoptSolverSolve(
                solver,
                x.as_mut_ptr(),
                std::ptr::null_mut(),
                obj as *mut f64,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
            )
        };

        // A converged solve holds a factor and records stats.
        let rc = solve(solver, &mut x, &mut obj);
        assert_eq!(rc, ApplicationReturnStatus::SolveSucceeded as Index);
        {
            let info = unsafe { &*solver };
            assert!(
                info.session.is_some(),
                "converged solve should hold a session factor"
            );
            assert!(
                info.problem.last_solve.is_some(),
                "converged solve should record stats"
            );
        }
        assert!(
            unsafe { IpoptSolverGetKktDim(solver) } >= 0,
            "a held factor reports a non-negative KKT dim"
        );

        // Corrupt the cached constraint count so the next solve bails early in
        // the guarded body (the InvalidProblemDefinition guard) — the same
        // place a caught panic would land — without recording anything.
        unsafe { (*solver).m = -1 };
        let mut x2 = [0.0_f64];
        let mut obj2 = 0.0_f64;
        let rc2 = solve(solver, &mut x2, &mut obj2);
        assert_eq!(
            rc2,
            ApplicationReturnStatus::InvalidProblemDefinition as Index
        );

        // Post-fix: the up-front invalidation dropped the stale factor and
        // stats. Pre-fix both survived — a subsequent KKT back-solve would run
        // silently against the abandoned factorization.
        {
            let info = unsafe { &*solver };
            assert!(
                info.session.is_none(),
                "bailed solve must drop the stale session factor (F5)"
            );
            assert!(
                info.problem.last_solve.is_none(),
                "bailed solve must clear stale stats (F5)"
            );
        }
        assert_eq!(
            unsafe { IpoptSolverGetKktDim(solver) },
            -1,
            "no factor is held after a bailed re-solve (F5)"
        );

        unsafe { IpoptFreeSolver(solver) };
        unsafe { FreeIpoptProblem(prob) };
    }
}