septal 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. septal-0.2.0/CHANGELOG.md +50 -0
  2. septal-0.2.0/LICENSE +21 -0
  3. septal-0.2.0/MANIFEST.in +3 -0
  4. septal-0.2.0/PKG-INFO +495 -0
  5. septal-0.2.0/README.md +452 -0
  6. septal-0.2.0/pyproject.toml +105 -0
  7. septal-0.2.0/setup.cfg +4 -0
  8. septal-0.2.0/src/septal/__init__.py +42 -0
  9. septal-0.2.0/src/septal/casadax/__init__.py +55 -0
  10. septal-0.2.0/src/septal/casadax/callbacks.py +304 -0
  11. septal-0.2.0/src/septal/casadax/factory.py +171 -0
  12. septal-0.2.0/src/septal/casadax/schema.py +102 -0
  13. septal-0.2.0/src/septal/casadax/solvers.py +367 -0
  14. septal-0.2.0/src/septal/casadax/utilities.py +69 -0
  15. septal-0.2.0/src/septal/jax/__init__.py +5 -0
  16. septal-0.2.0/src/septal/jax/sqp/__init__.py +94 -0
  17. septal-0.2.0/src/septal/jax/sqp/convergence.py +153 -0
  18. septal-0.2.0/src/septal/jax/sqp/factory.py +230 -0
  19. septal-0.2.0/src/septal/jax/sqp/filter.py +542 -0
  20. septal-0.2.0/src/septal/jax/sqp/hessian.py +222 -0
  21. septal-0.2.0/src/septal/jax/sqp/line_search.py +269 -0
  22. septal-0.2.0/src/septal/jax/sqp/qp_subproblem.py +630 -0
  23. septal-0.2.0/src/septal/jax/sqp/schema.py +394 -0
  24. septal-0.2.0/src/septal/jax/sqp/solver.py +943 -0
  25. septal-0.2.0/src/septal/py.typed +0 -0
  26. septal-0.2.0/src/septal.egg-info/PKG-INFO +495 -0
  27. septal-0.2.0/src/septal.egg-info/SOURCES.txt +44 -0
  28. septal-0.2.0/src/septal.egg-info/dependency_links.txt +1 -0
  29. septal-0.2.0/src/septal.egg-info/requires.txt +18 -0
  30. septal-0.2.0/src/septal.egg-info/top_level.txt +1 -0
  31. septal-0.2.0/tests/conftest.py +67 -0
  32. septal-0.2.0/tests/sqp/__init__.py +0 -0
  33. septal-0.2.0/tests/sqp/conftest.py +98 -0
  34. septal-0.2.0/tests/sqp/test_convergence.py +162 -0
  35. septal-0.2.0/tests/sqp/test_factory.py +219 -0
  36. septal-0.2.0/tests/sqp/test_filter.py +816 -0
  37. septal-0.2.0/tests/sqp/test_hessian.py +108 -0
  38. septal-0.2.0/tests/sqp/test_line_search.py +202 -0
  39. septal-0.2.0/tests/sqp/test_qp_subproblem.py +552 -0
  40. septal-0.2.0/tests/sqp/test_schema.py +203 -0
  41. septal-0.2.0/tests/sqp/test_solver.py +618 -0
  42. septal-0.2.0/tests/test_callbacks.py +142 -0
  43. septal-0.2.0/tests/test_factory.py +137 -0
  44. septal-0.2.0/tests/test_schema.py +91 -0
  45. septal-0.2.0/tests/test_solvers.py +195 -0
  46. septal-0.2.0/tests/test_utilities.py +67 -0
