Skip to content

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

DenseSolver(
    dtype: Any = jax.numpy.float64,
    settings: Settings | None = None,
)

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

\[ \begin{aligned} \min_{x}\quad & \tfrac{1}{2}\, x^\top P x + c^\top x \\ \text{s.t.}\quad & A x = b, \\ & h_l \le G x \le h_u, \\ & x_l \le x \le x_u, \end{aligned} \]

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 requires jax.config.update("jax_enable_x64", True) before any array is created.

float64
settings Settings

Solver configuration; by default the defaults of the core solver for dtype. Also available, and mutable, as :attr:settings. preconditioner_reuse_on_update and verbose must stay False. gradient_on_failure and the gradient_smoothing* settings apply to gradients through :meth:solve.

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
def __init__(self, dtype: Any = jax.numpy.float64, settings: Settings | None = None) -> None:
    if np.dtype(dtype) == np.float32:
        self._dtype = wp.float32
    elif np.dtype(dtype) == np.float64:
        self._dtype = wp.float64
    else:
        raise TypeError(f"dtype must be float32 or float64; got {dtype!r}.")
    if self._dtype is wp.float64 and not jax.config.jax_enable_x64:
        raise RuntimeError(
            f"{type(self).__name__} with dtype float64 requires 64-bit JAX arrays: "
            "call jax.config.update('jax_enable_x64', True) before creating any "
            "array, or use dtype=jnp.float32."
        )
    self.settings = Settings.for_dtype(self._dtype) if settings is None else settings

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, (n, n) or (B, n, n), symmetric positive semidefinite. Required.

required
c Array

Linear cost, (n,) or (B, n). Required.

required
A Array

Equality constraints A x = b: A of shape (p, n) or (B, p, n), b of shape (p,) or (B, p). Give both or neither.

None
b Array

Equality constraints A x = b: A of shape (p, n) or (B, p, n), b of shape (p,) or (B, p). Give both or neither.

None
G Array

Inequalities h_l <= G x <= h_u: G of shape (m, n) or (B, m, n), bounds (m,) or (B, m). At least one bound is required with G; a bound that is not given is absent (its multipliers have zero width). Use -inf / +inf entries for rows that are one-sided in a given bound.

None
h_l Array

Inequalities h_l <= G x <= h_u: G of shape (m, n) or (B, m, n), bounds (m,) or (B, m). At least one bound is required with G; a bound that is not given is absent (its multipliers have zero width). Use -inf / +inf entries for rows that are one-sided in a given bound.

None
h_u Array

Inequalities h_l <= G x <= h_u: G of shape (m, n) or (B, m, n), bounds (m,) or (B, m). At least one bound is required with G; a bound that is not given is absent (its multipliers have zero width). Use -inf / +inf entries for rows that are one-sided in a given bound.

None
x_l Array

Box bounds x_l <= x <= x_u, (n,) or (B, n).

None
x_u Array

Box bounds x_l <= x <= x_u, (n,) or (B, n).

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 B, or the blocks are inconsistent (A without b, bounds without G, G without any bound).

