C API
libpounce_cinterface is POUNCE’s C ABI. It is a drop-in replacement for
Ipopt 3.14’s IpStdCInterface.h: every upstream function name, argument list
and return code is kept, so a program (or a wrapper such as cyipopt, a GAMS or
AMPL driver, or the CasADi plugin) that links against libipopt can link
against libpounce_cinterface instead without source changes. POUNCE’s own
extensions carry a Pounce or Ipopt… name that upstream does not have.
The header, crates/pounce-cinterface/include/pounce.h, is the reference:
each prototype is documented there. This page is the map. Every exported
symbol is named on it, and a test (tests/export_surface.rs in the crate)
fails if one is not, or if the header and the library disagree on any
function’s name, arity or argument widths.
The IpoptProblem handle reaches the NLP path: the interior-point method and,
with algorithm=active-set-sqp, the active-set SQP loop. It does not route to
the CLI’s convex QP/QCQP engines. A matrix-form convex QP or conic program goes
through the separate PounceQp handle instead
(below).
Build and link
cargo build --release -p pounce-cinterface
cc app.c -I crates/pounce-cinterface/include \
-L target/release -lpounce_cinterface \
-Wl,-rpath,target/release -o app
make install copies libpounce_cinterface.{so,dylib} into $PREFIX/lib
(default $HOME/.local/lib). The header needs IpoptReturnCodes.h from the
same directory. Scalars match upstream: ipnumber is double, ipindex is
int, and Bool is C99 bool (one byte).
Lifecycle and options
CreateIpoptProblembuilds a handle from the dimensions, the bounds, the Jacobian and Hessian nonzero counts, the index style (0 = C, 1 = Fortran) and the five evaluation callbacks. It returnsNULLon an invalid definition.FreeIpoptProblemreleases it (NULLis a no-op).AddIpoptStrOption,AddIpoptNumOption,AddIpoptIntOptionset an option and returnFALSEfor an unknown keyword or a value of the wrong type.GetPounceOptionTypesays which of the three a keyword expects (it works with aNULLhandle too), for callers that receive options as untyped text. The full list is in Solver Options.OpenIpoptOutputFileattaches a log file at its own print level.SetIpoptProblemScalingsupplies objective, variable and constraint scaling factors; they take effect withnlp_scaling_method=user-scaling(see NLP and Linear-System Scaling).SetIntermediateCallbackinstalls the per-iteration callback. Returningfalsefrom it stops the solve withUser_Requested_Stop.IpoptSetNonlinearVariables/IpoptClearNonlinearVariablesdeclare which variables enter nonlinearly, which restricts the limited-memory Hessian approximation to them. Indices are in the problem’s index style; a bad declaration is refused whole.AddPounceComplementarityPair,SetPounceComplementarityPairs,ClearPounceComplementarityPairs,GetPounceComplementarityPairCount,GetPounceComplementarityPairsandAddPounceComplementsConstraintdeclare complementarity pairs; see Complementarity.SetPounceBounds/GetPounceBoundschange and read bounds on an existing handle; see Updating bounds.SetPounceIntegerMetaData,SetPounceNumericMetaData,SetPounceStringMetaDataandClearPounceMetaDataattach metadata to the variables and constraints; see Custom linear solver and metadata.
Solving
IpoptSolveruns a solve from the starting point inxand writes the solution, constraint values, objective and multipliers into the caller’s buffers (any output butxmay beNULL). It returns anApplicationReturnStatusfromIpoptReturnCodes.h.- Inside the intermediate callback,
GetIpoptCurrentIteratereads the currentx, bound multipliers,gand constraint multipliers, andGetIpoptCurrentViolationsreads the bound violations, complementarity and Lagrangian gradient, in scaled or unscaled space, as in Ipopt 3.14. Both returnFALSEoutside the callback or when the dimensions passed do not match the problem’s. - With complementarity pairs declared,
IpoptSolveruns the complementarity driver instead; see Complementarity.
Post-solve statistics
All of these read the most recent solve on the handle and answer “nothing”
(zero, -1 or FALSE, as documented in the header) before the first one.
GetIpoptIterCount,GetIpoptSolveTime,GetIpoptPrimalInf,GetIpoptDualInf,GetIpoptComplInf: iteration count, wall time, and the final primal infeasibility, dual infeasibility and complementarity error.GetPounceRestorationStats: restoration calls, inner and outer iterations, and wall time.GetPounceFdHessianStats: the finite-difference Hessian census (pattern used, nonzeros, colour groups);pattern_used = -1when the solve did not usehessian_approximation=finite-difference.GetPounceLinearSolverStatsfills aPounceLinearSolverStatsstruct: the KKT backend that ran, factorization counts, pattern reuse, fill, pivot range and final inertia, withNaN/-1for anything not reported.GetIpoptVersionwrites the library’s major, minor and patch version.
Working-set warm start
On the active-set SQP path, the converged working set (which bounds and constraints were active) can be read back and fed to the next solve of a nearby problem; see the active-set SQP warm-start design note.
IpoptGetWorkingSetreads the last solve’s working set as one status code per variable and per constraint (POUNCE_WS_*in the header).IpoptSetWarmStartWorkingSetstages one for the next solve (validated before it is stored);IpoptClearWarmStartWorkingSetdrops it.IpoptSolveWarmStartis set + solve + get in one call.- None of this combines with complementarity pairs: a staged working set
plus declared pairs makes
IpoptSolve(andIpoptSolveWarmStart) returnInvalid_Problem_Definitionwithout solving, andIpoptGetWorkingSetreturnsFALSEafter a solve with pairs.
Updating bounds
int SetPounceBounds(IpoptProblem, ipindex nx, const ipindex *x_idx,
const ipnumber *x_L, const ipnumber *x_U,
ipindex ng, const ipindex *g_idx,
const ipnumber *g_L, const ipnumber *g_U,
unsigned int flags, ipindex *bad_index);
int GetPounceBounds(IpoptProblem, ipindex nx, const ipindex *x_idx,
ipnumber *x_L, ipnumber *x_U,
ipindex ng, const ipindex *g_idx,
ipnumber *g_L, ipnumber *g_U,
int view, unsigned int flags, ipindex *bad_index);
SetPounceBounds changes bounds on a handle without rebuilding it, so
everything else on the handle stays: options, scaling, the
nonlinear-variables hint, declared pairs and Complements declarations. It
saves that bookkeeping, not solver work: each IpoptSolve builds its solver
afresh either way. Warm starts stay explicit; pass the previous solution and
multipliers to IpoptSolve with warm_start_init_point=yes.
The update is sparse: nx variable entries (x_idx[k], x_L[k], x_U[k])
and ng row entries, indices in the problem’s index style, at a cost that
depends on the entries and the pairs they touch, not on n, m or the
number of pairs. A NULL index array with the full count (n or m) is
dense; a NULL value array leaves that side of the named entries as it was.
flags must be 0 on both functions. No bit is defined yet: it exists so a
later relaxation of one of the refusals below can be asked for explicitly,
instead of changing what an existing call does. A bit the library does not
know is refused with POUNCE_ERR_FLAGS (-6), so an older library never ignores
one silently.
It is all or nothing: the batch is checked against the bounds it would install, and a refusal changes nothing. In order:
| check | code |
|---|---|
| NULL handle | POUNCE_ERR_NULL (-1) |
a bit in flags this library does not define | _ERR_FLAGS (-6) |
a negative count, a setter count above n (or m), or a NULL index array with a count other than 0 or the full size | _ERR_COUNT (-2) |
| per entry, variables first: index out of range | _ERR_OUT_OF_RANGE (-3) |
| the same index twice on one side | _ERR_DUPLICATE (-4) |
| a NaN bound | _ERR_NAN (-5) |
a Complements variable would move to another row of the MOI table | _ERR_COMPLEMENTS_CLASS (-41) |
a Complements row given a finite bound | _ERR_ROW_NOT_FREE (-23) |
| a declared pair would pair a different variable bound or row side | _ERR_PAIR_CHANGED (-40) |
| a staged SQP working set would claim something false | _ERR_WORKING_SET (-42) |
| inconsistent handle, internal error | _ERR_INTERNAL (-8) |
The range, duplicate and NaN checks run over every entry before any of the
rest. The Complements and pair checks then run entry by entry in batch
order (a variable’s Complements check before its pair’s), so the first
offending entry is the one reported; the working-set check comes last.
bad_index receives the position of the refused entry in the batch,
0..nx-1 for variables and nx..nx+ng-1 for rows, or -1. A pair is
checked once, against everything the batch does to it, so a
_PAIR_CHANGED refusal names the batch’s first entry touching the pair
(variables come first), which need not be the entry that changed it.
Declared pairs. A pair’s meaning is read off bounds, so an update may
move the paired bounds’ values, and the variable may gain or lose the bound
that is not in the pair, but the pair must keep pairing the same variable
bound (lower or upper) with the same row side (or stay mixed). The rule is
on what is paired, not on the shape’s name: x >= 0 ⟂ g <= 0 is a legal
one-sided pair, and if x gains a finite upper bound the bounds classify as
one-sided-plus-bound pairing g <= 0 with x <= x_U — every state valid, a
different complementarity condition. That update is refused, while the same
upper bound on x >= 0 ⟂ g >= 0 is accepted.
Complements declarations. The handle keeps two views of the bounds.
The user view is what CreateIpoptProblem and SetPounceBounds wrote;
the effective view, which the solve and every other function see, adds
the row edits AddPounceComplementsConstraint made. SetPounceBounds
writes the user view: a Complements row must stay free there (the
F >= 0 the helper wrote is not an input), and a Complements variable
must keep its row of the table (lower-only, upper-only, boxed, fixed, free),
since a change of row can create or remove a pair. To change either, build a
new problem. GetPounceBounds reads POUNCE_BOUNDS_VIEW_USER (0) or
POUNCE_BOUNDS_VIEW_EFFECTIVE (1), takes the same index arguments
(duplicates allowed), skips a NULL output array and writes nothing on a
refusal (POUNCE_ERR_ARGUMENT (-7) for an unknown view).
Crossed bounds (l > u) are not refused here; the solve reports them, as for
CreateIpoptProblem. The getters for the most recent solve stay readable
after an update and describe that solve. A session (IpoptCreateSolver)
owns its problem, so it takes no updates.
Custom linear solver and metadata
pounce’s KKT systems can be factored by a solver you supply as a shared library, with no fork and no rebuild (gh#1175). The library exports one function,
const PounceLinearSolver *pounce_linear_solver(void);
returning a table of callbacks — create, destroy, initialize_structure,
factor, solve, and the optional set_layout, set_metadata and
increase_quality — declared and documented in pounce.h. Select it with
options, from any frontend (C, an options file, the CLI, Python, the CasADi
plugin):
linear_solver custom
custom_linear_solver_lib /path/to/libmysolver.so
custom_linear_solver_options "anything; passed verbatim to create()"
The matrix arrives as 1-based triplets of one triangle (repeated pairs are
summed) on a pattern fixed at initialize_structure. When
provides_inertia is set, factor reports the number of negative
eigenvalues and pounce runs its usual inertia correction on it. A
linear_solver=custom whose library cannot be loaded refuses the solve
with Invalid_Option; it never falls back to another solver. The custom
solver serves the interior point, its restoration phase and the active-set
SQP’s QP subproblems; crossover keeps using FERAL.
Block labels. Metadata set with
int SetPounceIntegerMetaData(IpoptProblem, int target, const char *key,
ipindex len, const ipindex *values,
unsigned int flags);
(target is POUNCE_META_VARIABLES, len == n, or
POUNCE_META_CONSTRAINTS, len == m; flags must be 0) follows each
variable and constraint through presolve and fixed-variable removal. On the
interior-point systems, whose rows are ordered
[x | slacks | equality duals | inequality duals], the solver’s
set_layout receives the four block sizes and set_metadata receives each
integer key mapped to that order: an x row takes its variable’s value, a
slack and both dual rows their constraint’s, and a key set on one side only
reads -1 on the other’s rows. SetPounceNumericMetaData and
SetPounceStringMetaData set real and string keys (the string key
idx_names names rows in diagnostics); ClearPounceMetaData drops them
all. Refusals follow the shared check order and return POUNCE_ERR_*.
examples/custom_linear_solver/dense_solver.c is a complete, small
reference solver (dense, with exact inertia) that also records what it was
handed; the crate’s custom_linear_solver.rs test drives it.
An augmented-system solver, from Rust
linear_solver=custom hands your library the assembled matrix: Ipopt’s
sparse-linear-solver level. A structured solver that wants the pieces of the
system instead — W, D_x, δ_x, J_c, J_d, D_c, D_d, δ_c — and
owns regularization, inertia repair and refinement of the system it builds
from them, sits one level up, at Ipopt’s custom AugSystemSolver. In POUNCE
that level is the Rust trait
pounce_algorithm::linear_solver_provider::LinearSolverProvider:
use pounce_algorithm::linear_solver_provider::*;
struct Structured;
impl LinearSolverProvider for Structured {
fn name(&self) -> &'static str { "structured" } // linear_solver=structured
// Typed, bounded options: validated, documented and type-dispatched
// (C API, CasADi) like the built-in ones.
fn register_options(&self, r: &RegisteredOptions) -> Result<(), SolverException> {
r.set_registering_category("Structured Linear Solver");
r.add_lower_bounded_number_option("structured_penalty", "Primal penalty per block.",
0.0, false, 0.0, "")?;
Ok(())
}
fn aug_system_solver(&self, ctx: &AugSolverContext<'_>)
-> Result<Box<dyn AugSystemSolver>, String> {
let (penalty, _) = ctx.options.get_numeric_value("structured_penalty", ctx.prefix)
.map_err(|e| e.to_string())?;
// ctx.metadata: the KKT layout and the integer var/con metadata in
// KKT row order, filled before the first factorization.
// ctx.standard(ctx.default_backend()): POUNCE's own StdAugSystemSolver,
// for a provider that wraps it.
Ok(Box::new(MyAugSystemSolver::new(penalty, ctx.metadata.clone())))
}
}
static STRUCTURED: Structured = Structured;
fn main() {
// Before the first IpoptApplication is created.
register_linear_solver_provider(&STRUCTURED).unwrap();
// ... every frontend linked into this binary now accepts linear_solver=structured
}
The builder calls aug_system_solver everywhere it would otherwise build a
StdAugSystemSolver: on the main path; for both inner solvers of the
limited-memory low-rank wrapper, which it puts around the provider’s solver as
it does around the standard one; and in restoration, inside
AugRestoSystemSolver, where ctx.prefix is "resto.". The FERAL-only Schur
and block-parallel paths stand down. The active-set SQP’s QP subproblem is not
an augmented system and keeps the default backend. Registration is refused
for a name linear_solver already has, or for options that collide with
registered ones. An Err from the provider’s validate refuses the solve
with Invalid_Option. An Err from aug_system_solver fails it at the
first factorization. Neither falls back to FERAL.
From C and CasADi. Registration is a Rust call, but the C library needs
no change to carry it. Build your own libpounce_cinterface that re-exports
the stock one and registers your provider when the library loads, then link
or load it in place of the stock library (the CasADi plugin loads it by that
name):
[lib]
name = "pounce_cinterface"
crate-type = ["cdylib"]
[dependencies]
pounce-cinterface = "…" # the version you build against
pounce-algorithm = "…"
structured = { path = "…" } # your provider
#![allow(unused)]
fn main() {
pub use pounce_cinterface::*; // every C entry point, unchanged
extern "C" fn register() {
pounce_algorithm::linear_solver_provider::register_linear_solver_provider(
&structured::STRUCTURED,
)
.expect("register structured");
}
// Runs when the library is loaded (Linux/ELF; on macOS use the section
// "__DATA,__mod_init_func", or the `ctor` crate on either).
#[used]
#[unsafe(link_section = ".init_array")]
static REGISTER: extern "C" fn() = register;
}
AddIpoptStrOption(prob, "linear_solver", "structured") then selects it,
and your typed options are set with AddIpoptNumOption and the like, or
from a CasADi options dict.
Owning refinement. A solver that regularizes or repairs the system it
factors returns a step that leaves a residual on the rows it changed.
PdFullSpaceSolver’s iterative refinement against the unmodified system
would undo that change, and when the ratio stalls it would escalate quality
and treat the system as singular. A solver whose
AugSystemSolver::owns_refinement() returns true is solved once per
request and trusted: there is no residual refinement, and an “improve this
solution” request becomes a fresh solve. The low-rank and restoration
wrappers pass the answer through. It defaults to false.
Sessions
IpoptCreateSolver consumes a problem handle (and sets the caller’s copy to
NULL) and returns an IpoptSolver that keeps the converged KKT factor
between operations. IpoptSolverSolve solves; IpoptSolverGetKktDim,
IpoptSolverKktSolve (natural units) and IpoptSolverKktSolveScaled (the
solver’s internal scaling) back-solve against the factor;
IpoptSolverParametricStep and IpoptSolverReducedHessian answer
first-order sensitivity questions; IpoptFreeSolver releases it. A session
solve does not run the second-opinion ladder that IpoptSolve does. The
walkthrough is Sessions. A problem with complementarity pairs
is refused: IpoptCreateSolver returns NULL and leaves the handle with
the caller, because the session would hold the lowered model’s factor
(see Complementarity).
Complementarity
The C API solves models with declared complementarity pairs through the
same driver as the CLI and Python, described in Complementarity
Constraints. examples/complementarity.c in the crate
exercises every function in this section; make c-api-examples builds and
runs it.
Declaring pairs
A pair (row, var) pairs constraint row g_row with variable x_var, each
measured from its finite bound, in the three native shapes Python’s
Problem(complementarity=) and the .nl reader accept (one-sided,
one-sided plus a plain bound, mixed; the table is under Declaring
pairs):
int AddPounceComplementarityPair(IpoptProblem, ipindex row, ipindex var);
int SetPounceComplementarityPairs(IpoptProblem, ipindex n_pairs,
const ipindex *rows, const ipindex *vars,
unsigned int flags /* 0 */,
ipindex *bad_index /* may be NULL */);
Bool ClearPounceComplementarityPairs(IpoptProblem);
ipindex GetPounceComplementarityPairCount(IpoptProblem); /* -1 on NULL */
Bool GetPounceComplementarityPairs(IpoptProblem, ipindex *rows, ipindex *vars);
Add appends; Set replaces the set with a batch, all or nothing, and
writes the batch position of the first refused pair to bad_index (-1 on
success); n_pairs = 0 clears. flags must be 0: as for
SetPounceBounds, no bit is defined yet, and one this library does not know
is refused with POUNCE_ERR_FLAGS (-6, checked after the handle and before
the count), so a later relaxation is opt-in and an older library never
ignores it. Indices are in the problem’s index style,
and are read back in it. Each declaration is checked at once, against the
handle’s bounds and the pairs already declared, by the classifier the
solve’s lowering runs, so a pair Python or the .nl reader would refuse is
refused here, and a refused call changes nothing. The codes below are in
check order. Set runs the range and already-paired checks over the whole
batch before any shape check, so a batch with a bad index at pair 3 and a
bad shape at pair 0 reports POUNCE_ERR_OUT_OF_RANGE at 3:
| code | value | meaning |
|---|---|---|
POUNCE_OK | 0 | declared |
POUNCE_ERR_NULL | -1 | NULL handle |
POUNCE_ERR_FLAGS | -6 | Set: flags has a bit this library does not define |
POUNCE_ERR_COUNT | -2 | Set: n_pairs < 0, or n_pairs > min(n, m) (which must repeat a variable or a row) |
POUNCE_ERR_NULL | -1 | Set: a NULL array with n_pairs > 0 |
POUNCE_ERR_OUT_OF_RANGE | -3 | row or variable outside the problem (in its index style) |
POUNCE_ERR_VAR_ALREADY_PAIRED | -20 | the variable is already in a pair, or twice in the batch |
POUNCE_ERR_ROW_ALREADY_PAIRED | -21 | the row is already in a pair, or twice in the batch |
POUNCE_ERR_SHAPE | -22 | not a native shape (boxed or equality row, both sides free, a fixed variable with a free row, …) |
POUNCE_ERR_INTERNAL | -8 | an internal error caught at the boundary; not a diagnosis of the input |
Pairs persist across solves until cleared or replaced.
MOI [F, x] ∈ Complements
int AddPounceComplementsConstraint(IpoptProblem, ipindex row, ipindex var);
MathOptInterface reads the sign of F off x’s bounds; the native pairs
read both signs off bounds. AddPounceComplementsConstraint takes MOI’s
semantics on a row with no finite bound and transcribes them by writing
into the handle’s copy of that row’s bounds, then declaring the native
pair:
x bounds | edit on the handle | pair declared | returns |
|---|---|---|---|
l < u, both finite | none | native mixed | POUNCE_COMPLEMENTS_PAIR_MIXED (0) |
x >= l only | g_L[row] = 0 (F >= 0) | one-sided | POUNCE_COMPLEMENTS_PAIR_LOWER (1) |
x <= u only | g_U[row] = 0 (F <= 0) | one-sided | POUNCE_COMPLEMENTS_PAIR_UPPER (2) |
| free | g_L[row] = g_U[row] = 0 (F = 0) | none | POUNCE_COMPLEMENTS_ROW_FIXED_NO_PAIR (3) |
l == u | none (F free) | none | POUNCE_COMPLEMENTS_VAR_FIXED_NO_PAIR (4) |
A negative return is a refusal that changed nothing, checked in this order:
POUNCE_ERR_NULL (-1); _ERR_OUT_OF_RANGE (-3); _ERR_VAR_ALREADY_PAIRED
(-20) and _ERR_ROW_ALREADY_PAIRED (-21), for a variable or row in a
declared pair or in any earlier accepted call of this function, pair or
not (so a row this function already wrote reads as already paired);
_ERR_ROW_NOT_FREE (-23), for any other row with a finite bound,
including one whose bound agrees with the sign MOI implies (g_L = 0
with x >= 0: that is a native declaration, use
AddPounceComplementarityPair); _ERR_VAR_BOUNDS (-24), NaN or crossed
variable bounds; and _ERR_INTERNAL (-8). The edits and that ledger are
permanent on the handle: ClearPounceComplementarityPairs and
SetPounceComplementarityPairs drop pairs, not edits, and do not free a row
or variable for another call. So after a clear the handle solves a plain
NLP with the edited row bounds, which is neither the original model nor the
complementarity one; the only way back to the original bounds is to free the
problem and create it again. GetPounceComplementarityPairs lists the
pairs declared here like any other.
Solving
With pairs declared, IpoptSolve runs the complementarity driver instead
of one solve and the second-opinion ladder, honours the
complementarity_strategy, complementarity_continuation and
complementarity_lift options, and writes the reported point, its g,
objective and multipliers into the caller’s buffers (the multipliers are the declared
model’s; see Multipliers). GetIpoptIterCount
and the other post-solve accessors describe that reported solve, not the
whole run. With no pairs declared nothing changes. Three things refuse
pairs, because each is defined over the caller’s rows while the driver
solves a lowered model with more (a product row per pair, possibly lifted
variables):
IpoptCreateSolverreturnsNULLand does not consume the handle.IpoptSolve(andIpoptSolveWarmStart) with a staged SQP working set returnsInvalid_Problem_Definitionbefore any callback runs, and consumes neither the working set nor the pairs;IpoptSolveWarmStartthen writes nothing to its output working-set buffers.IpoptGetWorkingSetreturnsFALSE, writing nothing, while pairs are declared, after a driver solve, and after anyIpoptSolvethat did not complete, so a set left over from an earlier SQP solve on the handle is never read as the current one.- The intermediate callback fires from every lowered solve (each restarts
at iteration 0) and returning
FALSEends the run withUser_Requested_Stop, butGetIpoptCurrentIterateandGetIpoptCurrentViolationsreturnFALSEthroughout, for every request shape. This is per solve, not per thread: a pair-freeIpoptSolveof another problem started from inside that callback has working inspectors for its own duration.
SetIpoptProblemScaling applies to the caller’s rows and variables in
every lowered solve, and a nonlinear-variable declaration is forwarded with
the product variables added.
What the driver did
Bool GetPounceComplementarityStats(IpoptProblem, PounceComplementarityStats *);
Bool GetPounceComplementaritySolve(IpoptProblem, ipindex k,
PounceComplementaritySolve *);
ipindex GetPounceComplementarityText(IpoptProblem, int which,
char *buf, ipindex buflen);
Both structs are extensible: set
struct_size = sizeof before each call, or the getter returns FALSE.
GetPounceComplementarityStats fills a PounceComplementarityStats: the
strategy, what was reported (POUNCE_CC_REPORTED_ANSWER, _WEAK_FALLBACK,
_FEASIBLE_UNCERTIFIED, _VERDICT) and by which formulation, the number of
lowered solves and their total iterations, the certificate of the reported
point (POUNCE_CC_CLASS_S, _W, _NONE, _NOT_SEARCHED, or _ABSENT when
the model could not be evaluated there), the B-stationarity check
(POUNCE_CC_B_VERDICT_*), escapes, lifted pairs, the natural residual and
the polish. GetPounceComplementaritySolve reads lowered solve k
(0 <= k < n_solves: stage, tau, status, iterations, violation, seconds)
into a PounceComplementaritySolve. GetPounceComplementarityText copies
the summary line (POUNCE_CC_TEXT_SUMMARY), the polish’s reason for not
taking its point (POUNCE_CC_TEXT_POLISH_REASON) or the B-check’s reason
for not deciding (POUNCE_CC_TEXT_B_REASON) with snprintf’s contract:
buf = NULL, buflen = 0 returns the length without the NUL.
These are the fields of the solve report’s complementarity block, under
the same encodings. Where the block has null, a real reads NaN; where a
whole record is absent (no certificate, no B-check), its counts and 0/1
flags read -1; polish_taken reads 0 when the polish did not run.
The getters describe the most recent solve. They answer FALSE (-1
for the text) before any solve, after a solve without pairs, and after a
solve that was refused (a refused solve discards the previous record).
Clearing the pairs does not erase the record of the solve that used
them; the next solve replaces it.
Matching the CLI
A frontend that builds callbacks for a model it also has as a .nl file
(or compares against pounce model.nl) should expect the same answer
but, in two cases, a different path through the lowered solves. Both
were measured over the declared-pair fixtures
(crates/pounce-cli/tests/cinterface_mpcc_parity.rs); with them handled the
C API reproduces the CLI bit for bit, report block included.
- Where a row’s constant lives. AMPL writes a row’s constant into its
bound: the
.nlreader hands the solver2 y1 - x >= 1, where a hand-written model says2 y1 - 1 - x >= 0. The feasible set is the same, butgand the products the driver forms from it differ in the last bits, and on a degenerate model that moves the iteration count (qpec_small: 191 iterations in all from the.nlform, 139 from the hand-written one, same answer). To reproduce the CLI, pass the rows as the.nlfile writes them. Neither form is more correct. - The nonlinear variables, under
hessian_approximation=limited-memory. The.nlheader says which variables enter nonlinearly and the CLI restricts the L-BFGS approximation to them; a callback model is all nonlinear unless told. Declare the same list withIpoptSetNonlinearVariables(the product variables the lowering adds are included automatically). The exact Hessian ignores it.
A maximize objective is a third, cosmetic, difference: the .nl reader
negates it, so the CLI reports f* where a callback that minimizes -f
reports -f*.
Solve report
IpoptEnableIterHistory (before the solve) turns on per-iteration capture,
and IpoptWriteSolveReport writes the last solve as a
pounce.solve-report/v1 JSON file, at "summary" or "full" detail — the
same schema as the CLI’s --json-output (see
JSON Solve Report). It returns FALSE for a NULL
handle, no prior solve, an unknown detail level or an I/O error.
After a solve that ran the complementarity driver, the report carries the
complementarity block at either detail level, written by the conversion
the CLI and Python use, so the three frontends write the same block for the
same driver outcome. Its fields are the ones the
GetPounceComplementarity* getters return, with null or an absent key
where a getter reads NaN, -1 or an empty label. A solve without pairs
writes no block. A refused solve leaves no report: the write returns FALSE.
After a solve without pairs on which the second-opinion ladder ran a rung,
the report carries the second_opinion block at either detail level, from
the conversion the CLI and Python use: which rungs ran, which one was
promoted, and the base solve’s status and iteration count. On a promotion
solution.status and statistics.iteration_count are the promoted rung’s,
so the block is the only record in the report that the base solve failed
and of what the run cost (total_iteration_count). A solve on which no rung
ran (the converged one) writes no block, and neither does a solve with pairs
or a session solve, neither of which runs the ladder. Like the
complementarity block it describes the most recent solve and is replaced
by the next.
Matrix-form convex QP and conic programs
Separate from the NLP handle, a PounceQp handle takes a convex problem in
matrix form and solves it with the convex engines, through the pipeline
Python’s solve_qp and solve_socp run (pounce_convex::pipeline; see
Convex Solver). It is not an Ipopt API, so every name
carries the Pounce prefix. examples/qp_socp.c in the crate runs a QP, an
SOCP, an infeasibility certificate, the report and three refusals.
PounceQp qp = PounceCreateQp(n, m_eq, m_ineq, 0); /* 0-based triplets */
PounceQpSetObjective(qp, nnz_p, p_row, p_col, p_val, c); /* P: lower triangle */
PounceQpSetEqualities(qp, nnz_a, a_row, a_col, a_val, b);
PounceQpSetInequalities(qp, nnz_g, g_row, g_col, g_val, h);
PounceQpSetBounds(qp, lb, NULL); /* NULL: no upper bounds */
PounceQpAddCone(qp, POUNCE_CONE_SOC, 3, 0.0); /* optional */
int status = PounceQpSolve(qp); /* POUNCE_QP_STATUS_* or < 0 */
PounceQpGetSolution(qp, x, y, z, z_lb, z_ub, &obj, &iters);
PounceFreeQp(qp);
Standard form and indexing
minimize ½ xᵀP x + cᵀx
subject to A x = b, G x ≤ h (G x ⪯_K h with cones), lb ≤ x ≤ ub
PounceCreateQp(n, m_eq, m_ineq, index_style)fixes the dimensions:n ≥ 1variables,m_eq ≥ 0rows ofA,m_ineq ≥ 0rows ofG. It returnsNULLon any other argument.PounceFreeQpreleases the handle (NULLis a no-op).- Every matrix is a list of
(row, col, value)triplets, 0-based when the handle was created withindex_style = 0and 1-based withindex_style = 1(theIpoptProblemconvention). Duplicate triplets are summed. Pis given as its lower triangle (row ≥ col); an entry above the diagonal is refused.Pmay be empty (nnz_p = 0): an LP.AandGare given in full.PounceQpSetObjectivetakesPandc(lengthn, required);PounceQpSetEqualitiestakesAandb(lengthm_eq);PounceQpSetInequalitiestakesGandh(lengthm_ineq). Each must be called before a solve unless its row count is 0. A NULL array is accepted only where its length is 0.PounceQpSetBounds(lb, ub)sets the box. Either side may beNULL(no bound on that side); an entry≤ -1e19inlbor≥ 1e19inub(infinities included) is no bound, as in Ipopt. Refused, storing nothing:NaN, and a box no point satisfies —lb[i] ≥ 1e19(+∞),ub[i] ≤ -1e19(−∞) orlb[i] > ub[i].lb[i] == ub[i]fixes the variable. The default is no box. Bounds are accepted with cones too (they join the cone product as a trailing nonnegative block), which Python’ssolve_socpdoes not offer.- Each builder validates all of its input before writing any of it and
returns
FALSE, changing nothing, on aNULLhandle or array, an index out of range, an upper-triangle entry ofPor a non-finite value. A later call replaces the earlier one. A builder that succeeds discards the previous solve’s result (below).
Cones
Without cones every G row is Gx ≤ h. With cones, PounceQpAddCone(qp, kind, dim, alpha) appends one block to a partition of the G rows, in row
order, and returns its 0-based position. Each block’s slack s = h − Gx (its
rows of it) must lie in its cone:
| kind | dim | rows | cone |
|---|---|---|---|
POUNCE_CONE_NONNEG (0) | ≥ 0 | dim | s ≥ 0 |
POUNCE_CONE_SOC (1) | ≥ 1 | dim | s₀ ≥ ‖(s₁, …, s_{dim−1})‖₂ |
POUNCE_CONE_EXP (2) | 3 | 3 | (s₀, s₁, s₂) with s₁·exp(s₀/s₁) ≤ s₂, s₁ > 0 (closure) |
POUNCE_CONE_POW (3) | 3 | 3 | |s₀| ≤ s₁^α · s₂^(1−α), s₁, s₂ ≥ 0, α = alpha ∈ (0, 1) |
POUNCE_CONE_PSD (4) | matrix order k ≥ 1 | k(k+1)/2 | smat(s) ⪰ 0 |
- PSD layout. A PSD block’s rows are
svec(S)of the symmetrick × kslack matrix: the lower triangle column by column —(0,0), (1,0), …, (k−1,0), (1,1), (2,1), …, (k−1,k−1)— with every off-diagonal entry scaled by√2, so that⟨X, Y⟩ = svec(X)·svec(Y). TheGrows andhentries of an off-diagonal position carry that√2, and so does the dualzread back for it. alphais read forPOUNCE_CONE_POWonly and ignored otherwise.AddConereturnsPOUNCE_ERR_NULLfor aNULLhandle andPOUNCE_ERR_ARGUMENTfor an unknown kind, adimout of range or analphaoutside(0, 1)(NaNand±∞included); nothing is added.- At the solve, the blocks must cover exactly
m_ineqrows, and a PSD block cannot be mixed with an exponential or power one (they run on different drivers); either isPOUNCE_ERR_CONES. SOC mixes with either family.
Options
PounceQpSetNumOption and PounceQpSetStrOption return FALSE, changing
nothing, on a NULL handle, key or value, an unknown key, or a value out of
range. The names and meanings are the CLI’s and Python’s.
| key | values | meaning |
|---|---|---|
tol | (0, 1) | convergence tolerance |
max_iter | whole number ≥ 1 | iteration cap (POUNCE_QP_STATUS_ITERATION_LIMIT) |
time_limit | seconds ≥ 0, finite | wall-clock cap for this solve (POUNCE_QP_STATUS_TIME_LIMIT) |
tau, tau_max | (0, 1) | fraction-to-boundary floor and ceiling; a bare tau raises the ceiling to it, an explicit tau_max wins (Python’s rule) |
qp_reg | finite ≥ 0 | KKT regularization of the IPM |
method | ipm (default), active-set | the convex interior-point engine, or the pounce-qp parametric active-set engine |
hessian_inertia | auto (default), psd, indefinite, unknown | where the PSD verdict on P comes from (below) |
qp_presolve | yes, no | presolve → engine → postsolve (and, on the IPM, the unverified-optimal demotion) |
qp_hsde | yes, no | homogeneous self-dual embedding on the IPM (no: the direct driver) |
qp_equilibrate | yes, no | Ruiz equilibration |
qp_crossover | yes, no | crossover after the IPM |
An option the selected engine would drop is refused at the solve
(POUNCE_ERR_OPTIONS), not ignored:
- under
method=active-set(no cones), settingqp_reg,qp_hsdeorqp_crossoverat all, to either value; - with any cone,
method=active-set,tau,tau_max, everyqp_*switch (evenqp_hsde=yes, the conic default) and anyhessian_inertiabutauto(psd,indefinite,unknown): Python’ssolve_socptakes none of them, and always runs the PSD screen, so a claim would skip a check Python never skips. The conic solve readstol,max_iter,time_limitandmethod=ipm.
PSD screen
Under method=ipm, with or without cones, a P that is not certified positive
semidefinite is refused with POUNCE_ERR_INDEFINITE (gh#112): the convex
IPM would return a silently wrong “optimal” at a saddle point.
- With
hessian_inertia=auto(the default) an emptyPpasses, and any otherPis asked ofpounce_convex::certify_psd_lower_triangle, as the CLI’s dispatch does, at the CLI’s bandt = 1e-9 · min(max|P_ij|, 1)(pounce_convex::psd_band, the one definition both call; the largest entry after summing duplicates):Ppasses whenλ_min(P) ≥ −t, decided by a sign scan for a diagonalPand by the inertia of anLDLᵀfactorization ofP + t·Iotherwise. A factorization that cannot decide counts as not certified. The verdict is kept on the handle: a re-solve after changingb,h, the bounds, the cones or an option does not factorPagain;PounceQpSetObjectiveand anyhessian_inertiasetting drop it. - This is not Python’s check. Python decides the same question in numpy
(
python/pounce/qp.py::_psd_verdict: relative tolerance1e-8 · max|P_ij|, dense eigenvalues forn ≤ 1500, an inertia count above, an undecided factorization reported as unknown with a warning). On a borderlineP—λ_minwithin a few tolerances of zero, or a badly scaled rank-deficientP— the C entry can refuse aPthat Python’s numpy check accepts. It errs toward refusing. - Without cones,
hessian_inertia=psd,indefiniteorunknownreplaces the verdict with the caller’s claim, used as given (with cones a claim is refused, above):psdandunknownpass the screen,indefiniteis refused under the IPM.autorestores the computed verdict. Usepsdto accept aPyou know is PSD and the screen refuses. - Under
method=active-setthe verdict is not a refusal: it is handed to the engine, which solves an indefinitePto a first-order point (Python’smethod="active-set"; see Convex Solver). - A
Pwhose summed duplicate entries overflow to infinity isPOUNCE_ERR_ARGUMENTat the solve.
Solving, statuses and errors
PounceQpSolve returns a status (≥ 0) and keeps the result, or a negative
error before any engine runs. It discards the previous result first, either
way. Without cones it is Python’s solve_qp pipeline (the IPM, or presolve →
IPM → postsolve → unverified-optimal demotion with qp_presolve=yes; or the
active-set engine, optionally presolved); with any cone it is solve_socp’s
conic IPM (the symmetric driver, or the non-symmetric one when an exponential
or power cone is present).
| status | value | meaning | report solution.status |
|---|---|---|---|
POUNCE_QP_STATUS_OPTIMAL | 0 | converged to tol | Solve_Succeeded |
POUNCE_QP_STATUS_OPTIMAL_INACCURATE | 1 | reduced accuracy: usable point, residual above tol | Solved_To_Acceptable_Level |
POUNCE_QP_STATUS_PRIMAL_INFEASIBLE | 2 | infeasible, with a Farkas certificate | Infeasible_Problem_Detected |
POUNCE_QP_STATUS_DUAL_INFEASIBLE | 3 | unbounded, with a recession certificate | Diverging_Iterates |
POUNCE_QP_STATUS_ITERATION_LIMIT | 4 | max_iter reached | Maximum_Iterations_Exceeded |
POUNCE_QP_STATUS_TIME_LIMIT | 5 | time_limit reached | Maximum_WallTime_Exceeded |
POUNCE_QP_STATUS_NUMERICAL_FAILURE | 6 | the KKT factorization failed | Error_In_Step_Computation |
| error | value | returned when |
|---|---|---|
POUNCE_ERR_NULL | −1 | NULL handle (Solve, AddCone) |
POUNCE_ERR_ARGUMENT | −7 | AddCone: bad kind, dim or alpha; Solve: P entries whose sum overflows |
POUNCE_ERR_INCOMPLETE | −60 | no objective, or m_eq > 0 / m_ineq > 0 rows never set |
POUNCE_ERR_CONES | −61 | the cones do not cover exactly m_ineq rows, or PSD mixed with exp/power |
POUNCE_ERR_OPTIONS | −62 | an option the engine would drop (above) |
POUNCE_ERR_INDEFINITE | −63 | method=ipm and P not certified PSD |
POUNCE_ERR_INTERNAL | −8 | an internal error caught at the boundary |
The report column is the CLI’s convex mapping, so the AMPL solve_result_num
equals the CLI’s for the same status (0, 1, 200, 300, 400, 400, 500).
Reading the result
The getters describe the most recent PounceQpSolve that returned a status.
Before one, and after a solve that returned an error, they return FALSE and
write nothing. A builder call that succeeds (SetObjective,
SetEqualities, SetInequalities, SetBounds, AddCone) erases the result,
so the getters and the report never describe a problem the handle no longer
holds; they return FALSE until the next solve. An option call does not
erase it: the result is still a solve of the problem the handle holds, under
the options it ran with (as an IpoptProblem’s last solve survives
AddIpoptNumOption).
PounceQpGetSolution(qp, x, y, z, z_lb, z_ub, obj, iters)copiesx,z_lb,z_ub(lengthn),y(m_eq),z(m_ineq), the objective and the engine’s iteration count; any output may beNULL. It returnsFALSE, writing nothing, if a result vector is not of its stated length (an internal inconsistency, never copied past your buffer). Signs:Px + c + Aᵀy + Gᵀz − z_lb + z_ub = 0withz, z_lb, z_ub ≥ 0(zin the dual cone with cones; insveccoordinates on a PSD block).PounceQpGetResidualsandPounceQpGetCertificatefill extensible structs: setstruct_size = sizeoffirst, or the getter returnsFALSE.PounceQpGetResidualsfills aPounceQpResiduals(Python’sQpResult.residuals):primal_infeasibility,dual_infeasibility,complementarity,kkt_errorand their four_rawtwins. Without cones the first four are read above their finite-precision floor, in the objective’s units (the measurement theOptimalverdict is judged on), and the_rawfour are the plain absolute values; with cones both sets are the plain conic residuals.PounceQpGetCertificatefills aPounceQpCertificateand isTRUEafter every solve that returned a status.kindisPOUNCE_QP_CERT_PRIMAL_INFEASIBLE(1) on a primal-infeasible status — the Farkas ray is in they,z,z_lb,z_ubthatGetSolutionreturns —,POUNCE_QP_CERT_DUAL_INFEASIBLE(2) on a dual-infeasible one — the recession ray is inx—, andPOUNCE_QP_CERT_NONE(0) otherwise.scaleis the ray’s inf-norm (NaNwith no certificate); the ray carries the embedding’s1/τscale, so divide byscalefor a unit ray.tauandkappaare the homogeneous embedding’s scalars at termination,NaNwhen the answer came from a driver that records none: the direct IPM (qp_hsde=no), the active-set engine and the exponential/power-cone driver.
JSON report
PounceQpWriteSolveReport(qp, path, detail) writes the most recent result as
a pounce.solve-report/v1 JSON file (JSON Solve Report) at
detail "summary" (or NULL) or "full". It returns FALSE for a NULL
handle or path, no result, an unknown detail or an I/O error.
solution.engineiscvx-qp(the convex IPM),qp-active-set(the active-set engine) orcvx-qcqpfor any solve with a cone, exponential, power and PSD included: the conic IPM the CLI’s QCQP arm also runs. There is no separate engine string for a matrix-form conic solve.- The input descriptor is
TnlpDirect;problem.n_constraintsism_eq + m_ineq;solution.lambdaisyfollowed byz;solution.statusis the mapping in the status table; the statistics’ final residuals are the first fourPounceQpResidualsfields.
Python parity
The handle runs the functions Python’s solve_qp / solve_socp run, on the
same QpProblem. The crate’s tests/qp_python_parity.rs feeds 25 models
(LP, QP and every cone kind; both engines, presolve, crossover, the direct
driver and the tau / qp_reg options; infeasible, unbounded and capped) through the handle and compares
them with Python’s results: bit-exact on Linux x86_64 on status, objective,
iterations, x, y, z, z_lb, z_ub, all eight residuals, tau,
kappa and the certificate. Elsewhere the test asks only for Python’s status
and, on a solution, x and the objective to 1e-6, since the reference was generated on Linux x86_64
and floating-point results may differ by platform. The one deliberate
difference is the PSD screen above.
Fortran shim
The same library exports the eight Fortran 77 entry points of Ipopt’s
IpStdFInterface.c, with gfortran’s trailing-underscore mangling:
ipcreate_, ipfree_, ipsolve_, ipaddstroption_, ipaddnumoption_,
ipaddintoption_, ipsetcallback_ and ipunsetcallback_. Arguments are
passed by reference, strings as a buffer plus a trailing length, and the
option setters return 0 on success and 1 on failure. None of POUNCE’s C
extensions are mirrored there: they are C-only.
Error codes
Every POUNCE extension reports a refusal from one namespace, POUNCE_ERR_*,
and each value means the same thing whichever function returns it, so a
wrapper keeps a single code-to-message table and a logged -3 always means
“index out of range”. Success is POUNCE_OK (0). The sections above list
which codes each function returns.
Every function checks in the same order, so a call with several faults reports the same one whichever function it is:
- the handle (
POUNCE_ERR_NULL); flagsand enum arguments (_ERR_FLAGS,_ERR_ARGUMENT);- counts (
_ERR_COUNT), then the arrays they size (_ERR_NULL); - per entry, over the whole batch in batch order: range, then
duplicate or already paired, then NaN (
_ERR_OUT_OF_RANGE,_ERR_DUPLICATE,_ERR_VAR_ALREADY_PAIRED,_ERR_ROW_ALREADY_PAIRED,_ERR_NAN); - per entry, over the whole batch in batch order: what the entry would
mean (
_ERR_SHAPE,_ERR_ROW_NOT_FREE,_ERR_VAR_BOUNDS,_ERR_COMPLEMENTS_CLASS,_ERR_PAIR_CHANGED); - state beyond the batch (
_ERR_WORKING_SET;PounceQpSolve’s_ERR_INCOMPLETE,_ERR_CONES,_ERR_OPTIONS,_ERR_INDEFINITE).
So an argument fault anywhere in a batch is reported before a semantic
fault anywhere in it, and bad_index names the first entry with the
earliest-stage fault. crates/pounce-cinterface/tests/check_order.rs
holds each batch function to this.
const char *PounceErrorString(int code);
PounceErrorString returns the message for any POUNCE_OK / POUNCE_ERR_*
value, as a static string the caller must not free, and
"unknown error code" for anything else (never NULL). Non-negative
function-specific results, the QP statuses and the
AddPounceComplementsConstraint outcomes, are results rather than errors
and read as unknown.
| block | code | value | meaning |
|---|---|---|---|
| generic | POUNCE_ERR_NULL | -1 | NULL handle, or a NULL array the call needed |
POUNCE_ERR_COUNT | -2 | count negative, too large, or inconsistent with a NULL index array | |
POUNCE_ERR_OUT_OF_RANGE | -3 | index outside the problem (in its index style) | |
POUNCE_ERR_DUPLICATE | -4 | an index given twice where each may appear once | |
POUNCE_ERR_NAN | -5 | a NaN value | |
POUNCE_ERR_FLAGS | -6 | flags has a bit this library does not define | |
POUNCE_ERR_ARGUMENT | -7 | an argument outside its domain (unknown view or cone kind, bad cone dim/alpha, overflowing P entries) | |
POUNCE_ERR_INTERNAL | -8 | internal error or inconsistent handle; nothing changed | |
| pairs | POUNCE_ERR_VAR_ALREADY_PAIRED | -20 | variable already in a pair |
POUNCE_ERR_ROW_ALREADY_PAIRED | -21 | row already in a pair | |
POUNCE_ERR_SHAPE | -22 | not a native pair shape | |
POUNCE_ERR_ROW_NOT_FREE | -23 | a Complements row has, or would get, a finite bound | |
POUNCE_ERR_VAR_BOUNDS | -24 | variable bounds NaN or crossed | |
| bounds | POUNCE_ERR_PAIR_CHANGED | -40 | update would change what a declared pair pairs |
POUNCE_ERR_COMPLEMENTS_CLASS | -41 | update would move a Complements variable to another table row | |
POUNCE_ERR_WORKING_SET | -42 | update contradicts the staged working set | |
| QP | POUNCE_ERR_INCOMPLETE | -60 | no objective, or declared rows never set |
POUNCE_ERR_CONES | -61 | cones do not partition the inequality rows | |
POUNCE_ERR_OPTIONS | -62 | an option the engine would drop | |
POUNCE_ERR_INDEFINITE | -63 | method=ipm and P not certified PSD |
Generic codes are -1 to -19 and each function family has its own block of 20. A new code is appended inside its block, and a released number is never reused or renumbered; a new family gets a new block.
ABI and versioning
GetIpoptVersionreports the version the library was built as, and the header’sPOUNCE_VERSION_MAJOR,POUNCE_VERSION_MINOR,POUNCE_VERSION_PATCHandPOUNCE_VERSIONmatch it (a test and the release guard both check this). Compare the two to detect a header/library mismatch at run time.- Changes to the C ABI are additions only: no existing prototype,
#[repr(C)]struct layout (PounceLinearSolverStats,PounceComplementarityStats,PounceComplementaritySolve,PounceQpResiduals,PounceQpCertificate) or#definevalue changes within the 0.x line, except that the four extensible structs below may gain fields at their end. New capabilities arrive as new symbols. A test compiles a C program against the header and holds every struct’s size and every field’s offset and width to the Rust side. - POUNCE is pre-1.0, so wrappers gate on the minor version. Pounce.jl accepts a fixed range of native minors and checks its required symbols at load; widening that range is an ABI review (see Julia and JuMP).
Extensible output structs
PounceComplementarityStats, PounceComplementaritySolve,
PounceQpResiduals and PounceQpCertificate are caller-allocated and begin
with ipindex struct_size, which the caller sets to sizeof the struct
before every call:
PounceQpResiduals r;
r.struct_size = sizeof r;
if (PounceQpGetResiduals(qp, &r)) { /* ... */ }
- A
struct_sizesmaller than this release’ssizeof—0from= {0}, or an uninitialized value — is refused: the getter returnsFALSEand writes nothing. - Otherwise the getter writes this release’s fields only. It never writes
struct_size, and never writes a byte past this release’ssizeof, however largestruct_sizeis. - Growth rule: a later release only appends fields at the end (nothing is
removed, reordered or retyped) and writes
min(struct_size, its sizeof)bytes. A program built against an older header keeps working with a newer library, which honours its smallerstruct_size; a program built against a newer header gets the older library’s fields, with the rest of its struct left as it was.
This release’s sizes (x86_64 Linux, 32-bit ipindex) are 224, 72, 72 and 32
bytes; a mirror in another language must reproduce the header’s layout,
padding included, and the C layout test holds it to the Rust side.
PounceLinearSolverStats has no struct_size: it shipped before this
convention, and adding one would move every field under existing callers.
Its layout is frozen.