Crate pounce_cinterface

Expand description

POUNCE C ABI — port of Interfaces/IpStdCInterface.{h,cpp}.

Provides the CreateIpoptProblem / IpoptSolve / FreeIpoptProblem C entry points that existing PyIpopt / cyipopt / JuMP wrappers link against. Function names and signatures match upstream Ipopt 3.14.x exactly so consumers can swap libipopt.{dylib,so} for libpounce_cinterface without rebuilding.

Surface area (in IpStdCInterface.h order):

Lifecycle: CreateIpoptProblem, FreeIpoptProblem.
Options: AddIpoptStrOption, AddIpoptNumOption, AddIpoptIntOption, OpenIpoptOutputFile, SetIpoptProblemScaling.
Callbacks: SetIntermediateCallback.
Solve: IpoptSolve.
Introspection (only valid inside an intermediate callback): GetIpoptCurrentIterate, GetIpoptCurrentViolations.
Library info: GetIpoptVersion.

Pounce extensions for post-solve stats (not present in upstream Ipopt’s C API): GetIpoptIterCount, GetIpoptSolveTime, GetIpoptPrimalInf, GetIpoptDualInf, GetIpoptComplInf.

All entry points are extern "C" and #[no_mangle]. Pointers are raw and the caller is responsible for lifetime; the IpoptProblem handle is opaque (*mut c_void from C’s perspective). The Fortran 77 ABI shim lives in fortran.

Re-exports§

pub use bounds::*;
pub use errors::*;
pub use qp::*;

Modules§