Source code in cupiqp/interfaces/jax/dense.py
def solve(
    self,
    P: jax.Array,
    c: jax.Array,
    A: jax.Array | None = None,
    b: jax.Array | None = None,
    G: jax.Array | None = None,
    h_u: jax.Array | None = None,
    h_l: jax.Array | None = None,
    x_u: jax.Array | None = None,
    x_l: jax.Array | None = None,
) -> QPSolution:
    """Solve the QP (or the batch of QPs) given by the arrays.

    Parameters
    ----------
    P : jax.Array
        Quadratic cost, ``(n, n)`` or ``(B, n, n)``, symmetric positive
        semidefinite. Required.
    c : jax.Array
        Linear cost, ``(n,)`` or ``(B, n)``. Required.
    A, b : jax.Array, optional
        Equality constraints ``A x = b``: ``A`` of shape ``(p, n)`` or
        ``(B, p, n)``, ``b`` of shape ``(p,)`` or ``(B, p)``. Give both
        or neither.
    G, h_l, h_u : jax.Array, optional
        Inequalities ``h_l <= G x <= h_u``: ``G`` of shape ``(m, n)`` or
        ``(B, m, n)``, bounds ``(m,)`` or ``(B, m)``. At least one bound
        is required with ``G``; a bound that is not given is absent
        (its multipliers have zero width). Use ``-inf`` / ``+inf``
        entries for rows that are one-sided in a given bound.
    x_l, x_u : jax.Array, optional
        Box bounds ``x_l <= x <= x_u``, ``(n,)`` or ``(B, n)``.

    Returns
    -------
    QPSolution
        The solution, with a leading batch axis if any argument was
        batched. Differentiable with respect to every array argument.

    Raises
    ------
    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
        ``B``, or the blocks are inconsistent (``A`` without ``b``,
        bounds without ``G``, ``G`` without any bound).
    """
    arguments = dict(P=P, c=c, A=A, b=b, G=G, h_u=h_u, h_l=h_l, x_u=x_u, x_l=x_l)
    given = {name: value for name, value in arguments.items() if value is not None}
    check_constraint_blocks(A is not None, b is not None, G is not None, h_l is not None, h_u is not None)
    n = int(c.shape[-1])
    p = int(b.shape[-1]) if b is not None else 0
    m = int(G.shape[-2]) if G is not None else 0
    return self._compiled(given, n, p, m, {"P": (n, n), "A": (p, n), "G": (m, n)}).function(*given.values())

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,

\[ \begin{aligned} \min_{x}\quad & \tfrac{1}{2}\, x^\top P x + c^\top x \\ \text{s.t.}\quad & A x = b, \\ & h_l \le G x \le h_u, \\ & x_l \le x \le x_u, \end{aligned} \]

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 (n, n) quadratic cost: two 1-D int32 or int64 host arrays, e.g. NumPy (for a SciPy csr_matrix M, (M.indptr, M.indices)). Concrete JAX arrays are accepted too; other GPU arrays are not. Store the full symmetric matrix (both triangles). Column indices must be sorted within each row, without duplicates. Every entry that may be nonzero in any problem must be stored; explicit zeros are fine. Required.

required
A (indptr, indices)

CSR pattern of the (p, n) equality constraint matrix. Give it when :meth:solve will take A and b.

None
G (indptr, indices)

CSR pattern of the (m, n) inequality constraint matrix. Give it when :meth:solve will take G and at least one of h_l, h_u.

None
dtype float64 or float32

Floating-point precision of the solve; see :class:DenseSolver.

float64
settings Settings

Solver configuration; see :class:DenseSolver.

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
def __init__(
    self,
    P: Any,
    A: Any | None = None,
    G: Any | None = None,
    dtype: Any = jax.numpy.float64,
    settings: Any = None,
) -> None:
    super().__init__(dtype, settings)
    # The validated patterns as int32 host arrays, and a content hash
    # that identifies them in the signature: two solvers built from
    # equal patterns share one compiled solve and core solver.
    self._csr = {"P": validate_csr_pattern("P", P, None)}
    self._n = len(self._csr["P"][0]) - 1
    self._p = self._m = 0
    if A is not None:
        self._csr["A"] = validate_csr_pattern("A", A, self._n)
        self._p = len(self._csr["A"][0]) - 1
    if G is not None:
        self._csr["G"] = validate_csr_pattern("G", G, self._n)
        self._m = len(self._csr["G"][0]) - 1
    digest = hashlib.sha256()
    for name, (indptr, indices) in self._csr.items():
        digest.update(name.encode())
        digest.update(indptr.tobytes())
        digest.update(indices.tobytes())
    self._pattern_key = (tuple(self._csr), digest.hexdigest())

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, (nnz_P,) or (B, nnz_P), in the order of the pattern given to the constructor. Required.

required
c Array

Linear cost, (n,) or (B, n). Required.

required
A Array

Stored values of A, (nnz_A,) or (B, nnz_A), and b of shape (p,) or (B, p). Give both exactly when the solver has a pattern for A.

None
b Array

Stored values of A, (nnz_A,) or (B, nnz_A), and b of shape (p,) or (B, p). Give both exactly when the solver has a pattern for A.

None
G Array

