Struct IpoptApplication 

pub struct IpoptApplication { /* private fields */ }

Implementations

impl IpoptApplication

pub fn new() -> IpoptApplication

New application with empty options and a default journalist. Equivalent to IpoptApplication::IpoptApplication(true,true).

pub fn options(&self) -> &OptionsList

pub fn options_mut(&mut self) -> &mut OptionsList

pub fn set_presolve_already_applied(&mut self, applied: bool)

Declare whether callers have already applied an explicit presolve wrapper to the TNLPs submitted to Self::optimize_tnlp.

When set, optimize_tnlp leaves its input TNLP unchanged even if the presolve option is enabled. This preserves the option table for reporting and debugger use while allowing specialized frontends to supply a wrapper with capabilities unavailable to generic callback TNLPs, such as an expression provider for FBBT.

pub fn optimize_tnlp_without_presolve( &mut self, tnlp: Rc<RefCell<dyn TNLP>>, ) -> ApplicationReturnStatus

Solve without materializing the generic presolve wrapper.

This is for consumers that require the original TNLP coordinate system for the solve’s KKT matrix, such as sensitivity and reduced-Hessian drivers. It is scoped to this invocation and does not change the application’s presolve option or persistent explicit-wrapper setting.

pub fn registered_options(&self) -> &Rc<RegisteredOptions>

pub fn journalist(&self) -> &Rc<Journalist>

pub fn set_linear_backend_factory( &mut self, factory: Box<dyn FnMut(LinearSolverChoice) -> Box<dyn SparseSymLinearSolverInterface>>, )

Plug a custom symmetric-linear-solver factory. Useful for tests that want to swap MA57 for a stub. Production callers should leave this unset — the default (default_backend_factory) returns the workspace’s MA57 binding.

pub fn set_restoration_factory( &mut self, factory: Box<dyn FnMut() -> Box<dyn RestorationPhase>>, )

Plug a restoration-phase factory. Called once per optimize_tnlp invocation to mint a fresh Box<dyn RestorationPhase> that the outer algorithm uses as its line-search restoration fallback. Lives behind a setter (rather than at construction) because the concrete restoration strategies live in pounce-restoration, which depends on this crate; consumers in pounce-cli / integration tests wire the factory at the application boundary.

pub fn set_diagnostics(&mut self, diag: Rc<DiagnosticsState>)

Install the shared diagnostics state. Once set, every subsequent optimize_tnlp call forwards the state into the algorithm via IpoptAlgorithm::with_diagnostics so the KKT solver can emit --dump kkt:... artifacts.

pub fn set_debug_hook(&mut self, hook: Rc<RefCell<dyn DebugHook>>)

Install an interactive debugger hook for the next optimize_* call. The hook is moved into the main IpoptAlgorithm and consumed by that solve; reinstall it to debug a subsequent solve.

pub fn diagnostics(&self) -> Option<Rc<DiagnosticsState>>

Read-side accessor for the installed diagnostics state, if any. Lets the CLI write the top-level manifest/timing files after the solve completes.

pub fn set_restoration_factory_provider( &mut self, provider: Box<dyn FnMut() -> Box<dyn FnMut() -> Box<dyn RestorationPhase>>>, )

