JAX Interface¶
Pure-function wrappers of the solvers for jax.jit and jax.vmap, available
as cupiqp.jax. See the JAX Interface guide for the
workflow and the argument layouts.
DenseSolver¶
The JAX operator cupiqp.jax.DenseSolver, distinct from the core
cupiqp.DenseSolver it runs.
DenseSolver
¶
Bases: JaxSolverBase
A dense convex QP as a pure JAX function, solved on the GPU by the
core :class:cupiqp.DenseSolver. This is cupiqp.jax.DenseSolver: it
takes and returns JAX arrays, and :meth:solve is a pure function.
:meth:solve solves
and returns a :class:~cupiqp.jax.QPSolution of JAX arrays. The call is
a pure function of its array arguments: it works eagerly, under
jax.jit and under jax.vmap, and keeps no state the caller can
observe. The solve itself runs the core solver through an XLA custom
call on the GPU; nothing is re-implemented in jax.numpy.
What is fixed where. The solver object holds the floating-point
dtype and the :attr:settings. Everything else is read from the arrays
of each call: the dimensions, which constraint blocks are given, and the
batch size. Under jax.jit these are static shapes, so a function
that calls :meth:solve is compiled once per distinct problem
structure, as any JAX function is. Which entries of a bound are infinite
is not structure: it may change from call to call without
recompilation. Settings are read at each call; like any non-array value,
a function compiled by jax.jit keeps the settings it was traced
with, so set them before the first call.
Batching. Every argument is either shared, in the shape of one
problem (P of shape (n, n), c of shape (n,), ...), or
batched, with a leading axis of size B ((B, n, n),
(B, n), ...). The batched arguments must agree on B; shared
arguments are used by every problem of the batch without being copied
B times by you. If every argument is shared, one problem is solved
and the solution has no batch axis. jax.vmap over :meth:solve
produces the same single batched solve: mapped arguments become batched,
unmapped ones stay shared. Mapping over an argument that already has a
batch axis (nested batching) is not supported.
Gradients. jax.grad and jax.vjp through :meth:solve work
for every array argument, by implicit differentiation of the KKT
conditions (the core's backward_from_state()). The ten solution
fields are differentiable; status, iterations, primal_res
and dual_res are diagnostics with no gradient (a loss on them gets a
zero gradient). A shared argument's gradient is summed over the batch.
The backward refactorizes the KKT system at the saved solution, so it
costs about one iteration of the forward; the residuals JAX keeps are
the inputs and the solution of each differentiated call. Settings used
by the backward (gradient_on_failure, gradient_smoothing*) are
read when the gradient is traced. Second derivatives are not supported.
Failures do not raise. A problem that does not converge, or is
detected infeasible, is reported in solution.status with a code of
:class:cupiqp.Status; the other fields hold the last iterate. Read
status where you need it, for instance jnp.where(status == 0, ...).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
float64 or float32
|
Floating-point precision of the solve. All array arguments must
have this dtype; the solver never casts. |
float64
|
settings
|
Settings
|
Solver configuration; by default the defaults of the core solver
for |
None
|
Examples:
One problem, then the same structure under jit with a batch of
right-hand sides:
import jax, jax.numpy as jnp
jax.config.update("jax_enable_x64", True)
import cupiqp
from cupiqp.jax import DenseSolver
solver = DenseSolver()
solver.settings.eps_abs = 1e-6
solver.settings.eps_rel = 1e-6
P = jnp.eye(2)
c = jnp.array([-1.0, -4.0])
G = jnp.array([[1.0, 1.0]])
h_u = jnp.array([1.0])
h_l = jnp.array([-jnp.inf]) # one-sided row
sol = solver.solve(P, c, G=G, h_l=h_l, h_u=h_u) # sol.x has shape (2,)
print(cupiqp.Status(int(sol.status)).name)
@jax.jit
def solve_many(cs): # cs: (B, 2), everything else shared
return solver.solve(P, cs, G=G, h_l=h_l, h_u=h_u).x
xs = solve_many(jnp.stack([c, 2 * c])) # (2, 2), one custom call
xs2 = jax.vmap(lambda c: solver.solve(P, c, G=G, h_l=h_l, h_u=h_u).x)(jnp.stack([c, 2 * c]))
Notes
The solver object owns no GPU memory. For every distinct problem signature
(dtype, dimensions, given blocks, batch layout, forward settings) the
interface keeps one core solver alive in a process-wide
cache, so that repeated calls reuse its allocations and factorization
workspace. The first call of a signature sets that solver up and is
slow; keep shapes, batch sizes and settings stable, and warm up with one
call. :func:cupiqp.jax.release_solver_memory frees the solvers.
Calls of the same signature are serialized.
Two settings are rejected because they would break the pure-function
contract: preconditioner_reuse_on_update (results would depend on
earlier calls) and verbose (printing is a side effect XLA may skip).
The gradient settings (gradient_on_failure, gradient_smoothing*)
are part of the compiled call like the forward settings; enable_grad
and compute_timings are ignored.
JAX reserves most of the GPU memory when its backend starts, which can
leave the core solver unable to create its cuSOLVER or cuDSS handles.
Set XLA_PYTHON_CLIENT_PREALLOCATE=false (or a small
XLA_PYTHON_CLIENT_MEM_FRACTION) in the environment before JAX is
initialized.
Every call copies its inputs into the solver and its results into JAX-owned outputs. Both copies run on the GPU in stream order; the interface never waits on the host.
Source code in cupiqp/interfaces/jax/base.py
solve
¶
solve(
P: Array,
c: Array,
A: Array | None = None,
b: Array | None = None,
G: Array | None = None,
h_u: Array | None = None,
h_l: Array | None = None,
x_u: Array | None = None,
x_l: Array | None = None,
) -> QPSolution
Solve the QP (or the batch of QPs) given by the arrays.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
P
|
Array
|
Quadratic cost, |
required |
c
|
Array
|
Linear cost, |
required |
A
|
Array
|
Equality constraints |
None
|
b
|
Array
|
Equality constraints |
None
|
G
|
Array
|
Inequalities |
None
|
h_l
|
Array
|
Inequalities |
None
|
h_u
|
Array
|
Inequalities |
None
|
x_l
|
Array
|
Box bounds |
None
|
x_u
|
Array
|
Box bounds |
None
|
Returns:
| Type | Description |
|---|---|
QPSolution
|
The solution, with a leading batch axis if any argument was batched. Differentiable with respect to every array argument. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If an argument does not have the solver dtype. |
ValueError
|
If a setting is not supported by the JAX interface, an argument
has the wrong rank or shape, the batched arguments disagree on
|
Source code in cupiqp/interfaces/jax/dense.py
SparseSolver¶
SparseSolver
¶
SparseSolver(
P: Any,
A: Any | None = None,
G: Any | None = None,
dtype: Any = jax.numpy.float64,
settings: Any = None,
)
Bases: JaxSolverBase
A sparse convex QP as a pure JAX function, solved on the GPU by the
core :class:cupiqp.SparseSolver. This is cupiqp.jax.SparseSolver:
it takes and returns JAX arrays, and :meth:solve is a pure function.
It solves the same QP as :class:DenseSolver,
with P, A and G stored in CSR form. The sparsity patterns
are part of the structure: they are given once, to the constructor, as
the (indptr, indices) of each matrix, and every call of
:meth:solve takes only the stored values of each matrix, in the
order of its pattern. This splits the core's CSR triple
(indptr, indices, values) into what is fixed and what changes. Changing a pattern means creating
a new solver, which also means a new symbolic analysis of the KKT system
in the core, so build the solver outside your loop.
Everything else is as for :class:DenseSolver: values are shared or
batched ((nnz,) or (B, nnz) for a matrix, (k,) or (B, k)
for a vector), the dtype and :attr:settings are held by the solver
object, :meth:solve works eagerly and under jax.jit and
jax.vmap, failures are reported in solution.status, and
gradients flow to every array argument (for a matrix, to its stored
values).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
P
|
(indptr, indices)
|
CSR pattern of the |
required |
A
|
(indptr, indices)
|
CSR pattern of the |
None
|
G
|
(indptr, indices)
|
CSR pattern of the |
None
|
dtype
|
float64 or float32
|
Floating-point precision of the solve; see :class: |
float64
|
settings
|
Settings
|
Solver configuration; see :class: |
None
|
Examples:
import jax, jax.numpy as jnp
import scipy.sparse as sp
jax.config.update("jax_enable_x64", True)
from cupiqp.jax import SparseSolver
P = sp.csr_matrix(sp.diags([2.0, 1.0, 2.0])) # (3, 3) with 3 stored entries
A = sp.csr_matrix([[1.0, 1.0, 1.0]]) # (1, 3) with 3 stored entries
solver = SparseSolver(P=(P.indptr, P.indices), # patterns fixed here
A=(A.indptr, A.indices))
sol = solver.solve(jnp.asarray(P.data), jnp.array([1.0, -1.0, 0.0]),
A=jnp.asarray(A.data), b=jnp.array([1.0]))
@jax.jit
def solve_many(P_values, cs): # (B, 3) and (B, 3)
return solver.solve(P_values, cs, A=jnp.asarray(A.data), b=jnp.array([1.0])).x
See Also
DenseSolver : the same interface for dense problems, with the full description of batching, settings, caching and memory.
Source code in cupiqp/interfaces/jax/sparse.py
solve
¶
solve(
P: Array,
c: Array,
A: Array | None = None,
b: Array | None = None,
G: Array | None = None,
h_u: Array | None = None,
h_l: Array | None = None,
x_u: Array | None = None,
x_l: Array | None = None,
) -> QPSolution
Solve the QP (or the batch of QPs) given by the arrays.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
P
|
Array
|
Stored values of the quadratic cost, |
required |
c
|
Array
|
Linear cost, |
required |
A
|
Array
|
Stored values of |
None
|
b
|
Array
|
Stored values of |
None
|
G
|
Array
|
Stored values of |
None
|
h_l
|
Array
|
Stored values of |
None
|
h_u
|
Array
|
Stored values of |
None
|
x_l
|
Array
|
Box bounds |
None
|
x_u
|
Array
|
Box bounds |
None
|
Returns:
| Type | Description |
|---|---|
QPSolution
|
The solution, with a leading batch axis if any argument was batched. Differentiable with respect to every array argument; matrix gradients are the gradients of the stored values. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If an argument does not have the solver dtype. |
ValueError
|
If an argument has the wrong rank or shape (a value array whose
length is not the pattern's |
Source code in cupiqp/interfaces/jax/sparse.py
MultistageSolver¶
MultistageSolver
¶
Bases: JaxSolverBase
A multistage (block-structured) convex QP as a pure JAX function,
solved on the GPU by the core :class:cupiqp.MultistageSolver. This is
cupiqp.jax.MultistageSolver: it takes and returns JAX arrays, and
:meth:solve is a pure function.
It solves the same QP as :class:DenseSolver,
where the matrices are block-structured as in optimal control: N
stages of d variables (n = N * d), P symmetric
block-tridiagonal, A and G block lower-bidiagonal. The arguments
of :meth:solve are exactly those of the core setup(): each matrix
is a (diag, offdiag) pair of block arrays, and each vector is in the
block layout (num_blocks, rows) or the flat layout (k,). The
block sizes, and which matrices have off-diagonal blocks, are read from
the shapes of each call; under jax.jit they are static, like the
dimensions of :class:DenseSolver.
Everything else is as for :class:DenseSolver: arrays are shared or
batched (with a leading batch axis), the dtype and :attr:settings are
held by the solver object, :meth:solve works eagerly and under
jax.jit and jax.vmap, failures are reported in
solution.status, and gradients flow to every array argument,
including each block array. The solution
is in the flat layout, as in the core: x has shape (B, n); use
x.reshape(B, N, d) for the per-stage view.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
float64 or float32
|
Floating-point precision of the solve; see :class: |
float64
|
settings
|
Settings
|
Solver configuration; see :class: |
None
|
Examples:
import jax, jax.numpy as jnp
jax.config.update("jax_enable_x64", True)
from cupiqp.jax import MultistageSolver
N, d = 10, 3
P_diag = jnp.broadcast_to(2.0 * jnp.eye(d), (N, d, d))
P_offdiag = jnp.broadcast_to(-0.5 * jnp.eye(d), (N - 1, d, d))
solver = MultistageSolver()
@jax.jit
def solve_many(cs): # (B, N, d), the rest shared
return solver.solve(P=(P_diag, P_offdiag), c=cs,
x_l=-jnp.ones((N, d)), x_u=jnp.ones((N, d))).x
xs = solve_many(jnp.ones((8, N, d))) # (8, N * d)
See Also
DenseSolver : the same interface for dense problems, with the full description of batching, settings, caching and memory.
Source code in cupiqp/interfaces/jax/base.py
solve
¶
solve(
P: tuple[Array, Array | None],
c: Array,
A: tuple[Array, Array | None] | None = None,
b: Array | None = None,
G: tuple[Array, Array | None] | None = None,
h_u: Array | None = None,
h_l: Array | None = None,
x_u: Array | None = None,
x_l: Array | None = None,
) -> QPSolution
Solve the QP (or the batch of QPs) given by the arrays.
Every array is given for one problem, shared by the whole batch, or
with a leading batch axis B. The shapes below are for one problem.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
P
|
tuple of jax.Array
|
|
required |
c
|
Array
|
Linear cost, |
required |
A
|
optional
|
Equality constraints |
None
|
b
|
optional
|
Equality constraints |
None
|
G
|
optional
|
Inequalities |
None
|
h_l
|
optional
|
Inequalities |
None
|
h_u
|
optional
|
Inequalities |
None
|
x_l
|
Array
|
Box bounds, |
None
|
x_u
|
Array
|
Box bounds, |
None
|
Returns:
| Type | Description |
|---|---|
QPSolution
|
The solution in the flat layout, with a leading batch axis if any argument was batched. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If a matrix is not a |
ValueError
|
If the block shapes are inconsistent, an argument has the wrong
rank or shape, the batched arguments disagree on |
Source code in cupiqp/interfaces/jax/multistage.py
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 | |
QPSolution¶
QPSolution
¶
Bases: NamedTuple
Solution of one QP, or of a batch of QPs, returned by the solve
method of a JAX solver such as :class:~cupiqp.jax.DenseSolver.
Every field is a jax.Array owned by JAX: it can be used in further
JAX work, inside or outside jax.jit, and is never overwritten by a
later solve. For a batched call the leading axis of every field is the
batch axis of size B; for an unbatched call there is no leading
axis, and the shapes below lose their B.
Dual and slack variables of a constraint block that was not passed to
the call have zero width ((B, 0)) rather than being None, so the
structure of the tuple is the same for every problem. The width of a
block does not depend on which of its bound entries are infinite.
Attributes:
| Name | Type | Description |
|---|---|---|
x |
Array
|
Primal solution, |
y |
Array
|
Multipliers of the equality constraints |
z_l, z_u |
Array
|
Multipliers of the lower and upper inequality bounds
|
z_bl, z_bu |
Array
|
Multipliers of the lower and upper box bounds |
s_l, s_u, s_bl, s_bu |
Array
|
Slacks of the corresponding inequality and box bounds. |
status |
Array
|
One int32 code of :class: |
iterations |
Array
|
Number of interior-point iterations per problem, |
primal_res, dual_res |
Array
|
Final primal and dual residuals per problem, |
Cache¶
release_solver_memory
¶
Wait for pending solves, then release every core solver the JAX interface keeps, and its GPU memory. Compiled functions stay valid; their next call creates its solver again (a slow first call).