Stored values of G, (nnz_G,) or (B, nnz_G), and the bounds (m,) or (B, m). Give G exactly when the solver has a pattern for it, with at least one bound. Use -inf / +inf entries for one-sided rows.

None
h_l Array

Stored values of G, (nnz_G,) or (B, nnz_G), and the bounds (m,) or (B, m). Give G exactly when the solver has a pattern for it, with at least one bound. Use -inf / +inf entries for one-sided rows.

None
h_u Array

Stored values of G, (nnz_G,) or (B, nnz_G), and the bounds (m,) or (B, m). Give G exactly when the solver has a pattern for it, with at least one bound. Use -inf / +inf entries for one-sided rows.

None
x_l Array

Box bounds x_l <= x <= x_u, (n,) or (B, n).

None
x_u Array

Box bounds x_l <= x <= x_u, (n,) or (B, n).

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 nnz), the batched arguments disagree on B, or the given matrices do not match the patterns of the solver.

Source code in cupiqp/interfaces/jax/sparse.py
def solve(
    self,
    P: jax.Array,
    c: jax.Array,
    A: jax.Array | None = None,
    b: jax.Array | None = None,
    G: jax.Array | None = None,
    h_u: jax.Array | None = None,
    h_l: jax.Array | None = None,
    x_u: jax.Array | None = None,
    x_l: jax.Array | None = None,
) -> QPSolution:
    """Solve the QP (or the batch of QPs) given by the arrays.

    Parameters
    ----------
    P : jax.Array
        Stored values of the quadratic cost, ``(nnz_P,)`` or
        ``(B, nnz_P)``, in the order of the pattern given to the
        constructor. Required.
    c : jax.Array
        Linear cost, ``(n,)`` or ``(B, n)``. Required.
    A, b : jax.Array, optional
        Stored values of ``A``, ``(nnz_A,)`` or ``(B, nnz_A)``, and
        ``b`` of shape ``(p,)`` or ``(B, p)``. Give both exactly when the
        solver has a pattern for ``A``.
    G, h_l, h_u : jax.Array, optional
        Stored values of ``G``, ``(nnz_G,)`` or ``(B, nnz_G)``, and the
        bounds ``(m,)`` or ``(B, m)``. Give ``G`` exactly when the
        solver has a pattern for it, with at least one bound. Use
        ``-inf`` / ``+inf`` entries for one-sided rows.
    x_l, x_u : jax.Array, optional
        Box bounds ``x_l <= x <= x_u``, ``(n,)`` or ``(B, n)``.

    Returns
    -------
    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
    ------
    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 ``nnz``), the batched arguments
        disagree on ``B``, or the given matrices do not match the
        patterns of the solver.
    """
    arguments = dict(P=P, c=c, A=A, b=b, G=G, h_u=h_u, h_l=h_l, x_u=x_u, x_l=x_l)
    given = {name: value for name, value in arguments.items() if value is not None}
    for name in ("P", "A", "G"):
        if name in self._csr and name not in given:
            raise ValueError(f"the solver has a pattern for {name}, so {name} values must be given.")
        if name in given and name not in self._csr:
            raise ValueError(f"the solver has no pattern for {name}, so {name} values must not be given.")
    check_constraint_blocks(A is not None, b is not None, G is not None, h_l is not None, h_u is not None)
    matrix_shapes = {name: (len(indices),) for name, (_, indices) in self._csr.items()}
    return self._compiled(given, self._n, self._p, self._m, matrix_shapes, self._pattern_key).function(*given.values())

MultistageSolver

MultistageSolver

MultistageSolver(
    dtype: Any = jax.numpy.float64,
    settings: Settings | None = None,
)

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,

\[ \begin{aligned} \min_{x}\quad & \tfrac{1}{2}\, x^\top P x + c^\top x \\ \text{s.t.}\quad & A x = b, \\ & h_l \le G x \le h_u, \\ & x_l \le x \le x_u, \end{aligned} \]

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:DenseSolver.

float64
settings Settings