Plug a restoration-phase factory provider for drivers that need to run the inner IPM more than once per optimize_tnlp call (notably the Phase-3 ℓ₁-exact penalty-barrier outer loop, pounce#10). On each inner solve, the application consults the provider to mint a fresh RestorationFactory, replacing any stale one, so the default one-shot restoration factory does not panic on its second invocation. If both set_restoration_factory and this are configured, the provider wins.

pub fn set_on_converged( &mut self, cb: Box<dyn FnMut(&Rc<RefCell<IpoptData>>, &Rc<RefCell<IpoptCalculatedQuantities>>, &Rc<RefCell<dyn IpoptNlp>>, Rc<RefCell<PdFullSpaceSolver>>)>, )

Register a callback to run once the IPM has converged (status ApplicationReturnStatus::SolveSucceeded or ApplicationReturnStatus::SolvedToAcceptableLevel) but before finalize_solution flows back to the TNLP. See ConvergedCallback for the use case (post-optimal sensitivity).

pub fn enable_iter_history(&mut self)

Enable per-iteration trajectory capture. After the solve returns, Self::statistics() exposes pounce_nlp::solve_statistics::SolveStatistics::iterations populated with one pounce_nlp::solve_statistics::IterRecord per accepted iterate. Off by default — the pounce_sens and pounce binaries opt in when --json-output is passed.

pub fn initialize_with_option_file( &mut self, explicit: Option<&Path>, ) -> Result<OptionFileLoad, SolverException>

Read the run’s options file, resolving which file the way upstream’s IpoptApplication::Initialize does — with one deliberate difference, below.

explicit is the file the caller named (upstream: the option_file_name option, read out of the option store before this point). With None, the working directory is probed for DEFAULT_OPTION_FILE_NAMES and the first hit is read; an absent default file is not an error, it just means “no file”.

The difference: upstream opens a named file with a bare std::ifstream and reads nothing if the open fails, so a typo’d option_file_name runs at stock defaults without a word. That silence is what gh#518 was reported for — a benchmark that measured defaults while claiming to measure a configuration — so a named file that cannot be read is an error here.

pub fn initialize_with_options_file( &mut self, path: &Path, ) -> Result<(), SolverException>

Read an ipopt.opt-format options file. Equivalent to IpoptApplication::Initialize(const std::string& options_file).

pub fn initialize_with_options_str( &mut self, s: &str, ) -> Result<(), SolverException>

Read options from a string in ipopt.opt format. Useful for tests and embedded callers.

pub fn initialize(&mut self) -> Result<(), SolverException>

No-op initialize (just succeeds). Mirrors IpoptApplication::Initialize(bool allow_clobber) with no options file.

pub fn open_output_file(&mut self, fname: &str, print_level: i32) -> bool

Mirror IpoptApplication::OpenOutputFile. Sets the output_file / file_print_level options and attaches a matching FileJournal named OutputFile:<fname> to the journalist. Returns false if the file could not be opened or the option store rejected the request (e.g. clamped print level).

pub fn problem_dimensions(&self, tnlp: &mut dyn TNLP) -> Option<NlpInfo>

Wrap a TNLP and report problem dimensions. Used in tests until the full IPM path covers every entry shape.

pub fn statistics(&self) -> SolveStatistics

pub fn timing_stats(&self) -> Rc<TimingStatistics>

Shared timing accumulator from the most recent optimize_tnlp call. Each subsystem (algorithm, NLP, KKT solver) bumped its own fields during the solve; consumers read totals out of the returned Rc. The instance is replaced at the top of every subsequent solve, so cloning the Rc and holding it past a re-solve will give you the previous solve’s timings — by design.

pub fn linear_solver_summary(&self) -> Option<LinearSolverSummary>

Aggregate linear-solver post-mortem from the most recent optimize_tnlp call. Some when the workspace-default FERAL backend ran at least one factor; None when no factors were recorded (custom factory plugged via Self::set_linear_backend_factory, or solve aborted before the first KKT factor). Reset at the top of every solve.

pub fn variable_scaling(&self) -> Option<Vec<f64>>

The per-variable scaling factors applied to the last solve, if any (gh#486). A consumer reading the algorithm’s iterate rather than the finalize_solution payload sees scaled coordinates and must divide x by these, and multiply bound multipliers.

pub fn optimize_tnlp( &mut self, tnlp: Rc<RefCell<dyn TNLP>>, ) -> ApplicationReturnStatus

pub fn set_sqp_warm_start(&mut self, warm: SqpIterates)

Has the user set algorithm = active-set-sqp? Reads the string option and matches case-insensitively against the design-note §7.1 spelling. Any value other than “active-set-sqp” (including absence) routes to the default IPM path. Stash a warm-start iterate for the SQP path. Consumed by the next optimize_tnlp call when the algorithm option resolves to active-set-sqp; the IPM path ignores it. Phase 5c (§6) — the parametric / MPC warm-start hand-off.

The iterate is auto-cleared after use, so a follow-up solve without an intervening set_sqp_warm_start call cold-starts.

pub fn clear_sqp_warm_start(&mut self)

Drop any pending warm-start iterate without solving.

pub fn set_warm_start_iterate(&mut self, snap: IterateSnapshot)

Install a full primal-dual warm-start iterate for the next IPM optimize_tnlp. Captured by the debugger’s resolve so the re-solve continues from the paused interior point. The caller is responsible for also enabling warm_start_init_point=yes (and usually warm_start_target_mu=<μ>) so the re-optimize branch of WarmStartIterateInitializer preserves the installed iterate. Consumed once per solve, then auto-cleared.

pub fn set_external_ordering(&mut self, perm: Vec<usize>)

Install a caller-supplied fill-reducing permutation for the KKT linear solver (pounce#180 item 1). The next optimize_* builds the FERAL backend with pounce_feral::OrderingMethod::External, overriding the feral_ordering string option / env var. Use this to inject a block-triangular / Schur ordering a generic algorithm cannot see (Parker, Garcia & Bent, arXiv:2602.17968) or a tearing ordering from equation-oriented decomposition.

perm is a 0-based, new-to-old permutation (perm[k] is the original index that becomes index k), and its length must equal the augmented KKT system dimension (variables + slacks + constraint duals), not the problem’s n. A wrong length or a non-bijection is rejected by FERAL at the first factorization with an InvalidInput error (never a panic), surfacing as a solver failure rather than a silently-wrong solve — the ordering only affects fill/time, never the computed solution.

Persistent config: unlike the warm-start hooks it is not auto-cleared after a solve. Call Self::clear_external_ordering to drop it. Ignored by non-FERAL backends and by any custom factory plugged via Self::set_linear_backend_factory.

pub fn clear_external_ordering(&mut self)

Drop any installed external KKT ordering, restoring the feral_ordering-driven default for subsequent solves.

pub fn external_ordering(&self) -> Option<&[usize]>

The currently-installed external KKT ordering, if any.

pub fn set_kkt_schur_block(&mut self, indices: Vec<usize>)

Install a block-triangular / Schur KKT partition (pounce#180 item 2). indices are KKT-space indices (0..dim in the x, s, c, d block order the aug-system solver assembles) naming the Schur block S; that block is Schur-complemented out and only the two diagonal blocks are factorized (inertia via Sylvester’s law). Honored on the IPM + feral + exact-Hessian path; the Schur solver falls back to the standard full-space solver transparently when the partition is unsuitable (too large a fraction of the system, malformed, or a backend error), so a stray hook never breaks a solve. Persistent config (not auto-cleared); drop it via Self::clear_kkt_schur_block.

pub fn clear_kkt_schur_block(&mut self)

Drop any installed Schur KKT partition, restoring the standard full-space solver for subsequent solves.

pub fn kkt_schur_block(&self) -> Option<&[usize]>

The currently-installed Schur KKT partition, if any.

pub fn last_sqp_working_set(&self) -> Option<&WorkingSet>

Return the final QP working set from the most recent SQP solve, or None if the last solve wasn’t SQP, didn’t produce a working set (cold-start declared the iterate optimal before solving any QP), or no SQP solve has run.

pub fn unimplemented_linear_solver(&self) -> Option<String>

The linear_solver value when the caller explicitly asked for a backend pounce does not implement; None when the request can be served (or was never made).

pounce ships two: FERAL (pure Rust, the effective default) and MA57 (HSL, behind the ma57 feature). The option’s valid-value list is a faithful port of upstream Ipopt’s — ma27, ma77, ma86, ma97, mumps, pardiso, pardisomkl, spral, wsmp, custom — so an ipopt.opt written for Ipopt parses here, and every one of those names used to fall through a _ => arm to FERAL. A run “using MUMPS” was a FERAL run; a benchmark comparing backends compared FERAL with itself (gh#483 follow-up).

The registered default is feral, which pounce implements, so no explicit-vs-default distinction is needed: whatever the option resolves to must be a backend that exists. (It is checked unconditionally on purpose — a future default naming something unimplemented should trip this, not slip past it.)

Explicit ma57 on a build that lacks the feature is not refused; that fallback is reported in the banner (“ma57 requested but not compiled”), so it is visible rather than silent, and failing a portable ipopt.opt over a build flag would cost more than it buys.

pub fn unimplemented_option_refusal(&self) -> Option<String>

The message for the first option the caller set that names a feature pounce does not implement, or None. Public so the CLI can refuse before routing — the convex dispatch never reaches optimize_tnlp. See crate::unimplemented_options.

pub fn unhonored_option_file_name(&self) -> Option<String>

option_file_name set on a surface that never resolves it.

The option reaches a file through exactly one path — Self::initialize_with_option_file, which the pounce CLI drives. A library caller (Python, the C interface, WASM) sets its options directly and calls no such thing, so on those surfaces the option names a whole configuration and applies none of it: gh#518’s failure mode, one surface over. It used to be caught by the blanket crate::unimplemented_options refusal, which no longer covers it now that the feature exists; this keeps the guard exactly where the feature still doesn’t.

Deliberately not fixed by having the library read an options file too: an implicit ./ipopt.opt lookup under Python or the GAMS C link would be a surprising action at a distance, and pounce.opt already means something else to GAMS.

pub fn unexploited_hint_warnings(&self) -> Vec<String>

Warnings for caching hints pounce does not exploit. These never block a solve: the answer is identical either way, so refusing would cost the caller more than the silence did.

pub fn run_derivative_test(&self, tnlp: &Rc<RefCell<dyn TNLP>>)

Run the derivative checker, if asked, against the user’s own TNLP — before presolve wraps it and before any scaling — so the report is about the derivatives the caller wrote, in the caller’s own indices.

Advisory, like upstream: a suspicious entry is reported and the solve continues. The report goes to stderr so it survives print_level=0 and leaves --json-output’s stdout clean.

pub fn unimplemented_linear_solver_message(value: &str) -> String

The message Self::unimplemented_linear_solver earns, shared by every frontend so they cannot drift apart.

pub fn algorithm_builder_from_options(&self) -> AlgorithmBuilder

Build an AlgorithmBuilder populated from the app’s OptionsList. Public so callers wiring the restoration factory can hand the inner IPM a builder that mirrors the outer’s mu_strategy/mu_oracle/line-search choices — matching upstream IpAlgBuilder::BuildRestoIpoptAlgorithm, which reads the same mu_strategy option with prefix `“resto.”

• prefix` and falls back to the outer setting.

Trait Implementations

impl Debug for IpoptApplication

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for IpoptApplication

fn default() -> IpoptApplication

Returns the “default value” for a type.