Design notes: LP/QP routing and performance engineering

.gitignore

@@ -55,6 +55,11 @@
 !/benchmarks/lp/mps_to_nl.py
 !/benchmarks/lpopt/build_subset.py
 !/benchmarks/lpopt/mps_to_nl.py
+# The cblib suite is the conic (exp/power cone) tier: CBLIB .cbf instances
+# solved through the pounce_cblib binary. Track its runner (README via the
+# per-suite rule above); the per-run pounce.json stays ignored like every
+# other suite.
+!/benchmarks/cblib/run_cblib.py
 # Vanderbei reference status (derived once from cute_table.pdf): which
 # problems have a documented feasible optimum vs. are hard/infeasible/
 # unbounded/untabulated. Tracked so we never have to re-derive it.
@@ -87,6 +92,9 @@ python/dist/
 python/examples/*.png
 python/*.egg-info/
 
+# Local virtualenvs (e.g. for building the extension + running notebooks)
+.venv/
+
 # Claude Code local state
 .claude/
 

CHANGELOG.md

@@ -9,6 +9,91 @@ changes.
 
 ## [0.4.0] — 2026-06-05
 
+### Added — Convex / conic solver (`pounce-convex`; `solve_qp` / `solve_socp`)
+
+POUNCE is no longer NLP-only: a new pure-Rust convex interior-point solver
+(`pounce-convex`) handles **LP, convex QP, SOCP, and PSD / exp / power cones**,
+solving each to a **global** optimum (a convex problem has no other kind). It
+uses a homogeneous self-dual embedding (HSDE) — symmetric for the self-dual
+cones and a non-symmetric driver for the exponential/power cones — over a
+`Cone` abstraction (`nonneg`, `soc`, `psd`, `exp`, `power`, plus composite and
+chordal decompositions for sparse SDPs). Convex solvers extract the constant
+`P`, `A`, `c`, `b` data once at setup rather than re-evaluating per iteration,
+and share the `pounce-linsol` / `pounce-linalg` factorization substrate with the
+NLP path. Python entry points are typed (not SciPy-shaped, by necessity — a cone
+program is *data*, not a callable): `solve_qp(P, c, A, b, G, h, lb, ub, …)`,
+`solve_socp(…, cones=…)`, plus `solve_qp_batch` / `solve_qp_multi_rhs` for
+batched factor reuse, and a reduced-Hessian sensitivity API. The CLI reads conic
+instances from CBLIB / `.cbf` (including PSDCON / HCOORD / DCOORD SDP blocks).
+
+### Fixed — Convex LP/QP reported objective dropped tree-folded constant
+
+The convex LP/QP path (`solver_selection=lp-ipm` / `qp-ipm`) reported an
+objective off by the objective's constant term whenever AMPL/Pyomo folded that
+constant into the **nonlinear objective tree** (the `+9` of `(x-3)²`) rather
+than the `.nl` linear-section constant. The quadratic-form extractor
+(`analyze_quadratic_full`) discarded the degree-0 term — correct for the
+*minimizer*, wrong for the *reported value* — so e.g. `HS21` reported `0.04`
+instead of `−99.96` and `HS35` `−8.889` instead of `0.111`. The extractor now
+returns that constant and the convex driver adds it to the reported objective
+alongside `obj_constant`; the optimal point was always correct. Caught by a
+head-to-head NLP-vs-convex run over the Maros-Mészáros QP and NETLIB LP suites
+(`benchmarks/nl_compare_nlp_vs_convex.md`).
+
+### Fixed — Convex LP/QP IPM stalled on badly-scaled NETLIB LPs
+
+The static KKT regularization `δ` (added on the reduced KKT diagonal so the
+LDLᵀ has a stable inertia) was `1e-8`, large enough to **floor the achievable
+primal residual** at `δ·‖dy‖`: with a full Newton step `A·dx = −r_p + δ·dy`, so
+on instances with large equality multipliers the primal infeasibility cannot
+fall below `δ·‖dy‖`. On NETLIB `adlittle` (`‖dy‖ ≈ 4e8`) this froze `inf_pr`
+near 4 and the LP IPM ran to its iteration cap, returning a wrong objective
+(`439665` vs the published `225494.96`). Lowering the default `δ` to `1e-10` —
+still strictly positive, so the system stays quasi-definite — clears the floor:
+`adlittle` now converges in ~57 iterations to the optimum, `stocfor1` speeds up
+(139 → 71 iters), and the rest of the LP/QP suites are unchanged (the QP suite
+is bit-identical). The whole `1e-9‥1e-11` band converges the benchmark suites;
+`1e-10` is centered in it.
+
+Also: the convex IPM's opt-in iteration trace now records a **terminal record at
+the converged iterate** (the NLP path's N+1 convention), so the trace always
+ends at the optimum instead of at the last pre-step state — previously a solve
+that converged in a single step left only the cold-start record in the trace.
+
+### Added — SOS polynomial global optimization (`sos_minimize`)
+
+`sos_minimize(objective, *, inequalities, equalities, …)` computes **certified
+global** lower bounds for polynomial optimization via a sum-of-squares /
+Lasserre relaxation (Putinar localizing multipliers for constraints), built on
+the new PSD cone. When the relaxation is exact it extracts the global
+minimizer(s) with an exactness certificate (multi-atom extraction without a
+non-symmetric eig, plus facial reduction for degenerate solves).
+
+### Added — Spatial branch-and-bound global optimizer (`pounce-global`;
+`minimize_global` / `--solver global`)
+
+A new `pounce-global` crate solves **factorable nonconvex NLPs to a certified
+global optimum** by spatial branch-and-bound: αBB convex underestimators,
+polyhedral envelopes for univariate atoms, level-1 RLT cuts, multi-grouping
+trilinear relaxations, optimization-based bound tightening (OBBT), and
+cutting-plane bound refinement, with local NLP upper bounds. Branching is
+reliability-based (pseudocost + strong branching); the node pool and OBBT run in
+parallel (deterministic, ~2.3–2.6× wall-clock). Exposed as
+`minimize_global(objective, *, constraints, lo, hi, …)` in Python (a symbolic
+`Expr` + box) and `pounce --solver global` on `.nl` models, with frontier
+memory estimation and a pre-solve warning.
+
+### Added — Multi-backend interactive debugger (convex IPM + B&B tree)
+
+The interactive debugger was generalized over a `DebugState` trait so one REPL
+drives all three solvers. New backends: a **convex/conic** debugger
+(`pounce_cblib --debug`, wired through the symmetric and non-symmetric HSDE
+drivers) and an **interactive branch-and-bound tree debugger** that can `step`
+through nodes and `into` a node's relaxation — handing off to the interior-point
+REPL via a shared command queue (tree ↔ interior-point). This composes with the
+0.4.0 debugger features below (quote-aware tokenization, `ask` provider presets,
+`--debug-json` protocol, Ctrl-C escape hatch).
+
 ### Added — `pounce.curve_fit` (Python)
 
 A `scipy.optimize.curve_fit`-style nonlinear fitter on top of the

CLAUDE.md

@@ -0,0 +1,43 @@
+# pounce — release / publishing facts
+
+pounce ships to **three** registries on each release. Two are automated by
+GitHub Actions (tag-triggered); the **crates.io one is manual** and is the
+easiest to forget — it is NOT triggered by pushing a tag or by creating a
+GitHub Release.
+
+## Surfaces (all must reach the same X.Y.Z)
+
+1. **PyPI `pounce-solver`** — `.github/workflows/release-pounce.yml`, triggered
+   by pushing a `python-vX.Y.Z` tag. Builds wheels (incl. Windows) + sdist,
+   publishes to PyPI.
+2. **PyPI `pyomo-pounce`** — `.github/workflows/release-pyomo-pounce.yml`,
+   triggered by a `pyomo-pounce-vX.Y.Z` tag.
+3. **crates.io — 16 workspace crates** — **MANUAL**, via
+   `scripts/publish-crates.sh` (run locally). NO workflow does `cargo publish`.
+   Full procedure in `dev-notes/cargo-release.md`. The script publishes in
+   topological (dependency) order; resume a mid-batch failure with
+   `--start-from <crate>`. New-crate rate limits apply on first publish only.
+   Crates with `publish = false` (pounce-py, pounce-studio-*, iter-diff) are
+   intentionally excluded.
+
+   The CLI binary is also bundled inside the PyPI wheels, so an end user
+   `pip install pounce-solver` does not require the crates.io publish — but the
+   crates.io publish is still part of a complete release.
+
+## GitHub Release
+
+Created **by hand** (`gh release create vX.Y.Z --notes-file <file>`); no workflow
+makes it. Body has historically been the matching `## [X.Y.Z]` section of
+CHANGELOG.md. A git tag alone does NOT create a Release, and creating a Release
+does NOT trigger any workflow (nothing has an `on: release` trigger).
+
+## Checking what's published (don't get this wrong)
+
+crates.io API needs a User-Agent or it silently looks unpublished:
+
+    curl -s -H "User-Agent: pounce-release-check (jkitchin@andrew.cmu.edu)" \
+      https://crates.io/api/v1/crates/<name> | python3 -c \
+      "import sys,json; c=json.load(sys.stdin).get('crate'); print(c['max_version'] if c else 'NOT PUBLISHED')"
+
+Sanity-check against `serde` first; if serde reads NOT PUBLISHED your request is
+being rejected, not the crate missing.

Cargo.toml

@@ -13,6 +13,7 @@ members = [
     "crates/pounce-presolve",
     "crates/pounce-l1penalty",
     "crates/pounce-qp",
+    "crates/pounce-convex",
     "crates/pounce-sensitivity",
     "crates/pounce-solve-report",
     "crates/pounce-observability",
@@ -41,6 +42,7 @@ default-members = [
     "crates/pounce-presolve",
     "crates/pounce-l1penalty",
     "crates/pounce-qp",
+    "crates/pounce-convex",
     "crates/pounce-sensitivity",
     "crates/pounce-solve-report",
     "crates/pounce-observability",
@@ -74,11 +76,17 @@ pounce-restoration = { path = "crates/pounce-restoration", version = "0.4.0" }
 pounce-presolve = { path = "crates/pounce-presolve", version = "0.4.0" }
 pounce-l1penalty = { path = "crates/pounce-l1penalty", version = "0.4.0" }
 pounce-qp = { path = "crates/pounce-qp", version = "0.4.0" }
+pounce-convex = { path = "crates/pounce-convex", version = "0.4.0" }
 pounce-sensitivity = { path = "crates/pounce-sensitivity", version = "0.4.0" }
 pounce-solve-report = { path = "crates/pounce-solve-report", version = "0.4.0" }
 pounce-studio-core = { path = "crates/pounce-studio-core", version = "0.4.0" }
 pounce-observability = { path = "crates/pounce-observability", version = "0.4.0" }
-feral = "0.10.0"
+# feral HEAD past the 0.10.0 release checkpoint: issue #80 — MC64/scaling
+# perf work (Hungarian-heap reuse across columns, localized dense-column
+# cost, ldlt_compress profiling). Not yet on crates.io; pinned by rev for
+# reproducibility. NOTE: this git pin blocks the crates.io publish of the
+# pounce crates until feral cuts a release carrying these commits.
+feral = { git = "https://github.com/jkitchin/feral.git", rev = "11fb4b98d7caac0383c53b6a969e27632efcef77" }
 # Dense linear algebra for the debugger's numerical rank diagnosis
 # (SVD of the active-constraint Jacobian). Pure-Rust, MIT; we pull only
 # the dense `std` core — no rayon/sparse/rand/npy.

Makefile

@@ -70,6 +70,7 @@ endif
 
 .PHONY: all build debug test check clippy fmt fmt-check doc book install uninstall clean help \
         install-mcp uninstall-mcp install-skill uninstall-skill \
+        python-ext python-test \
         benchmark benchmark-rerun benchmark-report benchmark-gams
 
 all: build
@@ -118,6 +119,20 @@ clean:
 help:
 	@sed -n 's/^# \{0,1\}//p' Makefile | sed -n '1,45p'
 
+# ---- Python extension + tests -------------------------------------------
+# Rebuild the native extension in place, then run the Python test suite.
+# This is the safe way to run pytest: a stale in-place `_pounce*.so` (left
+# by an earlier `maturin develop`) silently shadows the current binding and
+# makes the suite fail with confusing errors. `python-ext` rebuilds it, and
+# `python/tests/conftest.py` additionally guards against running pytest
+# against a stale artifact. Requires `maturin` and the test extras in the
+# active environment (`pip install -e 'python[dev]'`).
+python-ext:
+	cd python && maturin develop
+
+python-test: python-ext
+	cd python && python -m pytest tests -q
+
 # ---- Benchmarks ----------------------------------------------------------
 # Single source of truth: benchmarks/Makefile. These shims forward
 # everything so users can drive runs from the repo root.