Solver configuration; see :class:DenseSolver.

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
def __init__(self, dtype: Any = jax.numpy.float64, settings: Settings | None = None) -> None:
    if np.dtype(dtype) == np.float32:
        self._dtype = wp.float32
    elif np.dtype(dtype) == np.float64:
        self._dtype = wp.float64
    else:
        raise TypeError(f"dtype must be float32 or float64; got {dtype!r}.")
    if self._dtype is wp.float64 and not jax.config.jax_enable_x64:
        raise RuntimeError(
            f"{type(self).__name__} with dtype float64 requires 64-bit JAX arrays: "
            "call jax.config.update('jax_enable_x64', True) before creating any "
            "array, or use dtype=jnp.float32."
        )
    self.settings = Settings.for_dtype(self._dtype) if settings is None else settings

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

(P_diag, P_offdiag): diagonal blocks (N, d, d) and lower off-diagonal blocks (N - 1, d, d) (block (k + 1, k)) of the symmetric block-tridiagonal cost. P_offdiag may be None: P is block diagonal. Required.

required
c Array

Linear cost, (N, d) or flat (N * d,). Required.

required
A optional

Equality constraints A x = b: A = (A_diag, A_offdiag), both (N, r, d), so A has N + 1 block rows, and b of shape (N + 1, r) or flat. A_offdiag may be None (per-stage equalities, N block rows): b is then (N, r) or flat. Give both or neither.

None
b optional

Equality constraints A x = b: A = (A_diag, A_offdiag), both (N, r, d), so A has N + 1 block rows, and b of shape (N + 1, r) or flat. A_offdiag may be None (per-stage equalities, N block rows): b is then (N, r) or flat. Give both or neither.

None
G optional

Inequalities h_l <= G x <= h_u: G = (G_diag, G_offdiag) laid out like A, bounds like b. At least one bound is required with G. Use -inf / +inf entries for one-sided rows.

None
h_l optional

Inequalities h_l <= G x <= h_u: G = (G_diag, G_offdiag) laid out like A, bounds like b. At least one bound is required with G. Use -inf / +inf entries for one-sided rows.

None
h_u optional

Inequalities h_l <= G x <= h_u: G = (G_diag, G_offdiag) laid out like A, bounds like b. At least one bound is required with G. Use -inf / +inf entries for one-sided rows.

None
x_l Array

Box bounds, (N, d) or flat (N * d,).

None
x_u Array

Box bounds, (N, d) or flat (N * d,).

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 (diag, offdiag) tuple or an argument does not have the solver dtype.

ValueError

If the block shapes are inconsistent, an argument has the wrong rank or shape, the batched arguments disagree on B, or the blocks are inconsistent (A without b, bounds without G, G without any bound).

