Struct Solver 

pub struct Solver { /* private fields */ }

Session-style solver: holds an IpoptApplication, its TNLP, and the converged factor between calls.

Implementations

impl Solver

pub fn new(app: IpoptApplication, tnlp: Rc<RefCell<dyn TNLP>>) -> Self

Build a new session. The app should already have its options configured and initialize() called.

pub fn app(&self) -> &IpoptApplication

Borrow the underlying IpoptApplication (e.g. to read its options table after a solve). Mutation between solve calls is supported via Self::app_mut.

pub fn app_mut(&mut self) -> &mut IpoptApplication

Mutable borrow of the underlying IpoptApplication. Useful for reconfiguring options before a follow-up solve(). Note that changing options that affect the KKT linear system between calls will invalidate the cached factor; the next solve() rebuilds it.

pub fn solve(&mut self) -> ApplicationReturnStatus

Run the IPM to convergence. On a successful solve the ConvergedState (including the KKT backsolver) is stashed inside the Solver and accessible via Self::converged.

Each call to solve() overwrites the previous converged state; the previously held factor is dropped.

pub fn converged(&self) -> Option<Ref<'_, ConvergedState>>

Borrow the converged state, if a successful solve has been run. Returns None if no solve has run or if the most recent solve failed before reaching convergence.

pub fn kkt_dim(&self) -> Option<usize>

Total dimension of the compound KKT vector (sum of block_dims). Returns None if no converged factor is held.

pub fn block_dims(&self) -> Option<[usize; 8]>

Block dimensions of the compound KKT vector in (x, s, y_c, y_d, z_l, z_u, v_l, v_u) order. Returns None if no converged factor is held.

