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.
- septal-0.2.0/CHANGELOG.md +50 -0
- septal-0.2.0/LICENSE +21 -0
- septal-0.2.0/MANIFEST.in +3 -0
- septal-0.2.0/PKG-INFO +495 -0
- septal-0.2.0/README.md +452 -0
- septal-0.2.0/pyproject.toml +105 -0
- septal-0.2.0/setup.cfg +4 -0
- septal-0.2.0/src/septal/__init__.py +42 -0
- septal-0.2.0/src/septal/casadax/__init__.py +55 -0
- septal-0.2.0/src/septal/casadax/callbacks.py +304 -0
- septal-0.2.0/src/septal/casadax/factory.py +171 -0
- septal-0.2.0/src/septal/casadax/schema.py +102 -0
- septal-0.2.0/src/septal/casadax/solvers.py +367 -0
- septal-0.2.0/src/septal/casadax/utilities.py +69 -0
- septal-0.2.0/src/septal/jax/__init__.py +5 -0
- septal-0.2.0/src/septal/jax/sqp/__init__.py +94 -0
- septal-0.2.0/src/septal/jax/sqp/convergence.py +153 -0
- septal-0.2.0/src/septal/jax/sqp/factory.py +230 -0
- septal-0.2.0/src/septal/jax/sqp/filter.py +542 -0
- septal-0.2.0/src/septal/jax/sqp/hessian.py +222 -0
- septal-0.2.0/src/septal/jax/sqp/line_search.py +269 -0
- septal-0.2.0/src/septal/jax/sqp/qp_subproblem.py +630 -0
- septal-0.2.0/src/septal/jax/sqp/schema.py +394 -0
- septal-0.2.0/src/septal/jax/sqp/solver.py +943 -0
- septal-0.2.0/src/septal/py.typed +0 -0
- septal-0.2.0/src/septal.egg-info/PKG-INFO +495 -0
- septal-0.2.0/src/septal.egg-info/SOURCES.txt +44 -0
- septal-0.2.0/src/septal.egg-info/dependency_links.txt +1 -0
- septal-0.2.0/src/septal.egg-info/requires.txt +18 -0
- septal-0.2.0/src/septal.egg-info/top_level.txt +1 -0
- septal-0.2.0/tests/conftest.py +67 -0
- septal-0.2.0/tests/sqp/__init__.py +0 -0
- septal-0.2.0/tests/sqp/conftest.py +98 -0
- septal-0.2.0/tests/sqp/test_convergence.py +162 -0
- septal-0.2.0/tests/sqp/test_factory.py +219 -0
- septal-0.2.0/tests/sqp/test_filter.py +816 -0
- septal-0.2.0/tests/sqp/test_hessian.py +108 -0
- septal-0.2.0/tests/sqp/test_line_search.py +202 -0
- septal-0.2.0/tests/sqp/test_qp_subproblem.py +552 -0
- septal-0.2.0/tests/sqp/test_schema.py +203 -0
- septal-0.2.0/tests/sqp/test_solver.py +618 -0
- septal-0.2.0/tests/test_callbacks.py +142 -0
- septal-0.2.0/tests/test_factory.py +137 -0
- septal-0.2.0/tests/test_schema.py +91 -0
- septal-0.2.0/tests/test_solvers.py +195 -0
- 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.
|
septal-0.2.0/MANIFEST.in
ADDED
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) |
|