PyTorch Layers¶
Differentiable torch.nn.Module wrappers of the solvers, available as
cupiqp.torch. See the PyTorch Layers guide for the workflow,
the gradient rules and max_pending_solves.
DenseSolverLayer¶
DenseSolverLayer
¶
DenseSolverLayer(
dtype: dtype = torch.float64,
stream: Stream | None = None,
device: device | str | None = None,
)
Bases: SolverLayerBase
Differentiable QP layer backed by cupiqp.DenseSolver.
Solves, for one problem or a batch,
minimize 0.5 x^T P x + c^T x
subject to A x = b
h_l <= G x <= h_u
x_l <= x <= x_u
with dense CUDA tensors. setup() fixes the dimensions and which
blocks exist and allocates all GPU memory; every later call updates the
values it is given, solves, and returns x::
layer = cupiqp.torch.DenseSolverLayer()
layer.setup(P, c, x_l=x_l, x_u=x_u)
x = layer(c=c_k) # solve with a new linear cost
x.sum().backward() # gradient for c_k
setup() takes the arguments of cupiqp.DenseSolver.setup as dense
CUDA tensors of the layer dtype: each matrix is (rows, cols) or
(B, rows, cols) and each vector (k,) or (B, k); the batch
size is read from the batched arguments. See :class:cupiqp.DenseSolver
for the meaning of every argument and for +/-inf bounds, and
:class:SolverLayerBase for max_pending_solves (several solves
awaiting one backward, as in a rollout).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
dtype
|
|
torch.float64
|
stream
|
Stream
|
Torch stream to order the solver with. By default the layer orders itself with Torch's current stream at every call. |
None
|
device
|
device or str
|
CUDA device to solve on. Defaults to the stream's device, else Torch's current CUDA device. All tensors must live on it. |
None
|
Source code in cupiqp/interfaces/torch/base.py
settings
property
writable
¶
Configuration of the core solver. Change fields before
setup() or between calls, e.g. layer.settings.max_iter = 50.
enable_grad is on by default for a layer.
result
property
¶
Full solution of the latest call (duals, slacks, status) as a
:class:TorchSolution, or None before the first call.
setup
¶
setup(
P: Tensor,
c: Tensor,
A: Tensor | None = None,
b: Tensor | None = None,
G: Tensor | None = None,
h_u: Tensor | None = None,
h_l: Tensor | None = None,
x_u: Tensor | None = None,
x_l: Tensor | None = None,
max_pending_solves: int = 1,
per_call_fields: Sequence[str] | None = None,
) -> None
Fix the problem structure from these tensors, load their values and allocate every GPU buffer of the layer.
Same arguments as the core solver's setup(): P and c are
required; A, b (equalities), G, h_u, h_l (inequalities) and
x_u, x_l (bounds) are optional. Each tensor is of the layer dtype,
on the layer device, and either shared (single-problem shape) or
batched (leading batch axis). The matrix format depends on the layer:
dense CUDA tensors for :class:DenseSolverLayer, CUDA sparse CSR
tensors for :class:SparseSolverLayer. Does not solve; call the
layer afterwards. Gradients are not tracked for setup() tensors,
only for those passed to the layer call.
max_pending_solves is how many differentiable calls may await
their backward at once: 1 reuses the forward factorization in the
backward; more saves every call's solution and refactorizes in its
backward, and then requires per_call_fields, the names of the
arguments every call passes. See the class documentation. Call
setup() once per layer; reset() allows a new one.
Source code in cupiqp/interfaces/torch/base.py
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 | |
forward
¶
forward(
P: Tensor | None = None,
c: Tensor | None = None,
A: Tensor | None = None,
b: Tensor | None = None,
G: Tensor | None = None,
h_u: Tensor | None = None,
h_l: Tensor | None = None,
x_u: Tensor | None = None,
x_l: Tensor | None = None,
) -> torch.Tensor
Load the given values, solve, and return the primal solution x
of shape (B, n).
Arguments left as None keep their current values. Each tensor is
either shared, in the single-problem shape fixed by setup(), or
batched with the leading batch axis. Gradients flow to every tensor
passed here that requires them. The returned tensor is a view of the
solver's result buffer, overwritten by the next call; layer.result
holds the duals, slacks and the per-problem status.
Source code in cupiqp/interfaces/torch/base.py
reset
¶
Discard the problem and its GPU memory; setup() may then be
called again, with a new structure. The settings are kept.
Refuses while a differentiable call is pending backward, since its
later backward() would run on the new solver: finish that
backward first, or drop the output so that its autograd graph is
freed.
Source code in cupiqp/interfaces/torch/base.py
SparseSolverLayer¶
SparseSolverLayer
¶
SparseSolverLayer(
dtype: dtype = torch.float64,
stream: Stream | None = None,
device: device | str | None = None,
)
Bases: SolverLayerBase
Differentiable QP layer backed by cupiqp.SparseSolver.
Solves the same QP as :class:DenseSolverLayer with sparse P,
A and G. The sparsity patterns are part of the structure: they
are given once, as CUDA sparse CSR tensors, to setup(), and every
later call takes only the stored values of each matrix, in the order of
the CSR pattern::
layer = cupiqp.torch.SparseSolverLayer()
layer.setup(P_csr, c, A=A_csr, b=b)
x = layer(P=P_csr.values(), c=c_k) # values only
x.sum().backward() # gradients for both
setup() takes P, A and G as CUDA sparse CSR tensors of
the layer dtype, 2-D or 3-D with one shared pattern; store the full
P (both triangles). The vectors are dense tensors, shared or
batched. Values at every call are (nnz,) or (B, nnz) tensors,
and their gradients have the same shape. A 3-D CSR tensor at setup()
must store the same pattern for every problem; the first one is used
and the others are not checked against it. Changing a pattern requires
reset() and a new setup(). See :class:SolverLayerBase for
max_pending_solves (several solves awaiting one backward, as in a
rollout).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
dtype
|
|
torch.float64
|
stream
|
Stream
|
Torch stream to order the solver with. By default the layer orders itself with Torch's current stream at every call. |
None
|
device
|
device or str
|
CUDA device to solve on. Defaults to the stream's device, else Torch's current CUDA device. All tensors must live on it. |
None
|
Source code in cupiqp/interfaces/torch/base.py
settings
property
writable
¶
Configuration of the core solver. Change fields before
setup() or between calls, e.g. layer.settings.max_iter = 50.
enable_grad is on by default for a layer.
result
property
¶
Full solution of the latest call (duals, slacks, status) as a
:class:TorchSolution, or None before the first call.
setup
¶
setup(
P: Tensor,
c: Tensor,
A: Tensor | None = None,
b: Tensor | None = None,
G: Tensor | None = None,
h_u: Tensor | None = None,
h_l: Tensor | None = None,
x_u: Tensor | None = None,
x_l: Tensor | None = None,
max_pending_solves: int = 1,
per_call_fields: Sequence[str] | None = None,
) -> None
Fix the problem structure from these tensors, load their values and allocate every GPU buffer of the layer.
Same arguments as the core solver's setup(): P and c are
required; A, b (equalities), G, h_u, h_l (inequalities) and
x_u, x_l (bounds) are optional. Each tensor is of the layer dtype,
on the layer device, and either shared (single-problem shape) or
batched (leading batch axis). The matrix format depends on the layer:
dense CUDA tensors for :class:DenseSolverLayer, CUDA sparse CSR
tensors for :class:SparseSolverLayer. Does not solve; call the
layer afterwards. Gradients are not tracked for setup() tensors,
only for those passed to the layer call.
max_pending_solves is how many differentiable calls may await
their backward at once: 1 reuses the forward factorization in the
backward; more saves every call's solution and refactorizes in its
backward, and then requires per_call_fields, the names of the
arguments every call passes. See the class documentation. Call
setup() once per layer; reset() allows a new one.
Source code in cupiqp/interfaces/torch/base.py
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 | |
forward
¶
forward(
P: Tensor | None = None,
c: Tensor | None = None,
A: Tensor | None = None,
b: Tensor | None = None,
G: Tensor | None = None,
h_u: Tensor | None = None,
h_l: Tensor | None = None,
x_u: Tensor | None = None,
x_l: Tensor | None = None,
) -> torch.Tensor
Load the given values, solve, and return the primal solution x
of shape (B, n).
Arguments left as None keep their current values. Each tensor is
either shared, in the single-problem shape fixed by setup(), or
batched with the leading batch axis. Gradients flow to every tensor
passed here that requires them. The returned tensor is a view of the
solver's result buffer, overwritten by the next call; layer.result
holds the duals, slacks and the per-problem status.
Source code in cupiqp/interfaces/torch/base.py
reset
¶
Discard the problem and its GPU memory; setup() may then be
called again, with a new structure. The settings are kept.
Refuses while a differentiable call is pending backward, since its
later backward() would run on the new solver: finish that
backward first, or drop the output so that its autograd graph is
freed.
Source code in cupiqp/interfaces/torch/base.py
MultistageSolverLayer¶
MultistageSolverLayer
¶
MultistageSolverLayer(
dtype: dtype = torch.float64,
stream: Stream | None = None,
device: device | str | None = None,
)
Bases: SolverLayerBase
Differentiable QP layer backed by cupiqp.MultistageSolver.
Solves the same QP as :class:DenseSolverLayer when P is block
tridiagonal and A and G are block lower bidiagonal, as in optimal
control over N stages of d variables (n = N*d). setup()
takes the arguments of cupiqp.MultistageSolver.setup: each matrix is
a (diag, offdiag) pair of CUDA tensors, and an offdiag given as
None means that matrix has no coupling blocks for the lifetime of
the layer::
layer = cupiqp.torch.MultistageSolverLayer()
layer.setup(P=(P_diag, None), c=c, A=(A_diag, A_offdiag), b=b,
x_l=x_l, x_u=x_u)
x = layer(c=c_k, A_offdiag=dyn_k) # x is (B, N*d)
x.sum().backward() # gradients for c_k and dyn_k
Every call takes one tensor per block, so each block can be passed,
shared or batched, and differentiated on its own: P_diag (N, d, d),
P_offdiag (N-1, d, d), A_diag, A_offdiag, G_diag and
G_offdiag (N, r, d), each optionally with a leading batch axis.
Vectors are flat, (k,) or (B, k), like the solution; a vector in
block layout (N, d) is passed as c.reshape(-1), a view. A block
absent at setup() cannot be passed later. per_call_fields names
these call arguments, e.g. ("c", "A_offdiag"). See
:class:cupiqp.MultistageSolver for the block layout and
:class:SolverLayerBase for max_pending_solves.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
dtype
|
|
torch.float64
|
stream
|
Stream
|
Torch stream to order the solver with. By default the layer orders itself with Torch's current stream at every call. |
None
|
device
|
device or str
|
CUDA device to solve on. Defaults to the stream's device, else Torch's current CUDA device. All tensors must live on it. |
None
|
Source code in cupiqp/interfaces/torch/base.py
settings
property
writable
¶
Configuration of the core solver. Change fields before
setup() or between calls, e.g. layer.settings.max_iter = 50.
enable_grad is on by default for a layer.
result
property
¶
Full solution of the latest call (duals, slacks, status) as a
:class:TorchSolution, or None before the first call.
setup
¶
setup(
P: Tensor,
c: Tensor,
A: Tensor | None = None,
b: Tensor | None = None,
G: Tensor | None = None,
h_u: Tensor | None = None,
h_l: Tensor | None = None,
x_u: Tensor | None = None,
x_l: Tensor | None = None,
max_pending_solves: int = 1,
per_call_fields: Sequence[str] | None = None,
) -> None
Fix the problem structure from these tensors, load their values and allocate every GPU buffer of the layer.
Same arguments as the core solver's setup(): P and c are
required; A, b (equalities), G, h_u, h_l (inequalities) and
x_u, x_l (bounds) are optional. Each tensor is of the layer dtype,
on the layer device, and either shared (single-problem shape) or
batched (leading batch axis). The matrix format depends on the layer:
dense CUDA tensors for :class:DenseSolverLayer, CUDA sparse CSR
tensors for :class:SparseSolverLayer. Does not solve; call the
layer afterwards. Gradients are not tracked for setup() tensors,
only for those passed to the layer call.
max_pending_solves is how many differentiable calls may await
their backward at once: 1 reuses the forward factorization in the
backward; more saves every call's solution and refactorizes in its
backward, and then requires per_call_fields, the names of the
arguments every call passes. See the class documentation. Call
setup() once per layer; reset() allows a new one.
Source code in cupiqp/interfaces/torch/base.py
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 | |
forward
¶
forward(
P_diag: Tensor | None = None,
P_offdiag: Tensor | None = None,
c: Tensor | None = None,
A_diag: Tensor | None = None,
A_offdiag: Tensor | None = None,
b: Tensor | None = None,
G_diag: Tensor | None = None,
G_offdiag: Tensor | None = None,
h_u: Tensor | None = None,
h_l: Tensor | None = None,
x_u: Tensor | None = None,
x_l: Tensor | None = None,
) -> torch.Tensor
Load the given blocks and vectors, solve, and return the primal
solution x of shape (B, N*d).
Arguments left as None keep their current values. Each tensor is
shared, in the single-problem shape, or batched with a leading batch
axis. Gradients flow to every tensor passed here that requires them.
The returned tensor is overwritten by the next call (see
:class:SolverLayerBase); layer.result holds the duals, slacks
and the per-problem status.
Source code in cupiqp/interfaces/torch/multistage.py
reset
¶
Discard the problem and its GPU memory; setup() may then be
called again, with a new structure. The settings are kept.
Refuses while a differentiable call is pending backward, since its
later backward() would run on the new solver: finish that
backward first, or drop the output so that its autograd graph is
freed.
Source code in cupiqp/interfaces/torch/base.py
TorchSolution¶
TorchSolution
¶
Solution of the latest call of a solver layer, as CUDA tensors.
Everything stays on the device. x has shape (B, n); the dual and
slack fields are (B, k) tensors, or None when the corresponding
constraint block was not given at setup(). status and
iterations are int32 (B,) tensors with one entry per problem.
All of them are views of the solver's buffers, written in stream order:
they can be used in further Torch work on the same stream without
synchronization, and the next call of the layer overwrites them. Use
:meth:clone to keep a result, and .cpu() on a tensor when you
need its values on the host.
info is the core solver's per-problem diagnostics (residuals,
objectives, step sizes, ...) as Warp arrays on the device; its
to_host() copies them all at once.
Example::
x = layer(c=c_k)
solved = layer.result.status == cupiqp.Status.CUPIQP_SOLVED # (B,) bool, on device
if not bool(solved.all()): # explicit host read
print(layer.result.status.cpu())
Source code in cupiqp/interfaces/torch/types.py
clone
¶
Return a solution whose tensors own independent storage, so that later calls of the layer do not change it. Allocates; meant for keeping a result, not for the hot path.
Source code in cupiqp/interfaces/torch/types.py
StructureMismatchError¶
StructureMismatchError
¶
Bases: ValueError
A tensor passed to a layer call does not fit the structure fixed by
setup(): a block that was not set up, or a shape other than the
single-problem or batched shape. Call reset() and setup() again,
or use another layer instance, to change the structure.