@@ -0,0 +1,50 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.2.0] - 2026-10-20
8
+
9
+ First release on PyPI.
10
+
11
+ ### Added
12
+ - Wächter–Biegler filter line search (`SQPConfig.step_acceptance="filter"`, now the
13
+ default) with second-order correction and an iterative feasibility restoration phase
14
+ that detects local infeasibility (`septal.jax.sqp.filter`).
15
+ - Complementarity residual in the KKT convergence test
16
+ (`SQPConfig.tol_complementarity`, `SQPResult.kkt_complementarity`).
17
+ - Solver counters `n_soc`, `n_restoration` and `n_local_infeasible` in `SQPState`.
18
+ - `septal.__version__`, `py.typed` marker, MIT `LICENSE` file.
19
+
20
+ ### Changed
21
+ - Every SQP iterate is projected onto the variable box.
22
+ - Stagnation and restoration-stall resets also zero the multipliers.
23
+ - Packaging moved to a single PEP 621 `[project]` table; the duplicate Poetry
24
+ metadata and lock file were removed. Minimum `jax`/`jaxlib` is now 0.4.30.
25
+ - CI is GitHub Actions only (Jenkinsfile removed): lint/format/type-check job, test
26
+ matrix on Python 3.10–3.13 plus macOS, and a build job that runs `twine check`.
27
+ - `ROADMAP.md` removed.
28
+
29
+ ### Fixed
30
+ - Stationarity and feasibility alone accepted non-KKT points with a non-zero
31
+ multiplier on an inactive constraint (HS013, HS016).
32
+ - A garbage QP solve could leave multipliers of order 1e25 that poisoned the exact
33
+ Hessian after a reset (HS023 trapped start).
34
+
35
+ ## [0.1.1] - 2026-05
36
+
37
+ ### Added
38
+ - Jenkins and GitHub Actions CI.
39
+
40
+ ## [0.1.0] - 2026-04
41
+
42
+ ### Added
43
+ - JAX SQP solver (`septal.jax.sqp`): ADMM QP subproblem with Ruiz equilibration and
44
+ active-set polishing, damped BFGS or exact Lagrangian Hessian with inertia
45
+ correction, L1 merit non-monotone line search, `vmap`/`pmap` batched solves.
46
+ - CasADi/IPOPT backend (`septal.casadax`) with JAX forward/reverse AD callbacks.
47
+
48
+ [0.2.0]: https://github.com/mycelia-intelligence/septal/compare/v0.1.1...v0.2.0
49
+ [0.1.1]: https://github.com/mycelia-intelligence/septal/compare/v0.1.0...v0.1.1
50
+ [0.1.0]: https://github.com/mycelia-intelligence/septal/releases/tag/v0.1.0
septal-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Max Mowbray
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,3 @@
1
+ include LICENSE README.md CHANGELOG.md
2
+ graft tests
3
+ global-exclude *.py[cod] __pycache__ .DS_Store
septal-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,495 @@
1
+ Metadata-Version: 2.4
2
+ Name: septal
3
+ Version: 0.2.0
4
+ Summary: Nonlinear programming with JAX: a vmappable SQP solver, plus a CasADi/IPOPT backend
5
+ Author: Max Mowbray
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/mycelia-intelligence/septal
8
+ Project-URL: Repository, https://github.com/mycelia-intelligence/septal
9
+ Project-URL: Issues, https://github.com/mycelia-intelligence/septal/issues
10
+ Project-URL: Changelog, https://github.com/mycelia-intelligence/septal/blob/main/CHANGELOG.md
11
+ Keywords: nonlinear programming,optimization,sqp,jax,casadi,ipopt,parametric optimization
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: casadi>=3.6
27
+ Requires-Dist: jax>=0.4.30
28
+ Requires-Dist: jaxlib>=0.4.30
29
+ Requires-Dist: jaxopt>=0.8
30
+ Requires-Dist: numpy>=1.24
31
+ Requires-Dist: scipy>=1.11
32
+ Provides-Extra: dev
33
+ Requires-Dist: pytest>=7; extra == "dev"
34
+ Requires-Dist: pytest-cov; extra == "dev"
35
+ Requires-Dist: ruff<0.12,>=0.11; extra == "dev"
36
+ Requires-Dist: mypy<1.15; extra == "dev"
37
+ Requires-Dist: black<23,>=22; extra == "dev"
38
+ Provides-Extra: docs
39
+ Requires-Dist: sphinx>=7; extra == "docs"
40
+ Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
41
+ Requires-Dist: sphinx-autodoc-typehints>=2; extra == "docs"
42
+ Dynamic: license-file
43
+
44
+ # septal
45
+
46
+ A lightweight Python library for solving **nonlinear programmes (NLPs)** with JAX-native solvers and optional CasADi/IPOPT integration.
47
+
48
+ ```
49
+ min f(x, p)
50
+ s.t. lhs ≤ g(x, p) ≤ rhs
51
+ lb ≤ x ≤ ub
52
+ ```
53
+
54
+ Two solver backends:
55
+
56
+ | Backend | Entry point | AD mode | Use case |
57
+ |---|---|---|---|
58
+ | **JAX SQP** | `ParametricSQPFactory` / `sqp_solve_single` | `jax.grad` / `jax.hessian` | Batched parametric NLP — GPU/TPU, `vmap`-compatible |
59
+ | **CasADi / IPOPT** | `SolverFactory` | `jvp` / `vjp` callbacks | General constrained NLP on CPU with IPOPT |
60
+
61
+ ---
62
+
63
+ ## Package structure
64
+
65
+ ```
66
+ src/septal/
67
+ ├── casadax/ — CasADi/IPOPT backend, AD callbacks, schema, utilities
68
+ │ ├── schema.py NLPProblem, SolveResult
69
+ │ ├── callbacks.py JAX↔CasADi AD wrappers (casadify_*)
70
+ │ ├── solvers.py CasadiSolver, JaxSolver
71
+ │ ├── factory.py SolverFactory
72
+ │ └── utilities.py generate_initial_guess (Sobol)
73
+ └── jax/
74
+ └── sqp/ — Pure-JAX SQP solver
75
+ ├── schema.py ParametricNLPProblem, SQPConfig, SQPState, SQPResult
76
+ ├── solver.py sqp_solve_single, sqp_solve_scan, make_solver
77
+ ├── qp_subproblem.py ADMM + Ruiz equilibration + OSQP polishing
78
+ ├── hessian.py Damped BFGS + exact Lagrangian Hessian
79
+ ├── line_search.py L1 merit + non-monotone Armijo backtracking ("merit" mode)
80
+ ├── filter.py Wächter–Biegler filter line search, SOC, restoration ("filter" mode, default)
81
+ ├── convergence.py KKT residuals incl. complementarity
82
+ └── factory.py ParametricSQPFactory (high-level API)
83
+ ```
84
+
85
+ ---
86
+
87
+ ## Installation
88
+
89
+ ```bash
90
+ pip install septal
91
+ ```
92
+
93
+ For development, clone the repository and install in editable mode with the dev tools:
94
+
95
+ ```bash
96
+ git clone https://github.com/mycelia-intelligence/septal.git
97
+ cd septal
98
+ pip install -e ".[dev]"
99
+ ```
100
+
101
+ **Dependencies**: `jax`, `jaxlib`, `numpy`, `scipy`, `jaxopt`, `casadi` (the last two for the `casadax` backend only). Python 3.10–3.13.
102
+
103
+ > **Float64 precision**: importing `septal.jax.sqp` sets `jax_enable_x64 = True` globally. This is required for numerical stability of BFGS and the KKT system.
104
+
105
+ ---
106
+
107
+ ## Quick start
108
+
109
+ ### 1. JAX SQP — single solve
110
+
111
+ ```python
112
+ import jax.numpy as jnp
113
+ from septal.jax.sqp import ParametricNLPProblem, SQPConfig, ParametricSQPFactory
114
+
115
+ def objective(x, p):
116
+ return jnp.sum((x - p) ** 2)
117
+
118
+ def constraints(x, p):
119
+ return jnp.array([jnp.sum(x) - 1.0]) # equality: sum(x) = 1
120
+
121
+ problem = ParametricNLPProblem(
122
+ objective=objective,
123
+ bounds=[jnp.full(3, -2.0), jnp.full(3, 2.0)],
124
+ n_decision=3,
125
+ n_params=3,
126
+ constraints=constraints,
127
+ constraint_lhs=jnp.zeros(1),
128
+ constraint_rhs=jnp.zeros(1),
129
+ )
130
+
131
+ factory = ParametricSQPFactory(problem, SQPConfig(max_iter=200))
132
+
133
+ x0 = jnp.zeros(3)
134
+ p = jnp.array([0.5, -0.3, 1.0])
135
+ result = factory.solve(x0, p)
136
+
137
+ print(result.success) # True
138
+ print(result.decision_variables) # x* ≈ [0.433, -0.367, 0.933]
139
+ print(result.kkt_stationarity) # < 1e-6
140
+ ```
141
+
142
+ ### 2. JAX SQP — batched parametric solve (GPU)
143
+
144
+ ```python
145
+ import jax
146
+ import jax.numpy as jnp
147
+ from septal.jax.sqp import ParametricNLPProblem, SQPConfig, ParametricSQPFactory
148
+
149
+ def objective(x, p):
150
+ return 0.5 * jnp.dot(x, x) - jnp.dot(p, x)
151
+
152
+ problem = ParametricNLPProblem(
153
+ objective=objective,
154
+ bounds=[jnp.full(4, -5.0), jnp.full(4, 5.0)],
155
+ n_decision=4,
156
+ n_params=4,
157
+ )
158
+
159
+ factory = ParametricSQPFactory(problem, SQPConfig())
160
+
161
+ # Solve 1000 NLPs in parallel
162
+ N = 1000
163
+ key = jax.random.PRNGKey(0)
164
+ params_batch = jax.random.normal(key, (N, 4))
165
+ x0_batch = jnp.zeros((N, 4))
166
+
167
+ result_batch = factory.solve_batch(x0_batch, params_batch)
168
+ print(result_batch.decision_variables.shape) # (1000, 4)
169
+ print(jnp.mean(result_batch.success)) # ≈ 1.0
170
+ ```
171
+
172
+ ### 3. JAX SQP — multi-start and parametric batches with `pmap`
173
+
174
+ When a batch exceeds what fits on a single accelerator, or when you want genuine
175
+ parallelism across multiple CPU cores / GPUs / TPU chips, use `pmap` rather
176
+ than `vmap`.
177
+
178
+ * **`vmap`** vectorises the batch inside one device — one XLA program, one
179
+ device's memory budget. Great for moderate batches on a single GPU.
180
+ * **`pmap`** distributes instances **across devices** (one replica per XLA
181
+ device). Ideal for multi-start on a multi-core host, multi-GPU parametric
182
+ sweeps, or TPU pods.
183
+
184
+ ```python
185
+ import jax
186
+ import jax.numpy as jnp
187
+ from septal.jax.sqp import ParametricNLPProblem, SQPConfig
188
+ from septal.jax.sqp.solver import make_batch_solver, batch_state_to_result
189
+ from septal.casadax.utilities import generate_initial_guess
190
+
191
+ problem = ParametricNLPProblem(
192
+ objective=lambda x, p: 0.5 * jnp.dot(x, x) - jnp.dot(p, x),
193
+ bounds=[jnp.full(4, -5.0), jnp.full(4, 5.0)],
194
+ n_decision=4,
195
+ n_params=4,
196
+ )
197
+ cfg = SQPConfig()
198
+
199
+ # --- Multi-start: same parameters, many Sobol-quasi-random x0 -----------
200
+ solve_batch = make_batch_solver(problem, cfg, mode="pmap")
201
+ D = jax.local_device_count()
202
+
203
+ x0_batch = generate_initial_guess(D, problem.n_decision, problem.bounds) # (D, n)
204
+ p_fixed = jnp.array([0.5, -0.3, 0.8, 0.1])
205
+ p_batch = jnp.broadcast_to(p_fixed, (D, 4)) # (D, m)
206
+
207
+ state = solve_batch(x0_batch, p_batch)
208
+ results = batch_state_to_result(state, problem)
209
+
210
+ # Best start: prefer converged, then min f
211
+ best = jnp.argmin(jnp.where(results.success,
212
+ results.objective,
213
+ results.objective + 1e10))
214
+
215
+ # --- Parametric sweep across N >> D: chunk along axis 0 -----------------
216
+ N = 1024
217
+ key = jax.random.PRNGKey(0)
218
+ params_all = jax.random.normal(key, (N, 4))
219
+ x0_all = jnp.zeros((N, 4))
220
+
221
+ # Reshape to (N // D, D, ...) and iterate one replicated call per chunk.
222
+ x0_chunks = x0_all.reshape(N // D, D, 4)
223
+ params_chunks = params_all.reshape(N // D, D, 4)
224
+ states = [solve_batch(x0_chunks[i], params_chunks[i]) for i in range(N // D)]
225
+
226
+ # Flatten back to (N, ...) along axis 0
227
+ state_all = jax.tree.map(
228
+ lambda *xs: jnp.concatenate(xs, axis=0), *states
229
+ )
230
+ results_all = batch_state_to_result(state_all, problem)
231
+ ```
232
+
233
+ **Rules of thumb.**
234
+
235
+ | Situation | Recommended mode |
236
+ |---|---|
237
+ | Batch fits on one GPU / CPU, ≤ few thousand instances | `mode="vmap"` (or `factory.solve_batch`) |
238
+ | Multi-start on multi-core host (`XLA_FLAGS=--xla_force_host_platform_device_count=D`) | `mode="pmap"` |
239
+ | Multi-GPU / TPU parametric sweep, N ≫ D | `mode="pmap"` + chunk `N → (N/D, D, …)` |
240
+ | Inside an outer `jax.pmap` | `mode="vmap"` — never nest `pmap` |
241
+
242
+ **Constraints.**
243
+
244
+ * `pmap` requires axis-0 length to equal `jax.local_device_count()` exactly
245
+ (chunk externally for larger batches — see above).
246
+ * `pmap` **cannot** be nested inside another `pmap`. Compose as
247
+ `pmap(vmap(...))`, not `pmap(pmap(...))`.
248
+ * To simulate `D` CPU devices for development set, **before** importing JAX:
249
+ ```bash
250
+ XLA_FLAGS=--xla_force_host_platform_device_count=8 python script.py
251
+ ```
252
+ * `pmap` replicates the closed-over `problem` and `cfg` to each device on first
253
+ call — compile-time cost is paid once, then amortised across all subsequent
254
+ `solve_batch` invocations with the same shapes.
255
+
256
+ ### 4. CasADi / IPOPT
257
+
258
+ ```python
259
+ import jax.numpy as jnp
260
+ from septal.casadax import NLPProblem, SolverFactory, casadify_reverse
261
+
262
+ def my_objective(x): # x: (n_d, 1) — CasADi column convention
263
+ return jnp.sum(x ** 2).reshape(1, 1)
264
+
265
+ n_d = 3
266
+ objective_cb = casadify_reverse(my_objective, n_d)
267
+
268
+ problem = NLPProblem(
269
+ objective=objective_cb,
270
+ bounds=[jnp.zeros(n_d), jnp.ones(n_d)],
271
+ )
272
+
273
+ cfg = type('C', (), {'n_starts': 5, 'max_solution_time': 60.0})()
274
+ factory = SolverFactory.from_problem(cfg, "general_constrained_nlp", problem)
275
+ result = factory.solve(factory.initial_guess())
276
+
277
+ print(result.success, result.objective, result.decision_variables)
278
+ ```
279
+
280
+ ---
281
+
282
+ ## API reference
283
+
284
+ ### `ParametricNLPProblem` (`septal.jax.sqp`)
285
+
286
+ ```python
287
+ @dataclass
288
+ class ParametricNLPProblem:
289
+ objective: Callable # f(x, p) -> scalar
290
+ bounds: List[Any] # [lb, ub], each (n,)
291
+ n_decision: int # n — dim of x
292
+ n_params: int # m — dim of p (0 for non-parametric)
293
+ constraints: Optional[Callable] = None # g(x, p) -> (n_g,)
294
+ constraint_lhs: Optional[Any] = None # (n_g,) lower bound on g
295
+ constraint_rhs: Optional[Any] = None # (n_g,) upper bound on g
296
+ n_constraints: Optional[int] = None # inferred from g if None
297
+ ```
298
+
299
+ Equality constraint: set `constraint_lhs[i] = constraint_rhs[i] = c`.
300
+ Inequality `g(x) ≤ 0`: set `constraint_lhs[i] = -inf`, `constraint_rhs[i] = 0`.
301
+
302
+ ### `SQPConfig` (`septal.jax.sqp`)
303
+
304
+ | Parameter | Default | Description |
305
+ |---|---|---|
306
+ | `max_iter` | `100` | Outer SQP iterations |
307
+ | `tol_stationarity` | `1e-6` | Projected-gradient stationarity tolerance |
308
+ | `tol_feasibility` | `1e-6` | L∞ constraint violation tolerance |
309
+ | `line_search_beta` | `0.5` | Armijo backtracking step multiplier |
310
+ | `line_search_c` | `1e-4` | Armijo sufficient-decrease constant |
311
+ | `line_search_alpha0` | `1.0` | Initial step length |
312
+ | `max_line_search` | `30` | Maximum backtracking trials |
313
+ | `penalty_init` | `1.0` | Initial L1 penalty parameter ρ₀ |
314
+ | `penalty_eps` | `1e-3` | Penalty margin ε_ρ |
315
+ | `penalty_decrease_factor` | `0.999` | Slow penalty shrink when feasible |
316
+ | `bfgs_init_scale` | `1.0` | H₀ = scale · I |
317
+ | `bfgs_skip_tol` | `1e-10` | Skip BFGS update when ‖s‖² < tol |
318
+ | `bfgs_max_cond` | `1e8` | Reset H to I when cond(H) > threshold |
319
+ | `admm_n_iter` | `500` | Fixed ADMM inner iterations |
320
+ | `admm_rho` | `1.0` | Initial ADMM penalty ρ₀ |
321
+ | `admm_sigma` | `1e-6` | ADMM proximal regularisation σ |
322
+ | `admm_alpha` | `1.6` | ADMM over-relaxation factor |
323
+ | `admm_adaptive_rho` | `True` | Enable adaptive ρ scaling |
324
+ | `admm_rho_eq_scale` | `100.0` | Per-row ρ multiplier for equality constraints |
325
+ | `admm_ruiz_iter` | `10` | Ruiz equilibration iterations (0 = disable) |
326
+ | `admm_polish` | `True` | OSQP-style active-set polishing |
327
+ | `admm_polish_reg` | `1e-8` | KKT system regularisation for polishing |
328
+ | `admm_polish_refine` | `3` | Iterative refinement steps in polishing |
329
+ | `use_exact_hessian` | `False` | Use `jax.hessian` instead of BFGS |
330
+ | `hess_reg_delta` | `1e-4` | Minimum eigenvalue floor for inertia correction |
331
+ | `hess_reg_min` | `1e-8` | Minimum regularisation shift |
332
+ | `nonmonotone_window` | `5` | Non-monotone line search memory M (1 = standard Armijo) |
333
+ | `stagnation_patience` | `30` | Reset after N consecutive near-zero steps |
334
+ | `stagnation_alpha_tol` | `1e-6` | Step-size threshold for stagnation detection |
335
+ | `stagnation_reset_hessian` | `True` | Reset H to I on stagnation |
336
+ | `stagnation_reset_penalty` | `True` | Reset ρ to `penalty_init` on stagnation |
337
+
338
+ ### `SQPState` — JAX pytree fields
339
+
340
+ All fields are JAX arrays. `SQPState` is a `NamedTuple` and therefore a valid JAX pytree, compatible with `vmap`, `scan`, and `pmap`.
341
+
342
+ | Field | Shape | Description |
343
+ |---|---|---|
344
+ | `x` | `(n,)` | Current primal iterate |
345
+ | `params_p` | `(m,)` | Parameter vector (fixed throughout solve) |
346
+ | `lam` | `(n_g,)` | Dual variables for `g(x, p)` |
347
+ | `hessian` | `(n, n)` | BFGS approximation or exact Lagrangian Hessian |
348
+ | `grad_lag` | `(n,)` | `∇_x L(x, λ, p)` |
349
+ | `f_val` | `()` | `f(x, p)` |
350
+ | `penalty` | `()` | L1 penalty parameter ρ |
351
+ | `merit` | `()` | L1 merit `φ(x; ρ)` |
352
+ | `stationarity` | `()` | Projected-gradient KKT stationarity |
353
+ | `feasibility` | `()` | L∞ constraint violation |
354
+ | `iteration` | `()` | Iteration counter |
355
+ | `converged` | `()` | `True` once KKT tolerances satisfied |
356
+ | `merit_window` | `(M,)` | Rolling merit buffer for non-monotone line search |
357
+ | `stagnation_count` | `()` | Consecutive near-zero step count |
358
+ | `alpha_last` | `()` | Last accepted step length |
359
+
360
+ ### `SQPResult` fields
361
+
362
+ | Field | Single solve | Batched | Description |
363
+ |---|---|---|---|
364
+ | `success` | `bool` | `(N,)` | KKT tolerances satisfied |
365
+ | `objective` | scalar | `(N,)` | `f(x*, p)` |
366
+ | `decision_variables` | `(n,)` | `(N, n)` | `x*` |
367
+ | `multipliers` | `(n_g,)` | `(N, n_g)` | `λ*` |
368
+ | `constraints` | `(n_g,)` | `(N, n_g)` | `g(x*, p)` |
369
+ | `kkt_stationarity` | scalar | `(N,)` | Stationarity residual |
370
+ | `kkt_feasibility` | scalar | `(N,)` | Feasibility residual |
371
+ | `iterations` | int | `(N,)` | Iterations used |
372
+ | `timing` | float | float | Wall-clock seconds |
373
+
374
+ ### Core solver functions (`septal.jax.sqp.solver`)
375
+
376
+ ```python
377
+ # Early-exit — JIT-compilable, NOT directly vmappable
378
+ sqp_solve_single(problem, x0, p, cfg) -> SQPState
379
+
380
+ # Fixed iterations — vmappable, use for batched solves
381
+ sqp_solve_scan(problem, x0, p, cfg) -> SQPState
382
+
383
+ # JIT-compiled vmappable solver (used by ParametricSQPFactory)
384
+ make_solver(problem, cfg) -> Callable[[x0, p], SQPState]
385
+
386
+ # Batched solver over devices
387
+ make_batch_solver(problem, cfg, mode="pmap") -> Callable[[x0_batch, p_batch], SQPState]
388
+
389
+ # Convert state to result
390
+ state_to_result(state, problem, timing=0.0) -> SQPResult
391
+ batch_state_to_result(state, problem, timing=0.0) -> SQPResult
392
+ ```
393
+
394
+ ### Utilities (`septal.casadax.utilities`)
395
+
396
+ ```python
397
+ generate_initial_guess(n_starts, n_d, bounds) -> jnp.ndarray # (n_starts, n_d)
398
+ ```
399
+
400
+ Generates Sobol-sequence quasi-random points within `bounds`, using `scramble=True, seed=42` for reproducibility.
401
+
402
+ ### AD callbacks (`septal.casadax`)
403
+
404
+ ```python
405
+ casadify_forward(fn, n_d) # force JVP (forward) mode
406
+ casadify_reverse(fn, n_d) # force VJP (reverse) mode
407
+ casadify(fn, n_d, n_out) # auto-select: forward if n_out > n_d
408
+ ```
409
+
410
+ ---
411
+
412
+ ## SQP algorithm
413
+
414
+ ### Core iteration
415
+
416
+ At iterate `(x_k, λ_k)`:
417
+
418
+ 1. **Evaluate** `f_k, ∇f_k, g_k, J_k` via `jax.value_and_grad` and `jax.jacfwd`
419
+ 2. **QP subproblem** — solve for step `d_k`:
420
+ ```
421
+ min ½ dᵀ H_k d + ∇f_kᵀ d
422
+ s.t. lhs - g_k ≤ J_k d ≤ rhs - g_k (linearised constraints)
423
+ lb - x_k ≤ d ≤ ub - x_k (box constraints on step)
424
+ ```
425
+ Solved via OSQP-style ADMM with Ruiz equilibration and active-set polishing.
426
+ 3. **Penalty update** — `ρ_k = max(‖λ_k‖_∞ + ε_ρ, ρ_{k-1})`
427
+ 4. **Line search** — Armijo backtracking on L1 merit `φ(x; ρ) = f + ρ‖c‖₁`
428
+ 5. **Primal update** — `x_{k+1} = x_k + α_k d_k`, `λ_{k+1} = λ_QP`
429
+ 6. **Hessian update** — damped BFGS (Powell 1978) or exact `∇²_xx L` via `jax.hessian`
430
+ 7. **Convergence** — projected-gradient stationarity ≤ `tol_stationarity` **and** L∞ feasibility ≤ `tol_feasibility`
431
+
432
+ ### Robustness features
433
+
434
+ **Exact Lagrangian Hessian** (`use_exact_hessian=True`): computes `∇²_xx L = ∇²f + Σ λᵢ ∇²gᵢ` via `jax.hessian`. Combined with inertia correction (`hess_reg_delta`) to ensure the QP Hessian remains PD on curved constraint manifolds.
435
+
436
+ **Ruiz diagonal equilibration** (`admm_ruiz_iter=10`): scales constraint rows/columns to unit ∞-norm before ADMM. Removes scale imbalance that stalls ADMM convergence on problems with mixed-scale constraints.
437
+
438
+ **OSQP-style polishing** (`admm_polish=True`): after ADMM, identifies the active set and solves a reduced KKT system with iterative refinement. Three acceptance gates prevent the polished solution from degrading the ADMM result: (1) must be finite, (2) primal residual must not increase, (3) must have active constraints.
439
+
440
+ **Non-monotone line search** (`nonmonotone_window=5`): reference merit is `max(merit_window)` — allows temporary merit increases to escape saddle points (Grippo et al. 1986).
441
+
442
+ **Stagnation reset** (`stagnation_patience=30`): after `N` consecutive near-zero steps, resets `H → bfgs_init_scale · I` and `ρ → penalty_init`. Helps escape local traps on non-convex problems.
443
+
444
+ **Equality-row boosting** (`admm_rho_eq_scale=100.0`): multiplies the ADMM penalty for equality rows by this factor, avoiding the O(1/k) convergence degradation specific to equalities.
445
+
446
+ ### `lax.scan` vs `lax.while_loop`
447
+
448
+ | | `sqp_solve_scan` | `sqp_solve_single` |
449
+ |---|---|---|
450
+ | Iterations | Always `max_iter` | Early exit on convergence |
451
+ | Vmappable | Yes (`jax.vmap`) | No (variable iteration count) |
452
+ | JIT-compilable | Yes | Yes |
453
+ | Use for | Batched solves | Single or sequential multi-start |
454
+
455
+ Converged iterates in `scan` mode are frozen via:
456
+ ```python
457
+ jax.tree.map(lambda new, old: jnp.where(state.converged, old, new), new_state, state)
458
+ ```
459
+
460
+ ---
461
+
462
+ ## Benchmark results
463
+
464
+ 28 HS/Rosen test problems × 5 Sobol starts = 140 total runs.
465
+
466
+ | Configuration | Solved / 140 |
467
+ |---|---|
468
+ | Baseline BFGS | 74 / 140 |
469
+ | + exact Lagrangian Hessian | 82 / 140 |
470
+ | + Ruiz equilibration | 94 / 140 |
471
+ | + OSQP polishing | 95 / 140 |
472
+ | + inertia correction + non-monotone LS + stagnation reset | **139 / 140** |
473
+
474
+ One failure: `hs023` start 1/5 — exterior-of-ellipse feasible set traps the Sobol point. Not a solver defect; multi-start handles this.
475
+
476
+ Benchmark config:
477
+ ```python
478
+ SQPConfig(
479
+ max_iter=1000, admm_n_iter=1000, tol=1e-7,
480
+ use_exact_hessian=True, admm_ruiz_iter=10, admm_polish=True,
481
+ penalty_init=10.0, admm_rho_eq_scale=100.0,
482
+ )
483
+ ```
484
+
485
+ ---
486
+
487
+ ## Schema — `NLPProblem` (`septal.casadax`)
488
+
489
+ | Field | Type | Description |
490
+ |---|---|---|
491
+ | `objective` | `Callable` | JAX / CasADi objective |
492
+ | `bounds` | `[lb, ub]` | Box bounds |
493
+ | `constraints` | `Callable` (optional) | `g(x) -> (n_g,)` |
494
+ | `constraint_lhs` / `rhs` | array (optional) | Bounds on `g(x)` |
495
+ | `n_starts` | `int` | Multi-start count (default 5) |