bounds: In-place bound updates on an IpoptProblem handle (gh#1147, Stage 2), and the indexed pair records they need.
errors: One error namespace for the whole C API.
fortran: Fortran 77 ABI shim — port of Interfaces/IpStdFInterface.c.
qp: Matrix-form convex QP / conic entry (gh#1147 Stage 3): the PounceQp* handle, its builders, PounceQpSolve, the getters and the report writer.
solver: Session-style C ABI built on pounce_sensitivity::Solver.

Structs§

IpoptProblemInfo: Internal owned state behind the opaque IpoptProblem handle. #[repr(C)] is unnecessary because C only sees the pointer.
PounceComplementaritySolve: C mirror of one MpccSolveRecord, for pounce.h’s PounceComplementaritySolve. Extensible, like PounceComplementarityStats.
PounceComplementarityStats: C mirror of the driver’s MpccOutcome for pounce.h’s PounceComplementarityStats. Field order is the ABI (Pounce.jl mirrors structs field for field); tests/c_examples_build_and_run.rs holds every offset to the C compiler’s. Sentinels instead of discriminants: NaN for a real that was not measured (or is not finite, as the report’s null), -1 for a count or flag whose record is absent.
PounceLinearSolverStats: C mirror of pounce_linsol::summary::LinearSolverSummary, laid out for pounce.h’s PounceLinearSolverStats. Optional fields carry sentinels rather than a discriminant, because a plain struct of scalars is what a C or C++ caller can consume without an accessor per field: NaN for absent reals, -1 for absent counts.

Constants§

POUNCE_CC_B_VERDICT_ABSENT: b_verdict: the check did not run.
POUNCE_CC_B_VERDICT_B: b_verdict: B-stationary.
POUNCE_CC_B_VERDICT_NOT_B: b_verdict: a branch descends.
POUNCE_CC_B_VERDICT_NOT_CHECKED: b_verdict: not decided (the reason is POUNCE_CC_TEXT_B_REASON).
POUNCE_CC_CLASS_ABSENT: certificate_class: no certificate (the model could not be evaluated at the reported point).
POUNCE_CC_CLASS_NONE: certificate_class: not a stationary point of the model.
POUNCE_CC_CLASS_NOT_SEARCHED: certificate_class: not determined (the multiplier set is too large to search).
POUNCE_CC_CLASS_S: certificate_class: strongly stationary.
POUNCE_CC_CLASS_W: certificate_class: weakly stationary only.
POUNCE_CC_REPORTED_ANSWER: reported: a formulation answered.
POUNCE_CC_REPORTED_FEASIBLE_UNCERTIFIED: reported: a converged point with every product in tolerance, no stationarity certified.
POUNCE_CC_REPORTED_VERDICT: reported: no feasible point; the exact-product solve’s verdict.
POUNCE_CC_REPORTED_WEAK_FALLBACK: reported: a weakly stationary point, reported when none answered.
POUNCE_CC_TEXT_B_REASON: GetPounceComplementarityText: why the B-stationarity check was not decided.
POUNCE_CC_TEXT_POLISH_REASON: GetPounceComplementarityText: why the polish’s point was not taken.
POUNCE_CC_TEXT_SUMMARY: GetPounceComplementarityText: the driver’s one-line account.
POUNCE_COMPLEMENTS_PAIR_LOWER: x >= l only: the row’s lower bound was set to 0 (F >= 0) and a native one-sided pair declared.
POUNCE_COMPLEMENTS_PAIR_MIXED: x boxed, l < u both finite: a native mixed pair was declared; the row’s bounds are unchanged (free).
POUNCE_COMPLEMENTS_PAIR_UPPER: x <= u only: the row’s upper bound was set to 0 (F <= 0) and a native one-sided pair declared.
POUNCE_COMPLEMENTS_ROW_FIXED_NO_PAIR: x free: both row bounds were set to 0 (F = 0); no pair.
POUNCE_COMPLEMENTS_VAR_FIXED_NO_PAIR: x fixed (l == u): nothing changed, F stays free; no pair.

Functions§

AddIpoptIntOption^⚠: Port of AddIpoptIntOption.
AddIpoptNumOption^⚠: Port of AddIpoptNumOption.
AddIpoptStrOption^⚠: Port of IpStdCInterface.cpp:AddIpoptStrOption.
AddPounceComplementarityPair^⚠: Declare one complementarity pair: constraint row row with variable var, both in the problem’s index style (gh#1147). The pair is in POUNCE’s native shapes — one-sided, one-sided plus a plain bound, or mixed — exactly as Python’s Problem(complementarity=) and the .nl reader accept, and is checked at once by the same classifier the solve’s lowering runs (pounce_nlp::mpcc::validate_pairs), against the handle’s bounds — those given to CreateIpoptProblem, as AddPounceComplementsConstraint may have edited them — and the pairs already declared.
AddPounceComplementsConstraint^⚠: Declare MOI’s [F, x] ∈ Complements for constraint row row (F) and variable var (x), both in the problem’s index style (gh#1147).
ClearPounceComplementarityPairs^⚠: Drop every declared complementarity pair. Returns FALSE only on a NULL handle.
CreateIpoptProblem^⚠: Port of IpStdCInterface.cpp:CreateIpoptProblem. Returns NULL on invalid arguments (negative n/m, missing required callbacks, NULL bound pointers when the corresponding dimension is positive).
FreeIpoptProblem^⚠: Port of IpStdCInterface.cpp:FreeIpoptProblem.
GetIpoptComplInf^⚠: Final complementarity error for the most recent solve.
GetIpoptCurrentIterate^⚠: Port of IpStdCInterface.cpp:GetIpoptCurrentIterate (Ipopt 3.14+). Designed to be called from inside an intermediate callback to inspect x, the bound multipliers z_L/z_U, the constraint values g, and the constraint multipliers lambda at the current iterate.
GetIpoptCurrentViolations^⚠: Port of IpStdCInterface.cpp:GetIpoptCurrentViolations (Ipopt 3.14+). Same contract as GetIpoptCurrentIterate; returns FALSE when called outside an active intermediate callback.
GetIpoptDualInf^⚠: Final dual infeasibility (max gradient-of-Lagrangian norm) for the most recent solve.
GetIpoptIterCount^⚠: Number of IPM iterations in the most recent solve, or 0 if the problem has not been solved yet.
GetIpoptPrimalInf^⚠: Final primal infeasibility (max constraint violation) for the most recent solve.
GetIpoptSolveTime^⚠: Wall-clock solve time in seconds for the most recent solve, or 0.0 if the problem has not been solved yet.
GetIpoptVersion^⚠: Port of IpStdCInterface.cpp:GetIpoptVersion (Ipopt 3.14.18+). Writes the pounce crate’s major.minor.patch into the buffers. Any pointer may be NULL to skip that component.
GetPounceComplementarityPairCount^⚠: Number of declared complementarity pairs, or -1 on a NULL handle.
GetPounceComplementarityPairs^⚠: Copy the declared pairs, in declaration order and in the problem’s index style, into rows and vars (each sized by GetPounceComplementarityPairCount). Returns FALSE, writing nothing, on a NULL handle or a NULL array while pairs are declared; with no pairs it returns TRUE and the arrays may be NULL.
GetPounceComplementaritySolve^⚠: Lowered solve k (0-based, in the order the driver ran them, k < n_solves) of the most recent driver solve; the caller sets solve->struct_size = sizeof(PounceComplementaritySolve) first. Returns FALSE, leaving solve untouched, on a NULL argument, a short struct_size, a k out of range, and whenever GetPounceComplementarityStats would.
GetPounceComplementarityStats^⚠: What the complementarity driver did on the most recent IpoptSolve (gh#1147): the strategy, what was reported and by which formulation, the iteration totals, the stationarity certificate, the B-stationarity check and the polish — the solve report’s complementarity block as a struct of scalars. The caller sets stats->struct_size = sizeof(PounceComplementarityStats) first. Returns FALSE, leaving stats untouched, on a NULL argument, a struct_size smaller than this release’s size, before any solve, and when the most recent solve did not run the driver (no pairs were declared, or it was refused or failed before the driver returned). The record describes the most recent solve: clearing the pairs afterwards does not erase it, the next solve does.
GetPounceComplementarityText^⚠: One of the driver’s free-form texts for the most recent driver solve, with C’s snprintf contract: writes at most buflen - 1 bytes of it plus a NUL into buf and returns its full length in bytes, without the NUL — so buf = NULL, buflen = 0 sizes the buffer, and a return >= buflen means it was truncated. Returns -1, writing nothing, when there is no such text: a NULL handle, a which that names none, whenever GetPounceComplementarityStats would return FALSE, or a text this run does not have (POUNCE_CC_TEXT_POLISH_REASON unless the polish ran and was not taken; POUNCE_CC_TEXT_B_REASON unless the B-stationarity check ran and was not decided). A NULL buf or a buflen <= 0 writes nothing and still returns the length.
GetPounceFdHessianStats^⚠: Finite-difference Hessian census from the most recent solve. Any pointer may be NULL to skip that component.
GetPounceLinearSolverStats^⚠: Post-mortem of the KKT linear solver for the most recent solve.
GetPounceOptionType^⚠: Which AddIpopt*Option setter a keyword expects.
GetPounceRestorationStats^⚠: Restoration-phase activity in the most recent solve. Each output may be NULL to skip it; all yield zero before the first solve.
IpoptClearNonlinearVariables^⚠: Drop a subset declared by IpoptSetNonlinearVariables, restoring the default (every variable treated as nonlinear).
IpoptClearWarmStartWorkingSet^⚠: Drop any pending warm-start working set without solving. The next IpoptSolve will cold-start.
IpoptEnableIterHistory^⚠: Enable per-iteration history capture on the underlying IpoptApplication. Must be called before IpoptSolve for the trajectory to appear in the report written by IpoptWriteSolveReport. Off by default — capturing each iterate has a small per-iter cost the IPM core skips otherwise.
IpoptGetWorkingSet^⚠: Retrieve the working set produced by the most recent SQP solve (algorithm = active-set-sqp). Buffer sizes are n for bound_status_out and m for cons_status_out. Pass NULL for either to skip that side. Entry i is variable i / constraint row i in the problem’s own order (a variable fixed by x_L == x_U reads POUNCE_WS_FIXED_OR_EQ), the same indexing IpoptSetWarmStartWorkingSet takes.
IpoptSetNonlinearVariables^⚠: Declare which variables enter the problem nonlinearly (gh#624).
IpoptSetWarmStartWorkingSet^⚠: Supply a warm-start working set consumed by the next IpoptSolve on this problem. Pass NULL for either side to cold-start it. The caller-owned buffers are copied; reuse across calls is safe. Indexed like IpoptGetWorkingSet: entry i is variable i / constraint row i in the problem’s own order.
IpoptSolve^⚠: Port of IpStdCInterface.cpp:IpoptSolve. Returns the ApplicationReturnStatus integer.
IpoptSolveWarmStart^⚠: Convenience one-shot: equivalent to IpoptSetWarmStartWorkingSet + IpoptSolve + IpoptGetWorkingSet in sequence. The input/output working-set buffers are independent (so a caller can read back the new working set into the same array used as input). Pass NULL for any in/out buffer to skip that side.
IpoptWriteSolveReport^⚠: Write a pounce.solve-report/v1 JSON file capturing the most recent IpoptSolve result. path is a NUL-terminated UTF-8 filesystem path. detail is one of "summary" or "full" (NUL-terminated); pass NULL for the default ("summary").
OpenIpoptOutputFile^⚠: Port of IpStdCInterface.cpp:OpenIpoptOutputFile. Opens file_name at print_level and attaches a journalist FileJournal so all solver output is mirrored to disk. Equivalent to setting output_file + file_print_level options and triggering IpoptApplication::Initialize.
SetIntermediateCallback^⚠: Port of SetIntermediateCallback.
SetIpoptProblemScaling^⚠: Port of IpStdCInterface.cpp:SetIpoptProblemScaling. Stores user-provided NLP scaling on the problem; the scaling is forwarded to the solver via TNLP::get_scaling_parameters when the option nlp_scaling_method=user-scaling is set. Passing NULL for x_scaling / g_scaling disables scaling on that axis.
SetPounceComplementarityPairs^⚠: Replace the declared pairs with n_pairs pairs (rows[k], vars[k]), indices in the problem’s index style. All or nothing: the new set is validated as a whole (on its own, not against the pairs it replaces) and stored only if every pair passes; otherwise the previous set stays. n_pairs == 0 clears the set (the arrays may then be NULL).

Type Aliases§

Bool: Mirrors C Bool, which pounce.h — like Ipopt 3.14’s IpStdCInterface.h — declares as the C99 bool. That is one byte, so this is u8 and not c_int.
Eval_F_CB
Eval_G_CB
Eval_Grad_F_CB
Eval_H_CB
Eval_Jac_G_CB
Index: Mirrors C Index.
Intermediate_CB
IpoptBoundStatus: C-ABI encoding of pounce_qp::BoundStatus (§7.2 of the active-set-SQP design note). Stable values: 0 = Inactive, 1 = AtLower, 2 = AtUpper, 3 = Fixed.
IpoptConsStatus: C-ABI encoding of pounce_qp::ConsStatus (§7.2). Stable values: 0 = Inactive, 1 = AtLower, 2 = AtUpper, 3 = Equality.
IpoptProblem
Number: Mirrors C Number typedef in IpStdCInterface.h.