Struct IpoptApplication 

pub struct IpoptApplication { /* private fields */ }

Implementations

impl IpoptApplication

pub fn new() -> Self

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: LinearBackendFactory)

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: RestorationFactory)

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: RestorationFactoryProvider, )

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: ConvergedCallback)

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 answer_restored_from_floor(&self) -> bool

Was the reported answer replayed from an earlier attempt’s floor, after a later attempt lost?

A caller that captures the solution in Self::set_on_converged must consult this. That callback fires once per attempt, and a losing retry that converged has already run it, so the capture belongs to the discarded point while everything else — status, objective, statistics — has been floored back. When this is true, take x and the multipliers from the last finalize_solution payload instead; that one is always the answer being reported, because the floor restores it by calling finalize_solution.

The payload is in the model’s own units and in the reduced presolve space: CountingTnlp-style consumers sit inside the gh#486 scaling wrapper (so x /= d, z *= d have already been applied) and outside the presolve one (so the row/column lift has not). A caller swapping it in must therefore skip its own scaling correction and keep its own lift; getting that backwards squares the factor, which is a silent wrong answer of exactly the shape this flag exists to remove.

Not consulted, and known not to be: the three other Self::set_on_converged consumers — pounce-sensitivity/src/{solver,convenience}.rs and pounce-cli/src/minima/mod.rs — read the converged KKT state and the factorization, which the finalize_solution payload does not carry and which cannot be rewound. After any floor replay their result describes the attempt that lost. Pre-existing, unfixed, and annotated at each site.

false on every solve that never spent a second attempt, which is almost all of them, so the ordinary path is unaffected.

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 least_square_init_report(&self) -> Option<LeastSquareInitReport>

Diagnostics from the safeguarded least_square_init_primal initializer step of the last solve (gh#605): the nonlinear violation before and after, the accepted step norm, how many backtracking trials were rejected, and why it stopped. None when least_square_init_primal was off or the model had no constraints.

pub fn statistics(&self) -> SolveStatistics

pub fn warm_start_diagnostics(&self) -> Option<WarmStartDiagnostics>

What the warm-start initializer made of the iterate the caller supplied to the most recent solve (gh#606): the residuals it measured, whether each multiplier block was accepted, reconstructed or discarded, and the barrier parameter it settled on.

None when the last solve was a cold start (warm_start_init_point=no), or when no solve has run. Reset at the top of every solve, like Self::timing_stats.

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<Number>>

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 optimize_tnlp_with_derivative_test_tnlp( &mut self, tnlp: Rc<RefCell<dyn TNLP>>, derivative_test_tnlp: Option<Rc<RefCell<dyn TNLP>>>, ) -> ApplicationReturnStatus

Solve through tnlp, optionally overriding the derivative-test target. None tests the scaled and conditioned TNLP.

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 crossover_report(&self) -> Option<&CrossoverReport>

What the crossover phase did on the most recent solve (gh#612).

None means crossover never ran — either crossover=no (the default) or the solve did not converge. A Some whose CrossoverReport::accepted is false means it ran and declined; the two are different facts about a solve and consumers that reason about active-set certainty (sensitivity’s AMBIGUOUS class, a downstream var_status) need to tell them apart.

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.

A run configuring nothing but backends pounce does not ship is refused here too, after the per-option table has had its say — see crate::unimplemented_options::backend_only_refusal. It is folded in rather than given its own accessor so that every surface already refusing on this method refuses on it as well; the CLI is not the only frontend, and a condition worth failing on is not worth failing on only from the CLI.

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

The message for the first string option the caller set to a registered value pounce does not implement, or None.

Separate from Self::unimplemented_option_refusal because the option itself is read and its other values work — it is one mode that is missing, not the feature. See crate::unimplemented_options::UNIMPLEMENTED_VALUES.

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 set_convex_routing_available(&mut self, available: bool)

Declare that this caller can route a model to the convex LP/QP / SOCP engines, so the qp_* knobs they read configure something.

The pounce CLI calls this: it owns the .nl structure extraction that classifies a model, which is the whole of what solver_selection’s convex values need. No library frontend can (see Self::unsupported_library_solver_selection), so the default is false and Self::unhonored_convex_option refuses the knobs there.

Declaring it also covers the CLI’s fallback: a convex attempt that returns no verified point hands the model to Self::optimize_tnlp, and the qp_* values it was given configured that attempt for real. Refusing them at the handoff would fail a run that used them.

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

The convex LP/QP knobs are registered core-side so every frontend parses them — but only the CLI can reach the engines that read them. On any other entry point the option names a whole configuration and applies none of it; this is the message that says so, in place of the silence.

gh#604. Same shape and same default gate as Self::unhonored_option_file_name: an explicitly-set default asks for nothing and must keep working, so only a value that differs is refused.

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 convex_unexploited_hint_warnings(&self) -> Vec<String>

Warnings for the constant-derivative hints when the solve routes to pounce-convex instead of here. Call site is the convex dispatch in the CLI, next to the other guards that live there for the same reason: that dispatch never reaches Self::optimize_tnlp, so install_constant_derivative_hints never runs and the hints are unread. On the NLP route they are honoured, so this must not be called there.

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

Warnings for knobs of a linear-solver backend pounce does not ship (ma97_*, pardiso_*, …), one line per backend family.

Warnings and not refusals: an ipopt.opt carrying settings for several backends so that one file runs everywhere is exactly what the registry exists to accept, and refusing it would fail a run over knobs it never touches. See the “Backend knobs warn, they do not refuse” section of crate::unimplemented_options. gh#551.

pub fn take_unimplemented_backend_warnings(&mut self) -> Vec<String>

The same warnings, but at most once per application: the second caller gets nothing.

Two sites emit them — the CLI, before routing, because a convex model never reaches Self::optimize_tnlp, and optimize_tnlp itself, for every frontend that is not the CLI. A CLI run passes through both, and printing the identical paragraph twice is how a warning teaches its reader to skip warnings.

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

Run the derivative checker, if requested, against tnlp.

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

Formats the value using the given formatter.

impl Default for IpoptApplication

fn default() -> Self

Returns the “default value” for a type.