Source code in cupiqp/interfaces/jax/multistage.py
def solve(
    self,
    P: tuple[jax.Array, jax.Array | None],
    c: jax.Array,
    A: tuple[jax.Array, jax.Array | None] | None = None,
    b: jax.Array | None = None,
    G: tuple[jax.Array, jax.Array | None] | None = None,
    h_u: jax.Array | None = None,
    h_l: jax.Array | None = None,
    x_u: jax.Array | None = None,
    x_l: jax.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
    ----------
    P : tuple of jax.Array
        ``(P_diag, P_offdiag)``: diagonal blocks ``(N, d, d)`` and lower
        off-diagonal blocks ``(N - 1, d, d)`` (block ``(k + 1, k)``) of
        the symmetric block-tridiagonal cost. ``P_offdiag`` may be
        ``None``: P is block diagonal. Required.
    c : jax.Array
        Linear cost, ``(N, d)`` or flat ``(N * d,)``. Required.
    A, b : optional
        Equality constraints ``A x = b``: ``A = (A_diag, A_offdiag)``,
        both ``(N, r, d)``, so ``A`` has ``N + 1`` block rows, and ``b``
        of shape ``(N + 1, r)`` or flat. ``A_offdiag`` may be ``None``
        (per-stage equalities, ``N`` block rows): ``b`` is then
        ``(N, r)`` or flat. Give both or neither.
    G, h_l, h_u : optional
        Inequalities ``h_l <= G x <= h_u``: ``G = (G_diag, G_offdiag)``
        laid out like ``A``, bounds like ``b``. At least one bound is
        required with ``G``. Use ``-inf`` / ``+inf`` entries for
        one-sided rows.
    x_l, x_u : jax.Array, optional
        Box bounds, ``(N, d)`` or flat ``(N * d,)``.

    Returns
    -------
    QPSolution
        The solution in the flat layout, with a leading batch axis if any
        argument was batched.

    Raises
    ------
    TypeError
        If a matrix is not a ``(diag, offdiag)`` tuple or an argument
        does not have the solver dtype.
    ValueError
        If the block shapes are inconsistent, an argument has the wrong
        rank or shape, the batched arguments disagree on ``B``, or the
        blocks are inconsistent (``A`` without ``b``, bounds without
        ``G``, ``G`` without any bound).
    """
    P_diag, P_offdiag = _split_pair("P", P)
    if P_diag is None:
        raise TypeError("MultistageSolver.solve requires P.")
    A_diag, A_offdiag = _split_pair("A", A)
    G_diag, G_offdiag = _split_pair("G", G)

    check_constraint_blocks(A is not None, b is not None, G is not None, h_l is not None, h_u is not None)
    P_shape = tuple(int(s) for s in getattr(P_diag, "shape", ()))
    if len(P_shape) not in (3, 4) or P_shape[-1] != P_shape[-2]:
        raise ValueError(f"P diag must have shape (N, d, d) or (B, N, d, d); got {P_shape}.")
    N, d = P_shape[-3], P_shape[-1]
    if N < 1:
        raise ValueError("P diag must contain at least one block.")
    r_A = _rows_per_block("A", A_diag, N, d) if A_diag is not None else 0
    r_G = _rows_per_block("G", G_diag, N, d) if G_diag is not None else 0
    # A and G have N + 1 block rows with off-diagonal blocks, N without.
    rows_A = N + int(A_offdiag is not None)
    rows_G = N + int(G_offdiag is not None)

    matrix_shapes = {"P_diag": (N, d, d), "P_offdiag": (N - 1, d, d),
                     "A_diag": (N, r_A, d), "A_offdiag": (N, r_A, d),
                     "G_diag": (N, r_G, d), "G_offdiag": (N, r_G, d)}
    vector_blocks = {"c": (N, d), "x_u": (N, d), "x_l": (N, d),
                     "b": (rows_A, r_A), "h_u": (rows_G, r_G), "h_l": (rows_G, r_G)}
    arguments = {
        "P_diag": P_diag, "P_offdiag": P_offdiag, "c": c,
        "A_diag": A_diag, "A_offdiag": A_offdiag, "b": b,
        "G_diag": G_diag, "G_offdiag": G_offdiag, "h_u": h_u, "h_l": h_l,
        "x_u": x_u, "x_l": x_l,
    }
    given = {}
    for name, value in arguments.items():
        if value is not None:
            given[name] = _flatten(value, *vector_blocks[name]) if name in vector_blocks else value
    return self._compiled(given, N * d, rows_A * r_A, rows_G * r_G, matrix_shapes).function(*given.values())

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, (B, n).

y Array

Multipliers of the equality constraints A x = b, (B, p).

z_l, z_u Array

Multipliers of the lower and upper inequality bounds h_l <= G x <= h_u, (B, m) each.

z_bl, z_bu Array

Multipliers of the lower and upper box bounds x_l <= x <= x_u, (B, n) each.

s_l, s_u, s_bl, s_bu Array

Slacks of the corresponding inequality and box bounds.

status Array

One int32 code of :class:cupiqp.Status per problem, (B,). cupiqp.Status.CUPIQP_SOLVED (0) means converged to tolerance. A failed solve never raises; read this field instead::

solved = sol.status == cupiqp.Status.CUPIQP_SOLVED   # (B,) bool
iterations Array

Number of interior-point iterations per problem, (B,) int32.

primal_res, dual_res Array

Final primal and dual residuals per problem, (B,), in the solver dtype.

Cache

release_solver_memory

release_solver_memory() -> None

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).

Source code in cupiqp/interfaces/jax/base.py
def release_solver_memory() -> None:
    """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)."""
    for compiled in CACHE.values():
        for owner in (compiled, compiled.backward):
            if owner is None:
                continue
            with owner.execution_lock:
                if owner.workspace is not None:
                    close_workspace(owner.workspace)
                    owner.workspace = None