pub fn with_converged<R>( &self, f: impl FnOnce(&ConvergedSolve<'_, PdSensBacksolver>) -> Result<R, SolverError>, ) -> Result<R, SolverError>

The calculations over the held factor, or SolverError::NotConverged when there is none.

pub fn classify_activity(&self) -> Result<ActivityReport, SolverError>

Classify every bounded variable and every finite-bounded inequality row of the converged solve by activity. See ConvergedSolve::classify_activity.

Requires the held solve to have run with bound_relax_factor=0. The guard reads ConvergedState::bound_relax_factor, the value that solve ran under, not the application’s current options. Setting the option after the fact neither unlocks a state whose bounds were relaxed nor invalidates one whose bounds were not. Re-solve to change the answer.

pub fn reduced_activity( &self, user_vars: &[usize], ) -> Result<ReducedActivityReport, SolverError>

The per-variable verdict for user_vars, re-measured against the reduced curvature along each coordinate. See ConvergedSolve::reduced_activity.

pub fn reduced_row_activity( &self, user_rows: &[usize], ) -> Result<ReducedRowActivityReport, SolverError>

The per-row verdict for user_rows, re-measured against the reduced curvature along each row’s gradient. See ConvergedSolve::reduced_row_activity.

pub fn row_normal(&self, user_row: usize) -> Result<Vec<Number>, SolverError>

The gradient of user constraint row user_row, in user variable order and natural units. See ConvergedSolve::row_normal.

pub fn hessian_vec(&self, v: &[Number]) -> Result<Vec<Number>, SolverError>

The exact Lagrangian Hessian times a user-space vector, in natural units. See ConvergedSolve::hessian_vec.

pub fn kkt_solve( &self, rhs: &[Number], lhs: &mut [Number], ) -> Result<(), SolverError>

Solve K · lhs = rhs against the converged KKT factor. Both slices must have length kkt_dim(), and the layout is the flat x || s || y_c || y_d || z_l || z_u || v_l || v_u packing.

K here is the natural-units (unscaled) KKT matrix: when the IPM solved with active NLP scaling, the backsolver scales the RHS/solution (all eight blocks, including the z/v bound-multiplier rows) so callers pass and receive data in the user’s own units (pounce#128). See crate::PdSensBacksolver::solve. For the raw scaled-space back-solve use Self::kkt_solve_scaled.

pub fn kkt_solve_scaled( &self, rhs: &[Number], lhs: &mut [Number], ) -> Result<(), SolverError>

Self::kkt_solve without the natural-units conjugation: the back-solve runs against the factor exactly as the IPM holds it (the solver’s internal scaled space). Identical to kkt_solve when no NLP scaling is active. “Scaled space” includes a user-scaling change of variables (gh#486), so on such a solve the x and z blocks here are in the substituted coordinates x̃ = d ⊙ x, not the model’s.

pub fn kkt_solve_many( &self, rhs_flat: &[Number], lhs_flat: &mut [Number], n_rhs: usize, ) -> Result<(), SolverError>

Batched-RHS back-solve. rhs_flat and lhs_flat are row-major (n_rhs, kkt_dim) buffers, each row solved against the same converged factor. Equivalent in result to looping Self::kkt_solve but reuses one IteratesVector for the RHS and one for the result across all n_rhs calls. See crate::algorithm_backsolver::PdSensBacksolver::solve_many.

pub fn kkt_solve_many_scaled( &self, rhs_flat: &[Number], lhs_flat: &mut [Number], n_rhs: usize, ) -> Result<(), SolverError>

Self::kkt_solve_many without the natural-units conjugation (the batched sibling of Self::kkt_solve_scaled).

pub fn parametric_step( &self, pin_constraint_indices: &[Index], deltas: &[Number], ) -> Result<Vec<Number>, SolverError>

First-order parametric step Δx ≈ ∂x*/∂p · Δp for a set of pinned equality constraints. See ConvergedSolve::parametric_step.

pub fn parametric_step_bounded( &self, pin_constraint_indices: &[Index], deltas: &[Number], max_iter: usize, bound_eps: Option<Number>, ) -> Result<(Vec<Number>, Vec<Index>, RefineStop), SolverError>

Parametric step with the bounds respected by pinning, not by clamping. See ConvergedSolve::parametric_step_bounded.

pub fn parametric_step_path( &self, pin_constraint_indices: &[Index], deltas: &[Number], max_iter: usize, ) -> Result<(Vec<Number>, Vec<PathSegment>), SolverError>

Parametric step taken along the path of active-set changes. See ConvergedSolve::parametric_step_path.

pub fn parametric_step_path_decided( &self, pin_constraint_indices: &[Index], deltas: &[Number], max_iter: usize, held_var_rows: &[Index], ) -> Result<(Vec<Number>, Vec<PathSegment>), SolverError>

Self::parametric_step_path with the weak-row decision supplied by the caller. See ConvergedSolve::parametric_step_path_decided.

pub fn correct_step( &self, pin_constraint_indices: &[Index], deltas: &[Number], step: &[Number], max_iter: usize, ) -> Result<(Vec<Number>, CorrectorReport), SolverError>

Newton iterations on the barrier system, refining a step that some mode already produced. See ConvergedSolve::correct_step.

pub fn parametric_step_bounded_decided( &self, pin_constraint_indices: &[Index], deltas: &[Number], max_iter: usize, held_var_rows: &[Index], bound_eps: Option<Number>, ) -> Result<(Vec<Number>, Vec<Index>, RefineStop), SolverError>

Self::parametric_step_bounded with the weak-row decision supplied by the caller. See ConvergedSolve::parametric_step_bounded_decided.

pub fn path_direction_decided( &self, pin_constraint_indices: &[Index], deltas: &[Number], released_bound_rows: &[Index], held_primal_rows: &[Index], operator: PathOperator, ) -> Result<(Vec<Number>, Vec<Number>), SolverError>

crate::boundcheck::path_direction for a working set the caller names. See ConvergedSolve::path_direction_decided.

pub fn parametric_step_release_all( &self, pin_constraint_indices: &[Index], deltas: &[Number], ) -> Result<(Vec<Number>, usize), SolverError>

The all-released step. See ConvergedSolve::parametric_step_release_all.

pub fn parametric_step_directional( &self, pin_constraint_indices: &[Index], deltas: &[Number], max_iter: usize, ) -> Result<(Vec<Number>, Vec<usize>, usize), SolverError>

The eq. 14 directional derivative. See ConvergedSolve::parametric_step_directional.

pub fn weakly_active_bounds(&self) -> Result<Vec<WeakBound>, SolverError>

The bounds the activity classifier could not call at the base point. See ConvergedSolve::weakly_active_bounds.

pub fn parametric_step_full( &self, pin_constraint_indices: &[Index], deltas: &[Number], ) -> Result<Vec<Number>, SolverError>

Full KKT-space parametric step. See ConvergedSolve::parametric_step_full.

pub fn parametric_rhs_full( &self, pin_constraint_indices: &[Index], deltas: &[Number], ) -> Result<Vec<Number>, SolverError>

The right-hand side Self::parametric_step_full answers, barrier term included. See ConvergedSolve::parametric_rhs_full.

pub fn g_multiplier_rows( &self, g_indices: &[Index], ) -> Result<Vec<Option<Index>>, SolverError>

Flat rows of the equality multipliers y_c for the given full-g constraint indices. See ConvergedSolve::g_multiplier_rows.

pub fn d_multiplier_rows( &self, g_indices: &[Index], ) -> Result<Vec<Option<Index>>, SolverError>

Flat rows of the inequality multipliers y_d for the given full-g constraint indices. See ConvergedSolve::d_multiplier_rows, which says when such a row is a derivative.

pub fn d_slack_rows( &self, g_indices: &[Index], ) -> Result<Vec<Option<Index>>, SolverError>

Flat rows of an inequality’s slack s. See ConvergedSolve::d_slack_rows.

pub fn x_primal_rows( &self, x_indices: &[Index], ) -> Result<Vec<Option<Index>>, SolverError>

Flat rows of the primal values x for the given full-x variable indices. See ConvergedSolve::x_primal_rows.

pub fn bound_multiplier_rows( &self, x_indices: &[Index], ) -> Result<Vec<(Option<Index>, Option<Index>)>, SolverError>

Flat rows of the bound multipliers (z_l, z_u) for the given full-x variable indices. See ConvergedSolve::bound_multiplier_rows.

pub fn n_full_x(&self) -> Result<usize, SolverError>

The user TNLP’s variable count: the length of a full-x report and the domain of Self::x_primal_rows.

pub fn n_full_g(&self) -> Result<usize, SolverError>

The user TNLP’s constraint count: the length of a full-g report and the domain of Self::reduced_row_activity.

pub fn compute_reduced_hessian( &self, pin_constraint_indices: &[Index], obj_scal: Number, ) -> Result<Vec<Number>, SolverError>

The negated reduced Hessian −H_R over the pinned equality rows, in natural units, so −inv of it is the parameter covariance. See ConvergedSolve::compute_reduced_hessian for the sign convention (gh#937), pinned by tests/issue_937_reduced_hessian_sign.rs.

Equivalent to crate::SensSolve::with_reduced_hessian but usable post-hoc on a held Solver. For the solver-space value use Self::compute_reduced_hessian_scaled.

pub fn compute_reduced_hessian_eigen( &self, pin_constraint_indices: &[Index], obj_scal: Number, ) -> Result<(Vec<Number>, Vec<Number>, Vec<Number>), SolverError>

Self::compute_reduced_hessian plus its eigendecomposition, (H_R, eigenvalues, eigenvectors). The eigenvalues are those of −H_R in ascending order, so they run stiffest mode first. See ConvergedSolve::compute_reduced_hessian_eigen.

pub fn compute_reduced_hessian_scaled( &self, pin_constraint_indices: &[Index], obj_scal: Number, ) -> Result<Vec<Number>, SolverError>

The reduced Hessian as the solver’s internal scaled space sees it. See ConvergedSolve::compute_reduced_hessian_scaled.

pub fn nlp_scaling( &self, ) -> Result<(Number, Option<Vec<Number>>, Option<Vec<Number>>), SolverError>

Effective NLP scaling the IPM applied on the most recent converged solve: (obj_scaling_factor, c_scale, d_scale). (1.0, None, None) means no scaling was active. The vectors are per-row factors over the algorithm’s equality (c) and inequality (d) blocks.

pub fn variable_scaling(&self) -> Result<Option<Vec<Number>>, SolverError>

The per-variable user-scaling factors d the held solve ran under (gh#486), in the user TNLP’s full-x space, or None when the solve applied no change of variables.

Every accessor on this type already reports natural units, so this is diagnostic rather than a correction a caller has to apply: it answers “was this solve conditioned, and by how much”, the x-axis counterpart of Self::nlp_scaling.

pub fn kkt_perturbations(&self) -> Result<[Number; 4], SolverError>

Inertia-correction perturbations (δ_x, δ_s, δ_c, δ_d) baked into the held KKT factor. All zero means the final factorization was unregularized and the natural-units back-solves invert the exact KKT matrix. See crate::PdSensBacksolver::kkt_perturbations.

pub fn pin_g_scaling( &self, pin_constraint_indices: &[Index], ) -> Result<Vec<Number>, SolverError>

Per-pin equality-row scaling factors dc_i (1.0 entries when no constraint scaling is active), ordered like pin_constraint_indices.